HyperParallel Trainer 接入 qwen3_vl_moe

本任务涉及围为 qwen3_vl_moe

背景

HyperParallel Trainer 已经具备基础的 FSDP、TP 和通用训练能力，但不同模型在权重加载、模型配置、输入数据和保存恢复流程上仍需要模型专用接入。

Qwen3-VL-MoE 同时包含文本 Decoder 和视觉 Encoder。要让它真正进入 Trainer 的可用模型范围，需要补齐训练模板、模型并行接入、checkpoint 保存恢复、集成测试和使用文档，并用单卡结果验证多卡训练的精度一致性。

任务目标

• 完成 qwen3_vl_moe 的 Trainer 训练接入；
• 提供可直接修改模型路径的训练配置模板；
• 使用现有 FSDP / TP 训练路径完成 2 卡训练；
• 支持训练 checkpoint 保存和断点恢复；
• 补充模型级集成测试、视觉塔前向回归测试和使用文档；
• 与 HyperParallel 单卡基线完成 100 step loss 对齐；
• 在条件允许时补充 Hugging Face + LlamaFactory 单卡结果作为外部参考。

功能需求

1. 模型训练接入

需要在现有 hyper_parallel/models/ 和 Trainer 发现机制下完成 qwen3_vl_moe 的训练入口，确保：

• model.name: qwen3_vl_moe 可以被 Trainer 正确识别；
• 模型权重和 tokenizer 路径可以通过配置传入；
• Qwen3-VL-MoE 的权重命名和模型配置可以正确加载；
• VL 模型的配置覆盖项可以正确生效；
• forward、loss、backward 和 optimizer step 能够进入正常训练流程；
• 使用现有 TP 参数切分和 FSDP 并行能力完成 2 卡训练。

2. 训练配置模板

需要提供：

examples/qwen3_vl_30b_a3b_instruct/train.yaml

模板至少包含：

• 模型权重和 tokenizer 路径；
• model.name: qwen3_vl_moe；
• VL 配置开关；
• 数据和序列长度配置；
• optimizer、mixed precision 和 gradient checkpointing 配置；
• 2 卡 accelerator 配置；
• 100 step 短训练配置；
• checkpoint 保存和恢复配置。

建议的 checkpoint 配置：

train:
  max_steps: 100
  checkpoint:
    output_dir: outputs/qwen3_vl_moe
    save_steps: 50
    load_path: null

视觉侧的 vision_parallel 可以作为 qwen3_vl_moe 模型专用配置保留，用于验证视觉塔并行路径，但它不是本任务的主要验收对象。

3. 保存和恢复

需要验证：

• 训练过程中可以按 save_steps 保存 checkpoint；
• 指定 load_path 可以从已有 checkpoint 继续训练；
• 模型参数、优化器状态、学习率调度器状态、随机数状态和 dataloader 状态能够恢复；
• 中断后恢复训练的 loss 与不中断训练的对应阶段保持一致；
• 保存恢复不引入新的、与现有 Trainer 不兼容的 checkpoint 格式。

4. 集成测试

需要补充覆盖以下内容的测试：

• qwen3_vl_moe 1 卡训练 smoke；
• qwen3_vl_moe 2 卡 FSDP / TP 训练 smoke；
• checkpoint 保存和恢复；
• 视觉塔 forward 语义回归；
• 多卡首步 loss 与单卡基线的自洽检查。

当前代码对应的测试入口可以放在：

tests/torch/qwen3_vl_moe/test_qwen3_vl_moe_vision_parity.py
tests/torch/qwen3_vl_moe/test_qwen3_vl_moe_vl_trainer.py

5. 使用文档

需要提供：

• docs/guide/qwen3_vl_moe.md；
• docs/index.md 中的文档入口；
• 模型路径、启动命令、保存路径和恢复方式说明；
• 2 卡训练和 loss 对齐验证方法；
• 不同并行配置的使用限制说明。

6. 精度对齐

主验收以 HyperParallel 单卡训练结果为基线：

1. 使用相同模型、数据、随机种子、优化器和训练超参；
2. 分别运行单卡和 2 卡训练；
3. 记录前 100 step 的 loss；
4. 比较 100 step 平均 loss。

验收标准：

abs(mean_loss_2card - mean_loss_1card) <= 5e-3

如果环境允许，额外与 Hugging Face + LlamaFactory 的单卡结果进行参考对比。外部框架结果只作为补充，不替代 HyperParallel 单卡基线。

验收命令

1. 训练模板

export HYPER_PARALLEL_PLATFORM=torch
export ASCEND_VISIBLE_DEVICES=0,1
export TORCH_DEVICE_BACKEND_AUTOLOAD=0

python -m hyper_parallel.trainer.launch \
  --config examples/qwen3_vl_30b_a3b_instruct/train.yaml

2. 视觉塔回归测试

export HYPER_PARALLEL_PLATFORM=torch
python -m pytest -q \
  tests/torch/qwen3_vl_moe/test_qwen3_vl_moe_vision_parity.py

3. Qwen3-VL-MoE 集成测试

export HYPER_PARALLEL_PLATFORM=torch
export ASCEND_VISIBLE_DEVICES=0,1
export TORCH_DEVICE_BACKEND_AUTOLOAD=0

python -m pytest -q \
  tests/torch/qwen3_vl_moe/test_qwen3_vl_moe_vl_trainer.py -s

当前验证记录

以下为当前服务器上已实际完成的 NPU 验证记录。

1. 环境信息

检查项	实际记录
NPU 型号和数量	2 x Ascend 910B2C，npu-smi 26.0.rc1，健康状态 OK
Python 版本	Python 3.10.20
PyTorch / torch-npu 版本	torch 2.6.0+cpu / torch-npu 2.6.0.post5
MindSpore 版本	MindSpore 2.9.0
CANN 版本	CANN 8.5.1
模型权重路径	未配置真实权重路径，当前使用 smoke 配置验证

2. 训练和精度结果

场景	step 数	平均 loss	与单卡差值	结论
HyperParallel 单卡 baseline	100	11.91719316959381	0	通过
HyperParallel 2 卡 FSDP / TP	100	11.917016038894653	1.7713e-4	通过
checkpoint 恢复训练	50（恢复后）	11.911257915496826	2.4796e-7（对齐 baseline 51-100 step 区间）	通过
Hugging Face + LlamaFactory 参考	100	11.919068269729614	1.8751e-3（仅参考）	通过

3. 保存恢复结果

检查项	实际结果
是否生成 checkpoint	是，step_50 和 step_100 目录均已生成，包含模型、优化器、scheduler、RNG 和 dataloader 状态
是否可以从 load_path 恢复	是，从训练过程中生成的 checkpoint-50 可正常恢复
恢复后 loss 是否连续	是，恢复首步 loss 与 baseline 第 51 步差值约 9.5e-7
恢复训练与不中断训练是否一致	是，恢复段 mean loss 与 baseline 51-100 step 区间差值约 2.5e-7

4. 性能和可靠性结果

场景	mean step time	tokens/s	peak memory	备注
单卡 baseline	0.030586 s	3643.17	427.68 MB	100 step smoke
2 卡 FSDP / TP	0.050384 s	2155.93	323.61 MB	100 step smoke

补充说明：单卡与 2 卡首步 loss 完全一致，均为 11.931214332580566；视觉塔回归测试 tests/torch/qwen3_vl_moe/test_qwen3_vl_moe_vision_parity.py 已通过。

外部参考补充：使用 LlamaFactory v1 + Hugging Face tiny-random/qwen3-vl-moe 在单 NPU npu:0 上完成 100 step 多模态 demo SFT，mean_loss=11.919068269729614，last_loss=11.922738075256348。验证时使用了本机临时工作目录生成的配置、数据副本和兼容层，最终在临时输出目录中生成了 checkpoint-50 和 checkpoint-100。
该结果只作为外部训练链路 smoke。