📚 课程目录第3章环境与配置

3. 环境与配置

DeepSpeed 的绝大多数训练故障，最终都能追溯到环境与配置层面：版本不匹配、配置文件字段写错、多机通信参数缺失、环境变量未生效。本章围绕“装得对、配得准、连得通”三条主线，梳理从安装部署到多机多卡配置的完整链路，并给出常见错误的定位方法。

一、核心原理：DeepSpeed 的三层配置体系

理解 DeepSpeed 的配置，关键是分清三个层次，它们的作用范围和优先级完全不同：

启动层：由 deepspeed 或 torchrun 启动器传入，决定进程数、节点数、通信后端，如 --num_gpus、--num_nodes、--master_addr。
环境变量层：由 shell 或启动脚本注入，控制 NCCL、CUDA、通信网卡等底层行为，如 NCCL_IB_DISABLE、CUDA_VISIBLE_DEVICES。
JSON 配置层：由 ds_config.json 描述，控制 ZeRO 阶段、混合精度、优化器、并行策略等训练语义。

三层之间存在覆盖关系：环境变量影响通信与设备可见性，启动参数决定进程拓扑，JSON 决定算法行为。故障排查时应按“先环境、再启动、后配置”的顺序逐层排除。

二、安装部署：版本匹配是第一原则

DeepSpeed 与 PyTorch、CUDA、NCCL 之间存在严格的版本耦合。最常见的安装故障是“装上了但跑不起来”，根源往往是 PyTorch 与 CUDA 版本不匹配，或 DeepSpeed 编译时链接到了错误的 CUDA 路径。

# 推荐：先确认基础环境
python -c "import torch; print(torch.__version__, torch.version.cuda)"
nvcc --version
nvidia-smi

# 安装 DeepSpeed（源码编译，确保与本地 CUDA 匹配）
git clone https://github.com/microsoft/DeepSpeed
cd DeepSpeed
pip install -v -e .

# 验证安装
ds_report

ds_report 是安装后必跑的检查命令，它会输出 CUDA、NCCL、PyTorch、DeepSpeed 的版本与编译状态。若其中 torch 与 cuda 显示为 False 或版本不一致，后续训练必然出现算子缺失或通信失败。

建议使用容器镜像固定环境，将 CUDA、PyTorch、DeepSpeed 版本写入 Dockerfile，避免“同一份代码在不同机器上表现不同”的问题。

三、配置文件解析：ds_config.json 的关键字段

DeepSpeed 的 JSON 配置决定了训练的核心行为。以下是最常用字段及其作用：

字段	作用	常见取值	典型错误
train_batch_size	全局批次大小	整数	与 micro_batch 不整除
gradient_accumulation_steps	梯度累积步数	整数	与 batch 计算冲突
fp16 / bf16	混合精度	enabled: true	两者同时开启
zero_optimization.stage	ZeRO 阶段	0/1/2/3	stage 3 未配 offload
optimizer	优化器类型	Adam / AdamW	参数名拼写错误
scheduler	学习率调度	WarmupLR	缺少 warmup_num_steps

一个最小可用的 ZeRO-2 配置如下：

{
  "train_batch_size": 64,
  "gradient_accumulation_steps": 4,
  "fp16": { "enabled": true },
  "zero_optimization": {
    "stage": 2,
    "allgather_partitions": true,
    "overlap_comm": true
  },
  "optimizer": {
    "type": "AdamW",
    "params": { "lr": 2e-5, "betas": [0.9, 0.999] }
  },
  "scheduler": {
    "type": "WarmupLR",
    "params": { "warmup_min_lr": 0, "warmup_max_lr": 2e-5, "warmup_num_steps": 500 }
  }
}

JSON 不支持注释，任何 // 或 # 都会导致解析失败。同时注意 train_batch_size 必须等于 micro_batch × grad_accum × world_size，否则 DeepSpeed 会直接报错退出。

四、多机多卡设置：通信是最大风险点

多机训练的核心是让所有节点通过正确的网卡和地址互相发现。启动命令需要显式指定节点数、每节点 GPU 数、主节点地址与端口：

# 节点 0（主节点）
deepspeed --num_nodes=2 --num_gpus=8 \
  --master_addr=10.0.0.1 --master_port=29500 \
  train.py --deepspeed ds_config.json

# 节点 1
deepspeed --num_nodes=2 --num_gpus=8 \
  --master_addr=10.0.0.1 --master_port=29500 \
  train.py --deepspeed ds_config.json

若使用 InfiniBand，需确认 NCCL_IB_DISABLE=0 且网卡名正确；若使用以太网，则设置 NCCL_SOCKET_IFNAME=eth0。多机场景下最常见的故障是“卡在初始化”或“NCCL timeout”，通常由防火墙、端口占用或网卡选择错误引起。

五、常见配置错误与复盘清单

版本不匹配：PyTorch CUDA 版本与系统 CUDA 不一致，导致 undefined symbol。
JSON 字段拼写错误：如 zero_optimization 写成 zero_opt，DeepSpeed 会忽略该段配置。
batch size 不整除：train_batch_size 无法被 micro_batch × grad_accum × world_size 整除。
环境变量未导出：在子进程中未继承 MASTER_ADDR，导致 rank 0 找不到。
多机端口冲突：master_port 被其他进程占用，表现为连接拒绝。
ZeRO-3 未配 offload：显存不足时未启用 offload_optimizer，直接 OOM。

复盘建议：每次环境变更后，先跑 ds_report，再用单机单卡验证配置，最后扩展到多机多卡。把“环境检查”作为训练脚本的第一步，可以拦截 80% 以上的配置类故障。

环境与配置是 DeepSpeed 训练的“地基”。安装阶段确保版本一致，配置阶段确保字段正确，多机阶段确保通信可达，三者缺一不可。掌握本章的三层配置体系与排查顺序，后续的显存、通信、精度类故障才能被快速定位。