CANN HIXL LLMDataDist 角色类型 LLMRole 详解init 与 switch_role 中的 PROMPT / DECODER / MIX【免费下载链接】hixlHIXLHuawei Xfer Library是一个灵活、高效的昇腾单边通信库面向集群场景提供简单、可靠、高效的点对点数据传输能力。项目地址: https://gitcode.com/cann/hixlLLMRole 是 CANN HIXL 开源仓库中 LLMDataDist 分布式 KV Cache 传输组件调用 init 初始化接口时必须传入的角色枚举类型用于声明当前进程在提示全量图与解码增量图两种计算场景中的身份。本文以 LLMRole API 参考文档 为骨架结合仓库内 Python 源码与官方示例说明三个枚举值的准确定义、底层实现、角色差异行为以及动态切换用法帮助开发者正确初始化 LLMDataDist 并排查角色配置错误。LLMRole 是什么在 LLM大语言模型分布式推理与 KV Cache 跨卡传输场景中参与传输的进程需要明确自己是提示阶段prefill还是解码阶段decode的一方才能正确决定建链方向、内存注册语义和监听行为。LLMRole 就是这一身份信息的载体它在构造LLMDataDist对象并调用init接口时传入属于 LLMDataDist-interface.md 所述初始化流程中的必选参数。仓库文档给出的枚举定义如下枚举值含义PROMPT提示全量图场景DECODER解码器增量图场景MIX混合其中全量图对应 LLM 推理的提示prefill阶段处理完整的输入序列并产出 KV Cache增量图对应解码decode阶段逐 token 生成并持续读写 KV Cache。MIX 则用于需要在同一进程中混合承担两种角色的场景。源码中的枚举定义LLMRole 定义在 configs.py 中继承自 Python 标准库的IntEnumclass LLMRole(IntEnum): PROMPT 1 DECODER 2 MIX 3 def __str__(self): return f{self.__class__.__name__}.{self.name}从源码结构看可以得出以下实现事实三个枚举值分别对应整数值 1、2、3因此 LLMRole 实例可以直接参与整数比较也可以被当作整型配置传入底层引擎自定义的__str__会输出形如LLMRole.PROMPT的字符串便于日志记录与排查该枚举同时被 v2 版接口和底层配置模块引用LLMClusterInfo.remote_role_type属性configs.py的 setter 也接受LLMRole或int两种形式说明该枚举在跨集群角色协商中同样被使用。LLMDataDist 初始化时如何使用 LLMRoleLLMRole 最核心的使用位置是LLMDataDist的构造函数。在 llm_datadist.py 中class LLMDataDist(object): def __init__(self, role: LLMRole, cluster_id: int): check_isinstance(role, role, LLMRole) self._role role check_uint64(cluster_id, cluster_id) self._cluster_id cluster_id ...构造函数通过check_isinstance强校验role必须是 LLMRole 实例传入其他类型会在初始化阶段直接报错。随后在init流程中角色会被转换为字符串并写入引擎选项self._engine_options[llm.Role] self._role_to_str(self._role)_role_to_strllm_datadist.py完成枚举到引擎配置字符串的映射role_mapping { LLMRole.PROMPT: Prompt, LLMRole.DECODER: Decoder, LLMRole.MIX: Mix, } return role_mapping[role]因此llm.Role引擎选项最终只可能出现Prompt、Decoder、Mix三种取值。典型的初始化代码如下参考 push_blocks_sample.pydatadist LLMDataDist(role, cluster_id) llm_config LLMConfig() llm_config.device_id args.device_id llm_config.local_comm_res if role LLMRole.PROMPT: llm_config.listen_ip_info f{args.local_host_ip}:26000 else: llm_config.listen_ip_info f{args.local_host_ip}:26001 llm_options llm_config.generate_options() datadist.init(llm_options)从示例可以观察到仓库约定的角色差异化约定PROMPT 角色监听26000端口DECODER 角色监听26001端口双方通过不同监听端口区分身份。PROMPT 与 DECODER 的差异化行为角色不只是标记还直接决定初始化参数校验与接口可用性这是实际使用中最容易踩坑的部分。集群信息生成差异在 config.py 的gen_cluster_info_if_not_exist中当引擎选项中未显式提供llm.ClusterInfo时PROMPT 角色有额外的强制校验if role LLMRole.PROMPT: raise_if_false(llm.listenIpInfo in engine_options, neither llm.ClusterInfo nor llm.listenIp was specified) listen_ip_info engine_options[llm.listenIpInfo] ...即 PROMPT 角色必须提供llm.listenIpInfo格式为ip:port多个设备用分号分隔条目数须与ge.exec.deviceId的设备数一致否则初始化直接失败而 DECODER 角色不强制要求该选项。此外生成 NUMA 配置时临时文件路径也包含角色名stub_numa_config_{role.name.lower()}_*.json说明不同角色的资源拓扑配置是隔离生成的。Cache 接口的可用性差异角色还会影响 KV Cache 管理接口的参数语义。在 cache_manager.py 的文档注释中明确说明blocks_cache_key与cache_keys两个可选参数仅当 LLMRole 为 PROMPT 时可设置用于让 DECODER 侧拉取 KV。这与推理流程一致——提示阶段持有完整 KV 的注册信息解码阶段负责拉取。传输后端与建链方向在 hixl_transfer_backend_sample.py 等示例中PROMPT 角色负责通过listen_ip_info暴露监听地址DECODER 角色基于LLMClusterInfo含remote_role_type发起link_clusters建链完成 KV Cache 的拉取。MIX 混合角色MIX 表示同一进程需要同时扮演提示与解码两种角色适用于需要同时承载全量图与增量图计算的部署形态。从源码看MIX 与 PROMPT、DECODER 一样属于合法的llm.Role取值映射为Mix并在_role_to_str中有一致处理但仓库内公开示例尚未提供 MIX 的完整演练代码实际部署时建议结合 LLMDataDist.md 的集群规划章节确认角色分配。switch_role运行期动态切换角色LLMRole 还用于运行期角色切换。在 switch_role_sample.py 中PROMPT 进程完成 KV 推拉后可切换为 DECODER 角色# 3. 切换角色 datadist.switch_role(LLMRole.DECODER)底层实现在 llm_datadist.py 中要点包括切换前会校验role类型并拒绝切换到与当前相同的角色role not changed切换后self._role同步更新_kv_cache_manager._switch_role(role)也会联动调整缓存管理器的角色状态切换过程中通过dist.barrier()等同步原语保证对端完成监听/解链后再继续避免建链竞态。这一能力支撑了先提示后解码的接力式推理部署同一节点先以 PROMPT 角色承接输入再切换为 DECODER 角色继续生成。校验规则与错误排查LLMRole 相关的校验集中在构造与切换两个入口LLMDataDist(role, cluster_id)check_isinstance(role, role, LLMRole)非法类型立即抛错switch_role(role, ...)同样强校验且raise_if_false(self._role ! role, ...)拒绝无效切换LLMClusterInfo.remote_role_typesetter接受 LLMRole 或 int其他类型被check_isinstance拦截。若初始化报错提示neither llm.ClusterInfo nor llm.listenIp was specified且进程是 PROMPT 角色优先检查是否在LLMConfig中设置了listen_ip_info或直接注入llm.listenIpInfo若提示角色类型错误检查构造LLMDataDist时是否误传了普通整数或字符串而非 LLMRole 枚举。小结LLMRole 是 LLMDataDist 初始化的身份入口通过 PROMPT全量图、DECODER增量图、MIX混合三个枚举值声明进程角色进而影响监听端口、集群信息校验、Cache 接口语义与建链方向。在 configs.py 中定义经 LLMDataDist 初始化与 switch_role_sample.py 演示的动态切换机制构成了跨进程 KV Cache 传输的角色管理闭环。【免费下载链接】hixlHIXLHuawei Xfer Library是一个灵活、高效的昇腾单边通信库面向集群场景提供简单、可靠、高效的点对点数据传输能力。项目地址: https://gitcode.com/cann/hixl创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考 CANN HIXL LLMDataDist 角色类型 LLMRole 详解：init 与 switch_role 中的 PROMPT / DECODER / MIX
CANN HIXL LLMDataDist 角色类型 LLMRole 详解init 与 switch_role 中的 PROMPT / DECODER / MIX【免费下载链接】hixlHIXLHuawei Xfer Library是一个灵活、高效的昇腾单边通信库面向集群场景提供简单、可靠、高效的点对点数据传输能力。项目地址: https://gitcode.com/cann/hixlLLMRole 是 CANN HIXL 开源仓库中 LLMDataDist 分布式 KV Cache 传输组件调用 init 初始化接口时必须传入的角色枚举类型用于声明当前进程在提示全量图与解码增量图两种计算场景中的身份。本文以 LLMRole API 参考文档 为骨架结合仓库内 Python 源码与官方示例说明三个枚举值的准确定义、底层实现、角色差异行为以及动态切换用法帮助开发者正确初始化 LLMDataDist 并排查角色配置错误。LLMRole 是什么在 LLM大语言模型分布式推理与 KV Cache 跨卡传输场景中参与传输的进程需要明确自己是提示阶段prefill还是解码阶段decode的一方才能正确决定建链方向、内存注册语义和监听行为。LLMRole 就是这一身份信息的载体它在构造LLMDataDist对象并调用init接口时传入属于 LLMDataDist-interface.md 所述初始化流程中的必选参数。仓库文档给出的枚举定义如下枚举值含义PROMPT提示全量图场景DECODER解码器增量图场景MIX混合其中全量图对应 LLM 推理的提示prefill阶段处理完整的输入序列并产出 KV Cache增量图对应解码decode阶段逐 token 生成并持续读写 KV Cache。MIX 则用于需要在同一进程中混合承担两种角色的场景。源码中的枚举定义LLMRole 定义在 configs.py 中继承自 Python 标准库的IntEnumclass LLMRole(IntEnum): PROMPT 1 DECODER 2 MIX 3 def __str__(self): return f{self.__class__.__name__}.{self.name}从源码结构看可以得出以下实现事实三个枚举值分别对应整数值 1、2、3因此 LLMRole 实例可以直接参与整数比较也可以被当作整型配置传入底层引擎自定义的__str__会输出形如LLMRole.PROMPT的字符串便于日志记录与排查该枚举同时被 v2 版接口和底层配置模块引用LLMClusterInfo.remote_role_type属性configs.py的 setter 也接受LLMRole或int两种形式说明该枚举在跨集群角色协商中同样被使用。LLMDataDist 初始化时如何使用 LLMRoleLLMRole 最核心的使用位置是LLMDataDist的构造函数。在 llm_datadist.py 中class LLMDataDist(object): def __init__(self, role: LLMRole, cluster_id: int): check_isinstance(role, role, LLMRole) self._role role check_uint64(cluster_id, cluster_id) self._cluster_id cluster_id ...构造函数通过check_isinstance强校验role必须是 LLMRole 实例传入其他类型会在初始化阶段直接报错。随后在init流程中角色会被转换为字符串并写入引擎选项self._engine_options[llm.Role] self._role_to_str(self._role)_role_to_strllm_datadist.py完成枚举到引擎配置字符串的映射role_mapping { LLMRole.PROMPT: Prompt, LLMRole.DECODER: Decoder, LLMRole.MIX: Mix, } return role_mapping[role]因此llm.Role引擎选项最终只可能出现Prompt、Decoder、Mix三种取值。典型的初始化代码如下参考 push_blocks_sample.pydatadist LLMDataDist(role, cluster_id) llm_config LLMConfig() llm_config.device_id args.device_id llm_config.local_comm_res if role LLMRole.PROMPT: llm_config.listen_ip_info f{args.local_host_ip}:26000 else: llm_config.listen_ip_info f{args.local_host_ip}:26001 llm_options llm_config.generate_options() datadist.init(llm_options)从示例可以观察到仓库约定的角色差异化约定PROMPT 角色监听26000端口DECODER 角色监听26001端口双方通过不同监听端口区分身份。PROMPT 与 DECODER 的差异化行为角色不只是标记还直接决定初始化参数校验与接口可用性这是实际使用中最容易踩坑的部分。集群信息生成差异在 config.py 的gen_cluster_info_if_not_exist中当引擎选项中未显式提供llm.ClusterInfo时PROMPT 角色有额外的强制校验if role LLMRole.PROMPT: raise_if_false(llm.listenIpInfo in engine_options, neither llm.ClusterInfo nor llm.listenIp was specified) listen_ip_info engine_options[llm.listenIpInfo] ...即 PROMPT 角色必须提供llm.listenIpInfo格式为ip:port多个设备用分号分隔条目数须与ge.exec.deviceId的设备数一致否则初始化直接失败而 DECODER 角色不强制要求该选项。此外生成 NUMA 配置时临时文件路径也包含角色名stub_numa_config_{role.name.lower()}_*.json说明不同角色的资源拓扑配置是隔离生成的。Cache 接口的可用性差异角色还会影响 KV Cache 管理接口的参数语义。在 cache_manager.py 的文档注释中明确说明blocks_cache_key与cache_keys两个可选参数仅当 LLMRole 为 PROMPT 时可设置用于让 DECODER 侧拉取 KV。这与推理流程一致——提示阶段持有完整 KV 的注册信息解码阶段负责拉取。传输后端与建链方向在 hixl_transfer_backend_sample.py 等示例中PROMPT 角色负责通过listen_ip_info暴露监听地址DECODER 角色基于LLMClusterInfo含remote_role_type发起link_clusters建链完成 KV Cache 的拉取。MIX 混合角色MIX 表示同一进程需要同时扮演提示与解码两种角色适用于需要同时承载全量图与增量图计算的部署形态。从源码看MIX 与 PROMPT、DECODER 一样属于合法的llm.Role取值映射为Mix并在_role_to_str中有一致处理但仓库内公开示例尚未提供 MIX 的完整演练代码实际部署时建议结合 LLMDataDist.md 的集群规划章节确认角色分配。switch_role运行期动态切换角色LLMRole 还用于运行期角色切换。在 switch_role_sample.py 中PROMPT 进程完成 KV 推拉后可切换为 DECODER 角色# 3. 切换角色 datadist.switch_role(LLMRole.DECODER)底层实现在 llm_datadist.py 中要点包括切换前会校验role类型并拒绝切换到与当前相同的角色role not changed切换后self._role同步更新_kv_cache_manager._switch_role(role)也会联动调整缓存管理器的角色状态切换过程中通过dist.barrier()等同步原语保证对端完成监听/解链后再继续避免建链竞态。这一能力支撑了先提示后解码的接力式推理部署同一节点先以 PROMPT 角色承接输入再切换为 DECODER 角色继续生成。校验规则与错误排查LLMRole 相关的校验集中在构造与切换两个入口LLMDataDist(role, cluster_id)check_isinstance(role, role, LLMRole)非法类型立即抛错switch_role(role, ...)同样强校验且raise_if_false(self._role ! role, ...)拒绝无效切换LLMClusterInfo.remote_role_typesetter接受 LLMRole 或 int其他类型被check_isinstance拦截。若初始化报错提示neither llm.ClusterInfo nor llm.listenIp was specified且进程是 PROMPT 角色优先检查是否在LLMConfig中设置了listen_ip_info或直接注入llm.listenIpInfo若提示角色类型错误检查构造LLMDataDist时是否误传了普通整数或字符串而非 LLMRole 枚举。小结LLMRole 是 LLMDataDist 初始化的身份入口通过 PROMPT全量图、DECODER增量图、MIX混合三个枚举值声明进程角色进而影响监听端口、集群信息校验、Cache 接口语义与建链方向。在 configs.py 中定义经 LLMDataDist 初始化与 switch_role_sample.py 演示的动态切换机制构成了跨进程 KV Cache 传输的角色管理闭环。【免费下载链接】hixlHIXLHuawei Xfer Library是一个灵活、高效的昇腾单边通信库面向集群场景提供简单、可靠、高效的点对点数据传输能力。项目地址: https://gitcode.com/cann/hixl创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考