DeepSpeed 提供了一个强大的命令行工具（deepspeed），用于启动分布式训练、配置环境、调试和监控训练过程。通过命令行参数，用户可以灵活地控制训练行为、硬件分配和 DeepSpeed 的优化功能。以下是对 DeepSpeed 命令行工具常用参数的全面列举和详细解释，内容结构化、深入且实用，适合你作为人工智能工程师学习和应用 DeepSpeed 的需求。

---

1. DeepSpeed 命令行工具概述

DeepSpeed 的命令行工具通过 deepspeed 命令启动训练脚本，自动管理分布式环境、GPU 分配和优化配置。它与 PyTorch 脚本结合使用，简化了分布式训练的复杂性。基本用法如下：

deepspeed [options] train.py [script_args]

• train.py：用户编写的 PyTorch 训练脚本，集成了 DeepSpeed（如使用 deepspeed.initialize()）。
• [options]：DeepSpeed 提供的命令行参数，用于配置训练环境和优化。
• [script_args]：传递给 train.py 的自定义参数。

核心功能：

• 初始化分布式训练环境（基于 torch.distributed 和 NCCL）。
• 分配 GPU 和节点资源。
• 加载 DeepSpeed 配置文件（ds_config.json）。
• 提供调试、日志和性能监控工具。

---

2. 常用命令行参数

以下是 DeepSpeed 命令行工具的常用参数列表（基于 DeepSpeed v0.14.0，截至 2025 年 4 月），按功能分类，并附详细解释和示例。

2.1 分布式训练参数

这些参数用于配置分布式训练的硬件分配和通信。

1. --num_gpus

   • 描述：指定每个节点使用的 GPU 数量。
   • 类型：整数（默认：使用所有可用 GPU）。
   • 作用：控制单节点内的 GPU 分配，适用于多 GPU 训练。
   • 示例：

     deepspeed --num_gpus 4 train.py
     

     使用 4 张 GPU 运行 train.py。
   • 注意：如果未指定，DeepSpeed 会尝试使用所有可用 GPU（通过 CUDA_VISIBLE_DEVICES 或硬件检测）。

2. --num_nodes

   • 描述：指定分布式训练的节点数量。
   • 类型：整数（默认：1）。
   • 作用：控制多节点分布式训练的规模，适用于集群环境。
   • 示例：

     deepspeed --num_nodes 2 --num_gpus 8 train.py
     

     在 2 个节点上运行，每个节点使用 8 张 GPU（共 16 张 GPU）。
   • 注意：需要集群管理工具（如 Slurm）或手动设置节点通信。

3. --hostfile

   • 描述：指定主机文件路径，定义多节点训练的主机列表和 GPU 分配。
   • 类型：字符串（默认：无）。
   • 作用：用于多节点训练，指定每个节点的 IP 地址和可用 GPU。
   • 示例：

     deepspeed --hostfile hostfile.txt train.py
     

     hostfile.txt 示例：

     node1 slots=8
     node2 slots=8
     

     表示 node1 和 node2 各有 8 张 GPU。
   • 注意：主机文件需与集群环境一致，IP 地址需可达。

4. --master_addr

   • 描述：指定主节点的 IP 地址，用于分布式通信。
   • 类型：字符串（默认：127.0.0.1）。
   • 作用：定义主节点地址，确保所有节点能够通信。
   • 示例：

     deepspeed --master_addr 192.168.1.100 train.py
     

   • 注意：多节点训练时必须设置，且主节点需可访问。

5. --master_port

   • 描述：指定主节点的通信端口。
   • 类型：整数（默认：随机端口）。
   • 作用：避免端口冲突，确保分布式通信正常。
   • 示例：

     deepspeed --master_addr 192.168.1.100 --master_port 29500 train.py
     

   • 注意：确保端口未被占用。

6. --include / --exclude

   • 描述：指定或排除特定主机或 GPU 用于训练。
   • 类型：字符串（格式：host:device_list）。
   • 作用：精细控制 GPU 分配，适合异构集群或调试。
   • 示例：

     deepspeed --include localhost:0,1 train.py
     

     仅使用本地的 GPU 0 和 GPU 1。

     deepspeed --exclude node1:0 train.py
     

     排除 node1 的 GPU 0。
   • 注意：优先级高于 --num_gpus 和 --hostfile。

2.2 DeepSpeed 配置参数

这些参数用于加载和控制 DeepSpeed 的优化配置。

7. --deepspeed_config

   • 描述：指定 DeepSpeed 配置文件路径（JSON 格式）。
   • 类型：字符串（默认：无）。
   • 作用：加载优化配置（如 ZeRO 阶段、混合精度、并行策略等）。
   • 示例：

     deepspeed --deepspeed_config ds_config.json train.py
     

     加载 ds_config.json 中的配置。
   • 注意：
     • 配置文件定义了训练的关键优化参数（如 zero_optimization、fp16）。
     • 如果未提供，DeepSpeed 使用默认配置（无优化）。

8. --deepspeed

   • 描述：启用 DeepSpeed 优化（与 --deepspeed_config 等效）。
   • 类型：字符串（默认：无）。
   • 作用：加载配置文件，简化命令（常用于 Hugging Face 集成）。
   • 示例：

     deepspeed --deepspeed ds_config.json train.py
     

   • 注意：与 --deepspeed_config 功能相同，优先级相同。

2.3 环境与调试参数

这些参数用于配置运行环境、日志和调试。

9. --local_rank

   • 描述：指定当前进程的本地秩（Local Rank）。
   • 类型：整数（默认：由 DeepSpeed 自动分配）。
   • 作用：用于多 GPU 训练，标识每个 GPU 的进程。
   • 示例：

     deepspeed --local_rank 0 train.py
     

   • 注意：通常由 DeepSpeed 或集群管理工具自动设置，用户无需手动指定。

10. --no_python

    • 描述：禁用 Python 脚本执行，直接运行底层命令。
    • 类型：布尔（默认：False）。
    • 作用：用于调试或运行非 Python 脚本。
    • 示例：

      deepspeed --no_python --num_gpus 4 some_binary
      

    • 注意：高级用法，普通用户很少使用。

11. --no_local_rank

    • 描述：禁用 local_rank 参数传递。
    • 类型：布尔（默认：False）。
    • 作用：避免脚本接收 local_rank 参数，适合特定场景。
    • 示例：

      deepspeed --no_local_rank train.py
      

    • 注意：仅在脚本不依赖 local_rank 时使用。

12. --log_dir

    • 描述：指定日志文件保存目录。
    • 类型：字符串（默认：无）。
    • 作用：保存训练日志（如内存使用、性能指标）。
    • 示例：

      deepspeed --log_dir logs train.py
      

    • 注意：推荐启用，便于调试和性能分析。

13. --log_level

    • 描述：设置日志级别。
    • 类型：字符串（选项：debug、info、warning、error，默认：info）。
    • 作用：控制日志详细程度，调试时使用 debug。
    • 示例：

      deepspeed --log_level debug train.py
      

    • 注意：debug 模式会生成详细日志，可能影响性能。

14. --force_multi

    • 描述：强制启用多进程模式，即使单 GPU。
    • 类型：布尔（默认：False）。
    • 作用：确保一致的分布式行为，适合调试。
    • 示例：

      deepspeed --force_multi train.py
      

    • 注意：仅在调试单 GPU 兼容性时使用。

2.4 集群管理参数

这些参数用于与集群管理工具（如 Slurm、PBS）集成。

15. --launcher

    • 描述：指定分布式训练启动器。
    • 类型：字符串（选项：pdsh、slurm、mpi，默认：pdsh）。
    • 作用：适配不同的集群管理工具。
    • 示例：

      deepspeed --launcher slurm train.py
      

      使用 Slurm 启动分布式训练。
    • 注意：需确保集群环境支持指定启动器。

16. --detect_nvlink_pairs

    • 描述：检测 GPU 之间的 NVLink 连接。
    • 类型：布尔（默认：False）。
    • 作用：优化 GPU 通信，利用 NVLink 提高性能。
    • 示例：

      deepspeed --detect_nvlink_pairs train.py
      

    • 注意：仅在支持 NVLink 的硬件（如 NVIDIA DGX）上有效。

17. --autotuning

    • 描述：启用自动调优，动态优化训练参数。
    • 类型：布尔（默认：False）。
    • 作用：自动调整批次大小、学习率等，最大化性能。
    • 示例：

      deepspeed --autotuning train.py
      

    • 注意：实验性功能，可能需要额外配置。

2.5 其他参数

18. --module

    • 描述：指定 Python 模块运行（替代脚本文件）。
    • 类型：字符串（默认：无）。
    • 作用：运行模块而非 .py 文件。
    • 示例：

      deepspeed --module my_package.train
      

    • 注意：适合运行打包的 Python 模块。

19. --no_ssh_check

    • 描述：禁用 SSH 连接检查。
    • 类型：布尔（默认：False）。
    • 作用：跳过多节点训练的 SSH 验证，加快启动。
    • 示例：

      deepspeed --no_ssh_check train.py
      

    • 注意：仅在确认 SSH 配置正确时使用。

20. --help

    • 描述：显示命令行帮助信息。
    • 类型：布尔（默认：False）。
    • 作用：列出所有可用参数和描述。
    • 示例：

      deepspeed --help
      

---

3. 典型使用场景与示例

以下是一些常见场景下的命令行参数使用示例，展示如何结合参数运行训练。

3.1 单节点多 GPU 训练

deepspeed --num_gpus 4 --deepspeed_config ds_config.json train.py --batch_size 16

• 使用 4 张 GPU，加载 ds_config.json。
• 传递 --batch_size 16 给 train.py。

3.2 多节点分布式训练

deepspeed --num_nodes 2 --num_gpus 8 --hostfile hostfile.txt --master_addr 192.168.1.100 --master_port 29500 --deepspeed_config ds_config.json train.py

• 在 2 个节点上运行，每个节点 8 张 GPU。
• 使用 hostfile.txt 指定节点，设置主节点地址和端口。

3.3 调试模式

deepspeed --num_gpus 2 --log_level debug --log_dir logs train.py

• 使用 2 张 GPU，启用调试日志，保存到 logs 目录。
• 便于排查内存或通信问题。

3.4 Slurm 集群训练

deepspeed --launcher slurm --num_nodes 4 --num_gpus 8 --deepspeed_config ds_config.json train.py

• 在 Slurm 集群上运行，4 个节点，每个节点 8 张 GPU。

3.5 单 GPU 优化

deepspeed --num_gpus 1 --force_multi --deepspeed_config ds_config.json train.py

• 在单 GPU 上运行，强制多进程模式，确保兼容性。

---

4. 参数注意事项

4.1 参数优先级

• 命令行参数（如 --num_gpus）优先于环境变量（如 CUDA_VISIBLE_DEVICES）。
• --deepspeed_config 的配置优先于脚本中的默认设置。
• --include/--exclude 优先于 --num_gpus 和 --hostfile。

4.2 分布式环境

• 多节点训练需要正确配置 --master_addr 和 --master_port。
• 确保所有节点安装了相同的 DeepSpeed 版本和依赖（如 NCCL、CUDA）。

4.3 日志与调试

• 始终启用 --log_dir 保存日志，便于分析性能和错误。
• 使用 --log_level debug 排查分布式通信或内存问题。

4.4 集群兼容性

• 使用 --launcher 适配集群环境（如 Slurm）。
• 确保主机文件（--hostfile）与集群配置一致。

4.5 性能优化

• 启用 --detect_nvlink_pairs 利用 NVLink 加速通信。
• 实验 --autotuning 自动优化批次大小和学习率。

---

5. 常见问题与解答

1. 为什么 --num_gpus 未生效？

   • 检查 CUDA_VISIBLE_DEVICES 是否限制了 GPU 可见性。
   • 确保 --include/--exclude 未覆盖 --num_gpus。

2. 如何调试分布式训练失败？

   • 启用 --log_level debug 和 --log_dir。
   • 检查 --master_addr 和 --master_port 是否正确。
   • 使用 deepspeed --check 测试环境。

3. 单 GPU 训练需要哪些参数？

   • 设置 --num_gpus 1，禁用分布式初始化（脚本中设置 dist_init_required=False）。
   • 使用 --force_multi 确保兼容性。

4. 如何优化多节点通信？

   • 使用高带宽网络（如 InfiniBand）。
   • 启用 --detect_nvlink_pairs（如果硬件支持）。
   • 在配置文件中启用通信压缩（"compress_communication": true）。

---

6. 进阶用法

6.1 结合环境变量

DeepSpeed 支持通过环境变量覆盖部分参数，例如：

export CUDA_VISIBLE_DEVICES=0,1
deepspeed train.py

限制训练使用 GPU 0 和 1。

6.2 自定义启动器

对于非标准集群，可以自定义启动器：

deepspeed --launcher mpi train.py

使用 MPI 启动分布式训练。

6.3 性能监控

结合 --log_dir 和 DeepSpeed 的性能分析工具：

from deepspeed.utils import memory_status
memory_status()  # 打印内存使用情况

6.4 与 Hugging Face 集成

Hugging Face 的 transformers.Trainer 支持 DeepSpeed 命令行：

deepspeed --deepspeed ds_config.json train.py --hf_deepspeed_config

---

7. 学习资源

• 官方文档：https://www.deepspeed.ai/docs/
• 命令行参考：https://deepspeed.readthedocs.io/en/latest/
• GitHub 仓库：https://github.com/microsoft/DeepSpeed
• 示例：https://github.com/microsoft/DeepSpeedExamples