企业官网建设流程全解析

VDN-Minimax-H3（下称 VDN-H3）是在 MiniMax H3 底座上构建的混合注意力视频/音视频生成模型，它用一个额外的线性注意力分支把长视频推理提速到"比播放还快"。本文面向新手，完整拆解整个训练配方里的第一块基石——Stage A1 训练：如何用"逐层 Teacher 对齐"这一策略，在只跑 200 步的情况下教会刚搭起来的线性分支，如何复现底座模型每一层的输出。

Stage A1 训练在训练配方中的位置

VDN-H3 的全部训练建立在冻结的 dense 底座之上，每个 Stage 都从上一阶段的最终检查点出发：

四个阶段的入口脚本都在 scripts/training/，配置在 configs/training/。Stage A1 是唯一从 YAML 创建混合架构的阶段——之后的 Stage 全部从检查点里继承ModelSpec，想改架构字段甚至会被配置加载器直接拒绝（见 src/config/stage_a1.py 的模块说明）。换句话说：A1 不只是一组训练步，它定义了模型"长成什么样子"。

混合注意力架构：Stage A1 训练了什么

先把要训练的东西说清楚。转换后的每个 DiT block 的.attn被替换成一个HybridAttention，它包裹并复用原始注意力模块，融合公式见 src/models/hybrid_attention.py：

softmax_output = orig.to_out( softmax_gate(x) * window_softmax(q, k, v) ) linear_readout = output_gate(x) * RMSNorm( linear_attention(q_raw, k_raw, v_raw) ) output = softmax_output + to_out_linear(linear_readout) # 仅视频 token 行

• 局部窗口 softmax 分支：只保留原始权重，冻结不动。窗口为chunk: 5, radius: 1，即"自身所在 5 帧 VAE chunk 再加左右各一个"，每帧只看约 15 帧（configs/training/stage_a1_c1_vdn_anchor.yaml）。
• 线性分支：全新参数（约 2.1B），负责"窗口之外"的远场信息。它复用softmax 分支的 QKV 投影（拿原始 q/k/v），只加自己的一套后处理，因此几乎不增加投影开销。
• 锚定帧：首尾两帧（anchor_frames: both）在 softmax 掩码里双向精确可见，线性分支则跳过它们（skip_ends），两支的分工保持严格不重叠。

架构转换只发生在 src/models/hybrid_transform.py 这一处；A1 通过 YAML 到达它，A2/B/推理则通过检查点里的 ModelSpec 到达。

下面这张图就是 FL2VA 示例的起始关键帧（仓库 prompts/image/ 示例输入之一），也是 Stage A1 训练时这类视频 token 所属的"latent 世界"：

💡 关键认知：Stage A1 只训练线性分支的新参数（含to_out_linear、门控等）。62 GiB 的底座权重全程冻结，softmax 窗口分支也冻结——生成质量的"下限"由底座托着，训练只负责让新分支"别添乱、补信息"。

逐层 Teacher 对齐：Stage A1 训练的核心机制

这是本文的重点。核心实现在 src/training/train_stage_a1.py 的AlignHook（L50-L95），策略可以概括为四步：

1. 教师轨迹：把每个HybridAttention置为teacher_mode（src/models/hybrid_attention.py），整个 forward 退化为原始 dense 注意力，no_grad跑一遍——这就是"教师"的输出。
2. 逐层捕获：每一层挂一个 forward hook。教师刚算完某层输出后，hook 立刻用detach 后的同一层输入，以学生身份（混合前向）重算该层，并马上backward()逐层 MSE。
3. 显存恒定：任何时刻最多只存在一层的 autograd 图（教师主干本身无梯度、底座冻结），所以 50 个 block 同时训练，显存开销却不随层数线性增长。
4. 全局步：所有层的梯度累加完，才做一次 all-reduce、裁剪与参数更新。

损失函数刻意做成了归一化相对误差（train_stage_a1.py）：

teacher_sq = teacher.float().pow(2).sum().clamp_min(1e-30) mse = diff.pow(2).mean() loss = diff.pow(2).sum() / teacher_sq # 即 rel^2

代码注释里写得很直白：不同层的 teacher 输出能量差好几个数量级，若用裸 MSE，"各层尺度不一致"会喧宾夺主，梯度裁剪反而成了实际支配步长的东西；归一化后每一层的损失和梯度都落在同一相对尺度上，grad_clip才真正成为离群值防护。

另外，配置里freeze_softmax_gate: true把 softmax 门控钉在 0.99 初值上：局部窗口分支因此始终几乎等于教师，学生只需要学会"让线性分支补上窗口外那部分"，把对齐问题从架构问题降级为训练策略（AlignHook的文档说明见 src/training/train_stage_a1.py）。

优化器超参与大小组学习率：A1 配置逐项解读

Stage A1 的完整配置是 configs/training/stage_a1_c1_vdn_anchor.yaml：

training: max_steps: 200 freeze_softmax_gate: true # 门控钉在 0.99 初值 optimizer: name: adamw lr: 1.0e-4 min_lr: 5.0e-6 warmup_steps: 50 # 50 步 warmup，余弦衰减到 min_lr weight_decay: 0.0 grad_clip: 0.1 # 逐层裁剪 big_lr_scale: 1.0 small_lr_scale: 5.0 small_eps: 2.0e-9

几个新手容易忽略的设计：

• muP 式大/小学习率分组：按模块结构（而不是参数名）把参数分成big/small两组（src/utils/lr_classes.py）。"width-fan-in"的宽矩阵（alpha.down、output_gate.down、beta_proj、to_out_linear、softmax_gate）用保守的 ×1.0；fan-in 固定或向量型参数（alpha.A_log、alpha.dt_bias、alpha.up、output_gate.up、分支 norm、短卷积 taps）用 ×5.0，且带独立的更小 AdamWeps。
• 逐层梯度裁剪：grad_clip: 0.1作用于"每一层的全部参数"，而不是按优化器组分别裁剪——把一层劈成两半各裁一次会悄悄改变--grad_clip的语义（src/training/train_stage_a1.py 注释）。
• 短而一次性：A1 假设一把跑完，检查点里不存训练态、不支持断点续训；输出目录若已存在最终工件会直接拒绝重训。

显存与分布式：ZeRO-1 按层分片优化器状态

A1 在 141 GB 显存的卡上跑得"贴着上限"（torch.cuda.set_per_process_memory_fraction(0.96)，src/training/train_stage_a1.py）。两个显存策略值得记一下：

• 按层分片的 ZeRO-1：完整 AdamW 动量 ≈ 2 × 4 bytes × ~2.1B 分支参数 ≈ 每卡 16 GiB，塞不进 62 GiB 底座副本旁边；改为"每个 rank 只保存自己负责的层的动量"后降到 ~2 GiB（src/training/train_stage_a1.py）。梯度仍全局 all-reduce，保证裁剪范数跨卡一致；每步只更新自己负责的层，再把更新后的参数broadcast给所有人。
• 特征链反向重算：A1 不做 block 级梯度 checkpointing，而是让线性分支在 backward 里重算 conv+SiLU+L2Norm 特征链（checkpoint_features = True，src/models/linear_attention/branch.py），省掉每层学生重算时多存的几个 GiB。

训练数据、运行方式与产出物

A1 读取预编码 latent（H3 标准管线）：video/（bf16，归一化空间）、audio/（立体声）、text/（prompt_embeds+text_token_tags），由video_index.jsonl的latent_path串联（目录结构见 README 的 "Data Preprocess"，读取逻辑在 src/training/dataset_h3_latents.py）。参考图示例长这样（prompts/reference/ 示例之一）：

运行一条命令即可（8 卡单机，200 步）：

bash scripts/training/stage_a1.sh data.index_file=/path/to/video_index.jsonl

产出是带完整ModelSpec的 v2 "weights" 工件hybrid_step000025.pt等（early_saves: [0,1,2,4,8]+ 每 25 步一存），并写metrics.jsonl记录每步的逐层align_mse/rel/ 梯度范数 / 峰值显存。

Stage A1 之后：A2 / B / DMD 如何接力

A1 只负责"把分支对齐到教师"，质量与能力的接力交给后续阶段：

⚙️ 一句话总结：Stage A1 是 VDN-Minimax-H3 混合注意力架构的"出生证"——用逐层 Teacher 对齐的归一化相对误差，在 200 步内让线性分支学会复刻每一层教师输出，为后续端到端精修（A2）、LoRA 微调（B）与少步蒸馏（DMD）打好地基。想深入实现，建议直接读 src/training/train_stage_a1.py 的AlignHook与 src/models/hybrid_transform.py 两处源码，配合 configs/training/stage_a1_c1_vdn_anchor.yaml 逐项对照。