VDN-Minimax-H3 检查点系统解析：ModelSpec、Factory 与可复用权重架构-优快云博客

【免费下载链接】vdn-minimax-h3

VideoDeltaNet-H3: Live T2VA / I2VA / FL2VA / Ref2VA-like generation based on Minimax H3.

项目地址： https://gitcode.com/gh_mirrors/vd/vdn-minimax-h3

VDN-Minimax-H3（简称 VDN-H3）是一个基于 MiniMax H3 的混合注意力（hybrid attention）视频生成模型，能以超过播放速度生成带音频的视频。它的检查点系统（Checkpoint v2）用 ModelSpec 自描述架构、用 Factory 统一构造模型，使得训练与推理共享同一套可复用权重——理解这套设计，是读懂该项目权重文件的第一把钥匙。

📌 一句话总结：检查点里只存"模型是什么"（ModelSpec + 权重），不存"怎么跑"（运行时配置），因此同一个检查点既能作为下一训练阶段的种子，也能直接驱动视频推理。

一、检查点 v2：三种工件，一个读写入口

整个检查点逻辑集中在 src/checkpoints/ 目录，格式版本锁定为 v2——不支持旧格式，直接拒绝而不是兼容（见 schema.py 的 validate_payload）。

工件类型（kind）	内容	用途
`weights`	ModelSpec + 权重	评估与推理消费；也是下一训练阶段的种子
`train_state`	上述 + 优化器状态 / 步数 / RNG / 训练配置	断点续训
`optimizer_shard`	分片的优化器矩	ZeRO-1 按 rank 分片保存

三条值得记住的设计：

单一读写入口：读统一走 loader.py 的 load_checkpoint，写统一走 writer.py 的 save_checkpoint。路径可以是一个 .pt 文件，也可以是展开的目录（见第四节），调用方拿到的是同一个 CheckpointArtifact。
原子写入：先写 .tmp 再 os.replace，中途断电不会留下半个文件。
按"名字"而不是"下标"存优化器状态：这让离线重命名权重键成为可能，索引式状态在写入时即被拒绝。

python -m src.checkpoints.export_dir IN.pt OUT_DIR   # 把单个 .pt 展开为目录

二、ModelSpec：把"模型是什么"写进检查点

项目里存在三层配置，model_spec.py 是中间那一层：

Hugging Face 基础配置 —— 原始 MiniMax H3 长什么样；
ModelSpec —— 我们对它做了哪些结构性改动（transforms、adapters）；
实验/运行时配置 —— 某次训练或推理怎么跑（kernel 选择、fp8、窗口 softmax 后端等），永不进入检查点。

一个 ModelSpec 由三部分组成：

BaseSpec：基础模型的来源与"已解析配置"（resolved_config），并附一个 config_hash——对规范 JSON 求 sha256，任何人改动配置后忘记重新哈希都会被 factory.py 的校验当场抓住；
transforms 列表：架构变换。本项目只有一个 hybrid_attention，把每个 DiT block 的注意力替换为"线性分支 + 窗口 softmax 分支"的混合体；
adapters 列表：LoRA 适配器（rank、alpha、targets），例如 8 步加速用的 turbo 适配器。

校验器强制两条铁律（validate_spec）：

所有值必须是"已解析"的：配置里 linear_head_dim: null（表示继承基础模型）在写入 spec 前会被解析成具体整数，spec 中不允许 null；
运行时开关一律拒绝：softmax_backend、fp8、compile 等键混进 spec 会直接报错——它们属于第 3 层，不该污染架构描述。

训练 YAML 中的架构段示例见 stage_a1_c1_vdn_anchor.yaml，可以看到 delta_rule、anchor_frames、short_conv.targets 这些真正决定模型结构的参数。

三、Factory：所有阶段共用的唯一构造器

factory.py 的 build_model 是全项目唯一的模型构造入口——A1、A2、B、DMD 四个训练阶段和推理路径都通过它建模型，标准用法只有三行：

artifact = load_checkpoint(path)
model    = build_model(artifact.model_spec)
load_model_weights(model, artifact.weights)

它的工作流：按 spec 里的 base 加载 Hugging Face 基础模型 → 用 _verify_base_config 做子集校验（spec 盖章的每个键必须与加载模型一致，不一致说明"这不是该检查点所基于的底座"，直接抛错）→ 按顺序应用 transforms。

几个细节体现"可复用"：

transform 是唯一构建架构的地方：hybrid_transform.py 不修改 diffusers 源码，只是把每个 block 的 .attn 换成包裹原模块的 HybridAttention，原始教师模型随时可以通过 attn.orig 恢复；
规范模型不含任何 overlay：FSDP、fp8、编译、推理 kernel 都是加载之后叠加的"运行时层"，绝不进入 spec；
LoRA 的两种消费方式：Stage B 训练需要活的 peft 模块（inject_adapters），推理则把 LoRA 折叠进底座权重（merge_lora_state），渲染时零额外开销；
resolve_model_spec 负责 A1 阶段的"解析"：YAML 架构段 + 实际加载的基础配置 → 全解析的 ModelSpec。

四、权重如何被复用：从训练到推理

VDN-H3 在冻结的稠密模型上做四个阶段的训练，每一阶段以上一阶段的最终检查点为起点：

阶段	训练内容	步数
A1	新增的线性注意力分支，逐层对齐稠密模型	200
A2	同一组参数端到端	500
B	QKV/O 投影上的 LoRA + 线性分支	2000
DMD	8 步 `turbo` LoRA（DMD2 蒸馏）	250

检查点因此是流水线货币：A1 的产物是 A2 的种子，B 的产物（50 步版）直接发布为推理权重，DMD 再在其上叠一个 turbo 适配器（8 步版）。下载后的目录布局是：

ckpts/
  h3-base/             基础 MiniMax H3：transformer、视频/音频 VAE · 72 GB
  stage-b-step-2000/   50 步版：linear_branch/ + adapters/default/ · 4.3 GB
  stage-dmd-step-250/  8 步版：上述 + adapters/turbo/ · 5.1 GB

多卡训练写入时的安全性由 fsdp_stage.py 保证：保存前做跨 rank 指纹校验，不一致就拒绝保存；断点续训时若检查点携带的 ModelSpec 与本次运行不一致，同样拒绝混用。

推理侧则按固定顺序装配（assemble.py）：读 spec → 加载底座 → 应用 hybrid transform → 加载线性分支权重 → 折叠 LoRA → 叠加推理 kernel / fp8 等运行时层。路径解析见 paths.py：ckpts/ 相对仓库根目录书写，本地缺失时自动从权重仓库拉取对应子目录。

五、展开目录导出：配置与权重分离

单个 .pt 对人工检查不友好。export_dir.py 可以把 weights 工件展开成目录——内容与 .pt 完全相同、由同一个 load_checkpoint 读取，只是"人能打开看"：

OUT_DIR/
  model_spec.json              架构描述：base 来源、transforms、adapters
  metadata.json                工件类型与元数据
  linear_branch/
    config.json                hybrid_attention 变换配置（供人阅读）
    model.safetensors          变换引入的全部非 LoRA 张量
  adapters/<name>/
    adapter_spec.json          该适配器的 rank / alpha / targets
    adapter_model.safetensors  其 lora_A / lora_B 张量

JSON 可以直接阅读，权重按组件分开存放；一个 DMD 工件的两个适配器会是两个独立目录，而不是混在一个十几 GB 的 pickle 里。

六、同一个检查点，四种生成任务

正因为检查点自描述且与运行时解耦，发布权重无需按任务区分：T2VA、I2VA、L2VA、FL2VA（首末关键帧驱动）共用同一份检查点，甚至零样本支持 Ref2VA-like 参考图生成。

FL2VA 示例的首帧关键帧（prompts/image/）：

对应末帧关键帧：

Ref2VA-like 任务则直接复用 FL2VA 权重，把参考图作为 <Picture i> 进入提示词。示例参考图之一（prompts/reference/）：

快速上手只需：

git clone https://gitcode.com/gh_mirrors/vd/vdn-minimax-h3
cd vdn-minimax-h3
# 下载权重到 ckpts/ 后（见 README），单卡 8 步推理：
bash scripts/inference/8nfe_tuned_fp8.sh

更多配置与多卡（Ulysses）用法见 docs/inference.md，提示词示例见 prompts/README.md。

小结

ModelSpec 是检查点的"身份证"：只描述架构，值必须已解析，运行时开关一律拒收，且带哈希防篡改（src/models/model_spec.py）；
Factory 是唯一构造器：所有训练阶段与推理共用 build_model，架构可复现、底座可校验（src/models/factory.py）；
权重是流水线货币：weights 工件既是推理输入，也是下一训练阶段的种子，原子写入 + 跨 rank 指纹 + spec 一致性校验保证可信（src/checkpoints/）；
展开目录导出让架构配置变成可读 JSON、权重变成可检查的 safetensors，配置与权重彻底分离。

理解了这套"spec 描述架构、spec 绑定权重、运行时外挂一切"的分层设计，你就能把任意阶段的检查点安全地在训练与推理之间流转复用。