一、概述

本文档介绍如何在百舸（AIHC）开发机中，使用百舸提供的 diffsynth 训练加速镜像，对 Wan2.2-T2V-A14B 文生视频 MoE 扩散模型执行全参微调。

镜像已预装训练代码与全部 Python 依赖，开箱即用，无需额外安装虚拟环境；内置的启动脚本自适应单机与多机拓扑，进程数与通信参数全部由平台注入的环境变量推导，使用者无需修改。

二、适用场景

• 需要在自有视频数据上微调 Wan2.2-T2V-A14B（high_noise 专家）的文生视频任务。
• 需要单机多卡或多机多卡分布式训练。
• 希望直接复用已调优的启动脚本与并行配置，减少环境搭建与参数调试成本。

三、模型简介

Wan2.2-T2V-A14B 是 Wan2.2 系列的文生视频 MoE 扩散模型，按 timestep 分成 high_noise 与 low_noise 两个专家。本文的训练流程只微调 high_noise 专家的 DiT（--max_timestep_boundary 0.417、--trainable_models "dit"），low_noise 不加载，因此权重只需取 high_noise_model/*。

训练框架为 DiffSynth-Studio，使用 accelerate + DeepSpeed ZeRO-2，配合 USP（unified sequence parallel，本文配置 --sp_size 1，即不切序列、纯数据并行）。文本编码器使用 UMT5-XXL，VAE 使用 Wan2.1_VAE（TI2V-5B 走 Wan2.2_VAE，同仓库但不可混用）。

四、环境与资源要求

镜像内目录结构：

1/root/workspace/DiffSynth-Studio/
2├── diffsynth/                          # 源码（未安装进 site-packages）
3├── examples/
4│   └── wanvideo/
5│       └── model_training/
6│           ├── train.py
7│           └── full/                   # 启动脚本 + accelerate/deepspeed 配置
8├── models/                             # 权重挂载点（镜像内为空）
9│   └── train/                          # 训练输出
10└── TestVidData/
11    └── video_1sampe/                   # 592 KB 单样本冒烟数据

diffsynth 未安装到 site-packages，而是从源码目录导入，因此启动脚本必须设置 PYTHONPATH（内置脚本已处理，无需手动设置）。

五、准备工作：创建百舸开发机

本文的训练流程包含准备权重、校验、按需调参重跑等交互式操作，建议在百舸开发机中执行：

1. 登录百舸平台，进入「开发机」创建页。
2. 选择推荐加速卡资源规格：lgn7ib × 8（单机；多机训练时按需申请多节点）。
3. 挂载权重存储目录，挂载点与后文 MODEL_BASE_PATH 保持一致（默认 /root/workspace/DiffSynth-Studio/models）。
4. 如需使用自有数据集，挂载数据集存储目录。
5. 开发机启动后，打开终端（或 WebIDE 终端），进入代码目录：

1cd /root/workspace/DiffSynth-Studio

后续「准备模型权重」「准备数据集」「启动训练」等命令均在该终端中按顺序执行。

六、准备模型权重

镜像不含权重。权重目录约定为 ${MODEL_BASE_PATH}/<org>/<repo>/...，涉及两个 org：Wan-AI 与 DiffSynth-Studio。

MODEL_BASE_PATH 默认为 ${WORKSPACE_DIR}/models，须与开发机的权重挂载点一致。

6.1 权重清单

A14B 训练需要下面 4 个仓库，共约 69 GB：

仓库 2、3、4 虽未出现在启动命令的 --model_id_with_origin_paths 中，但训练过程会强制加载，缺失时报错信息不会直接指出缺哪个文件，请务必备齐。详见「常见问题」。

6.2 从 BOS 下载

1# 仓库 1：Wan2.2-T2V-A14B 主权重
2bosutil cp -r bos:/aihc-models-bj/Wan-AI/Wan2.2-T2V-A14B/ ${MODEL_BASE_PATH}/Wan-AI/Wan2.2-T2V-A14B/
3
4# 仓库 2：Wan-Series-Converted-Safetensors（T5 / VAE）
5bosutil cp -r bos:/aihc-models-bj/noodlepop/Wan-Series-Converted-Safetensors/ ${MODEL_BASE_PATH}/DiffSynth-Studio/Wan-Series-Converted-Safetensors/
6
7# 仓库 3：Wan2.1-T2V-1.3B（tokenizer）
8bosutil cp -r bos:/aihc-models-bj/Wan-AI/Wan2.1-T2V-1.3B/ ${MODEL_BASE_PATH}/Wan-AI/Wan2.1-T2V-1.3B/
9
10# 仓库 4：Wan2.2-S2V-14B（audio processor 配置）
11bosutil cp -r bos:/aihc-models-bj/Wan-AI/Wan2.2-S2V-14B/ ${MODEL_BASE_PATH}/Wan-AI/Wan2.2-S2V-14B/

6.3 校验

权重落地后先确认 glob 能匹配到文件，否则会在加载阶段报难以定位的错误：

1M=${MODEL_BASE_PATH:-/workspace/DiffSynth-Studio/models}
2ls $M/Wan-AI/Wan2.2-T2V-A14B/high_noise_model/diffusion_pytorch_model*.safetensors | wc -l   # 应 > 0
3ls $M/DiffSynth-Studio/Wan-Series-Converted-Safetensors/models_t5_umt5-xxl-enc-bf16.safetensors
4ls $M/DiffSynth-Studio/Wan-Series-Converted-Safetensors/Wan2.1_VAE.safetensors
5ls $M/Wan-AI/Wan2.1-T2V-1.3B/google/umt5-xxl/
6ls $M/Wan-AI/Wan2.2-S2V-14B/wav2vec2-large-xlsr-53-english/

七、准备数据集

镜像内置单样本冒烟数据集 TestVidData/video_1sampe（592 KB），可直接用于跑通验证，无需额外下载。

如需使用完整数据集，从 BOS 下载：

1mkdir -p /root/workspace/datasets/VidData
2bosutil cp -r bos:/<your-bucket>/<path-to-dataset>/ /workspace/datasets/VidData/

完整数据集尚未上传至百舸 BOS，请联系百舸相关人员协助上传后获取实际路径。 自定义数据集需包含视频文件与 metadata.csv，目录结构参考镜像内置的 TestVidData/video_1sampe。下载完成后通过 DATA_PATH 指向数据目录即可。

八、配置训练环境变量

启动脚本已为下列变量设置默认值，仅在需要覆盖时显式传入。

九、关键训练参数说明

启动脚本自适应单机 / 多机，进程数与拓扑全部由平台注入的环境变量推导，使用者无需修改拓扑相关参数。

--model_id_with_origin_paths 中写的是 .pth 原始文件名，框架会自动改写成 Converted-Safetensors 仓库中的 .safetensors，请勿手工改成 .safetensors。

十、启动训练

在开发机终端中执行内置启动脚本，单机与多机使用同一脚本：

1S=/root/workspace/DiffSynth-Studio/examples/wanvideo/model_training/full/Wan2.2-T2V-A14B.sh
2
3bash "$S"                      # 默认 DATASET_REPEAT=1000、2 epoch，单机 8 卡约 250 step
4TARGET_STEPS=70 bash "$S"      # 只跑 70 step，单机 8 卡与双机 16 卡都是 70 step
5DATASET_REPEAT=5000 bash "$S"  # 长稳测试，按样本数控制

如需切换数据目录或输出目录：

1DATA_PATH=/root/workspace/datasets/VidData bash "$S"
2OUTPUT_DIR=/root/workspace/outputs bash "$S"

10.1 启动脚本内容

脚本位于 /root/workspace/DiffSynth-Studio/examples/wanvideo/model_training/full/Wan2.2-T2V-A14B.sh，单机 / 多机合并为一份，靠平台注入的变量自动判断（百舸 PyTorch 任务默认注入 MASTER_ADDR / MASTER_PORT / RANK / WORLD_SIZE / NPROC_PER_NODE，其中 RANK 是节点序号、WORLD_SIZE 是节点总数）：

1#!/bin/bash
2set -o pipefail
3
4WORKSPACE_DIR=${WORKSPACE_DIR:-/workspace/DiffSynth-Studio}
5MODEL_BASE_PATH=${MODEL_BASE_PATH:-${WORKSPACE_DIR}/models}
6DATA_PATH=${DATA_PATH:-${WORKSPACE_DIR}/TestVidData/video_1sampe}
7OUTPUT_DIR=${OUTPUT_DIR:-${WORKSPACE_DIR}/models/train/Wan2.2-T2V-A14B_high_noise_full}
8
9export PYTHONPATH="${WORKSPACE_DIR}:/usr/local/lib/python3.12/dist-packages:$PYTHONPATH"
10export DIFFSYNTH_MODEL_BASE_PATH=${MODEL_BASE_PATH}
11export DIFFSYNTH_SKIP_DOWNLOAD=true
12
13# 多机参数（单机时 WORLD_SIZE 缺省为 1）
14GPUS_PER_NODE=${NPROC_PER_NODE:-8}
15NNODES=${WORLD_SIZE:-1}
16NODE_RANK=${RANK:-0}
17
18# 步数控制：TARGET_STEPS 优先（按卡数反推 repeat），未设时用 DATASET_REPEAT
19NUM_EPOCHS=${NUM_EPOCHS:-2}
20TARGET_STEPS=${TARGET_STEPS:-0}
21DATASET_REPEAT=${DATASET_REPEAT:-1000}
22if [ "${TARGET_STEPS}" -gt 0 ]; then DATASET_REPEAT=$(( TARGET_STEPS * NNODES * GPUS_PER_NODE / NUM_EPOCHS )); fi
23
24cd ${WORKSPACE_DIR}
25accelerate launch 
26  --deepspeed_multinode_launcher standard 
27  --num_machines ${NNODES} 
28  --machine_rank ${NODE_RANK} 
29  --main_process_ip ${MASTER_ADDR:-127.0.0.1} 
30  --main_process_port ${MASTER_PORT:-29500} 
31  --num_processes $(( NNODES * GPUS_PER_NODE )) 
32  --config_file examples/wanvideo/model_training/full/accelerate_config_zero2_usp.yaml 
33  examples/wanvideo/model_training/train.py 
34  --dataset_base_path ${DATA_PATH} 
35  --dataset_metadata_path ${DATA_PATH}/metadata.csv 
36  --height 480 --width 832 --num_frames 49 
37  --dataset_num_workers 16 
38  --dataset_repeat ${DATASET_REPEAT} 
39  --model_id_with_origin_paths "Wan-AI/Wan2.2-T2V-A14B:high_noise_model/diffusion_pytorch_model*.safetensors,Wan-AI/Wan2.2-T2V-A14B:models_t5_umt5-xxl-enc-bf16.pth,Wan-AI/Wan2.2-T2V-A14B:Wan2.1_VAE.pth" 
40  --learning_rate 1e-5 
41  --num_epochs ${NUM_EPOCHS} 
42  --remove_prefix_in_ckpt "pipe.dit." 
43  --output_path ${OUTPUT_DIR} 
44  --trainable_models "dit" 
45  --max_timestep_boundary 0.417 
46  --min_timestep_boundary 0 
47  --sp_size 1 
48  --total_flops 2600.933 
49  --gradient_checkpointing_interval 1

10.2 步数控制说明

默认行为为 DATASET_REPEAT=1000、2 epoch。冒烟或复测只想跑固定步数时传 TARGET_STEPS，脚本按当前卡数反推 DATASET_REPEAT，单机与多机得到相同步数——TARGET_STEPS=70 在单机 8 卡和双机 16 卡都是 70 步，无需自己按卡数换算。整数除法在 TARGET_STEPS × 总卡数 不被 NUM_EPOCHS 整除时会有 ±1 步误差，需要精确时同时传 NUM_EPOCHS=1。

10.3 多机训练说明

• 脚本自动读取平台注入的 MASTER_ADDR、MASTER_PORT、RANK、WORLD_SIZE、NPROC_PER_NODE，无需手动设置。
• --deepspeed_multinode_launcher standard 在百舸这类无 pdsh / SSH 免密的环境做多机训练时必需：accelerate 在 DeepSpeed 模式下默认走 pdsh launcher 枚举节点，该环境下不会报错，而是退化成每节点各自跑单机。该参数在单机场景下无副作用。
• 脚本内不设置 NCCL 变量，交由平台注入。

10.4 查看日志与产物

在开发机终端中查看训练日志的 [Step N] 指标行（仅 rank 0 打印，一行一步，步号跨 epoch 累加）：

1[Step    126] | Rank: 0 | loss: 0.00296 | lr: 1.00000e-05 | step/t: 13.856s | fwd/t: 0.000s | bwd/t: 0.000s | opt/t: 0.000s | TFLOPS: 187.714

• step/t 为单步瞬时墙钟时间（含前向 / 反向 / 优化器），是性能观测的主要口径。
• 进度条上的 13.82s/it 是 tqdm 自算的平均迭代耗时，含首步与数据加载摊薄，与 step/t 不是同一量，不建议用于性能评估。
• 首步包含编译预热，耗时明显偏高，不计入稳态性能。
• fwd/t、bwd/t、opt/t 恒为 0.000，为当前版本未开启细分计时，不是异常。

checkpoint 输出在 OUTPUT_DIR（默认 ${WORKSPACE_DIR}/models/train/Wan2.2-T2V-A14B_high_noise_full），存盘时已去掉 pipe.dit. 前缀，为 bf16 精度。

十一、性能参考

以下数据为特定测试环境下的参考值，step time 取自训练稳态末 10 步的区间，TFLOPS 由 --total_flops 2600.933 ÷ step time 换算，与 step time 同源。实际性能会受资源规格、数据读取方式、网络环境、任务参数等因素影响。

双机口径说明：global batch 由 8 翻到 16，因此 step 数减半为 63/epoch × 2 = 126 step，与单机不可直接比较总耗时与 loss。按每卡计算量不变折算，双机吞吐为单机的约 1.90 倍，弱扩展效率约 95%，差值即跨机通信开销。

测试扩展比时无需修改 batch size 等配置，直接使用脚本默认值即可；当前配置 micro batch size 仅支持 1。

十二、常见问题

12.1 权重加载报错 Cannot detect the model type

报错示例：

1ValueError: Cannot detect the model type. File: []. Model hash: d41d8cd98f00b204e9800998ecf8427e

该 hash 是空内容的 MD5，说明 glob 没有匹配到任何文件。

原因：框架加载时默认开启 redirect_common_files，会把 T5 / VAE 的 .pth 静默改写到 Converted-Safetensors 仓库中的 .safetensors。若该仓库未下载或路径不对，就会找不到文件。日志中出现 ... is redirected to ('DiffSynth-Studio/Wan-Series-Converted-Safetensors', ...) 即为该逻辑生效。

解决：确认权重清单中的仓库 2 已下载至 ${MODEL_BASE_PATH}/DiffSynth-Studio/Wan-Series-Converted-Safetensors/。

12.2 tokenizer 加载失败

未显式传 --tokenizer_path 时，框架会从 Wan-AI/Wan2.1-T2V-1.3B:google/umt5-xxl/ 加载 tokenizer。

解决：补齐权重清单中的仓库 3；或显式传 --tokenizer_path，指向 A14B 仓库自带的 google/umt5-xxl/。

12.3 报错 Can't load feature extractor

未显式传 --audio_processor_path 时，框架会加载 Wan-AI/Wan2.2-S2V-14B:wav2vec2-large-xlsr-53-english/。T2V 任务用不到该模块，但 pipeline 构造阶段仍会加载。

解决：补齐权重清单中的仓库 4 下的 4 个 json 文件（仅 2.2 KB）。

12.4 多机训练退化为多个独立单机

日志中出现 world_info={"localhost": [0..7]}、--master_addr=127.0.0.1 或 Unable to find hostfile，说明多机通信退化成每节点各自跑单机，此时的 step time 不能作为多机性能数据。

解决：确认启动命令中包含 --deepspeed_multinode_launcher standard；确认平台注入的 MASTER_ADDR、WORLD_SIZE 等环境变量正确。可通过以下方式核对实际并行规模：

1# NCCL 通信域、DeepSpeed 数据并行度均应等于总卡数（双机 16 卡场景为 16）
2grep -m1 -oE 'nranks [0-9]+' <训练日志>
3grep -m1 -oE 'self.dp_world_size=[0-9]+' <训练日志>

12.5 工作目录约束

脚本内部会 cd ${WORKSPACE_DIR}，因此从任意目录调用均可。但若显式覆盖 WORKSPACE_DIR，必须指向 DiffSynth-Studio 仓库根，否则 --config_file 与 train.py 的相对路径会找不到。

12.6 断点续训

当前训练框架版本（DiffSynth-Studio 2026.1 main branch）不支持断点续训，加速镜像也未提供该能力。如有续训需求，请联系百舸相关人员评估。

十三、后续操作

• 训练产出的 checkpoint 位于 OUTPUT_DIR，可用于后续推理或继续微调。
• 需要调整分辨率或帧数时，同步重算 --total_flops，否则 TFLOPS 指标不准确。
• 需要长稳压测时，直接加大 DATASET_REPEAT；需要对齐固定步数时使用 TARGET_STEPS。