企业官网建设流程全解析

HCCL_ALG_MULTIPLE_DIMENSION_SPLIT_RATIO：HCCL 两维度并行算法数据切分比例配置与调优指南

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

本文以 HCCL（Huawei Collective Communication Library）环境变量HCCL_ALG_MULTIPLE_DIMENSION_SPLIT_RATIO为核心，讲解两维度并行通信算法（Server 内 Mesh + Server 间 NHR）下两片数据的切分比例语义，并结合 CANN/hccl 开源仓库源码说明该变量的解析流程、优先级规则与调优方法。读完后你可以理解：该变量在 AllReduce/AllGather/ReduceScatter/Broadcast/Reduce 算子中各自代表哪条通信路径的数据占比、它与显式通信域配置的优先级关系，以及如何基于路径耗时差异正确调整取值。

一、功能定位：调整两维度并行算法的负载均衡

HCCL_ALG_MULTIPLE_DIMENSION_SPLIT_RATIO用于配置 AllReduce、AllGather、ReduceScatter、Broadcast、Reduce 算子在特定两维度并行通信算法下的数据切分比例。所谓两维度并行，是指 Server 内通信与 Server 间通信并行执行的场景：

• Server 内通信使用Mesh算法；
• Server 间通信使用NHR算法。

在此场景下，HCCL 会将每轮待通信的数据切分为两片，分别走两条可并行的通信路径：一片数据先执行 Mesh 通信、再执行 NHR 通信（Mesh -> NHR），另一片数据先执行 NHR 通信、再执行 Mesh 通信（NHR -> Mesh）。该环境变量用于调整这两片数据的大小——使耗时较长的通信路径分配较少数据，耗时较短的通信路径分配较多数据，从而改善两条路径的负载均衡。

关键参数信息：

以R表示HCCL_ALG_MULTIPLE_DIMENSION_SPLIT_RATIO的取值，需要注意：

• 该环境变量仅影响HCCL 已经选择两维度并行通信算法时上述五类算子的两片数据分配比例，不用于选择通信算法（算法选择由 HCCL 根据拓扑、数据量等条件自行决定）；
• AllReduce 和 ReduceScatter 算子中，数据片 0、1 的目标切分比例为“R”和“1-R”；AllGather 算子内部使用的切分顺序与 AllReduce、ReduceScatter、Broadcast、Reduce相反，即数据片 0、1 的目标切分比例为“1-R”和“R”；
• 实际切分时会根据数据类型大小、对齐要求和尾块数据量进行取整或对齐处理，因此实际切分比例可能与配置值存在少量偏差；
• 通信域显式配置的切分比例优先于该环境变量。两者均未配置有效比例时，系统尝试按链路端口信息自适应计算比例，无法计算时回退到 0.5；level0 拓扑为MESH_1D_CLOS的场景跳过自适应计算，直接使用 0.5（AICPU 和 CCU 均适用），显式配置的有效比例仍正常生效；
• 若该环境变量配置为非数字格式，系统会在初始化环境变量时返回错误（详见第四节的源码解析）；
• 一般情况下保持默认值 0.5 即可。仅建议在确认当前业务处于跨框、两维度通信场景，且需要针对特定组网、数据量进行性能调优时修改该环境变量。

二、切分语义详解：ReduceScatter 与 AllGather 为什么相反

两维度并行算法使用“数据片 0”和“数据片 1”对应两条通信路径，但 ReduceScatter 与 AllGather 的分片与通信路径的对应关系相反。原因在于两者通信语义相反：ReduceScatter 将完整输入数据规约并分散到各 rank，AllGather 则将各 rank 上的分片数据收集还原为完整输出数据。

具体对应关系：

• ReduceScatter 中，R对应数据片 0，即Mesh -> NHR通信路径；
• AllGather 中，R对应数据片 1，即NHR -> Mesh通信路径。

因此同样设置R=0.6时：ReduceScatter 表示 Mesh -> NHR 通信路径分配约 60% 的数据；AllGather 表示 NHR -> Mesh 通信路径分配约 60% 的数据。

ReduceScatter 算子中，数据片 0 的大小为R，数据片 1 的大小为1-R：

每轮待通信数据 |---------------- 数据片0：R ----------------|------ 数据片1：1-R ------| 并行阶段1： 数据片0：Mesh =============================> 数据片1：NHR =============================> 并行阶段2： 数据片0：NHR =============================> 数据片1：Mesh =============================> 数据片0通信路径：Mesh -> NHR，大小为R 数据片1通信路径：NHR -> Mesh，大小为1-R

若 ReduceScatter 算子中“Mesh -> NHR”通信路径较慢，可调小R；若“NHR -> Mesh”通信路径较慢，可调大R。

AllGather 算子中，数据片 0 的大小为1-R，数据片 1 的大小为R：

每轮待通信数据 |------ 数据片0：1-R ------|---------------- 数据片1：R ----------------| 并行阶段1： 数据片0：Mesh =============================> 数据片1：NHR =============================> 并行阶段2： 数据片0：NHR =============================> 数据片1：Mesh =============================> 数据片0通信路径：Mesh -> NHR，大小为1-R 数据片1通信路径：NHR -> Mesh，大小为R

若 AllGather 算子中“Mesh -> NHR”通信路径较慢，可调大R；若“NHR -> Mesh”通信路径较慢，可调小R。AllReduce、Broadcast、Reduce 与 ReduceScatter 采用相同的对应规则（R对应 Mesh -> NHR 路径）。

这一语义差异在源码中可以得到印证：AllGather 两维度并行执行器 中明确注释“与 ReduceScatter 等算子相反，配置值 multipleDimensionSplitRatio 表示数据片 1 的比例”，而 AllReduce 两维度并行执行器 则按R/1-R的原始方向计算切分。

三、配置示例

export HCCL_ALG_MULTIPLE_DIMENSION_SPLIT_RATIO=0.5

调优时的建议流程：

1. 确认当前业务确实处于跨框（Server 间）两维度通信场景，且 HCCL 已选择两维度并行算法（若选择了其他算法，该变量不生效）；
2. 通过 profiling 等手段观察两条路径（Mesh -> NHR 与 NHR -> Mesh）的实际耗时，判断哪条路径更慢；
3. 按照第二节的对应关系，向“慢路径少分配数据”的方向小幅调整R（例如在 0.3～0.7 之间取值）；
4. 结合 HCCL 性能分析 的完整数据对比验证调整收益，避免盲目设置过大或过小的值导致两片数据负载不均。

四、源码解析：解析流程与错误处理

从源码结构看，该环境变量在通信域初始化阶段被统一解析，核心实现在 alg_env_config.cc：

• ParseMultipleDimensionSplitRatio()通过std::getenv("HCCL_ALG_MULTIPLE_DIMENSION_SPLIT_RATIO")读取环境变量。未设置时仅记录multipleDimensionSplitRatioSet = false，后续走默认比例，不报错；
• 若设置了值，则先经IsValidNumberFormat()（alg_env_config.cc）做严格格式校验：只允许非负数字，含小数点时小数点前必须有整数位、小数部分不能为空。格式非法（如0.5a、-.5）时打印 WARNING 并返回HCCL_E_PARA；
• 格式合法后调用SalStrToDouble()转换为 double，解析失败同样返回HCCL_E_PARA；
• 解析成功后将取值存入线程局部配置g_algEnvConfig（字段定义见 alg_env_config.h），并通过GetExternalInputMultipleDimensionSplitRatio()供算子层读取。

在 InitEnvConfig() 中，该解析失败会绑定错误码EI0001（环境变量配置错误）上报，与文档中“非数字格式会在初始化环境变量时返回错误”的描述一致。这与 环境变量配置错误排查 的处理路径相同：若日志中出现HCCL_ALG_MULTIPLE_DIMENSION_SPLIT_RATIO failed相关错误，说明变量格式非法，需修正为 [0,1] 区间内的合法数字。

五、优先级规则：显式配置 > 环境变量 > 内置公式

算子执行前，HCCL 通过 SetMultipleDimensionSplitRatio() 决定最终使用的比例，源码清晰体现了三级优先级：

1. COMM_CONFIG（通信域显式配置，最高优先级）：通过HcclConfigGetInfo查询通信域上配置的HCCL_CONFIG_TYPE_MULTIPLE_DIMENSION_SPLIT_RATIO（见 QuerySplitRatioByConfigGetInfo()）。查询到的值必须是有限值且位于 [0,1]，否则报HCCL_E_PARA；值为 0 视为“未配置”；
2. ENV_CONFIG（环境变量）：调用GetExternalInputMultipleDimensionSplitRatio()读取环境变量。即使解析阶段通过了格式校验，执行前仍会二次检查取值是否有限且在 [0,1] 内，越界时打印 WARNING 并回退默认值 0.5；
3. BUILTIN_FORMULA（内置公式，兜底）：以上两者均未配置有效值时，使用默认 0.5。对应文档描述的“按链路端口信息自适应计算，无法计算时回退到 0.5；level0 拓扑为 MESH_1D_CLOS 的场景跳过自适应直接使用 0.5”。

每个算子参数都会同时记录比例值和来源（multipleDimensionSplitRatio与multipleDimensionSplitRatioSource，定义见 alg_param.h），执行器据此区分“用户显式配置”和“内置公式”：例如在 AllReduce 并行执行器 中，仅当来源为BUILTIN_FORMULA时才走自适应比例计算分支，显式配置的R则直接按目标切分比例生效。

此外，在 OmniPipe 数据切分计算中，该比例会被转换为路径带宽比来驱动两片数据的实际大小，转换逻辑见 omnipipe_data_slice_calc.cc（bandwidthRatio = (xRankSize - 1) / (1.0 - multipleDimensionSplitRatio)），且注释说明比例仅在 (0,1) 开区间内生效、否则回退原始带宽比（见 omnipipe_data_slice_calc.h）。这也解释了文档中“实际切分比例可能与配置值存在少量偏差”以及边界值需谨慎使用的提示。

六、使用约束与产品支持情况

使用约束：

• 该环境变量仅在 AllReduce、AllGather、ReduceScatter、Broadcast、Reduce 算子选择两维度并行通信算法时生效。若当前拓扑、数据量、数据类型、reduce 类型或算子展开模式选择了其他通信算法，则该环境变量不生效；
• 建议业务结合实际组网和通信数据量进行性能验证后再调整该环境变量。过小或过大的配置可能导致两片数据负载不均，影响通信性能。

产品支持情况（以官方文档标注为准）：

七、小结

HCCL_ALG_MULTIPLE_DIMENSION_SPLIT_RATIO是 HCCL 面向跨框两维度并行通信场景的负载均衡调优参数：它不改变算法选择，只调整“Mesh -> NHR”与“NHR -> Mesh”两条并行路径间的数据分配比例R（取值 [0,1]，默认 0.5）。调整时务必记住 AllGather 与其他算子的切分方向相反；在取值优先级上，通信域显式配置高于该环境变量，二者皆缺省时回退到内置公式/0.5。常规业务保持默认即可，仅在确认处于两维度并行场景且 profiling 数据显示两条路径耗时失衡时，才按“慢路径少分数据”的原则谨慎调优，并通过完整性能数据验证收益。

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