企业官网建设流程全解析

HCCL_ALGO 环境变量完全指南：昇腾集合通信库 Server 间与超节点间通信算法配置

【免费下载链接】hccl集合通信库（Huawei Collective Communication Library，简称HCCL）是基于昇腾AI处理器的高性能集合通信库，为计算集群提供高性能、高可靠的通信方案项目地址: https://gitcode.com/cann/hccl

导读

HCCL_ALGO是 CANN 昇腾集合通信库（HCCL）中用于配置 Server 间（level1）与超节点间（level2）通信算法的核心环境变量。本指南基于 HCCL_ALGO.md 展开，结合 HCCL 开源仓库源码，完整讲解该变量的语法格式、每种通信算法的原理与适用场景、全局配置与按算子配置两种方式、以及环境变量在源码中的解析与生效机制。读完本文，你将能够针对不同产品形态、集群规模和通信数据量，为 AllReduce、AllGather、ReduceScatter 等集合通信算子手工指定最优通信算法，并在确定性计算、保序等约束下正确规避配置陷阱。

功能概述：什么时候需要配置 HCCL_ALGO

HCCL 内置了自适应算法选择机制，默认会根据产品形态、数据量和 Server 个数自动选择合适的通信算法，一般情况下用户无需手工指定。但存在两类典型场景需要开发者显式配置HCCL_ALGO：

• 网络存在拥塞或拓扑特殊：默认算法在特定网络环境下表现不佳，需要切换为 ring、NHR 等对拥塞更鲁棒的算法；
• 通信数据量极大或极小的极端场景：例如大流量下希望启用 pipeline 算法并发使用 Server 内与 Server 间链路。

需要注意的关键语义：一旦通过HCCL_ALGO指定了 Server 间或超节点间通信算法，HCCL 的自适应算法选择功能即不再生效，被指定的层级将完全遵循用户的配置。同时，在某些通信算子中，当使用特定类型的 AI 处理器且数据量较小时，通信算法仍会由 HCCL 自适应选择，不受此环境变量的控制。

HCCL 支持配置的算法为全量通信算法，但不同产品下支持的 Server 间通信算法与超节点间通信算法各不相同，配置前请务必核对两份支持度列表：Server间通信算法支持度列表 与 超节点间通信算法支持度列表。

配置语法：三级 level 模型

HCCL_ALGO的取值基于「层级（level）+ 算法（algo）」的结构，完整语法为：

export HCCL_ALGO="level0:<algo>;level1:<algo>;level2:<algo>"

各层级的含义如下：

level0：Server 内通信算法（仅 NA）

level0 代表 Server 内（节点内）通信算法，当前版本仅支持配置为NA，即不干预 Server 内的算法选择，由 HCCL 内部根据拓扑自动确定（如基于 HCCS 链路的 Whole Ring、Mesh 等拓扑，参见 alg_type.h 中的AlgTypeLevel0枚举）。

level1：Server 间通信算法

level1 代表 Server 间的通信算法，是HCCL_ALGO配置中最核心、使用最频繁的层级，支持以下取值：

• ring：基于环结构的通信算法。通信步数多（线性复杂度），时延相对较高，但通信关系简单，受网络拥塞影响较小。适合通信域内 Server 个数较少、通信数据量较小、网络存在明显拥塞、且 pipeline 算法不适用的场景。
• H-D_R：递归二分和倍增算法（Recursive Halving-Doubling，RHD）。通信步数少（对数复杂度），时延相对较低，但在非 2 的整数次幂节点规模下会引入额外的通信量。适合通信域内 Server 个数是 2 的整数次幂且 pipeline 算法不适用的场景，或 Server 个数不是 2 的整数次幂但通信数据量较小的场景。
• NHR：非均衡的层次环算法（Nonuniform Hierarchical Ring）。通信步数少（对数复杂度），时延相对较低。适合通信域内 Server 个数较多且 pipeline 算法不适用的场景。

  注意（Ascend 950PR/Ascend 950DT）：当前版本 950PR/950DT 产品仅支持配置 NHR 算法。

• NHR_V1：对应历史版本的 NHR 算法，通信步数少（对数复杂度），时延相对较低，适合通信域内 Server 数为非 2 的整数次幂且 pipeline 算法不适用的场景。NHR_V1 算法理论性能低于新版 NHR 算法，该配置项未来会逐步停用，建议开发者使用 NHR 算法。
• NB：非均匀的数据块通信算法（Nonuniform Bruck）。通信步数少（对数复杂度），时延相对较低。适合通信域内 Server 个数较多且 pipeline 算法不适用的场景。
• AHC：层次化集合通信算法（Asymmetric Hierarchical Concatenate）。适用于通信域内 NPU 分布存在多个层次、多个层次间 NPU 对称或者非对称分布（即卡数非对称）的场景，当通信域内层次间存在带宽收敛时相对收益会更好。

  联动语义：当 level1 配置为AHC时，level2（超节点间通信算法）将自动采用AHC算法，无需另行配置，即使 level2 设置了其他算法，这些设置也不会生效。

• pipeline：流水线并行算法，可并发使用 Server 内与 Server 间的链路，适合通信数据量较大且通信域内每机包含多卡的场景。
• pairwise：逐对通信算法，仅用于 AlltoAll、AlltoAllV 与 AlltoAllVC 算子。通信步数较多（线性复杂度），时延相对较高，且需要额外申请内存，内存大小与数据量成正比，但可以避免网络中出现「一打多」现象。适合通信数据量较大、需要规避网络一打多的场景。

不设置 level1 时的默认行为（按产品区分）：

• Ascend 950PR/Ascend 950DT：默认使用 NHR 算法；
• Atlas A3 训练系列产品/Atlas A3 推理系列产品：内部根据产品形态、节点数以及数据量自动选择算法；
• Atlas A2 训练系列产品/Atlas A2 推理系列产品：内部根据产品形态、节点数以及数据量自动选择算法；
• Atlas 训练系列产品：当通信域内 Server 的个数为非 2 的整数次幂时，默认使用 ring 算法；其他场景默认使用 H-D_R 算法。

level2：超节点间通信算法

level2 代表超节点（SuperPod）间的通信算法，支持取值如下：

• ring：通信步数多（线性复杂度），时延相对较高，但通信关系简单，受网络拥塞影响较小。适合通信域内超节点个数较少且不是 2 的整数次幂的场景。
• H-D_R：通信步数少（对数复杂度），时延相对较低，但在非 2 的整数次幂节点规模下会引入额外通信量。适合通信域内超节点个数是 2 的整数次幂的场景，或超节点个数不是 2 的整数次幂但通信数据量较小的场景。
• NHR：通信步数少（对数复杂度），时延相对较低。适合通信域内超节点个数较多的场景。
• NB：通信步数少（对数复杂度），时延相对较低。适合通信域内超节点个数较多的场景。
• pipeline：可并发使用超节点内与超节点间的链路，适合通信数据量较大且通信域内每个超节点包含多卡的场景。

不设置 level2 时的默认行为：当通信域内超节点个数小于 8 且不是 2 的整数次幂时，采用 ring 算法；其他场景采用 H-D_R 算法。

level2 配置的产品适用范围：

• Ascend 950PR/Ascend 950DT：仅支持配置 NHR 算法，仅支持通信算子展开模式为 AI_CPU 的场景；
• Atlas A3 训练系列产品/Atlas A3 推理系列产品：仅支持通信算子展开模式为 AI_CPU 的场景。

通信算子展开模式可通过环境变量 HCCL_OP_EXPANSION_MODE 配置。

每种超节点间通信算法支持的通信算子、数据类型、网络运行模式及确定性计算支持情况，详见 超节点间通信算法支持度列表。

两种配置方式

方式一：全局配置算法类型

全局配置对通信域内所有集合通信算子生效，语法为：

export HCCL_ALGO="level0:NA;level1:<algo>;level2:<algo>"

其中 level1 与 level2 的取值见上文。不设置的层级保持 HCCL 默认的自适应选择行为。

方式二：按算子类型配置算法类型

按算子配置可对不同类型的通信算子分别指定算法，未被指定的算子仍走自适应选择。语法为：

export HCCL_ALGO="<op0>=level0:NA;level1:<algo0>;level2:<algo1>/<op1>=level0:NA;level1:<algo3>;level2:<algo4>"

其中：

• <op>为通信算子的类型，支持如下取值：

  配置名	对应的通信算子
  allgather	AllGather、AllGatherV
  reducescatter	ReduceScatter、ReduceScatterV
  allreduce	AllReduce
  broadcast	Broadcast
  reduce	Reduce
  scatter	Scatter
  alltoall	AlltoAll、AlltoAllV、AlltoAllVC

• <algo>为指定算子采用的通信算法，支持的取值与全局配置中的 level1/level2 取值一致。请确保指定的通信算法为该通信算子支持的算法类型，每种算法支持的通信算子可参见 Server间通信算法支持度列表 与 超节点间通信算法支持度列表；

• 多个算子之间的配置使用/分隔；

• 未指定通信算法的通信算子，会根据产品形态、节点数以及数据量自动选择通信算法。

从源码实现看（alg_env_config.cc 的CheckAlgoConfigValid），全局配置与按算子配置两种方式不能混用：若同时检测到两种配置（配置串中既存在带=的算子级条目又存在不带=的全局条目），HCCL 会直接报错拒绝；全局配置方式下也只允许存在一条配置。

配置示例

示例一：全局配置算法类型

export HCCL_ALGO="level0:NA;level1:NHR"

即 Server 内不干预（NA），Server 间统一使用 NHR 算法。

示例二：按算子配置算法类型

# AllReduce算子使用Ring算法，AllGather算子使用RHD算法，其他算子根据产品形态、节点数以及数据量自动选择通信算法。 export HCCL_ALGO="allreduce=level0:NA;level1:ring/allgather=level0:NA;level1:H-D_R"

源码视角：HCCL_ALGO 的解析与生效机制

HCCL_ALGO在 HCCL 初始化阶段被读取解析，其实现位于 src/common/alg_env_config.cc，核心链路如下：

1. 读取与入口：ParseHcclAlgo()（alg_env_config.cc）通过GetEnv("HCCL_ALGO")读取环境变量，非空时调用SetHcclAlgoConfig()进入解析流程。该入口仅在特定设备类型下生效——从 InitEnvConfig 可以看到，A3 系列（DEV_TYPE_910_93）会走ParseHcclAlgo解析流程，而 A5 系列则明确跳过该解析，改用 costmodel 新流程（日志提示 "A5 uses costmodel flow"）。

2. 预处理与拆分：SetHcclAlgoConfig()（alg_env_config.cc）会先剔除配置串中的所有空格，再通过SplitHcclOpType()以/为分隔符递归拆分出各算子条目，随后调用CheckAlgoConfigValid()校验全局/按算子两种方式是否混用。

3. 解析每个 level：ParseAlgoString()以;拆分 level 条目，ParserHcclAlgoLevel()（alg_env_config.cc）以:拆分出层级名与算法名，并分别对照两张映射表完成字符串到枚举的转换：

   • 层级映射：level0/level1/level2/level3→HCCL_ALGO_LEVEL_0/1/2/3；
   • 算法映射：ring、pipeline、fullmesh、H-D_R、pairwise、NHR、NHR_V1、AHC、AHC_BROKE、NB、NA、null分别映射到 alg_type.h 中定义的HcclAlgoType枚举。

   同时解析器会做严格的合法性校验：层级名或算法名不在映射表中会直接返回HCCL_E_PARA；同一 level 被重复配置也会报错（alg_env_config.cc）。

4. 写入配置表：全局配置通过SetCommonAlgType()将算法向量应用到全部算子类型；按算子配置通过SetSpecificAlgType()（alg_env_config.cc）写入到g_algEnvConfig.hcclAlgoConfig[opType]映射中。值得注意的实现细节：alltoall的算法配置会自动同步到AlltoAllV与AlltoAllVC（源码中HCCL_CMD_ALLTOALLV、HCCL_CMD_ALLTOALLVC直接拷贝HCCL_CMD_ALLTOALL的配置）。

5. 算法选择器消费：算子下发时，AutoSelectorBase::Select()（auto_selector_base.cc）通过GetExternalInputHcclAlgoConfigAllType()拉取整张配置表，再结合执行模式（AICPU/AIV/CCU 等）与拓扑信息交给各算子的自动选择器（如 all_reduce_auto_selector.cc）做最终算法匹配，匹配到的 executor 名称即为最终选定的通信算法。

使用约束与优先级

使用HCCL_ALGO时需注意以下约束：

• level0 仅支持 NA：当前版本 Server 内通信算法仅支持配置为NA；
• 确定性保序场景慎用：针对 Atlas A2 训练系列产品/Atlas A2 推理系列产品，在严格确定性计算的保序场景下，不建议配置HCCL_ALGO环境变量（此时应依赖确定性计算机制内部固定的算法选择）；此外，针对 Atlas A2/A3 等产品，pipeline 算法在开启确定性计算时不会生效（参见 Server间通信算法支持度列表 中 pipeline 算法一节的注意事项）；
• 通信域粒度配置优先：若调用 HCCL C 接口初始化具有特定配置的通信域时，通过HcclCommConfig的hcclAlgo参数指定了通信算法，则以通信域粒度的配置优先于HCCL_ALGO环境变量的全局配置。

产品支持情况

HCCL_ALGO环境变量的产品支持矩阵如下：

配置前请务必对照 Server间通信算法支持度列表 与 超节点间通信算法支持度列表，确认目标产品形态下所选算法与通信算子、数据类型、网络运行模式（单算子模式/图模式 Ascend IR）以及算子展开模式（AI_CPU/CCU_SCHED 等）的匹配关系——例如 Atlas A2/A3 产品下 ring、NHR、H-D_R、NB 等算法所支持的算子集合并不完全相同，AHC 算法仅覆盖 ReduceScatter、AllGather、AllReduce 三类算子，pairwise 算法则仅服务于 AlltoAll 系列算子，这些支持度差异正是HCCL_ALGO配置能否生效的关键前提。

【免费下载链接】hccl集合通信库（Huawei Collective Communication Library，简称HCCL）是基于昇腾AI处理器的高性能集合通信库，为计算集群提供高性能、高可靠的通信方案项目地址: https://gitcode.com/cann/hccl