第4章 环境搭建与安装：硬件要求、软件依赖、pip安装、源码编译、验证安装

DeepSpeed 的安装并不复杂，但它对硬件、驱动、CUDA 版本和 Python 环境有比较明确的依赖关系。很多初学者在安装阶段就遇到“编译失败”“找不到 CUDA”“版本不匹配”等问题，根本原因往往不是 DeepSpeed 本身，而是环境没有对齐。本章按照“先确认硬件，再对齐软件，最后选择安装方式并验证”的顺序，把安装过程拆成可复现的步骤。

一、硬件要求：先确认你的机器能跑什么

DeepSpeed 的核心能力是分布式训练与显存优化，因此硬件决定了你能使用哪些特性。最基础的判断维度是：是否有 NVIDIA GPU、GPU 数量、单卡显存、GPU 之间的互联方式，以及是否具备 NVMe SSD。

  • GPU 型号：建议使用 Volta 架构及以上的 NVIDIA GPU（如 V100、A100、H100、RTX 30/40 系列）。DeepSpeed 的 ZeRO-Offload、FP16/BF16 等特性对计算能力有要求，过老的架构可能无法启用。
  • 显存容量：单卡 16GB 以上可以较顺畅地体验 ZeRO-2；若要做 7B 以上模型训练，通常需要 24GB 或 40GB/80GB 显存，并配合 ZeRO-3 与 CPU Offload。
  • 多卡互联：多卡训练时，NVLink 的带宽远高于 PCIe，能显著减少通信瓶颈。若没有 NVLink，也可用 PCIe，但需要关注梯度通信开销。
  • NVMe SSD：当启用 ZeRO-Infinity 或参数 Offload 到磁盘时，NVMe 的顺序读写速度直接影响训练吞吐。
如果只是学习 DeepSpeed 的 API 和配置，单张 8GB 显存的 GPU 也能跑通小模型示例；但若要复现大模型训练，硬件门槛会明显提高。

二、软件依赖：版本对齐是成功的关键

DeepSpeed 依赖 PyTorch、CUDA、Python 和编译器。最常见的失败原因是 PyTorch 自带的 CUDA 版本与系统 CUDA 版本不一致，导致编译扩展时找不到头文件或链接库。安装前建议先执行以下命令确认现状：

nvidia-smi
python --version
python -c "import torch; print(torch.__version__, torch.version.cuda)"
nvcc --version
gcc --version

推荐的环境组合如下表所示。注意：torch.version.cuda 才是 PyTorch 编译时使用的 CUDA 版本，它必须与 nvcc --version 一致或兼容。

组件推荐版本说明
Python3.8 – 3.113.12 部分依赖尚未完全适配
PyTorch2.0 及以上建议使用官方预编译 CUDA 版本
CUDA11.7 / 11.8 / 12.1与 PyTorch 的 CUDA 版本保持一致
GCC7.5 – 11过高版本可能触发编译警告或错误
NCCL随 PyTorch 安装多卡通信依赖，通常无需单独安装

三、pip 安装：最快捷的入门方式

对于大多数用户，pip 安装是最省事的方式。DeepSpeed 在 PyPI 上提供源码包，安装时会根据当前环境编译部分扩展。若只想快速使用，可以只安装纯 Python 部分：

# 基础安装（会尝试编译扩展）
pip install deepspeed

# 仅安装纯 Python 部分，跳过 CPU 优化扩展编译
DS_BUILD_CPU_ADAM=0 pip install deepspeed

# 指定版本
pip install deepspeed==0.14.0

如果安装过程中出现编译错误，通常是因为缺少 CUDA 工具链或 GCC 版本不匹配。此时可以先设置环境变量，再重新安装：

export CUDA_HOME=/usr/local/cuda
export PATH=$CUDA_HOME/bin:$PATH
export LD_LIBRARY_PATH=$CUDA_HOME/lib64:$LD_LIBRARY_PATH
pip install deepspeed --no-cache-dir
不要混用 conda 与 pip 安装 PyTorch。conda 安装的 PyTorch 可能链接到 conda 自带的 CUDA 运行时，而 pip 安装的 DeepSpeed 会去系统路径找 CUDA，二者不一致时极易报错。

四、源码编译：需要定制或调试时的选择

当你需要启用特定加速算子（如 CPU Adam、Fused Adam、稀疏注意力）或修改源码时，应从 GitHub 克隆并本地编译。源码编译能让你精确控制编译哪些扩展，减少不必要的依赖。

git clone https://github.com/microsoft/DeepSpeed.git
cd DeepSpeed
pip install -r requirements/requirements.txt

# 只编译需要的算子，加快安装速度
DS_BUILD_CPU_ADAM=1 DS_BUILD_FUSED_ADAM=1 pip install -e .

# 查看可用的编译选项
DS_BUILD_HELP=1 pip install -e .

源码编译的核心流程可以用下面的示意图理解：环境检查决定能否编译，编译选项决定生成哪些算子，最终安装到当前 Python 环境。

DeepSpeed 源码编译流程 环境检查 CUDA / GCC / PyTorch 克隆源码 git clone DeepSpeed 选择编译算子 DS_BUILD_* 变量 安装到环境 pip install -e . 常见编译算子与用途 CPU Adam CPU 端优化器，配合 Offload Fused Adam GPU 端融合优化器，提速明显 Sparse Attention 稀疏注意力，长序列场景 提示：编译前确保 nvcc 可用，且 CUDA_HOME 指向正确的 CUDA 安装目录。

五、验证安装：确认 DeepSpeed 真正可用

安装完成后，必须做两步验证：一是确认版本与导入正常，二是确认分布式通信与加速算子可用。只看到 pip install 成功并不代表 DeepSpeed 能正常工作。

# 1. 查看版本与基本信息
ds_report

# 2. Python 中导入并检查
python -c "import deepspeed; print(deepspeed.__version__)"

# 3. 运行官方自检（单卡）
deepspeed --num_gpus=1 -m deepspeed.launcher.runner --help

# 4. 多卡通信自检
deepspeed --num_gpus=2 -m deepspeed.launcher.runner --help

ds_report 会输出一张环境报告表，重点看 torch、cuda、nccl 和各个 op 的状态。如果某个算子显示 NO，说明该算子未编译成功，但不影响基础训练；若 torch 或 cuda 显示不匹配，则需要回到第二步重新对齐版本。

验证清单：
1. ds_report 中 CUDA 与 PyTorch 版本一致；
2. import deepspeed 无报错；
3. 单卡能启动一个最小训练脚本；
4. 多卡时 NCCL 能正常初始化，无超时或连接错误。

六、常见误区与复盘

  • 误区一：只看 nvidia-smi 的 CUDA 版本。nvidia-smi 显示的是驱动支持的最高 CUDA 版本，不是实际安装的 CUDA 工具链版本，必须用 nvcc --version 确认。
  • 误区二：在同一个环境里反复 pip 与 conda 混装。这会导致 CUDA 运行时冲突，建议用 conda 创建干净环境后，统一用 pip 安装 PyTorch 与 DeepSpeed。
  • 误区三：忽略 GCC 版本。GCC 过高（如 12 以上）可能编译失败，可通过 conda install gcc=10 或系统包管理器降级。
  • 误区四：安装完不验证。很多问题在真正启动训练时才暴露，提前用 ds_report 和最小脚本验证，能节省大量排障时间。

整体来看，DeepSpeed 的安装可以归纳为一条清晰的主线：先确认 GPU 与显存是否满足目标场景，再对齐 Python、PyTorch、CUDA、GCC 的版本，然后根据需求选择 pip 安装或源码编译，最后用 ds_report 和最小训练脚本完成验证。把这条主线走通，后续的 ZeRO 配置与训练调优才有稳定的基础。

← 上一章 📖 返回目录 下一章 →