DeepSpeed config 全字段词典

7.1 这章怎么用

本章不是要你背全部字段，而是给一份"凭印象查得到"的索引：

• 新写一份 config 时，对照本章的 8 个"段落"组织 JSON；
• 看到不认识的字段 → 在本章按段落找；
• 本章找不到 → grep -rn '"<字段>"' deepspeed/runtime/config.py。

7.2 一份 config.json 的 8 个段落

{
  // 段落 1：batch / accumulation
  "train_batch_size":                  "auto",
  "train_micro_batch_size_per_gpu":    "auto",
  "gradient_accumulation_steps":       "auto",
  "gradient_clipping":                 1.0,
  "steps_per_print":                   100,
  "wall_clock_breakdown":              false,

  // 段落 2：精度（fp16 / bf16 二选一）
  "bf16": { "enabled": "auto" },
  "fp16": { "enabled": false },

  // 段落 3：optimizer
  "optimizer": {
    "type": "AdamW",
    "params": { "lr": 1e-4, "betas": [0.9, 0.95], "eps": 1e-8, "weight_decay": 0.01 }
  },

  // 段落 4：scheduler
  "scheduler": {
    "type": "WarmupDecayLR",
    "params": { "total_num_steps": 10000, "warmup_min_lr": 0, "warmup_max_lr": 1e-4, "warmup_num_steps": 200 }
  },

  // 段落 5：ZeRO（重头戏）
  "zero_optimization": {
    "stage": 3,
    "offload_optimizer": { "device": "cpu", "pin_memory": true },
    "offload_param":     { "device": "none" },
    "overlap_comm":      true,
    "contiguous_gradients": true,
    "stage3_gather_16bit_weights_on_model_save": true
  },

  // 段落 6：activation checkpointing
  "activation_checkpointing": {
    "partition_activations": false,
    "cpu_checkpointing":     false,
    "contiguous_memory_optimization": false,
    "synchronize_checkpoint_boundary": false,
    "profile": false
  },

  // 段落 7：通信 / 数据
  "communication_data_type":  "fp32",
  "prescale_gradients":       false,
  "data_efficiency": { ... },        // 数据效率（curriculum learning）

  // 段落 8：杂项
  "zero_allow_untested_optimizer": true,
  "zero_force_ds_cpu_optimizer":   true,
  "torch_compile":                { "enabled": false }
}

7.3 段落 1：batch / accumulation

7.4 段落 2：精度

7.5 段落 3：optimizer

支持的内置 type（来自 deepspeed/ops/adam/ 等）：

不在白名单的优化器（如 PyTorch 自带的 SGD）需要加：

"zero_allow_untested_optimizer": true

7.6 段落 4：scheduler

对 HF Trainer 来说，scheduler 通常由 Trainer 自己接管，不写这段更稳。

7.7 段落 5：zero_optimization

第 5、6 章已经讲过 stage 和 offload 字段，这里补全剩余项：

7.8 段落 6：activation_checkpointing

大模型训练几乎必开：

"activation_checkpointing": {
  "partition_activations":            true,    // ZeRO-3 时切激活
  "cpu_checkpointing":                false,   // 激活也 offload 到 CPU
  "contiguous_memory_optimization":   true,
  "number_checkpoints":               null,
  "synchronize_checkpoint_boundary":  false,
  "profile":                          false
}

HF Trainer 用户通常在 TrainingArguments 设 gradient_checkpointing=True 即可，DS 这段会自动衔接。

7.9 段落 7：通信 / 数据

7.10 段落 8：杂项 / debug

7.11 三份"开箱可用"的模板

A. 小模型 SFT（13B 以下 / 8 卡 / 显存够）

{
  "train_micro_batch_size_per_gpu":  "auto",
  "gradient_accumulation_steps":     "auto",
  "train_batch_size":                "auto",
  "gradient_clipping":               "auto",
  "bf16":  { "enabled": "auto" },
  "zero_optimization": {
    "stage": 2,
    "overlap_comm": true,
    "contiguous_gradients": true,
    "reduce_bucket_size": "auto",
    "allgather_bucket_size": "auto"
  }
}

B. 70B 全参 / 8 卡（要 offload）

{
  "train_micro_batch_size_per_gpu": "auto",
  "gradient_accumulation_steps":    "auto",
  "train_batch_size":               "auto",
  "gradient_clipping":              "auto",
  "bf16": { "enabled": "auto" },
  "zero_optimization": {
    "stage": 3,
    "offload_optimizer": { "device": "cpu", "pin_memory": true },
    "offload_param":     { "device": "cpu", "pin_memory": true },
    "overlap_comm": true,
    "contiguous_gradients": true,
    "sub_group_size": 1e9,
    "reduce_bucket_size": "auto",
    "stage3_prefetch_bucket_size": "auto",
    "stage3_param_persistence_threshold": "auto",
    "stage3_max_live_parameters": 1e9,
    "stage3_max_reuse_distance": 1e9,
    "stage3_gather_16bit_weights_on_model_save": true
  }
}

C. 极限 ZeRO-Infinity（NVMe offload）

{
  "train_micro_batch_size_per_gpu": "auto",
  "gradient_accumulation_steps":    "auto",
  "bf16": { "enabled": "auto" },
  "zero_optimization": {
    "stage": 3,
    "offload_optimizer": {
      "device": "nvme",
      "nvme_path": "/local_nvme/ds_swap",
      "pin_memory": true
    },
    "offload_param": {
      "device": "nvme",
      "nvme_path": "/local_nvme/ds_swap",
      "buffer_count": 5,
      "buffer_size": 1e8,
      "max_in_cpu": 1e9
    },
    "aio": {
      "block_size": 1048576,
      "queue_depth": 8,
      "thread_count": 1,
      "single_submit": false,
      "overlap_events": true
    },
    "overlap_comm": true,
    "stage3_gather_16bit_weights_on_model_save": true
  }
}

7.13 真实默认值表（从源码 grep 出来的，不是猜的）

到处都在写 "auto" 的副作用是：用户经常不知道"没写、也没填 auto 时默认值是多少"。下表是 deepspeed/runtime/zero/config.py 里 DeepSpeedZeroConfig（line 90 起）的真实默认值：

同文件还有 ZeroStageEnum（line 81）：

# runtime/zero/config.py:81
class ZeroStageEnum(Enum):
    disabled         = 0
    optimizer_states = 1   # 切优化器状态
    gradients        = 2   # 切优化器 + 梯度
    weights          = 3   # 切优化器 + 梯度 + 参数
    max_stage        = 3

7.14 deprecated 字段映射

这些字段在源码里通过 pydantic 的 json_schema_extra: { "deprecated": true } 标记。它们当下还能跑，但会出 deprecation warning，新项目别用。

7.15 2024 之后新增字段对照

7.16 字段拼错不会报错

校验方法：

1. 训练启动时关注首屏的 Unrecognized config field: ... warning；
2. 需要严格校验时，把字段名贴到 runtime/zero/config.py 或 runtime/config.py 里 grep 一下，不存在就肯定是拼错；
3. 用 python -c "from deepspeed.runtime.zero.config import DeepSpeedZeroConfig; print(DeepSpeedZeroConfig.model_fields.keys())" 直接列出所有合法字段名。

7.17 字段写错的常见提示