跳到主要内容

环境变量

MCCL 提供了一套广泛的环境变量，用于特定用途的调整。

环境变量也可以在 /etc/mccl.conf 中静态设置（由管理员设置系统范围的值）或在 ${MCCL_CONF_FILE} 中设置。例如，这些文件可能包含：

MCCL_DEBUG=WARN
MCCL_SOCKET_IFNAME=ens1f0

环境变量分为两类。有些变量需要使 MCCL 遵循系统特定的配置，并且可以保留在脚本和系统配置中。"调试" 部分中列出的其他参数在生产环境中不应使用。

系统配置​

MCCL_SOCKET_IFNAME​

MCCL_SOCKET_IFNAME 变量指定用于通信的 IP 接口。

接受的值​

定义为要由 MCCL 使用的接口的前缀列表。

可以提供多个前缀，用 , 符号分隔。

使用 ^ 符号，MCCL 将排除以该列表中任何前缀开头的接口。

要匹配（或不匹配）确切的接口名称，请以前缀字符串以 = 字符开头。

示例：

  • eth：使用所有以 eth 开头的接口，例如 eth0、eth1...
  • =eth0：仅使用接口 eth0
  • =eth0,eth1：仅使用接口 eth0 和 eth1
  • ^docker：不使用任何以 docker 开头的接口
  • ^=docker0：不使用接口 docker0

注意：默认情况下，回环接口（lo）和 docker 接口（docker*）除非没有其他接口可用，否则不会被选中。

MCCL_SOCKET_FAMILY​

MCCL_SOCKET_FAMILY 变量允许用户强制 MCCL 仅使用 IPv4 或 IPv6 接口。

接受的值​

设置为 AF_INET 以强制使用 IPv4，或 AF_INET6 以强制使用 IPv6。

MCCL_SOCKET_NTHREADS​

MCCL_SOCKET_NTHREADS 变量指定每个网络连接使用的 CPU 辅助线程数。增加此值可能会提高套接字传输性能，但代价是更高的 CPU 使用率。

接受的值​

1 到 16。默认情况下自动选择；若无法识别网络设备类型，则不启动额外辅助线程。

对于通用的 100G 网络，此值可以手动设置为 4。然而，MCCL_SOCKET_NTHREADS 和 MCCL_NSOCKS_PERTHREAD 的乘积不能超过 64。另见 MCCL_NSOCKS_PERTHREAD。

MCCL_NSOCKS_PERTHREAD​

MCCL_NSOCKS_PERTHREAD 变量指定每个套接字传输辅助线程打开的套接字数。在每个套接字速度受限的环境中，将此变量设置为大于 1 可能会提高网络性能。

接受的值​

默认情况下自动选择；若无法识别网络设备类型，则默认值为 1。

对于通用的 100G 网络，此值可以手动设置为 4。然而，MCCL_SOCKET_NTHREADS 和 MCCL_NSOCKS_PERTHREAD 的乘积不能超过 64。另见 MCCL_SOCKET_NTHREADS。

MCCL_CROSS_NIC​

MCCL_CROSS_NIC 变量控制 MCCL 是否允许环/树使用不同的 NIC，导致不同节点之间的通信在不同节点上使用不同的 NIC。

为了在使用多个 NIC 时最大化节点间通信性能，MCCL 尝试在节点间通信时使用相同的 NIC，以允许每个 NIC 连接到不同网络交换机（网络轨道）的网络设计，并避免任何流量干扰风险。因此，MCCL_CROSS_NIC 设置取决于网络拓扑，特别是网络结构是否经过轨道优化。

这对只有一个 NIC 的系统没有影响。

接受的值​

0：始终使用相同的 NIC 进行相同的环/树，以避免交叉网络轨道。适用于每个 NIC 连接到不同交换机（轨道）的网络，且跨轨道连接速度较慢。请注意，如果通信器在每个节点上不包含相同的 GPU，则 MCCL 可能仍需要跨 NIC 通信。

1：允许为相同的环/树使用不同的 NIC。这适用于所有 NIC 都连接到同一交换机的网络，因此尝试通过相同的 NIC 通信无助于避免流量冲突。

2：（默认）尝试为相同的环/树使用相同的 NIC，但如果使用不同的 NIC 可以带来更好的性能，则仍允许使用不同的 NIC。

MCCL_IB_HCA​

MCCL_IB_HCA 变量指定用于通信的主机通道适配器（RDMA）接口。

接受的值​

定义为过滤要由 MCCL 使用的 IB Verbs 接口。列表以逗号分隔；可以使用 : 符号指定端口号。可选前缀 ^ 表示列表是排除列表。第二个可选前缀 = 表示令牌是确切名称，否则 MCCL 默认将每个令牌视为前缀。

示例：

mlx5：使用所有以 mlx5 开头的卡的所有端口

=mlx5_0:1,mlx5_1:1：使用卡 mlx5_0 和 mlx5_1 的端口 1

^=mlx5_1,mlx5_4：不使用卡 mlx5_1 和 mlx5_4。

注意：使用 mlx5_1 而不带前导 = 将选择 mlx5_1 以及 mlx5_10 到 mlx5_19（如果存在）。因此，始终建议添加 = 前缀以确保精确匹配。

注意：MCCL 支持的主机通道适配器（HCA）设备有固定的上限，为 32 个。

MCCL_IB_TIMEOUT​

MCCL_IB_TIMEOUT 变量控制 InfiniBand Verbs 超时。

超时计算为 4.096 µs * 2 ^ timeout，正确的值取决于网络的大小。增加该值可以帮助非常大的网络，例如，如果 MCCL 在调用 ibv_poll_cq 时出现错误 12。

有关更多信息，请参见 InfiniBand 规范。

接受的值​

MCCL 使用的默认值为 14。

值可以是 1-31。

注意：将值设置为 0 或 >= 32 将导致无限超时值。

MCCL_IB_RETRY_CNT​

MCCL_IB_RETRY_CNT 变量控制 InfiniBand 重试计数。

有关更多信息，请参见 InfiniBand 规范。

接受的值​

默认值为 7。

MCCL_IB_GID_INDEX​

MCCL_IB_GID_INDEX 变量定义在 RoCE 模式中使用的全局 ID 索引。请参见 InfiniBand show_gids 命令以设置此值。

有关更多信息，请参见 InfiniBand 规范第一卷或供应商文档。

接受的值​

默认值为 0。

MCCL_IB_SL​

定义 InfiniBand 服务级别。

有关更多信息，请参见 InfiniBand 规范第一卷或供应商文档。

接受的值​

默认值为 0。

MCCL_IB_TC​

定义 InfiniBand 流量类别字段。

有关更多信息，请参见 InfiniBand 规范第一卷或供应商文档。

接受的值​

默认值为 0。

MCCL_NET​

强制 MCCL 使用特定网络，例如确保 MCCL 使用外部插件，并且不会自动回退到内部 IB 或套接字实现。如果没有设置（未定义），MCCL 将自动选择最佳网络模块。

接受的值​

MCCL_NET 的值必须与使用的 MCCL 网络的名称完全匹配（不区分大小写）。内部网络名称为 "IB"（通用 IB Verbs）和 "Socket"（TCP/IP 套接字）。外部网络插件定义自己的名称。默认值未定义。

MCCL_NET_PLUGIN​

将其设置为后缀字符串或库名称，以在多个 MCCL 网络插件中进行选择。此设置将导致 MCCL 使用以下策略查找网络插件库：

  • 如果设置了 MCCL_NET_PLUGIN，则尝试加载由 MCCL_NET_PLUGIN 指定名称的库；
  • 如果设置了 MCCL_NET_PLUGIN 并且之前的失败，则尝试加载 libmccl-net-<MCCL_NET_PLUGIN>.so；
  • 如果未设置 MCCL_NET_PLUGIN，则尝试加载 libmccl-net.so；
  • 如果没有找到插件（无论是用户定义的还是默认的），则使用内部网络插件。

例如，设置 MCCL_NET_PLUGIN=foo 将导致 MCCL 尝试加载 foo，如果 foo 找不到，则加载 libmccl-net-foo.so（前提是系统上存在）。

接受的值​

插件后缀、插件文件名或 "none"。

MCCL_IGNORE_CPU_AFFINITY​

MCCL_IGNORE_CPU_AFFINITY 变量可用于使 MCCL 忽略作业提供的 CPU 亲和性，而只使用 GPU 亲和性。

接受的值​

默认为 0，设置为 1 以使 MCCL 忽略作业提供的 CPU 亲和性。

MCCL_DEBUG​

MCCL_DEBUG 变量控制从 MCCL 显示的调试信息。这个变量通常用于调试。

接受的值​

VERSION - 在程序开始时打印 MCCL 版本。

WARN - 每当任何 MCCL 调用出错时，打印明确的 error 消息。

INFO - 打印调试信息

TRACE - 打印可重放的跟踪信息，每次调用都会打印。

MCCL_DEBUG_FILE​

MCCL_DEBUG_FILE 变量将 MCCL 调试日志输出定向到文件。文件名格式可以设置为 filename.%h.%p，其中 %h 被替换为主机名，%p 被替换为进程 PID。这不接受路径中的 ~ 字符；请先转换为相对路径或绝对路径。

接受的值​

默认输出文件是 stdout，除非设置了此环境变量。

设置 MCCL_DEBUG_FILE 将导致 MCCL 创建并覆盖任何同名的先前文件。

注意：如果文件名在所有作业进程中不唯一，则输出可能会丢失或损坏。

MCCL_DEBUG_SUBSYS​

MCCL_DEBUG_SUBSYS 变量允许用户根据子系统过滤 MCCL_DEBUG=INFO 输出。值应为要包含在 MCCL 调试日志跟踪中的子系统的逗号分隔列表。

在子系统名称前加上 ^ 将禁用该子系统的日志记录。

接受的值​

默认值为 INIT,BOOTSTRAP,ENV。

支持的子系统名称有 INIT（代表初始化）、COLL（代表集体操作）、P2P（代表点对点）、SHM（代表共享内存）、NET（代表网络）、GRAPH（代表拓扑检测和图搜索）、TUNING（代表算法/协议调整）、ENV（代表环境设置）、ALLOC（代表内存分配）和 ALL（包括每个子系统）。

MCCL_COLLNET_ENABLE​

启用 CollNet 插件的使用。

接受的值​

默认为 0，定义并设置为 1 以使用 CollNet 插件。

MCCL_COLLNET_NODE_THRESHOLD​

节点数量的阈值，低于此阈值时不会启用 CollNet。

接受的值​

默认为 2，定义并设置为整数。

MCCL_TOPO_FILE​

在检测拓扑之前加载的 XML 文件的路径。默认情况下，如果存在，MCCL 将加载默认拓扑文件。

接受的值​

描述部分或全部拓扑的可访问文件的路径。

MCCL_TOPO_DUMP_FILE​

在检测后转储 XML 拓扑的文件路径。

接受的值​

将被创建或覆盖的文件的路径。

调试​

这些环境变量应谨慎使用。MCCL 的新版本可能有不同的工作方式，强制它们为特定值将阻止 MCCL 自动选择最佳设置。因此，它们可能导致长期的性能问题，甚至破坏某些功能。

它们适用于实验或调试问题，但通常不应为生产代码设置。

MCCL_P2P_DISABLE​

MCCL_P2P_DISABLE 变量禁用点对点（P2P）传输，该传输使用 NVLink 或 PCI 之间的 GPU 直接访问 MUSA。

接受的值​

定义并设置为 1 以禁用直接 GPU 到 GPU（P2P）通信。

MCCL_P2P_LEVEL​

MCCL_P2P_LEVEL 变量允许用户精确控制何时使用 GPU 之间的点对点（P2P）传输。级别定义了 MCCL 将使用 P2P 传输的 GPU 之间的最大距离。应使用表示路径类型的短字符串来指定使用 P2P 传输的拓扑截止。

如果未指定，MCCL 将根据其运行的架构和环境尝试选择一个最优值。

接受的值​

  • LOC：从不使用 P2P（始终禁用）
  • NVL：当 GPU 通过 NVLink 连接时使用 P2P
  • PIX：当 GPU 在同一 PCI 开关上时使用 P2P
  • PXB：当 GPU 通过 PCI 开关连接时使用 P2P（可能多个跳数）。
  • PHB：当 GPU 在同一 NUMA 节点上时使用 P2P。流量将通过 CPU。
  • SYS：在 NUMA 节点之间使用 P2P。

整数值（遗留）​

还有将 MCCL_P2P_LEVEL 声明为对应路径类型的整数的选项。这些数值值是为了向后兼容而保留的，适用于在允许字符串之前使用数值值的人。

由于路径类型的破坏性更改 - 文字值可能会随时间变化。为了避免调试配置时的头痛，请使用字符串标识符。

  • LOC：0
  • PIX：1
  • PXB：2
  • PHB：3
  • SYS：4

大于 4 的值将被解释为 SYS。使用遗留整数值不支持 NVL。

MCCL_SHM_DISABLE​

MCCL_SHM_DISABLE 变量禁用共享内存（SHM）传输。当点对点无法发生时，SHM 在设备之间使用，因此，主机内存被使用。当禁用 SHM 时，MCCL 将使用网络（即 InfiniBand 或 IP 套接字）在 CPU 套接字之间通信。

接受的值​

定义并设置为 1 以禁用通过共享内存（SHM）通信。

MCCL_BUFFSIZE​

MCCL_BUFFSIZE 变量控制 MCCL 在 GPU 对之间通信数据时使用的 Simple 协议缓冲区大小。

如果在使用 MCCL 时遇到内存限制问题，或者您认为不同的缓冲区大小可以提高性能，请使用此变量。

接受的值​

默认情况下自动选择：x86 等平台默认 4194304（4 MiB），ARM 平台默认 1048576（1 MiB）。

值是整数，以字节为单位。建议使用 2 的幂。例如，1024 将给出 1KiB 缓冲区。

MCCL_LL_BUFFSIZE​

MCCL_LL_BUFFSIZE 变量控制 MCCL 使用 LL 协议时的缓冲区大小。

接受的值​

默认情况下由 MCCL 自动选择。

值是整数，以字节为单位。

MCCL_LL128_BUFFSIZE​

MCCL_LL128_BUFFSIZE 变量控制 MCCL 使用 LL128 协议时的缓冲区大小。

接受的值​

默认情况下由 MCCL 自动选择。

值是整数，以字节为单位。

MCCL_NTHREADS​

MCCL_NTHREADS 变量设置每个 MUSA 块的 MUSA 线程数。MCCL 将为每个通信通道启动一个 MUSA 块。

如果您认为您的 GPU 时钟速度低，并且想要增加线程数，请使用此变量。

您还可以使用此变量减少线程数以降低 GPU 工作负载。

接受的值​

对于最近一代 GPU，默认值为 512，对于某些旧一代，默认值为 256。

允许的值是 64、128、256 和 512。

MCCL_MAX_NCHANNELS​

MCCL_MAX_NCHANNELS 变量限制 MCCL 可以使用的通道数量。减少通道数量也会减少用于通信的 MUSA 块数量，从而减少对 GPU 计算资源的影响。

接受的值​

任何大于或等于 1 的值。

MCCL_MIN_NCHANNELS​

MCCL_MIN_NCHANNELS 变量控制您希望 MCCL 使用的最小通道数量。增加通道数量也会增加 MCCL 使用的 MUSA 块数量，这可能有助于提高性能；然而，它使用了更多的 MUSA 计算资源。

当在 MCCL 通常只创建一个通道的平台上使用聚合集体操作时，这特别有用。

接受的值​

默认值为 32。接受的值为整数值。

MCCL_CHECK_POINTERS​

MCCL_CHECK_POINTERS 变量启用每个集体调用上的 MUSA 内存指针检查。检查在开发过程中很有用，但可能会增加延迟。

接受的值​

默认为 1，设置为 0 以禁用检查。

MCCL_IB_DISABLE​

MCCL_IB_DISABLE 变量阻止 MCCL 使用 IB/RoCE 传输。相反，MCCL 将回退到使用 IP 套接字。

接受的值​

定义并设置为 1 以禁用使用 InfiniBand Verbs 进行通信（并强制使用另一种方法，例如 IP 套接字）。

MCCL_IB_AR_THRESHOLD​

阈值，超过此阈值时我们将以单独的消息发送 InfiniBand 数据，这可以利用自适应路由。

接受的值​

字节大小，默认值为 8192。

将其设置为高于 MCCL_BUFFSIZE 将完全禁用使用自适应路由。

MCCL_IB_QPS_PER_CONNECTION​

两个 rank 之间每个连接使用的 IB 队列对数。这在需要多个队列对以获得良好的路由熵的多级 fabric 上很有用。参见 MCCL_IB_SPLIT_DATA_ON_QPS 了解在多个 QP 上拆分数据的不同方式，因为它可能影响性能。

接受的值​

1 到 128 之间的数字，默认为 1。

MCCL_NET_GDR_LEVEL​

MCCL_NET_GDR_LEVEL 变量允许用户精确控制何时使用 NIC 和 GPU 之间的 GPU Direct RDMA。级别定义了 NIC 和 GPU 之间的最大距离。应使用表示路径类型的字符串来指定 GpuDirect 的拓扑截止。

如果未指定，MCCL 将根据其运行的架构和环境尝试选择一个最优值。

接受的值​

  • LOC：从不使用 GPU Direct RDMA（始终禁用）。
  • PIX：当 GPU 和 NIC 在同一 PCI 开关上时使用 GPU Direct RDMA。
  • PXB：当 GPU 和 NIC 通过 PCI 开关连接时使用 GPU Direct RDMA（可能多个跳数）。
  • PHB：当 GPU 和 NIC 在同一 NUMA 节点上时使用 GPU Direct RDMA。流量将通过 CPU。
  • SYS：即使在 NUMA 节点之间的 SMP 互连上也使用 GPU Direct RDMA（始终启用）。

整数值（遗留）​

还有将 MCCL_NET_GDR_LEVEL 声明为对应路径类型的整数的选项。这些数值值是为了向后兼容而保留的，适用于在允许字符串之前使用数值值的人。

由于路径类型的破坏性更改 - 文字值可能会随时间变化。为了避免调试配置时的头痛，请使用字符串标识符。

  • LOC：0
  • PIX：1
  • PXB：2
  • PHB：3
  • SYS：4

大于 4 的值将被解释为 SYS。

MCCL_NET_GDR_READ​

MCCL_NET_GDR_READ 变量允许用户控制发送方向是否使用 GPU Direct RDMA read。

接受的值​

默认值为自动选择。设置为 0 将禁用发送方向的 GDR read；设置为 1 将允许在满足拓扑距离等条件时使用 GDR read。

MCCL_NET_SHARED_BUFFERS​

允许在节点间点对点通信中使用共享缓冲区。这将使用一个大型池供所有远程对等方使用，具有恒定的内存使用量，而不是随着远程对等方数量的增加而线性增加。

接受的值​

默认情况下自动选择：普通通信默认启用，MUSA Graph 场景默认禁用。设置为 0 以禁用，设置为 1 以启用。

MCCL_ALGO​

MCCL_ALGO 变量定义 MCCL 将使用的算法。

接受的值​

算法名称的逗号分隔列表（不区分大小写），包括：Ring、Tree 和 CollNet。

若要指定要排除的算法，以 ^ 开始列表。

默认值未设置，由 MCCL 根据节点拓扑和架构自动选择可用的算法。

MCCL_PROTO​

MCCL_PROTO 变量定义 MCCL 被允许使用的协议。

不鼓励用户设置此变量，除非在怀疑 MCCL 中存在错误时禁用特定协议。

接受的值​

协议名称的逗号分隔列表（不区分大小写），包括：LL、LL128 和 Simple。

若要指定要排除的协议，以 ^ 开始列表。

默认值未设置，由 MCCL 根据节点拓扑和架构自动选择可用的协议。

MCCL_GRAPH_REGISTER​

在 MCCL 调用被 MUSA Graph 捕获时启用用户缓冲区注册。

仅在 MUSA Graph 场景下，且以下条件同时成立时有效：（i）正在使用 CollNet 算法；（ii）节点内所有 GPU 都可以相互 P2P 访问；（iii）每个进程只有一个 GPU/rank。

用户缓冲区注册可能会减少用户缓冲区和 MCCL 内部缓冲区之间的数据副本数量。当 MUSA Graph 被销毁时，用户缓冲区将自动取消注册。

接受的值​

0 或 1。默认值为 0（禁用）。

MCCL_SET_STACK_SIZE​

将 MUSA 内核堆栈大小设置为所有 MCCL 内核中的最大堆栈大小。

这可能会避免在加载时 MUSA 内存重新配置。如果您因 MUSA 内存重新配置而遇到挂起，请将其设置为 1。

接受的值​

0 或 1。默认值为 0（禁用）。

MCCL_DMABUF_ENABLE​

启用使用 Linux dma-buf 子系统进行 GPU Direct RDMA 缓冲区注册。

Linux dma-buf 子系统允许 GPU Direct RDMA 能力的 NIC 直接读取和写入 MUSA 缓冲区，无需 CPU 参与。

接受的值​

0 或 1。默认值为 1（启用），但如果 Linux 内核或 MUSA/NIC 驱动程序不支持，则该功能将自动禁用。

版权所有 2024 摩尔线程，本文档受国际版权法保护。

摩尔线程和摩尔线程徽标是摩尔线程智能科技 (北京)有限责任公司的注册商标。

免责声明

本文档提供有关摩尔线程产品的信息。本文档并未授权任何知识产权的许可，并未以明示或暗示，或以禁止反言或其他方式授予任何知识产权许可。