跳到主要内容

MT-DeepSpeed 新特性与 AutoEP

版本与验证范围

TrainingSuite v2.2.0 镜像中的 DeepSpeed 版本为 0.19.3。

Qwen3.5 多模态训练目前只验证了 Qwen3.5-35B-A3B + LLaVA-Pretrain。

1. v2.2.0 更新概览​

MT-DeepSpeed 主要新增和修复:

  1. 增加 Qwen3 系列 MoE 的 AutoEP 自动专家并行;
  2. 支持 Qwen3.5-35B-A3B 在 LLaVA-Pretrain 数据上的多模态训练;
  3. 修复 ZeRO-3 初始化时参数分片导致 Hugging Face 初始化未实际写入的问题;
  4. 适配 TrainingSuite v2.2.0 使用的 Transformers 5.16.1。

2. 版本检查​

进入容器后执行:

python3 - <<'PY'
import importlib.metadata
import deepspeed

print("deepspeed module:", deepspeed.__version__)
print("deepspeed package:", importlib.metadata.version("deepspeed"))
PY

ds_report

通过标准:

  • DeepSpeed 版本包含 0.19.3;
  • v2.2.0 容器检查结果为 0.19.3;
  • ds_report 显示 accelerator 为 musa;
  • musa_fused_adam 等所需 fused op 可用;
  • 所有训练节点使用相同的 DeepSpeed、PyTorch、torch_musa 和 Transformers 版本。

3. Transformers 5.16.1 适配​

Qwen3.5 和 AutoEP 要求 transformers>=5.2.0。TrainingSuite v2.2.0 使用 Transformers 5.16.1,并已完成结构性验证。

检查版本:

python3 - <<'PY'
import transformers

print("transformers:", transformers.__version__)
PY

注意:

  • 不要执行测试目录中的 pip install -r req.txt,该文件会把 Transformers 固定回 4.57.0;
  • Transformers 5.16 起,modeling_qwen3_5_moe 不再提供模块级 chunk_gated_delta_rule;
  • _enable_fla_delta_rule() 在检测不到该钩子时直接返回,DeltaNet 由 Transformers 自己分发;
  • 没有 [FLA] 日志不代表失败,也不再依赖 fla-core;
  • 更早版本仍带该钩子时,才会将 FLA kernel 赋给 DeltaNet;ENABLE_FLA=0 可强制使用 Torch 路径。

4. AutoEP 自动专家并行​

AutoEP 将 MoE 专家按 EP 维度切分并常驻对应 rank,使其不参与 ZeRO-3 每一步的 all-gather。

4.1 已验证模型​

模型启动脚本测试层数专家配置
Qwen3-30B-A3Brun_qwen3_30B_autoep.sh24 层128 个专家,EP=8,每卡 16 个
Qwen3.5-35B-A3Brun_qwen3_5_35b_autoep.sh20 层256 个专家,EP=8,每卡 32 个

以上是当前已接入并完成验证的两个 MoE 模型。未列出的模型不因为结构接近而自动获得支持。

4.2 配置​

utils/ds_utils.py 中的 get_train_ds_config(enable_autoep=True, ...) 会注入:

"expert_parallel": {
"enabled": true,
"autoep_size": 8,
"preset_model": "qwen3_moe",
"use_grouped_mm": false
}

约束:

  • autoep_size 必须同时整除专家数和 world size;
  • use_grouped_mm 固定为 false,当前环境没有 torch._grouped_mm;
  • 修改 autoep_size 后重新核对专家数、GPU 数和并行拓扑。

4.3 必须完成的接线​

optimizer 写入 DeepSpeed 配置​

AutoEP 在 deepspeed.initialize() 中替换 MoE 层,并重建 w1、w2 和 w3。需要:

model_engine, optimizer, _, _ = deepspeed.initialize(
model=model,
model_parameters=model.parameters(),
config=ds_config,
optimizer=None,
)

如果将提前创建的 client optimizer 传给 DeepSpeed,它仍持有替换前的 Parameter,训练不会报错,但专家参数实际不更新。

不标记旧 SparseMoeBlock 的 ZeRO-3 leaf​

启用 AutoEP 时,不要把 SparseMoeBlock 标记为 ZeRO-3 leaf。该 leaf 指向即将被替换的旧模块,无法覆盖 AutoEP 新建的专家参数。

多模态模型只替换语言模型 MoE​

在 Qwen3.5-35B-A3B 中,AutoEP 只替换:

language_model.layers.*.mlp

视觉塔仍使用普通 ZeRO。

4.4 启动验证​

启动后日志必须出现替换记录,例如 Qwen3.5-35B-A3B 当前测试配置为:

[AutoEP] replaced 20 MoE layer(s) with autoep_size=8

20 必须等于当前文本骨干层数。日志没有出现该行、替换数量为 0 或数量与配置不一致时,不要继续训练。

结构性回归由 test_autoep_preset.py 覆盖,并接入 run_musa_ut.sh。该测试检查 preset 解析、文本骨干层匹配、模块路径、Qwen3-MoE 匹配和从 config 读取专家数/top-k。升级 Transformers 后,先执行该测试,避免 AutoEP 匹配到 0 层但不报错。

5. Qwen3.5-35B-A3B 多模态训练​

5.1 验证范围​

当前验证范围仅为:

  • 模型:Qwen3.5-35B-A3B;
  • 数据:LLaVA-Pretrain;
  • 模式:从模型配置随机初始化,不加载模型权重;
  • 目的:结构性和训练链路验证。

5.2 准备模型配置​

测试只下载 config、tokenizer 和 preprocessor,不下载 safetensors:

modelscope download \
--model Qwen/Qwen3.5-35B-A3B \
--include '*.json' '*.txt' '*.jinja' 'tokenizer*' \
--exclude '*.safetensors' \
--local_dir model_configs/Qwen3.5-35B-A3B

启动脚本检测到模型目录中存在 safetensors 时会拒绝启动。该限制用于明确当前流程只做 from_config 随机初始化训练。

5.3 启动多模态训练​

DATASET=/path/to/llava_pretrain \
bash ./run_qwen3_5_35b_autoep.sh \
./outputs/qwen3.5-35b

训练入口与纯文本模型不同:

  • 使用 AutoModelForImageTextToText,而不是 AutoModelForCausalLM;
  • MoE 字段位于 text_config,需要从 config.get_text_config() 读取;
  • --num_hidden_layers 只裁剪 text_config.num_hidden_layers 和 layer_types 前缀,不裁剪视觉塔 depth;
  • 训练入口在导入 Transformers 之前先导入 torchada,使后续 PEFT 和 bitsandbytes 使用 MUSA 接口。

5.4 多模态数据要求​

数据通过 utils/data/vl_data.py 处理:

  • 使用 processor 和 DataCollatorVisionLanguage,不使用纯文本 tokenizer/collator;
  • 保留 mm_token_type_ids;
  • pixel_values 使用 cat,不能对不同图片 patch 数使用 stack;
  • 视觉输入使用扁平张量 pixel_values 和 image_grid_thw;
  • 图像块放在输入前部;
  • prompt 部分的 labels 设置为 -100,只对 caption 计算 loss。

vl_data.py 当前只支持 LLaVA-Pretrain 记录格式:

conversations
from: human | gpt
<image>

更换数据集前先核对字段命中率。脚本大量使用默认值兜底,字段不匹配时可能不报错,而是静默训练空文本或回退到合成图像。

6. ZeRO-3 初始化修复​

问题原因:

  • deepspeed.zero.Init 创建模型时,Hugging Face _init_weights 作用于 0 元素参数分片,初始化变成 no-op;
  • 专家权重保留未初始化内存,实际测试中出现 NaN;
  • router 权重可能保持全零;
  • 参数分片导致初始化结果没有真正写回完整参数。

修复流程:

  1. 先按模块聚合需要初始化的参数;
  2. 在完整参数上重新执行初始化;
  3. 增加跨 rank 异常检查,及时发现 NaN、全零 router 和初始化结果不一致;
  4. Qwen3.5 视觉语言模型在 hf 策略下先用 no_init_weights() 包住建模型流程;
  5. ZeRO-3 建模型后调用 _redo_init_under_zero3()。

相关单元测试:

test_init_under_zero3.py

出现专家 loss 异常、router 权重全零或初始 loss 明显异常时,应优先检查 ZeRO-3 初始化修复是否生效,而不是先调整学习率或数据。

7. 常见问题​

7.1 AutoEP 没有替换任何层​

检查:

  • Transformers 版本是否满足 >=5.2.0;
  • test_autoep_preset.py 是否通过;
  • 模型 preset 是否解析到文本骨干;
  • num_experts 和 top_k 是否从 config.get_text_config() 读取;
  • 日志中的替换层数是否等于文本层数。

7.2 AutoEP 开启后专家参数不更新​

检查是否把 optimizer 写进 ds_config,并确认调用:

deepspeed.initialize(..., optimizer=None)

7.3 打开 AutoEP 时报 grouped GEMM 相关错误​

当前环境不支持 torch._grouped_mm,保持:

"use_grouped_mm": false

7.4 Qwen3.5 多模态 loss 快速塌缩​

确认 prompt token 的 labels 全部为 -100,只保留 caption 监督;同时确认图像块前置并检查 pixel_values 使用 cat。

7.5 没有 [FLA] 日志​

Transformers 5.16 已由自身分发 DeltaNet,不再依赖模块级 FLA 钩子。没有 [FLA] 日志本身不代表失败。

8. 相关文档​