企业官网建设流程全解析

HCCL 功能相关环境变量全解析：超时控制、算法选择、链路配置与确定性计算实战指南

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

导读

本文基于 CANN/hccl 开源仓库的官方环境变量参考文档（功能相关），系统讲解 HCCL（华为集合通信库）中与通信功能直接相关的 10 个核心环境变量，覆盖通信超时控制、算法与通信链路选择、算子执行模式、确定性计算、缓存区管理与超节点逻辑划分六大功能域。读完本文，你将掌握每个环境变量的取值范围、默认值、配置语法、产品支持差异，并能结合源码理解其在 alg_env_config.cc 中的解析逻辑，在实际分布式训练/推理场景中精准调优。

一、总览：10 个功能相关环境变量一览

上述变量全部在初始化阶段由 alg_env_config.cc 统一读取与解析（核心入口为GetEnv与InitEnvVarParam），下文逐一深入。

二、通信超时控制：HCCL_CONNECT_TIMEOUT 与 HCCL_EXEC_TIMEOUT

2.1 HCCL_CONNECT_TIMEOUT：限制设备间建链超时

功能：分布式训练或推理场景下，不同设备进程在集合通信初始化之前可能因其他因素（如加载权重、准备数据）导致执行不同步。该变量控制设备间 socket 建链的超时等待时间——在配置的时间内，各设备进程等待其他设备建链同步。

关键参数：

• 类型：整数；取值范围 [120, 7200]，默认值 120，单位 s。
• 重要细节：实际建链超时等待时间 = 环境变量值 + 20 秒。例如设置为 150，则实际超时为 170 秒。额外 20 秒用于通知各节点通信域初始化失败的原因，因此该变量的值会直接影响链路故障场景的异常上报时间。

配置示例：

export HCCL_CONNECT_TIMEOUT=200

产品支持：Ascend 950PR/Ascend 950DT、Atlas A3、Atlas A2、Atlas 训练系列、Atlas 推理系列均支持。

2.2 HCCL_EXEC_TIMEOUT：控制设备间执行同步等待

功能：分布式训练/推理过程中，不同设备进程存在卡间执行任务不一致的场景（如仅特定进程保存 checkpoint）。该变量控制设备间执行时同步等待的时间，在配置时间内各设备进程等待其他设备执行通信同步。默认值 1836（单位 s），一般保持默认即可，当默认值无法满足同步需求时可适当调大。

按产品与展开模式的取值差异（展开模式参见 HCCL_OP_EXPANSION_MODE）：

关键细节 1——AIV 模式的时间对齐机制：AIV 模式下实际生效的超时时间为 interval×N×10⁻³ 毫秒，其中 interval 为硬件支持的算子超时最短时间间隔（单位 us，可通过aclrtGetOpTimeoutInterval接口获取），N 为 [1, 254] 范围内整数。如果配置的超时时间不等于 interval×N×10⁻³ 毫秒，则向上对齐至该值。

关键细节 2——Atlas 训练/推理系列的整除规则：系统实际设置的超时时间 = 环境变量取值先整除 68、再乘以 68（单位 s）；取值小于 68 时按 68s 处理。例如HCCL_EXEC_TIMEOUT=600，实际生效为 600÷68=8（整除），8×68=544s。

配置示例：

export HCCL_EXEC_TIMEOUT=1800

使用约束：若通过 C 接口HcclCommConfig的hcclExecTimeOut参数配置了通信域粒度的执行同步等待时间，则以通信域粒度配置为准。

三、通信算法选择：HCCL_ALGO

3.1 功能定位与自适应算法

该变量用于配置集合通信Server 间通信算法以及超节点间通信算法，支持全局配置与按算子配置两种方式。HCCL 默认提供自适应算法选择功能，会根据产品形态、数据量和 Server 个数自动选择合适的算法，一般情况下无需手工指定；一旦通过该变量显式指定算法，自适应选择不再生效。

注意：某些通信算子在特定类型 AI 处理器且数据量较小时，算法仍由 HCCL 自适应选择，不受该变量控制。各产品支持的具体算法可参见 Server间通信算法支持度列表 与 超节点间通信算法支持度列表。

从源码看，alg_env_config.cc 维护了层级与算法类型的映射表，支持level0/level1/level2/level3四个层级以及ring、pipeline、fullmesh、H-D_R、pairwise、NHR、NHR_V1、AHC、AHC_BROKE、NB、NA、null等算法类型字符串，解析结果存入g_algEnvConfig.hcclAlgoConfig[opType]，按算子类型（HcclCMDType）粒度生效。

3.2 全局配置算法类型

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

• level0：Server 内通信算法，当前仅支持配置为NA。
• level1：Server 间通信算法，取值与适用场景如下：

不设置 level1 时的默认行为：

• Ascend 950PR/950DT：默认使用 NHR 算法；

• Atlas A3 训练/推理系列：内部根据产品形态、节点数及数据量自动选择；

• Atlas A2 训练/推理系列：内部自动选择；

• Atlas 训练系列：通信域内 Server 个数非 2 的整数次幂时默认 ring，其他场景默认 H-D_R。

• level2：超节点间通信算法，取值包括ring、H-D_R、NHR、NB、pipeline，含义与 level1 同名算法类似。不设置 level2 时：超节点个数小于 8 且非 2 的整数次幂采用 ring，其他场景采用 H-D_R。level2 配置当前仅适用于：

  • Ascend 950PR/950DT：仅支持 NHR，且仅支持算子展开模式为 AI_CPU；
  • Atlas A3 训练/推理系列：仅支持算子展开模式为 AI_CPU。

3.3 按算子类型配置通信算法

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 取值，需确保为算子支持的算法类型；未指定算法的算子仍由系统自动选择。
• 多个算子配置之间用/分隔。从源码看，alg_env_config.cc 按HcclCMDType将各算子配置写入hcclAlgoConfig，其中 AlltoAllV、AlltoAllVC 会继承 AlltoAll 的配置。

3.4 配置示例与使用约束

# 全局配置：Server 间使用 NHR export HCCL_ALGO="level0:NA;level1:NHR" # 按算子配置：AllReduce 用 ring，AllGather 用 H-D_R，其余算子自适应 export HCCL_ALGO="allreduce=level0:NA;level1:ring/allgather=level0:NA;level1:H-D_R"

使用约束：

• Server 内算法仅支持NA；
• Atlas A2 训练/推理系列在严格确定性计算的保序场景下不建议配置该变量；
• 若通过 C 接口HcclCommConfig的hcclAlgo参数指定了通信域粒度算法，则通信域粒度配置优先。

产品支持：Ascend 950PR/950DT、Atlas A3、Atlas A2、Atlas 训练系列支持；Atlas 推理系列不支持。

四、通信链路选择：HCCL_INTRA_PCIE_ENABLE、HCCL_INTRA_ROCE_ENABLE 与 HCCL_INTER_HCCS_DISABLE

4.1 Server 内链路：PCIe 与 RoCE 的组合控制

HCCL_INTRA_PCIE_ENABLE用于配置 Server 内是否使用 PCIe 链路通信（默认 1）；HCCL_INTRA_ROCE_ENABLE用于配置 Server 内（Atlas 训练/A2 系列）或超节点内（A3 系列 + LLM-DataDist 场景）是否使用 RoCE 链路通信（默认 0）。两者可单独或同时配置，组合规则如下：

不支持的组合（源码中会校验并报错，见 alg_env_config.cc 的"0 or 1 (but not both 1)"约束）：

• 两者同时配置为 1；
• HCCL_INTRA_PCIE_ENABLE=0且HCCL_INTRA_ROCE_ENABLE不配置；
• HCCL_INTRA_PCIE_ENABLE不配置且HCCL_INTRA_ROCE_ENABLE=0。

配置示例：

export HCCL_INTRA_PCIE_ENABLE=1 export HCCL_INTRA_ROCE_ENABLE=1

A3 系列的特别语义：仅在使用 LLM-DataDist 作为集群管理组件时生效，用于配置超节点内是否使用 RoCE 链路。0：超节点内采用默认 HCCS/PCIe 链路（LLM-DataDist 与 HCCL 通信均受影响）；1：针对 Atlas 800T A3 超节点、Atlas 800I A3 超节点与 Atlas 900 A3 SuperPoD 超节点，超节点内 LLM-DataDist 通信采用 RoCE 而 HCCL 通信不受影响；针对 A200T A3 Box8 超节点，LLM-DataDist 与 HCCL 通信都采用 RoCE。

使用约束（Atlas 200T A2 Box16 异构子框）：该产品存在左右两个模组（0~7 卡与 8~15 卡）。单机场景下，若 Server 内采用 PCIe 链路通信且需同时使用两个模组的卡，两个模组必须使用相同卡数且在同一平面（即 0 卡与 8 卡、1 卡与 9 卡以此类推同时使用）；采用 RoCE 链路通信时无此限制。

产品支持：Ascend 950PR/950DT、Atlas A3（仅 LLM-DataDist 场景生效）、Atlas 推理系列不支持；Atlas A2 系列仅支持 Atlas 200T A2 Box16 异构子框；Atlas 训练系列仅支持 Atlas 300T Pro 训练卡。

4.2 超节点内链路：HCCL_INTER_HCCS_DISABLE

该变量用于配置超节点模式组网中超节点内的通信链路类型，默认FALSE：

• TRUE：超节点内 AI 节点间使用RoCE 进行 RDMA 通信；
• FALSE：超节点内 AI 节点间使用HCCS 通信链路进行 SDMA 通信。

export HCCL_INTER_HCCS_DISABLE=FALSE

源码中 alg_env_config.cc 仅在 A3 设备上解析该变量，并校验取值必须为true或false。产品支持上仅 Atlas A3 训练/推理系列支持，其余产品不支持。

五、算子执行（展开）模式：HCCL_OP_EXPANSION_MODE

5.1 功能与按产品取值

该变量配置通信算子的展开模式（即算子在何种计算单元上展开、由谁调度执行）。不同产品支持的取值差异较大，汇总如下：

Ascend 950PR/950DT（设置不支持的值会报错）：

• AI_CPU：算子在 AI CPU 展开，Device 侧按硬件型号自动选择调度器。支持 Broadcast、Reduce、AllReduce、Scatter、ReduceScatter、ReduceScatterV、AllGather、AllGatherV、AlltoAll、AlltoAllV、AlltoAllVC、Send、Recv、BatchSendRecv。该配置将在后续版本废弃，由 AICPU_TS 替代（当前功能完全一致）。
• AICPU_TS（默认值）：算子在 AI CPU 展开，使用STARS 调度器调度运行，支持算子同 AI_CPU。
• AICPU_CacheDisable：关闭 HCCL 算子的 AI CPU cache 特性。AI CPU cache 指同一通信算子第二次执行时复用首次执行结果以节省展开开销，但会带来显存开销；在通信数据量频繁变化的服务场景建议关闭 cache 以减小显存开销。
• AIV：算子在 Vector Core 展开并执行。仅支持对称组网、推理特性；不支持多通信域并行；仅支持 Broadcast、Reduce、AllReduce、ReduceScatter、Scatter、AllGather、AlltoAll、AlltoAllV、AlltoAllVC、Send、Recv（其中 Reduce/AllReduce/ReduceScatter 数据类型支持 int8/int16/int32/int64/float16/float32/bfp16）；支持控核能力。
• CCU_MS：算子在 CCU 展开，使用 CcuBuffer 进行内存读写（Ascend 950PR 不支持）。CCU 与多个远端通信时以 CcuBuffer 作为中转，节省内存读写带宽；CCU 资源不足时自动切换为 AI_CPU；仅支持 Broadcast、Reduce、AllReduce、ReduceScatter、AllGather，仅支持单机场景。
• CCU_SCHED：算子在 CCU 展开，使用调度模式——CCU 作为调度器向 UB 引擎调度 UB WQE 任务，不使用 CcuBuffer，直接在两个 rank 间进行片上内存到片上内存的数据传输。单机 AllReduce/ReduceScatter/Reduce 数据量超阈值时自动切换 AI_CPU；ReduceScatterV、AllGatherV 仅支持单 Server；CCU 资源不足时自动切换 AI_CPU。

Atlas A3 训练/推理系列（设置不支持的值时使用默认值）：

• AI_CPU（默认值）：超节点内与超节点间支持全量通信算子；Reduce、ReduceScatter、ReduceScatterV、AllReduce 数据类型仅支持 int8/int16/int32/float16/float32/bfp16，reduce 操作仅支持 sum/max/min。
• AICPU_CacheDisable：关闭 AI CPU cache 特性（同前）。
• AIV：Vector Core 展开。仅支持对称组网、推理特性；不支持多通信域并行；仅支持 Broadcast、AllReduce、ReduceScatter、AllGather、AlltoAll、AlltoAllV、AlltoAllVC（各类算子有具体数据类型与超节点内单机/多机限制，均不支持跨超节点通信）；Broadcast/AllReduce/ReduceScatter/AllGather/AlltoAll（单机）数据量超阈值时自动切换 AI_CPU，AlltoAllV/AlltoAllVC/AlltoAll（多机）不会自动切换，建议任意两个 rank 最大通信数据量不超过 1MB 时使用 AIV；支持控核能力（Broadcast 建议至少 ranksize 个 vector 核；AllGather、非确定性 ReduceScatter 建议最少 max(2, ceil(ranksize/20)) 个核；AllReduce、确定性 ReduceScatter、AlltoAll 系列建议 max(2, ceil(ranksize/20)) 且为偶数）。

Atlas A2 训练/推理系列：

• HOST（默认值）：算子在 Host 侧 CPU 展开，Device 侧自动选择调度器。
• HOST_TS：算子在 Host 侧 CPU 展开，Host 向 Device 的 Task Scheduler 下发任务，由 Device 调度执行。
• AI_CPU：算子在 AI CPU 展开，仅支持 AllGather、AlltoAll、AlltoAllV、AlltoAllVC。
• AIV：Vector Core 展开，仅支持对称组网、推理特性；不支持多通信域并行；仅支持 Broadcast、AllReduce、AlltoAll、AlltoAllV、AlltoAllVC、AllGather、ReduceScatter、AllGatherV、ReduceScatterV（各算子有数据类型与单机/单算子模式等限制，如 Broadcast 仅支持单机 8 卡以内的单算子模式，AlltoAllV/AlltoAllVC 仅支持单机场景）；控核建议：AllReduce/ReduceScatter/ReduceScatterV 最少 24 核，Broadcast/AlltoAll 系列/AllGather/AllGatherV 最少 16 核。

Atlas 300I Duo 推理卡：

• HOST（默认值）：Host 侧 CPU 展开。
• AI_CPU：仅支持单机单通信域场景；仅支持 AllReduce；配置后通信算子不再支持 profiling 性能数据采集；静态 shape 图不支持此配置。

通用注意事项：

• 图模式（Ascend IR）或图捕获（aclgraph）场景下，AI CPU 模式单卡并发图数量不能超过 6 个，否则可能因 AI CPU 核被占满导致通信阻塞；
• A3 系列 AI_CPU 模式依赖开放 AI CPU 用户态下发调度任务，存在一定安全风险，需确保自定义算子安全可靠；
• A2/A3 系列：展开位置为 AIV 时若同时设置 HCCL_DETERMINISTIC 为 true/strict，确定性计算优先级更高，某些场景 AIV 展开可能不生效；
• A2 系列推理特性配置 AIV 时，若以 CTRL+C 强制结束进程，Device 侧日志可能出现 devmm/tsdrv 相关的非法地址错误（关键词devmm_page_fault_d2h_query_flag、devmm_svm_device_fault、ipc_fault_msg_para_check），此类错误不影响卡状态与后续任务。

配置示例：

export HCCL_OP_EXPANSION_MODE="AI_CPU"

使用约束：通过 C 接口HcclCommConfig的hcclOpExpansionMode参数配置时，以通信域粒度配置优先。

六、确定性计算：HCCL_DETERMINISTIC

6.1 功能与取值

该变量控制归约类通信算子（AllReduce、ReduceScatter、ReduceScatterV、Reduce）的确定性计算或保序功能。开启后，算子在相同的硬件和输入下多次执行将产生相同输出。支持三个取值：

• false（默认值）：关闭确定性计算。产品差异：Ascend 950PR/950DT 所有归约类算子强制确定性计算，不受此配置影响；Atlas A3 若展开模式为 AI CPU 则强制确定性计算，Vector Core 下仅 AllReduce/ReduceScatter 涉及非确定性计算（默认关闭）；Atlas A2 所有归约类算子默认关闭。
• true：开启确定性计算。Ascend 950PR/950DT 强制且不受配置影响；A3 仅在 Vector Core 展开模式下对 AllReduce/ReduceScatter 生效（AI CPU 下本就强制）；A2 支持 AllReduce、ReduceScatter、ReduceScatterV、Reduce。
• strict：开启严格确定性计算（保序），在确定性基础上保证所有 bit 位的归约顺序一致。需满足：仅支持 INF/NaN 模式、不支持饱和模式；相较确定性计算有一定性能下降，建议推理场景使用。产品差异：
  • Ascend 950PR/950DT：支持 AllReduce、ReduceScatter；rank size ≥ 3；仅支持展开模式为 AI_CPU，其他展开模式（CCU_MS、CCU_SCHED、AIV）配置保序会回退到 AI_CPU。
  • Atlas A3：仅支持多机对称分布场景（不支持卡数非对称）；支持 AllReduce、ReduceScatter，数据类型 float16/float32/bfp16，归约操作仅支持 sum；rank size ≥ 3；超节点内多个 AI Server 时仅支持 HCCS-SDMA 通信，不支持将 HCCL_INTER_HCCS_DISABLE 设置为 TRUE。
  • Atlas A2：仅支持多机对称分布场景；支持 AllReduce、ReduceScatter、ReduceScatterV。

源码中 alg_env_config.cc 对取值做大小写归一化后校验，仅接受STRICT、TRUE、FALSE，非法值会报错提示。

6.2 使用建议

一般情况下无需开启确定性计算。当模型多次执行结果不同或需精度调优时，可通过该变量开启辅助调试，但开启后算子执行时间变慢、性能下降。若同时设置了展开模式为 AIV，则确定性计算优先级更高（某些场景 AIV 展开可能不生效）。

export HCCL_DETERMINISTIC=true

使用约束：通过 C 接口HcclCommConfig的hcclDeterministic参数配置时，以通信域粒度配置优先。产品支持：Ascend 950PR/950DT、Atlas A3、Atlas A2 支持；Atlas 训练/推理系列不支持。

七、缓存区与超节点逻辑划分：HCCL_BUFFSIZE 与 HCCL_LOGIC_SUPERPOD_ID

7.1 HCCL_BUFFSIZE：控制通信域共享数据缓存区

该变量控制通信域使用的共享数据缓存区大小，需配置为整数，取值 ≥ 1，默认 200，单位 MB。

关键机制：

• 每个通信域实际占用2 × HCCL_BUFFSIZE大小的内存，分别用于收发内存；
• 该资源按通信域粒度管理，每个通信域独占一组2 × HCCL_BUFFSIZE内存，保证多通信域并发算子互不影响；
• 申请的内存为 HCCL 独占，不可与其他业务内存复用；
• 集群中通信域较多时整体缓存占用增加，可能影响模型数据存储，此时可调小该值；业务模型数据量小但通信数据量大时可调大以提升通信效率；
• 当数据量超过 HCCL_BUFFSIZE 取值时可能出现性能下降，建议取值大于数据量。

大语言模型场景建议配置值：

(MicrobatchSize × SequenceLength × hiddenSize × sizeof(DataType)) / (1024×1024)，向上取整

典型适用场景：动态 shape 网络；开发人员调用 HCCL C 接口进行框架对接。

export HCCL_BUFFSIZE=200

使用约束：通过 C 接口HcclCommConfig的hcclBufferSize参数配置时，以通信域粒度配置优先。所有列示产品均支持。

7.2 HCCL_LOGIC_SUPERPOD_ID：物理超节点划分逻辑超节点

针对 Atlas A3 训练/推理系列的超节点模式组网，若不使用 rank table 文件配置集群资源信息，可通过该变量指定当前节点运行进程所属的超节点 ID，实现将一个物理超节点划分为多个逻辑超节点的功能。

• 类型：string，长度需小于 128 个字符，默认值为空字符串；
• 若不配置，会获取环境中 "Super Pod ID" 的值作为超节点 ID，可通过npu-smi info -t spod-info -i <id> -c <chip_id>命令查看；
• 使用约束：仅适用于未使用 rank table 文件的场景（若使用则优先 rank table 配置）；仅支持将物理超节点划分为多个逻辑超节点，不支持将归属于不同物理超节点的 rank 配置到同一逻辑超节点内。

export HCCL_LOGIC_SUPERPOD_ID=super_pod_id_1

产品支持：仅 Atlas A3 训练/推理系列支持，其余产品不支持。

八、通信域粒度配置的优先级规则

多个功能相关环境变量均支持通过 HCCL C 接口在通信域粒度覆盖全局环境变量，汇总如下：

规则：若通过 C 接口初始化具有特定配置的通信域时指定了上述参数，则以通信域粒度配置优先。这一设计与源码中g_algEnvConfig（src/common/alg_env_config.h）保存全局配置、通信域初始化时再叠加域级配置的实现一致。

九、底层实现佐证

所有功能相关环境变量在通信域初始化阶段由 alg_env_config.cc 统一解析：

• GetEnv（alg_env_config.cc）为读取入口，未设置的环境变量返回"EmptyString"，调用方据此区分"未配置"与"显式配置"；
• 校验不合法取值时会打印告警/错误日志并回退默认值或直接报错，例如HCCL_EXEC_TIMEOUT的格式非法、数值过大都会触发HCCL_WARNING（见 alg_env_config.cc）；
• HCCL_ALGO的解析通过SetHcclAlgoConfig与hcclAlgoLevelMap/hcclAlgoTypeMap两张映射表完成（alg_env_config.cc），并支持 AlltoAllV/AlltoAllVC 继承 AlltoAll 配置（alg_env_config.cc）；
• HCCL_INTRA_PCIE_ENABLE与HCCL_INTRA_ROCE_ENABLE在 A5（Ascend 950）上不解析不打印（alg_env_config.cc），HCCL_INTER_HCCS_DISABLE仅在 A3 设备解析（alg_env_config.cc），与文档中的产品支持矩阵一一对应；
• HCCL_DETERMINISTIC取值做大小写归一化后仅接受 STRICT/TRUE/FALSE（alg_env_config.cc）。

十、总结：典型调优场景速查

如需进一步了解性能、网络、调试、可靠性、安全相关的其余环境变量，可参见 环境变量参考 的总览索引。

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