DeepSpeed 高级安装指南：Ops 预编译、多节点分发与 GPU 架构定制-平芜编程栈

推理引擎
大模型

【免费下载链接】FlexGen

Running large language models on a single GPU for throughput-oriented scenarios.

项目地址：https://gitcode.com/gh_mirrors/fl/FlexGen

DeepSpeed 在训练与推理时依赖一组 C++/CUDA 扩展（即 "ops"），安装方式直接决定了首次运行是即时编译还是提前编译，进而影响部署速度与多机一致性。本文以 DeepSpeed 官方安装文档（benchmark/third_party/DeepSpeed/docs/_tutorials/advanced-install.md）为主线，结合本仓库内随附的 DeepSpeed 源码（benchmark/third_party/DeepSpeed，作为 FlexGen 基准测试套件的第三方依赖被引入），系统讲解快速安装、Ops 预编译开关、多节点分发、JIT 缓存管理、GPU 架构定制与功能依赖等完整安装细节。读完本文，你将掌握从单机pip install到跨节点 wheel 分发的全套 DeepSpeed 部署方案，并能独立排查no kernel image、扩展缓存冲突等典型安装问题。

快速开始：pip 安装与 JIT 默认模式

DeepSpeed 最快捷的安装方式是通过 pip 安装最新发布版，该版本不绑定特定 PyTorch 或 CUDA 版本：

pip install deepspeed

安装完成后，DeepSpeed 自带若干 C++/CUDA 扩展（官方统称为 "ops"）。默认情况下，所有这些扩展/ops 都会采用即时编译（Just-In-Time，JIT）方式，即利用 PyTorch 的 JIT C++ 扩展加载器（依赖 ninja）在运行时完成构建和动态链接，而不是在安装阶段编译。

安装结束后，推荐立即验证安装结果并查看当前机器与哪些 ops 兼容，使用 DeepSpeed 环境报告工具：

ds_report

等价地，也可以使用 Python 模块方式调用：

python -m deepspeed.env_report

这份报告在排查 DeepSpeed 安装或兼容性问题时非常有用。从仓库源码看，该工具实现在 deepspeed/env_report.py，它输出两类信息：

DeepSpeed C++/CUDA extension op report：逐项列出所有 op 的installed（是否已安装）与compatible（系统依赖是否满足）状态，并检查 JIT 编译所必需的ninja是否可用；
general environment info：torch 安装路径与版本、torch cuda/hip 版本、nvcc 版本、deepspeed 安装路径、deepspeed 版本/ git 哈希 / 分支，以及 wheel 编译时对应的 torch 与 cuda 版本。

报告还支持两个参数：--hide_operator_status（隐藏各 op 的安装与兼容状态）和--hide_errors_and_warnings（隐藏警告与错误信息）。运行入口脚本位于 bin/ds_report。

预编译 DeepSpeed Ops

在某些场景下，提前编译部分或全部 DeepSpeed C++/CUDA ops、而不是依赖 JIT 编译路径，会更有优势（例如：提前发现编译错误、缩短首次运行时间、为多机部署准备一致的二进制）。

注意：如果打算预编译任何 DeepSpeed c++/cuda ops，PyTorch 必须事先安装好；而默认的 JIT 编译模式则无此要求。这一点在 setup.py 中也有体现：一旦开启预编译（DS_BUILD_OPS），若 torch 不可用会直接断言失败。

一键开启全部 Ops 预编译

通过环境变量DS_BUILD_OPS=1告诉安装器（无论是install.sh还是pip install）尝试安装全部 ops：

DS_BUILD_OPS=1 pip install deepspeed

DeepSpeed 只会安装与当前机器兼容的 ops；具体哪些 op 与你的系统兼容，请使用上文介绍的ds_report工具查看。

从源码机制看，setup.py 会遍历ALL_OPS中注册的所有 op builder，逐个调用builder.is_compatible()做兼容性检查：兼容且被开启的 op 会加入ext_modules参与预编译；被请求但不可用的 op 会直接中止安装，并提示可通过对应DS_BUILD_*环境变量置 0 来禁用。ALL_OPS的注册逻辑见 op_builder/all_ops.py，它会反射扫描所有*Builder类并实例化。

只安装特定 Op

如果只想安装某一个 op（例如FusedLamb），可以在安装时使用对应的DS_BUILD环境变量开关：

DS_BUILD_FUSED_LAMB=1 pip install deepspeed

可用的DS_BUILD选项如下：

环境变量	作用
`DS_BUILD_OPS`	切换全部 ops（=1 安装全部）
`DS_BUILD_CPU_ADAM`	构建 CPUAdam op
`DS_BUILD_FUSED_ADAM`	构建 FusedAdam op
`DS_BUILD_FUSED_LAMB`	构建 FusedLamb op
`DS_BUILD_SPARSE_ATTN`	构建稀疏注意力 op
`DS_BUILD_TRANSFORMER`	构建 transformer op
`DS_BUILD_TRANSFORMER_INFERENCE`	构建 transformer-inference op
`DS_BUILD_STOCHASTIC_TRANSFORMER`	构建随机 transformer op
`DS_BUILD_UTILS`	构建各类优化工具
`DS_BUILD_AIO`	构建异步（NVMe）I/O op

每个开关在源码中都有对应定义，例如 op_builder/fused_lamb.py 中BUILD_VAR = 'DS_BUILD_FUSED_LAMB'、op_builder/cpu_adam.py 中BUILD_VAR = "DS_BUILD_CPU_ADAM"、op_builder/fused_adam.py 中BUILD_VAR = "DS_BUILD_FUSED_ADAM"、op_builder/async_io.py 中BUILD_VAR = "DS_BUILD_AIO"。op 的注册清单见 op_builder/builder_names.py，完整的 builder 实现目录为 op_builder/，除上表所列外还包括cpu_adagrad、quantizer、spatial_inference等。

并行化全量编译

全量构建比较耗时，可以通过并行编译加速：

DS_BUILD_OPS=1 pip install deepspeed --global-option="build_ext" --global-option="-j8"

这种方式通常能让完整构建提速 2～3 倍。-j后的数字表示参与构建的 CPU 核数，上例为 8 核，可按机器核数调整。

构建 wheel 并在多台机器分发

如果多台机器的 GPU 型号相同、软件环境一致（CUDA toolkit、PyTorch、Python 等），可以先在本机构建二进制 wheel，再批量安装：

DS_BUILD_OPS=1 python setup.py build_ext -j8 bdist_wheel

该命令会在dist目录下生成 PyPI 二进制 wheel，例如：

dist/deepspeed-0.3.13+8cd046f-cp38-cp38-linux_x86_64.whl

然后在各台目标机器上直接安装：

pip install dist/deepspeed-0.3.13+8cd046f-cp38-cp38-linux_x86_64.whl

关于 wheel 版本号，setup.py 展示了生成规则：基础版本号读取自 version.txt，默认会拼接当前 git 短哈希（如示例中的+8cd046f）；若通过DS_BUILD_STRING环境变量指定（例如发布场景），则拼接该字符串；安装官方分发包时则读取build.txt。此外，setup.py 会把已安装 ops、兼容 ops、torch 版本信息写入deepspeed/git_version_info_installed.py，供ds_report与运行时校验使用。

从源码安装 DeepSpeed

克隆 DeepSpeed 仓库后，可以通过 pip 以 JIT 模式安装：

pip install .

由于此模式不编译任何 C++/CUDA 源码，安装会很快完成。

多节点安装：install.sh

对于跨多节点的安装场景，官方建议使用仓库自带的 install.sh 脚本。该脚本会在本地构建 python wheel，并将其拷贝到 hostfile 中列出的所有节点（hostfile 可通过--hostfile指定，默认路径为/job/hostfile）。

结合脚本源码，其可选参数包括：

参数	说明
`-l, --local_only`	仅在本地机器安装
`-s, --pip_sudo`	以 sudo 运行 pip install（默认不加 sudo）
`-r, --allow_sudo`	允许以 root 身份运行脚本（通常不建议，建议改用`--pip_sudo`）
`-n, --no_clean`	不清除先前的构建状态（默认会在构建 wheel 前删除旧构建文件，如`dist`、`build`、`deepspeed.egg-info`等）
`-m, --pip_mirror`	使用指定的 pip 镜像源
`-H, --hostfile`	指定 MPI 风格 hostfile（默认`/job/hostfile`）
`-e, --examples`	仅检出 deepspeed 示例子模块（不安装）
`-v, --verbose`	详细日志
`-h, --help`	帮助信息

脚本流程（install.sh）大致为：若默认 hostfile 不存在则回退为本地安装；否则先python setup.py bdist_wheel构建本地 wheel，再借助pdsh/pdcp在 hostfile 列出的所有节点上卸载旧版、分发 wheel 并逐一执行ds_report验证。

JIT 编译与扩展缓存目录

当代码首次使用 DeepSpeed 时，只会自动构建当前运行所必需的 CUDA 扩展，默认放置在~/.cache/torch_extensions/目录下。下一次执行同一程序时，这些已预编译的扩展会直接从该目录加载。

多虚拟环境场景的坑：默认只有一个torch_extensions目录，而不同的虚拟环境可能使用不同的配置（如不同 Python 或 CUDA 版本），此时加载由另一个环境构建的 CUDA 扩展会失败。解决方法是使用TORCH_EXTENSIONS_DIR环境变量覆盖默认位置，在每个虚拟环境中指向各自独立的目录：

TORCH_EXTENSIONS_DIR=./torch-extensions deepspeed ...

这样 DeepSpeed 会使用该目录保存和加载 CUDA 扩展，且仅对本次运行生效。

为正确的 GPU 架构构建

如果运行 deepspeed 时出现如下错误：

RuntimeError: CUDA error: no kernel image is available for execution on the device

说明当前 CUDA 扩展并不是为正在使用的显卡构建的。

从源码构建时，DeepSpeed 会尝试支持尽可能广泛的架构；
但在 JIT 模式下，它只支持构建时可见（visible）的架构。

可以为期望的架构范围显式构建，通过设置TORCH_CUDA_ARCH_LIST环境变量：

TORCH_CUDA_ARCH_LIST="6.1;7.5;8.6" pip install ...

只构建少数几个架构时，编译速度也会更快。这也是确保使用确切架构的推荐做法：由于种种技术原因，分发的 PyTorch 二进制并未完整支持所有架构（会跳过二进制兼容的架构），可能导致你的显卡计算能力未被充分利用。构建结束后，可以保存日志并grep-gencode参数，查看 deepspeed 从源码构建时实际包含了哪些架构。

从源码机制看，op_builder/builder.py 中的compute_capability_args()说明了架构选择的优先级：

JIT 模式下，会遍历当前可见的每张 GPU，用torch.cuda.get_device_capability()取实际计算能力，并在最后一个架构后追加+PTX以保证前向兼容；
非 JIT（预编译/交叉编译）模式下，TORCH_CUDA_ARCH_LIST环境变量优先，其次使用get_default_compute_capabilities()返回的默认值（builder.py）：默认基础为6.0;6.1;7.0，若系统 CUDA 主版本 ≥ 11，则追加8.0;8.6（CUDA 11.0 特例仅追加8.0）；
最终每个架构都会生成-gencode=arch=compute_XX,code=sm_XX编译参数，+PTX架构还会额外生成-gencode=arch=compute_XX,code=compute_XX。

此外，builder.py 的assert_no_cuda_mismatch()会校验系统 nvcc 的 CUDA 版本与 PyTorch 编译所用 CUDA 版本是否一致（小版本在兼容列表内可放行，如 CUDA 10.x 与 11.x 各自内部的次版本），版本不匹配时编译会直接报错。

功能相关依赖

部分 DeepSpeed 功能除了通用依赖外，还需要额外的特定依赖：

Python 包依赖：各功能/op 对应的 Python 依赖请查看仓库的 requirements 目录，其中包含：
- requirements.txt：基础安装依赖（setup.py 的install_requires即读取此文件）；
- requirements-1bit-mpi.txt、requirements-inf.txt、requirements-autotuning.txt、requirements-autotuning-ml.txt、requirements-dev.txt、requirements-readthedocs.txt、requirements-sparse_attn.txt、requirements-sd.txt等，分别对应 1-bit 通信（MPI）、推理、自动调优、开发、文档构建、稀疏注意力等功能；
- setup.py 将这些需求映射为extras_require，即可以通过pip install deepspeed[all]、pip install deepspeed[1bit]、pip install deepspeed[inf]等 extras 方式按需安装。
系统级依赖：DeepSpeed 会尽量将系统级依赖控制在最少，但部分功能仍需要特殊的系统级软件包。请查看ds_report工具的输出，确认某个功能是否缺失系统级包。

以异步 NVMe I/O op（AIO）为例，op_builder/async_io.py 会通过编译并链接一个调用io_submit的测试程序来探测libaio是否存在；若缺失，会进一步通过dpkg/pacman/rpm等包管理器检测对应的libaio-dev/libaio/libaio-devel包并给出安装提示，同时建议可通过CFLAGS与LDFLAGS环境变量指定 libaio 头文件与库文件的搜索路径。

预编译 DeepSpeed 构建（PyPI）

官方文档对 "Pre-compiled DeepSpeed builds from PyPI" 标注为Coming soon（即将推出），即目前 PyPI 上的发布版本默认走 JIT 路径，尚未提供开箱即用的预编译二进制分发；如需预编译版本，请按上文方式自行构建 wheel。

常见安装问题速查

现象	原因与对策
`ds_report`中 op 状态为`compatible=NO`	缺少该系统 op 所需的系统级依赖（如 AIO 缺`libaio`），按报告提示安装对应系统包，或通过`DS_BUILD_*`环境变量置 0 跳过该 op
预编译时报错 "Unable to pre-compile ..."	该 op 被开启但与系统不兼容，按提示用对应`DS_BUILD_*`=0 禁用
运行时`no kernel image is available`	扩展未针对当前 GPU 架构构建，用`TORCH_CUDA_ARCH_LIST`重新构建
多虚拟环境加载扩展失败	用`TORCH_EXTENSIONS_DIR`为每个环境指定独立扩展目录
预编译时提示 torch 未安装	预编译路径（`DS_BUILD_OPS`系列）要求先装 PyTorch；JIT 模式无此要求

小结

DeepSpeed 的安装体系围绕"JIT 即时编译"与"预编译"两条路径展开：日常单机使用直接pip install deepspeed即可，配合ds_report验证环境；追求更快的首次运行、更可控的多机一致部署时，可通过DS_BUILD_OPS=1、单个DS_BUILD_*开关、-jN并行编译和bdist_wheel分发构建统一二进制；针对特定 GPU 架构可用TORCH_CUDA_ARCH_LIST定制；多虚拟环境场景用TORCH_EXTENSIONS_DIR隔离扩展缓存；特殊功能则按requirements/目录与ds_report提示补齐依赖。相关源码（setup.py、install.sh、op_builder/builder.py）与本文所述行为一一对应，可作为排查安装问题的第一手依据。