HCCL 环境变量配置集群资源信息指南CM_CHIEF/CM_WORKER 系列环境变量详解与 TensorFlow 分布式训练实践【免费下载链接】hccl集合通信库Huawei Collective Communication Library简称HCCL是基于昇腾AI处理器的高性能集合通信库为计算集群提供高性能、高可靠的通信方案项目地址: https://gitcode.com/cann/hccl导读在基于昇腾 AI 处理器的分布式训练场景中除通过 rank table 文件描述集群资源外HCCL 还提供了一套以CM_CHIEF_*/CM_WORKER_*环境变量为核心的资源信息配置方式无需额外文件即可在 TensorFlow 框架下完成通信域初始化。本文以 docs/zh/user_guide/cluster_info_config/env_config_info.md 为主体逐项解析每个环境变量的语义、取值范围与约束并结合多节点配置示例与配套环境变量文档帮助开发者快速落地一套可复现、可排查的分布式训练环境。一、为什么需要环境变量配置方式在 HCCL 的集群信息配置体系中开发者主要有两条路径描述参与集合通信的 NPU 资源rank table 文件方式将集群拓扑、Device 归属、IP 地址等信息写入 rank table 文件适用于通过 C 接口如HcclCommInitClusterInfo初始化通信域或 TensorFlow 分布式网络通信域初始化场景环境变量方式在执行训练的每个 AI Server 节点上分别导出CM_CHIEF_*、CM_WORKER_*等环境变量由 HCCL 在初始化时自动收集并组建集群。需要特别强调的是针对 TensorFlow 框架网络开发者只能在 rank table 与环境变量两种方式中选择其一不支持混用参见 docs/zh/user_guide/cluster_info_config/intro.md。当通过环境变量配置集群信息时环境中不能存在RANK_TABLE_FILE、RANK_ID、RANK_SIZE这三个环境变量否则配置方式会发生冲突。该方式仅适用于以下产品Atlas A2 训练系列产品 / Atlas A2 推理系列产品对应 910B 芯片Atlas 训练系列产品对应 910 芯片。二、环境变量全景配置说明与取值范围需要在执行训练的每个 AI Server 节点上分别配置如下环境变量进行资源信息配置一个最简配置如下export CM_CHIEF_IP192.168.1.1 export CM_CHIEF_PORT6000 export CM_CHIEF_DEVICE0 export CM_WORKER_SIZE8 export CM_WORKER_IP192.168.0.1 export HCCL_SOCKET_FAMILYAF_INET各环境变量的含义与约束如下环境变量作用取值要求CM_CHIEF_IPMaster 节点的 Host 监听 IP即与其他节点进行通信的 IP 地址常规 IPv4 或 IPv6 格式CM_CHIEF_PORTMaster 节点的监听端口整数取值范围 065520需确保端口未被其他进程占用CM_CHIEF_DEVICEMaster 节点中统计 Server 端集群信息的 Device 逻辑 ID整数取值范围 [0Server 内最大 Device 数量-1]CM_WORKER_SIZE组网中参与集群训练的 Device 总数量整数取值范围 0~32768CM_WORKER_IP当前节点与 Master 进行通信时所用的网卡 IP常规 IPv4 或 IPv6 格式HCCL_SOCKET_FAMILY可选控制 Device 侧通信网卡使用的 IP 协议版本AF_INET使用 IPv4AF_INET6使用 IPv6缺省优先使用 IPv42.1 MasterChief与 Worker 的角色划分在上述配置中CM_CHIEF_*描述的是集群中的Master 节点它承担集群信息管理、资源分配与调度职责是所有 Worker 节点的汇聚中心CM_WORKER_*描述的是参与训练的 Worker 侧信息。CM_CHIEF_DEVICE指定 Master 节点上用于统计 Server 端集群信息的 Device 逻辑 ID其上限与单 Server 内的最大 Device 数量相关例如单 Server 8 卡时取值范围为 [0,7]。2.2 HCCL_SOCKET_FAMILY 的深入说明该环境变量在本文场景中用于控制Device 侧通信网卡使用的 IP 协议版本其细节在 docs/zh/user_guide/hccl_env/HCCL_SOCKET_FAMILY.md 中有更完整的描述缺省使用 IPv4 协议。从故障排查角度看HCCL 默认先使用 IPv4若 Device 侧没有配置 IPv4 协议的 IP才会回退到 IPv6 对应的 IP参见 docs/zh/user_guide/fault_diagnosis/ip_family_check_inconsistent_EI0001.md 中关于同一次作业所有 rank 的 IP Family 应保持一致的要求。以实际网卡信息为准如果HCCL_SOCKET_FAMILY指定的 IP 协议与实际获取到的网卡信息不匹配则以实际环境上的网卡信息为准。例如环境变量指定为AF_INET6但 Device 侧只存在 IPv4 协议的网卡则实际会使用 IPv4 协议的网卡。配置示例export HCCL_SOCKET_FAMILYAF_INET # IPv4 export HCCL_SOCKET_FAMILYAF_INET6 # IPv6三、完整配置示例2 节点 16 Device以执行分布式训练的 AI Server 节点数量为 2、Device 数量为 16 为例每个 AI Server 节点有 8 个 Device。启动每个 Device 上的训练进程前在对应的 shell 窗口中配置如下环境变量。节点 0Master 节点负责集群信息管理、资源分配与调度export CM_CHIEF_IP192.168.1.1 export CM_CHIEF_PORT6000 export CM_CHIEF_DEVICE0 export CM_WORKER_SIZE16 export CM_WORKER_IP192.168.1.1节点 1export CM_CHIEF_IP192.168.1.1 export CM_CHIEF_PORT6000 export CM_CHIEF_DEVICE0 export CM_WORKER_SIZE16 export CM_WORKER_IP192.168.2.1从示例中可以提炼出三个关键配置要点集群规模由CM_WORKER_SIZE统一声明两个节点上的CM_WORKER_SIZE均为 16即组网中参与集群训练的 Device 总数量而不是单个节点的 Device 数CM_CHIEF_IP/CM_CHIEF_PORT/CM_CHIEF_DEVICE全集群一致每个节点都指向同一个 Master 节点的监听 IP、端口及统计 DeviceCM_WORKER_IP按节点差异化配置各节点填写自身与 Master 通信所用的网卡 IP示例中节点 0 为 192.168.1.1节点 1 为 192.168.2.1。3.1 端口与单卡多进程场景建议针对 Atlas A2 训练系列产品 / Atlas A2 推理系列产品若业务为单卡多进程场景即多个业务进程同时共用一个 NPU建议通过环境变量 HCCL_NPU_SOCKET_PORT_RANGE 配置 HCCL 在 NPU 侧使用的通信端口否则可能会导致端口冲突配置示例export HCCL_NPU_SOCKET_PORT_RANGEauto该环境变量的核心语义如下详见 HCCL_NPU_SOCKET_PORT_RANGE.md支持配置为具体的端口号、端口范围或字符串auto端口号取值范围 [1,65535]其中 [1,1023] 为系统保留端口应避免使用多个端口号/范围可用英文逗号组合但逗号之间的端口号/端口范围不能存在范围交叉如61000,61050-61100,61200-61210指定为auto时HCCL 在 NPU 侧使用的端口号由操作系统动态分配不配置时HCCL 在 NPU 侧使用的通信端口默认为 16666使用约束多卡场景下同一通信域内的所有卡都必须配置该环境变量单卡多进程虽然可以规避端口冲突但多进程会对资源开销、通信性能产生一定影响需要结合实际业务评估。四、配置方式与通信域初始化的衔接从 HCCL 整体通信流程看参见 docs/zh/user_guide/api_comm_impl.md任何集合通信能力都始于集群信息配置 → 创建通信域句柄 → 初始化 HCCL 通信域。环境变量方式本质上是在 rank table 文件之外为 TensorFlow 框架网络提供一套“零文件”的集群信息注入通道HCCL 在初始化阶段读取各节点导出的CM_CHIEF_*/CM_WORKER_*环境变量自动完成 Master-Worker 关系的建立与 Device 资源的统计随后即可下发点对点通信与集合通信算子如 AllReduce、AllGather、Broadcast 等用于梯度同步和参数更新。通信域中的每个通信对象称为一个 rank每个 rank 分配 0~n-1n 为 NPU 数量的唯一标识。环境变量方式下的CM_WORKER_SIZE正是决定该 n 值的关键输入因此务必保证其与实际组网 Device 总数一致。五、常见错误与排查要点结合 docs/zh/user_guide/fault_diagnosis/ 目录下的故障诊断文档环境变量配置方式下需重点核查以下几点IP 协议家族不一致EI0001同一次作业的所有 rank 的 IP Family 应保持一致。HCCL 默认先使用 IPv4 协议若 Device 侧没有 IPv4 协议的 IP 则使用 IPv6可通过HCCL_SOCKET_FAMILY显式指定避免因主机侧与 Device 侧协议版本不一致导致建链失败参见 ip_family_check_inconsistent_EI0001.md端口被占用CM_CHIEF_PORT的取值范围为 065520配置前应确认端口未被其他进程占用单卡多进程场景下还应关注 NPU 侧默认端口 16666 的冲突问题配置方式冲突使用环境变量方式时环境中不得残留RANK_TABLE_FILE、RANK_ID、RANK_SIZE否则需先清除后再启动训练进程规模声明不一致所有节点的CM_WORKER_SIZE必须一致且等于实际参与训练的 Device 总数Master 的CM_CHIEF_IP/CM_CHIEF_PORT/CM_CHIEF_DEVICE必须在所有节点上保持完全一致。六、总结环境变量配置资源信息方式是 HCCL 针对 TensorFlow 框架网络提供的一种轻量级集群组网方案通过CM_CHIEF_IP、CM_CHIEF_PORT、CM_CHIEF_DEVICE、CM_WORKER_SIZE、CM_WORKER_IP五个必配项与HCCL_SOCKET_FAMILY一个可选项即可完成多节点资源编排且与 rank table 文件方式互斥。实际部署时请严格遵循“全集群统一声明规模、按节点差异化配置网卡 IP、保持协议版本一致”的原则并结合 HCCL_NPU_SOCKET_PORT_RANGE 处理单卡多进程的端口规划即可快速获得一套稳定可用的分布式训练通信环境。【免费下载链接】hccl集合通信库Huawei Collective Communication Library简称HCCL是基于昇腾AI处理器的高性能集合通信库为计算集群提供高性能、高可靠的通信方案项目地址: https://gitcode.com/cann/hccl创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考