MiniMax H3 本地部署指南：文件构成、版本选型与显存规划

MiniMax H3 本地部署指南：文件构成、版本选型与显存规划

【免费下载链接】MiniMax-H3MiniMax H3 是一个通用的全模态生成系统。它支持对由文本、图像、视频和音频组成的多模态上下文进行统一理解，并能生成分辨率高达 2K、时长可达 15 秒的带原生立体声音频的视频。得益于面向任务泛化的系统设计，H3 在预训练阶段就已具备广泛的多模态上下文理解与生成能力，能够出色地执行复杂的多模态指令。项目地址: https://ai.gitcode.com/MiniMax-AI/MiniMax-H3

MiniMax H3 可生成带原生立体声音频、时长 4–15 s、最高 2K 分辨率的声画同步视频。MiniMax H3 本地部署的三大障碍是文件数量多、两个任务版本易混、BF16 权重显存门槛高。本文按文件清单、版本选型、显存规划三步展开，读完即可按硬件完成选型与下载准备。

模块架构与文件清单

H3-Base 按「输入处理层 → 核心生成层 → 输出解码层」三级流水线组织，每个任务 checkpoint 都包含这三层所需的全部文件。原始格式（FL2VA/、Ref2VA/目录）与 diffusers 格式（仓库顶层）并存，两者按框架选用、不可混用。

输入处理层（原料入库）

• text_encoder— 将文本与视觉输入编码为统一隐状态（Qwen3-VL-32B，32B 参数 · 14 个分片 · 流水线入口）
• tokenizer— 分词并承载生成用特殊 token（Qwen2TokenizerFast，含<d>等 · 小文件）
• processor— 多模态输入预处理（Qwen3VLProcessor · 小文件）

核心生成层（工序加工）

• transformer— 联合预测视频与音频 latent（H3-Omni-Transformer，33B 参数 · 14 个分片，原始格式 13 个 · 主工序）
• scheduler/audio_scheduler— 视频与音频扩散步长调度（MiniMaxH3Scheduler，shift=12.0 · 配置文件）

输出解码层（出货打包）

• vae（原始格式为video_vae）— 视频 latent 解码为帧序列（H3-VisualVAE，f16t4d24，空间 16×/时间 4× 压缩 · 3 个分片，原始格式 1 个文件）
• audio_vae— 音频 latent 解码为 32 kHz 立体声（H3-AudioVAE，32 kHz ↔ 40 Hz token · 1 个文件）

分片规模：diffusers 格式顶层共 46 个权重分片（text_encoder 14 + transformer 14 + transformer_ref 14 + vae 3 + audio_vae 1）；每个原始任务族（FL2VA / Ref2VA）各 29 个权重分片（14 + 13 + 1 + 1），另含 tokenizer、processor、model_index.json 等配置。缺少任一层都会导致加载失败，因此下载时应以所选框架的完整清单为准，而不是只拿体积最大的主干文件。diffusers 格式额外包含transformer_ref一组权重，对应 Ref2VA 任务的 Transformer（与 FL2VA 所用的transformer同规模），原始格式中则各自内嵌于对应任务目录，两套均不可省略。

FL2VA 与 Ref2VA 版本对比

两个 checkpoint 的权重不可互换，输入能力与显存开销差异明显，选型前先对照下表。

决策规则（if-then）：

• 若输入仅有文本或不超过 2 张图，选 FL2VA。
• 若需参考 3 张以上图像，或携带任意参考视频/参考音频，选 Ref2VA。
• 若两类任务都要做，分别部署两个 checkpoint，不要共用同一份权重。

FL2VA 与 Ref2VA 的核心区别在输入侧而非输出侧：两者输出均为 768p 声画同步视频，差异是 Ref2VA 的上下文里额外携带参考素材。参考素材越多，进入 Transformer 的 token 序列越长，注意力计算与 KV 占用随之上升，这也是显存开销更高的直接原因。

显存档位与量化方案

官方权重为 BF16（33B Transformer + 32B 编码器，合计约 130 GB），单卡放不下，需多卡或量化。社区量化版本是 H3 显存需求的主要解法，下表按本地常见显存档位给出可行配置。

量化精度与速度权衡：4-bit 加载最快、显存最省，精度略降；FP8/8-bit 居中。规划 H3 本地跑需要什么显卡时，可按「档位下限 + 16% 余量」估算：显存占用 = 权重体积 + 激活/KV 缓存，缓存部分随时长与分辨率上升，因此同档位下建议先按 8 s 时长验证再逐步加到 15 s。

768p 是本地默认输出（短边 768 像素），2K 需官方 H3-Regenerate-2K 增强。该模块未开源，仅经 API 提供，本地无法直接出 2K；规划时不要为 2K 预留显存，那是云端职责。

部署问题排查

按「现象 → 原因 → 处置」定位，括号内为可搜索的报错关键词，前四条覆盖本地部署最常见的四类失败。

• 文件缺失：加载即报module not found/weights not found（关键词safetensors、subfolder）。原因：只下了主干，漏了 text_encoder、VAE、tokenizer。处置：按所选格式的完整清单一次下齐，分片数见上节。
• 格式混用：报pipeline class not found/ 结构不匹配（关键词model_index、_class_name）。原因：FL2VA 原始目录与 diffusers 顶层文件混装。处置：按框架锁定单一格式，SGLang/vLLM 用原始格式，diffusers 用顶层格式。
• 显存溢出：CUDA out of memory（关键词OOM、Tried to allocate）。原因：BF16 全精度超显存。处置：换 4-bit 量化权重并降分辨率/时长，见显存档位表。
• 2K 预期偏差：本地只出 768p，误以为拿到 2K（关键词768p、Regenerate-2K）。原因：2K 增强模块未开源。处置：本地出 768p 后经官方 API 做 Regenerate-2K，或直接调用 API 出 2K。

四条失败有一个共同前置原因：下载前没有建立清单。正确顺序是先定框架、再定版本、最后逐文件核对数量，下载完成后用 safetensors 文件数对照第一节清单即可排除前三类问题。

部署前检查清单

本清单按部署的实际操作顺序排列，建议自上而下一次性执行，中途不要跳步补做，否则容易在配置阶段发现文件缺口。

• 环境：确认 GPU 显存档位与量化版本匹配（见上节档位表）
• 格式选择：按推理框架锁定原始格式或 diffusers 格式，不混用
• 文件下载：按所选任务族一次下齐全部分片与配置
• 配置：核对 model_index.json 指向的组件与本地目录一致
• 首次运行：先用 可复现 768p 请求脚本 验证，再上正式任务

格式单一、文件齐全、显存匹配是本地跑通的三个前提；组件与调用细节见 FL2VA 组件配置 与官方 API 文档。

【免费下载链接】MiniMax-H3MiniMax H3 是一个通用的全模态生成系统。它支持对由文本、图像、视频和音频组成的多模态上下文进行统一理解，并能生成分辨率高达 2K、时长可达 15 秒的带原生立体声音频的视频。得益于面向任务泛化的系统设计，H3 在预训练阶段就已具备广泛的多模态上下文理解与生成能力，能够出色地执行复杂的多模态指令。项目地址: https://ai.gitcode.com/MiniMax-AI/MiniMax-H3