安装与版本矩阵

2.1 装之前要先承认的事

DeepSpeed 的依赖关系比 LLaMA-Factory 更挑剔，原因有两点：

• 它自己有 C++/CUDA 扩展（op_builder/、csrc/）：fused Adam、fused LayerNorm、NVMe swap 等都要编译；
• 它有 多种构建模式：JIT（按需编译）/ pre-built（提前编译）/ ds-build（环境变量精细控制）。

不会编译 C++ 也能用 DeepSpeed，但装不好就只能用 fallback 实现，性能差一截。本章把"怎么装得对"讲清楚。

2.2 硬性依赖

仓库 requirements/requirements.txt 列出的核心依赖：

einops
hjson
msgpack
ninja
numpy
packaging>=20.0
psutil
py-cpuinfo
pydantic>=2.0.0
torch>=2.0.0
tqdm

除此之外，编译 CUDA 扩展时还需要：

2.3 三条安装路线

路线 A：纯 pip 安装（JIT 编译）

# 最简单：装到 site-packages，等用到时按需编译 CUDA op
pip install deepspeed

# 看版本
ds_report

ds_report 会输出长长一段，告诉你：

• 各 op（fused_adam / cpu_adam / fused_lamb ...）是不是已编译；
• CUDA / PyTorch / NCCL 版本；
• 缺哪个就显示 [NO]。

这条路线第一次跑训练会卡几分钟编译 CUDA，之后会缓存。

路线 B：提前编译指定 op（pre-built）

跑生产任务前一次性把所有 op 编完，避免训练时被编译时间打扰：

# 编译全部 op
DS_BUILD_OPS=1 pip install deepspeed

# 只编 ZeRO 必要 op，省 60% 编译时间
DS_BUILD_CPU_ADAM=1 DS_BUILD_FUSED_ADAM=1 DS_BUILD_UTILS=1 \
  pip install deepspeed

# 看支持的环境变量列表
python -c "from op_builder import ALL_OPS; print(list(ALL_OPS.keys()))"

仓库 op_builder/ 下每个文件对应一个 op。常用的几个环境变量：

完整可枚举的 op 列表在 op_builder/all_ops.py（第 30 行的 ALL_OPS = {op.name: op for op in __op_builders__}）。任何时候想知道"这个版本支持哪些 op"，跑：

python -c "from op_builder import ALL_OPS; print(sorted(ALL_OPS.keys()))"

路线 C：用 NGC / 官方 Docker

仓库自带 docker/Dockerfile，但更常见做法是直接用 NVIDIA NGC 镜像或 HuggingFace 的镜像（里面已经装好 DeepSpeed）：

# NGC PyTorch 容器（已含 DS）
docker run --gpus all -it --rm nvcr.io/nvidia/pytorch:24.10-py3 bash

# 进容器后确认
ds_report

2.4 版本对应矩阵

DeepSpeed × PyTorch × CUDA 不能乱配。本基线 commit 时的推荐组合：

2.5 验证安装

ds_report 是最权威的一招，但还有几个快速检查：

# 1. import 不报错
python -c "import deepspeed; print(deepspeed.__version__)"

# 2. 看哪些 op 已编译
python -c "from deepspeed.ops.adam import FusedAdam; print('FusedAdam OK')"
python -c "from deepspeed.ops.adam import DeepSpeedCPUAdam; print('CPUAdam OK')"

# 3. 看 launcher 可用
deepspeed --help

# 4. 跑最小训练（torchrun 风格）
deepspeed --num_gpus 1 -- examples/sdma_allgather/test.py
# 或仓库自带的 tests/unit/runtime/zero/test_zero.py

如果 FusedAdam import 报错但训练能跑，那说明你正在用 fallback PyTorch Adam——能用，但慢。DS_BUILD_FUSED_ADAM=1 pip install --force-reinstall deepspeed --no-build-isolation 重新装一次。

2.5.1 一份典型的 ds_report 输出该长啥样

真实输出会很长（几十行），关键是看下面这几块。本节的"应有形态"对照可以帮你迅速定位"我哪儿少装了"：

--------------------------------------------------
DeepSpeed C++/CUDA extension op report
--------------------------------------------------
JIT compiled ops requires ninja
ninja .................. [OKAY]
--------------------------------------------------
op name ................ installed .. compatible
--------------------------------------------------
async_io ............... [YES] ...... [OKAY]      ← NVMe offload 必须 [OKAY]
cpu_adam ............... [YES] ...... [OKAY]      ← CPU offload 必须 [OKAY]
cpu_adagrad ............ [NO] ....... [OKAY]
fused_adam ............. [YES] ...... [OKAY]      ← GPU 训练强烈建议 [OKAY]
fused_lamb ............. [NO] ....... [OKAY]      ← 不用 Lamb 可以 [NO]
quantizer .............. [NO] ....... [OKAY]      ← 不做量化可以 [NO]
random_ltd ............. [NO] ....... [OKAY]
sparse_attn ............ [NO] ....... [NO]        ← 已弃用，不用管
spatial_inference ...... [NO] ....... [OKAY]
transformer ............ [NO] ....... [OKAY]      ← v1 推理用；不推理可 [NO]
stochastic_transformer . [NO] ....... [OKAY]
transformer_inference .. [NO] ....... [OKAY]      ← DS-Inference v1 要 [OKAY]
--------------------------------------------------
DeepSpeed general environment info:
torch install path ............... ['...']
torch version .................... 2.5.1
deepspeed install path ........... ['...']
deepspeed info ................... 0.19.1, ...

判读规则：

• "installed" = 这个 op 此刻已经在本环境编译好；
• "compatible" = 当前 CUDA / PyTorch 组合能不能编译这个 op；如果是 [NO]，DS_BUILD_ 也救不了；
• 训练（无 offload）：只需 fused_adam = [OKAY]；
• 训练 + CPU offload：还需 cpu_adam = [OKAY]；
• 训练 + NVMe offload：再加 async_io = [OKAY]；
• DS-Inference v1：transformer_inference = [OKAY]。

2.6 三个最常踩的安装坑

2.7 装好后该读哪几个文件

装完别急着跑业务训练，先扫一眼这些文件，省后续大量调试时间：