通用环境变量

在提交训练任务时，ACP会自动注入多个通用环境变量，便于您在代码中直接使用。本文为您介绍系统中默认提供的环境变量列表。

系统环境变量说明（不能覆盖）

环境变量	默认值	环境变量说明
ECP_JOB_NAME	Job的name值	后端为 Pod 内部添加任务的name，以便用户后续进行回溯。name为Job的唯一标识，不运行用户

网络环境变量说明

ACP训练平台底层计算资源已开启了RDMA特性，且默认设置了最优NCCL/MCCL变量。您可以根据训练框架、通信框架以及模型特点进行必要的调整。强烈建议您使用平台预置系统内的默认变量，可以获得较优性能。

目前N卡底层适配的是GPU通信源语库NCCL，国产化芯片沐曦C500适配的是GPU通信源语库MCCL。NCCL关键环境变量的说明如下表所示，更多关于NCCL其他环境变量的说明，请参见NCCL链接。

目前商汤在集群建设上面提供了3类高性能网络方案：IB网络、RoCE v2 200G网络和RoCE v2 400G网络。用户在创建训练任务的时候，平台层会默认根据集群的属性注入基础的环境变量，如果用户需要更多细粒度的控制，可以通过环境变量自定义。

具体属于哪种网络方案可以通过AEC2集群属性可以判断，在集群详情页可以查阅到训练网类型。

针对IB网络，平台会默认注入如下环境变量：

环境变量	默认值	环境变量说明
NCCL_IB_TIMEOUT	22	遇到通信延迟或者网络问题时，控制 InfiniBand 网络操作的超时时间（取值范围1-22），可以提升训练任务时的容错性能，若未配置或配置错误，可能会导致训练任务出现中断。建议在大模型训练任务中设置成最大值22，可以减少不少nccl timeout异常。
NCCL_IB_RETRY_CNT	13	变量控制 InfiniBand 的重试次数。建议在大模型训练任务中设置成13，尽可能多重试。
NCCL_IB_AR_THRESHOLD	0	改值设置为0是所有网络流量都会走ar来进行调度。

如果 IB 网络上启用 SHARP 时，需要注入如下俩个环境变量。开启 SHARP 就是利用 IB 网络交换机做“梯度归约计算”，从而加速分布式训练，尤其是在大规模 GPU 集群中效果明显。

另外目前只有Base镜像nvidia24.04-ubuntu22.04-py3.10-cuda12.4-cudnn9.1-torch2.3.0-transformerengine1.5 （该镜像为NV的 PyTorch Release 24.04），以及PyTorch DDP框架下做过相关能力验证测试。

环境变量默认值环境变量说明

NCCL_COLLNET_ENABL

环境变量	默认值	环境变量说明
NCCL_COLLNET_ENABL	1	`CollNet` 是 NCCL 的一种集体通信拓扑结构，相对于传统的 Ring 或 Tree 拓扑，它在多机多卡的 InfiniBand 集群中性能更优。开启后，NCCL 会使用多层拓扑来执行如 `AllReduce` 的操作，优化跨节点通信路径。与 `SHARP`等技术可以配合使用，实现更低延迟和更高带宽。
NCCL_PLUGIN_P2P	ucx	`UCX`（Unified Communication X）是一个高性能通信框架，支持多种网络协议：包括 InfiniBand、RDMA、RoCE、TCP 等； `NCCL_PLUGIN_P2P=ucx` 告诉 NCCL 使用 UCX 来处理 GPU 之间的 point-to-point 通信（如 Send/Recv 或 ring-based AllReduce 中的环形点对点通信）； `UCX` 通常用于支持多种底层网络通信优化，尤其是在 MPI、SHARP、GDR（GPU Direct RDMA）环境中。

CollNet 是 NCCL 的一种 集体通信拓扑结构，相对于传统的 Ring 或 Tree 拓扑，它在 多机多卡的 InfiniBand 集群中性能更优。

开启后，NCCL 会使用多层拓扑来执行如 AllReduce 的操作，优化跨节点通信路径。

与 SHARP等技术可以配合使用，实现更低延迟和更高带宽。

NCCL_PLUGIN_P2P

ucx

UCX（Unified Communication X）是一个高性能通信框架，支持多种网络协议：包括 InfiniBand、RDMA、RoCE、TCP 等；

NCCL_PLUGIN_P2P=ucx 告诉 NCCL 使用 UCX 来处理 GPU 之间的 point-to-point 通信（如 Send/Recv 或 ring-based AllReduce 中的环形点对点通信）；

UCX 通常用于 支持多种底层网络通信优化，尤其是在 MPI、SHARP、GDR（GPU Direct RDMA）环境中。

针对RoCE v2 *200G，网络平台会默认注入如下环境变量：

环境变量	默认值	环境变量说明
NCCL_IB_GID_INDEX	5	指定使用哪一个 GID (Global Identifier) 来建立 InfiniBand 网络连接。在 RoCE（RDMA over Converged Ethernet）配置下，IB 设备可能有多个 GID，每个 GID 对应不同的网络路径（子网、VLAN等）。选择不同的 GID 可能影响到数据包如何路由，尤其是在启用多个子网、VLAN 或 IPv6 环境时。
NCCL_IB_TC	106	设置 InfiniBand 的 Traffic Class (TC)，影响网络通信的服务质量（QoS）。Traffic Class 是 RoCEv2 协议中的一个字段（RoCEv1没有），用于决定数据包的优先级。设置合理的 `NCCL_IB_TC`值可以避免网络拥塞或提高通信吞吐量。

针对RoCE v2 *400G，网络平台会默认注入如下环境变量：

环境变量	默认值	环境变量说明
NCCL_IB_GID_INDEX	5	指定使用哪一个 GID (Global Identifier) 来建立 InfiniBand 网络连接。在 RoCE（RDMA over Converged Ethernet）配置下，IB 设备可能有多个 GID，每个 GID 对应不同的网络路径（子网、VLAN等）。选择不同的 GID 可能影响到数据包如何路由，尤其是在启用多个子网、VLAN 或 IPv6 环境时。
NCCL_IB_TC	138	设置 InfiniBand 的 Traffic Class (TC)，影响网络通信的服务质量（QoS）。Traffic Class 是 RoCEv2 协议中的一个字段（RoCEv1没有），用于决定数据包的优先级。设置合理的 NCCL_IB_TC 值可以避免网络拥塞或提高通信吞吐量。
NCCL_IB_QPS_PER_CONNECTION	8	指定每个NCCL peer-to-peer 连接要创建多少个 Queue Pairs（QP）。控制每个通信连接上创建的 QP 数量（Queue Pairs），以提升带宽或优化并发。
OMPI_MCA_btl_tcp_if_include	eth0	训练任务使用MPI框架，需要注入这个变量。这个变量是 OpenMPI 中的一个环境变量，用于显式指定 TCP BTL（Byte Transfer Layer）使用的网络接口。

补充说明：

如果通过nccl-test做集群网络的基线测试，可以设置NCCL_MIN_NCHANNELS=32，可以大幅度提高测试结果，这个参数用于优化 NCCL 通信并发度的环境变量设置，控制 NCCL 内部用于并发通信的数据通道（channel）的 最小数量。不过在实际训练过程中，通信用的资源多，计算可用资源就会变少，用户要根据实际情况做调整。

MCCL关键环境变量的说明如下表所示。

环境变量	默认值	环境变量说明
MCCL_P2P_LEVEL	SYS	指定MCCL使用P2P传输的gpu之间的最大距离是，通信的gpu属于同一NUMA。
MCCL_NET_GDR_LEVEL	SYS	指定MCCL使用GDR传输的gpu与网卡之间的最大距离是，gpu与网卡属于同一NUMA。
MCCL_CROSS_NIC	1	允许ring/trees使用不同的网卡通信，节点间通信在不同节点上使用不同的网卡。
FORCE_ACTIVE_WAIT	1	指定UMD中Host侧等待事件或流之间同步的CPU行为，进程抢占CPU进行等待相对温和。
MCCL_LIMIT_RING_LL_THREADTHRESHOLDS	1	对Ring算法LL协议使用场景做限制。