开发者指南:Minimax-H3-T2VA-Veda-8NFE-600Step-Preview 稀疏注意力 Python API 与 bundle.load 加载详解
开发者指南:Minimax-H3-T2VA-Veda-8NFE-600Step-Preview 稀疏注意力 Python API 与 bundle.load 加载详解
Minimax-H3-T2VA-Veda-8NFE-600Step-Preview 是面向 MiniMax-H3 文本生成音视频(T2VA)扩散模型的 Veda 稀疏注意力预测器(Veda predictor) 检查点。它用一个轻量级预测器只保留约 10% 的注意力计算,在画质与音质几乎无损的前提下,将注意力速度最高提升 6.8 倍、端到端生成速度最高提升 3.1 倍。本文面向开发者,详解如何用 Python API(miowtion.veda 的 bundle.load)加载这个检查点、读懂 config.json 中的关键配置,并避开常见部署坑。
🎯 先搞懂:这个 Veda 检查点是什么
Veda 是一种学习型稀疏注意力方法:注意力占据了视频扩散推理的绝大部分开销,但其中只有一小部分对输出有实际贡献。Veda 从完整模型中蒸馏出一个轻量预测器(TileScorePredictor),按注意力头选择最重要的 10% 注意力块(keep_ratio = 0.1),其余直接跳过。
它有三个关键特性,决定了集成方式:
- 不是 LoRA:不改背骨(backbone)权重、不改风格,只改变注意力的计算方式,可与任意 LoRA 及微调过的 MiniMax-H3 变体叠加使用;
- 模态与步数无关:适用于 MiniMax-H3 支持的全部模态(T2VA、FL2VA、R2VA)与任意扩散步数,名称中的
T2VA与8NFE仅表示训练配置; - 小体积:预测器权重以 FP8(
float8_e4m3fn)存储,整个检查点仅约 263 MB。
官方报告的加速效果(MiniMax-H3 + Turbo LoRA,保留 10% 注意力):
| GPU | 视频规格 | 注意力加速 | 端到端加速 |
|---|---|---|---|
| RTX PRO 6000 Blackwell | 16:9 · 14.4 s | 6.79× | 3.12× |
| RTX 4090 | 16:9 · 14.4 s | 6.31× | 2.82× |
| RTX 4090 | 16:9 · 5.17 s | 4.75× | 1.77× |
视频样例(完整注意力 vs Veda 对比)可直接查看 media/ 目录下的 7 个样本视频。
📦 仓库结构一览
| 文件 | 说明 |
|---|---|
| minimax_h3_t2va_veda_8nfe_600step_preview_fp8.safetensors | 预测器检查点(约 263 MB,FP8),plan 表内嵌其中 |
| config.json | 检查点元数据:几何 plan、keep_ratio、dtype、层数/头数等 |
| README.md | 主文档:功能、性能、Usage 与许可 |
| AGENTS.md | 部署指南:硬件要求、分架构注意事项、排障表 |
| LICENSE | MiniMax H3 Community License |
| media/ | 示例视频(对比片段与 Veda 单独生成片段) |
🚀 用 bundle.load 加载检查点:Python API 详解
miowtion.veda 提供了 bundle 模块,一行 bundle.load() 即可拿到完整预测器(含内嵌的 plan 表)。前提是已安装 Miowtion 运行时并装好 gpu 依赖:
pip install -e '.[gpu,encode]'
加载示例(来自 README.md):
from miowtion.veda import bundle
loaded = bundle.load(
'minimax_h3_t2va_veda_8nfe_600step_preview_fp8.safetensors', device='cuda')
loaded.predictor # TileScorePredictor:逐头 tile 打分预测器
loaded.plans.select(geo) # 按几何(geometry)取对应的 tile plan
loaded.keep_ratio # 0.1
三个返回成员分别对应稀疏注意力的三要素:
loaded.predictor—— 核心预测器TileScorePredictor,在每个注意力头内为 128 行的 query tile 打分,选出值得计算的 key tile;loaded.plans.select(geo)—— 给定几何(如16x9_t37)返回对应的 tile 切分计划。plan 表内嵌在同一个 safetensors 文件中,因此不需要单独的 plan 目录,也不要把预测器和它没训练过的 plan 表混搭;loaded.keep_ratio—— 保留比例,本检查点固定为 0.1(训练时即 0.1,不建议随意调大调小)。
参数说明:第一个参数是检查点文件路径(相对或绝对路径均可),device='cuda' 指定推理设备。检查点内部按 bfloat16 加载、float32 计算(见 config.json 的 load_dtype / compute_dtype 字段),FP8 只是存储格式。
⚙️ config.json 关键字段速读
config.json 是 bundle.load 读取同一份元数据的来源,开发中最常用的是以下几项:
| 字段 | 值 | 含义 |
|---|---|---|
model_type |
veda_tile_score_predictor |
预测器类型,bundle.load 据此解析 |
keep_ratio |
0.1 |
保留 10% 注意力块 |
num_inference_steps |
8 |
在 8 步 Turbo LoRA 下蒸馏,必须配套 8 步生成 |
num_layers / num_heads / head_dim |
50 / 56 / 128 |
与 MiniMax-H3 DiT 对齐的结构参数 |
tile_size |
128 |
128×128 的稀疏 tile,与 FA4 块对齐 |
dtype |
float8_e4m3fn |
FP8 存储 |
geometries |
12 组 | 4 种宽高比 × 3 种 latent_t(37 / 72 / 102) |
scale_granularity |
per_head_amax |
FP8 反量化的逐头缩放粒度 |
几何(geometry)的命名规则值得注意:config.json 中写作 16x9_t37 这类键(如 config.json#L28-L39),而命令行参数写作 16:9@37。可用几何共 12 种:16:9、9:16、4:3、1:1 各配 latent_t 为 37、72、102。plans.select(geo) 传入的键必须来自这 12 种之一。
🧭 命令行与 Python API 的对应关系
在 Miowtion 的 scripts/generate.py 中使用该检查点时,关键参数与 Python API 一一对应(详见 README.md · Usage):
| 命令行选项 | 对应概念 | 说明 |
|---|---|---|
--predictor <path> |
bundle.load(path) |
指向本检查点的 safetensors 文件 |
--attention veda |
启用稀疏路径 | dense veda 可同时渲染两种模式并输出并排对比视频 |
--geometry 16:9@37 |
plans.select(geo) |
必须是 12 种几何之一 |
--keep-ratio |
loaded.keep_ratio |
覆盖默认 0.1(0.1 是训练值) |
--dense-steps |
— | 指定前若干去噪步保留稠密注意力 |
--offload-blocks / --mlp-chunk-rows |
— | 24 GB 显存卡建议 50 / 4096 |
一个典型生成命令(8 步 Turbo LoRA):
python scripts/generate.py \
--root weights/MiniMax-H3 --variant FL2VA \
--schedule turbo --num-steps 8 \
--adapter weights/turbo_lora/<8-step-lora>.safetensors \
--geometry 16:9@37 --attention veda \
--predictor weights/veda/h3-t2va-8nfe-600/minimax_h3_t2va_veda_8nfe_600step_preview_fp8.safetensors \
--out-dir artifacts/generate/demo
🛠 开发者常见坑位清单
以下均来自 AGENTS.md 的排障表,是集成时最容易踩的几个坑:
| 症状 | 原因 | 解决 |
|---|---|---|
KeyError(geometry 相关) |
该宽高比/latent_t 组合在 bundle 中没有 plan |
换用 config.json 中 12 种几何之一 |
| 预测器加载成功但输出是噪声 | 预测器与它没训练过的 plan 表配对 | 统一走 --predictor(plan 内嵌于同一文件) |
生成了但速度没提升 / NotImplementedError |
GPU 架构未启用块稀疏(fa4.available() 为 False) |
按 AGENTS.md 检查 Ada / Hopper / Blackwell 各自的注意事项 |
进程在 load weights ... done 后静默死亡 |
主机内存 OOM(每个进程约需 40 GB pinned RAM),不是显存问题 | 同一机器只跑一个进程,启动前检查空闲内存 |
另请注意:8 步之外的步数是分布外(out-of-distribution)的——该预测器在 8 步 Turbo LoRA 教师模型下蒸馏,换用其他步数时稀疏选择质量无保证。
📝 Preview 版本的使用边界
- 本检查点为 Preview:600 次从零更新 + 100 次全轨迹更新,在 5.17 s 与 14.4 s 片段、四种宽高比上训练;10.1 s 几何经打包可用,但训练中未见过;
- 稀疏输出与稠密输出不保证逐位一致(10% 保留率下即使 oracle 掩码也只能恢复约 63%~71% 的注意力质量),生产前建议用
--attention dense veda做并排目检; - 许可方面,该模型继承 LICENSE 中的 MiniMax H3 Community License。
📚 延伸阅读
- 快速上手与样例:README.md
- 硬件要求、分架构部署与完整排障:AGENTS.md
- 检查点元数据:config.json
- 生成效果对比视频:media/