文档中心

GPU云服务器

安装veCCL

安装veCCL通信库（Analyzer 专用）

veCCL（Volcano Engine Collective Communication Library）Analyzer专用版本是火山引擎基于NCCL（Nvidia Collective Communication Library）自研开发的高性能集合通信库，支持安装在单节点或多节点的多张GPU卡上，提供一系列关于通信的无损插桩，用于实现故障发现、根因定位，性能分析和可视化等功能。

本文以ecs.hpcpni3ln.45xlarge实例为例，为您介绍veCCL通信库的安装流程。

主要特性

快速定位故障：能够在复杂的分布式集群协作任务中，快速识别并精准界定通信故障点。

极致稳定性（Softbond）：能够应对复杂多变的网络异常情况。通过提供Softbond能力，在底层网卡发生故障时可实现毫秒级自动切换，保障业务稳定运行不中断。了解更多。

准备工作

创建GPU计算型实例：请根据通过向导购买实例指引，创建一台符合如下条件的实例。

配置项	推荐配置
基础配置
计算规格	ecs.hpcpni3ln.45xlarge 说明 ecs.hpcpni3ln.45xlarge规格实例正在邀测中，如需试用，请提交工单或联系客户经理申请。
镜像	Ubuntu 22.04 with GPU Driver 535.161.08 and doca 说明若您选用其他发行版本的镜像，需在创建实例后自行安装GPU驱动。

检查软件环境

请先登录GPU实例，并确认您的系统满足以下软件环境。

GPU 驱动：用于驱动NVIDIA GPU正常工作的底层程序，执行nvidia-smi命令，确认驱动正常。本文以535.161.08版本为例。

CUDA 环境（12.4 及以上）：执行nvcc -V命令查看当前的CUDA版本。若未安装或版本低于要求，请安装 CUDA。

Python 环境：执行python3 --version命令确认已安装Python 3。若未安装，请安装 Python。

操作步骤

步骤一：安装veCCL

登录购买的GPU实例。了解更多。

执行以下命令，安装veCCL。

pip install veccl -i https://private.ivolces.com/pypi/simple

执行以下命令检查安装是否成功。

ls `python3 -c "import veccl; print(veccl.ld_library_path())"`

若回显如下信息，则已成功安装veCCL。

（可选）若安装失败，请执行如下命令从pip官方源重新下载并安装veCCL。

pip uninstall veccl
pip install veccl -i https://pypi.org/simple

步骤二：配置veCCL通信环境

veCCL安装成功后，必须通过环境变量将其注入到当前进程中，以确保程序在运行时优先加载veCCL通信库。请在执行训练脚本前，执行如下命令导入环境变量。

export LD_PRELOAD=$(python3 -c "import veccl; print(veccl.lib_paths())"):${LD_PRELOAD}​
export NCCL_NET_PLUGIN=soft-bonding​
export LD_LIBRARY_PATH=$(python3 -c "import veccl; print(veccl.ld_library_path())"):$LD_LIBRARY_PATH​

说明

此配置方式仅临时生效，关闭窗口或断开连接后环境变量将会失效，再次运行时需重新导入。

步骤三：验证veCCL运行效果

本节以单机8卡的PyTorch分布式训练测试脚本为例，验证veCCL的all_reduce集合通信加速效果。

执行如下命令确认已安装PyTorch，若未安装，请安装PyTorch。

python3 -c "import torch; print(torch.__version__)

创建测试脚本，命名为test.py 并填入以下代码。

import os
import torch
import torch.distributed as dist

def main():
# 1. 环境变量解析
rank = int(os.environ["RANK"])# 全局进程编号，当前进程在整个分布式集群中的实际序号
local_rank = int(os.environ["LOCAL_RANK"])# 本机GPU编号，当前进程在当前节点（机器）内的GPU序号
world_size = int(os.environ["WORLD_SIZE"])# 总进程数（总GPU数）

# 2. 设备与通信初始化
torch.cuda.set_device(local_rank)
dist.init_process_group(backend="nccl")

# 3. 在每个 GPU 上生成随机张量，并进行 all_reduce 累加操作
tensor = torch.randn(1024, device=f"cuda:{local_rank}")
print(f"Rank {rank}: before allreduce tensor sum = {tensor.sum().item()}")

dist.all_reduce(tensor, op=dist.ReduceOp.SUM)

# 4. 验证 all_reduce 结果并释放资源
print(f"Rank {rank}: after allreduce tensor sum = {tensor.sum().item()}")
dist.destroy_process_group()

if __name__ == "__main__":
main()

执行以下命令运行test.py脚本，启动单节点8卡分布式训练测试。

NCCL_DEBUG=INFO torchrun --nproc_per_node=8 test.py

检查加载结果。

检查控制台输出日志，若包含NCCL INFO PROFILER/Plugin: loaded Bytedance-profiler字样，则veCCL分析器插件已成功挂载。

检查各个Rank的all_reduce运算结果日志是否符合预期，即未发生卡死（Hang），且所有Rank最终打印的after数值完全一致。

附录

关键环境变量说明

在多实例多卡训练或复杂网络环境下，您可能需要调整以下NCCL环境变量以保证通信的最佳性能和稳定性。

环境变量	描述	取值示例
NCCL_SOCKET_IFNAME	NCCL初始化时建连使用的网卡接口名称，不同规格的实例网卡可能不同，请以实际为准。说明未配置或配置错误会导致建连失败。	eth0
NCCL_IB_GID_INDEX	用于设置RDMA通信使用的GID，仅多台实例运行时有效。说明配置错误会导致跨机NCCL运行报错。	-
NCCL_IB_TIMEOUT	用于决定RDMA数据发送的超时重传时间，仅多台实例运行时有效。说明配置为18意味着约1.07s会触发丢包重传。若使用Softbond，该变量同时决定了判定链路不可用的切流时间阈值。	使用Softbond时推荐值为18。使用非Softbond时推荐值为23。
NCCL_NET_PLUGIN	用于指定NCCL使用的网络插件。配置为soft-bonding 以启用veCCL的链路稳定性增强能力，若无需使用，推荐设置为none以防止误加载其他非预期插件。	soft-bonding
NCCL_DEBUG	用于设置NCCL日志级别。建议设置为INFO级别，INFO级别仅在初始化时打印关键信息，不影响通信性能，有助于快速排查建连与网络拓扑问题。	INFO
NCCL_RASP_DISABLE	veCCL Proxy通信过程的打点（Profiling）开关，也是检测Hang（卡死）的主要数据源，默认为0（开启）。说明若将其设置为 1 将关闭共享内存日志的写入。关闭后相关打点数据将不再输出，可能导致Analyzer无法正常采集通信信息，进而影响Hang检测与问题定位能力。	保持默认

最近更新时间：2026.05.08 15:36:24

这个页面对您有帮助吗？

有用

无用