开发者指南:Minimax-H3-T2VA-Veda-8NFE-600Step-Preview 稀疏注意力 Python API 与 bundle.load 加载详解

原创2026-11-09 19:49:011,913 阅读
文章标签:人工智能深度学习基础模型媒体生成视频多模态模型优化计算机视觉

开发者指南: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。

📚 延伸阅读

登录后查看全文
Minimax-H3-T2VA-Veda-8NFE-600Step-Preview