VDN-Minimax-H3（简称 VDN-H3）是一个基于 MiniMax H3 的混合注意力视频生成开源模型，能在 8×B200 上约 9 秒生成 14.4 秒视频。它的 softmax 分支使用窗口注意力（window attention），并提供两种实现：基于 BlockMask 的稀疏 kernel，以及不使用任何 mask 的Decomposed dense 分解。本文面向新手，讲清后者如何把"稀疏窗口注意力"改写成几次 dense 调用，从而在 B200 上跑得更快。

上图为仓库内置 FL2VA 示例的首帧关键帧（见 prompts/image/），配合末帧即可驱动 14.4 秒视频生成。

一、为什么需要窗口注意力：长序列的注意力开销

🎬 VDN-H3 的输入是一条打包序列：345 帧（102 个 latent 帧）× 每帧数百个空间 token，加上文本和音频 token，总长可达10 万+ 行。若对全部序列做完整 dense 注意力，开销不可接受。

因此它的每个 DiT 块被替换为 HybridAttention：

• 线性注意力分支：帧级、近似 O(T)，负责"远距离"信息；
• softmax 窗口分支：每帧只允许看到邻近帧（chunk 对齐的窗口），文本/音频等"全局 token"则保持全连接。

窗口边界由 window_bounds() 定义：每 K 个 latent 帧为一个 chunk，帧 t 只能看到[c-radius, c+radius]内的整块chunk（c1 配置即前、当前、后各一块）。这种"局部窗口 + 全局 token 全连接"的组合，正是加速的关键前提。

二、BlockMask 路径：标准做法及其代价

flex路径用 FlexAttention 表达同一个窗口 mask：build_window_block_mask() 通过create_block_mask物化一个块级掩码（H3 规模下约10 MiB/个，缓存上限 64 个，见 MAX_CACHED_MASKS）。

这条路径有两个天然限制：

1. 块粒度浪费：mask 按块（sm100 上必须 (256, 128) 的瓦片）判断保留/丢弃，窗口边缘会被整块"向上取整"，稀疏利用率并非完美。
2. 编译形态分裂：FLASH（FA4 CuTe）后端拒绝在动态编译下使用 BlockMask，所以训练只能用 Triton 动态变体，推理只能静态编译——两种变体性能相差约 1.6×，且静态变体要求"一个渲染进程只有一种序列长度"。

三、Decomposed 核心思想：mask = 若干 dense 矩形的并集

💡 decomposed.py 的注释开门见山：

这个 mask 不是任意稀疏——每个被保留的 (q, kv) 对都落在少数几个 dense 矩形里。把 query 行按"保留的 KV 集合完全相同"分组，每组就是一个普通 dense 注意力。

具体拆成两条腿，见 window_softmax_decomposed()：

两条腿的结果直接 scatter 写回连续输出（行集互不相交、正好覆盖全序列）。窗口组与索引的构造逻辑在 _Plan 中，并按几何形状缓存（最多 4 份计划）。

数学完全等价：每个 query 的 softmax 恰好只在其保留集合上归一化，与 mask kernel 的结果仅有 bf16 归约顺序差异（相对差约 1e-3，与两个 flex 后端互差相当）。仓库还保留了逐帧循环的 window_softmax_reference() 作为正确性基准。

四、为什么更快：kernel 选择与实测收益

不同卡上两条路径各自挑选最快的 kernel（decomposed 的 kernel 选择）：

收益来自：dense kernel 在"低稀疏度"的窗口 mask 上效率远高于 block-sparse kernel——源码注释指出在 sm100 上 dense 调用"明显更快"，sm90 上两者持平。因此：

• 8 卡 B200：8nfe_tuned_fp8_ulysses_b200.yaml 显式写死softmax_backend: decomposed，5+3 分支并行布局下实测 1.425 s/NFE（6+2 为 1.629）；
• 8 卡 H200：8nfe_tuned_fp8_ulysses_h200.yaml 仍用flex（6+2），因为两者在该卡上速度相同；
• 单卡 B200 上 VDN-H3 FP8 达到6.41 s/NFE，而 dense 基座 MiniMax H3 是 16.74 s/NFE。

五、配置与使用：窗口注意力后端怎么切

后端由配置项kernels.softmax_backend控制，取值auto | flex | decomposed | ref（InferenceKernels）：

• auto（默认）：在任何 CUDA 卡上解析为decomposed，非 CUDA 环境退回flex。解析逻辑见 resolve_softmax_backend()，选择会由 set_softmax_backend() 写入每个混合层；
• flex：BlockMask 路径，训练始终用它（可微、动态序列长度）；
• ref：eager 参考实现，用于对拍调试。

在 diffusers 组件中切换也很简单（docs/diffusers.md）：

pipe.load_components(trust_remote_code=True, torch_dtype=torch.bfloat16, softmax_backend={"transformer": "decomposed"})

⚠️内存权衡：decomposed会为每个窗口组收集全局行，峰值内存略高于flex（H200、345 帧实测：T2VA 71.4 vs 62.7 GiB，速度相同）。在 80 GB 卡上跑多图参考（Ref2VA-like）示例时decomposed可能 OOM，此时建议切回flex（docs/inference.md 内存一节）：

python src/inference/infer.py --config configs/inference/8nfe_tuned_fp8.yaml \ checkpoint=ckpts/stage-dmd-step-250 kernels.softmax_backend=flex \ render.prompt_file=prompts/reference/example_ref2va.pt render.out=results/example_ref2va.mp4

上图为 Ref2VA-like 示例的参考图之一（prompts/reference/），正是需要flex回退的典型长条件场景。

六、延伸阅读与核心文件

一句话总结：VDN-Minimax-H3 的decomposed窗口注意力把"带 BlockMask 的稀疏 kernel"改写成"两次无 mask 的 dense/变长 dense 调用"，在数学等价的前提下让 sm100 用上了最快的 dense kernel，这也是它在 B200 上把窗口注意力算到 1.4 s/NFE 的核心原因。