本地部署 H3-Base 的完整路径：从下载范围到 SGLang 起服务

很多人看到 MiniMax H3 开源就直接去找「怎么本地跑」，然后在半路上卡住——不是卡在命令上，是卡在认知上：开源出来的那部分，和你在官方 App 里看到的那套东西，不是同一个范围。所以这篇先把边界划清楚，再往下走命令。全文依据截至 2026-08-09 的官方仓库 README 与仓库文件树，我们没有下载权重、没有部署、也没有发起过任何一次推理请求。

一、先搞清楚「本地部署」到底部署的是哪一块

按 README 的 System Overview，完整的 H3 系统由三个模块串起来：

模块	职责	开源状态
H3-Context-IR	把复杂的多模态输入深度理解并精炼成 Context Intermediate Representation，再交给生成	未包含在本次开源发布中，官方提供 API
H3-Base	基于 Context-IR 的输出生成音视频，产出 768p 结果	已开源，两个 checkpoint
H3-Regenerate-2K	把 768p 结果连同原始上下文送回，重新生成 2K	尚未开源，官方提供 API 用于验证结果

也就是说，本地部署能拿到的只有中间那一层。README 对 Context-IR 还专门强调了一句：它对最终输出质量至关重要，强烈建议要么把它接进你的生成流水线，要么照着 Prompting Guidance 自建一套上下文处理系统。这句话值得反复读——拿到开源权重不等于拿到官方效果，前面的上下文理解和后面的 2K 重生成都不在你手里。

理解了这个结构，README 给的两条验证路径就顺理成章了：

1. Full 2K Workflow：本地部署的 H3-Base 结合官方开放平台 API，端到端验证 2K 输出。
2. Local Deployment of H3-Base：只用本地部署的 H3-Base，验证 768p 输出。

如果你的目的是「确认这套权重在我的机器上能起来、能出东西」，走第二条就够了，全程不需要联网调 API。如果你要复现官方那种 2K 质量，第二条路径本身就走不到终点——那是第一条路径的事，而第一条路径必然要用到官方 API。本文讲的是第二条。

二、两个 checkpoint 与任务的对应关系

H3-Base 开源了两个 checkpoint，选错了后面全白搭。README 原表如下：

Checkpoint	支持任务	输入条件	输出	精度
MiniMax-H3 Base FL2VA	t2va、fl2va	文本；可选首帧、尾帧或两者	视频与音频	BF16
MiniMax-H3 Base Ref2VA	ref2va	文本 + 参考图像、视频和/或音频	视频与音频	BF16

FL2VA 那一栏的「可选」有细分：不给图像就是文生视频，给 1 张是首帧生视频或尾帧生视频，给 2 张是首尾帧生视频。Ref2VA 走的是另一条线，吃的是多模态参考输入。

两个细节容易被跳过。第一，README 明确写了发布的 checkpoint 是 CFG-distilled 的 Omni Transformer 权重——这是权重本身的形态描述，跟你熟悉的某些开源模型不一定是一回事，看到相关配置项时别按惯性理解。第二，精度是 BF16。这一点在你同时接触 ComfyUI 侧的 H3 时特别重要：那边用的是量化权重，和官方 BF16 不是同一份东西，两边不要混着评估。

三、下载：--include 不是可选项

这是本地部署第一个真正的坑，而且原因很具体：仓库把原始 checkpoint（FL2VA/、Ref2VA/）与 diffusers 格式并排托管。你不加限定直接全量拉，会同时拿到两套东西。README 的证据也摆在文件树里——tokenizer 相关文件（tokenizer.json、vocab.json、merges.txt）在两套格式里各出现一次。

README 给的命令原样如下：

# Original checkpoint, both task families (SGLang, vLLM):
hf download MiniMaxAI/MiniMax-H3 --include "model_index.json" "FL2VA/*" "Ref2VA/*" --local-dir MiniMax-H3

# Or a single task family:
hf download MiniMaxAI/MiniMax-H3 --include "model_index.json" "FL2VA/*" --local-dir MiniMax-H3

逐项解释一下每个选项为什么在这：

• --include "model_index.json"：model_index.json 是仓库级的公共入口，两个任务族的 diffusers 索引则分别在 FL2VA/model_index.json 与 Ref2VA/model_index.json。所以这个根级文件要单独点名。
• --include "FL2VA/*" "Ref2VA/*"：跑 SGLang 或 vLLM 的人要的是原始格式，这两个目录就是全部所需。只做首尾帧和文生视频的人，第二条命令那样只下 FL2VA/* 就行，不必下 Ref2VA/*。
• --local-dir MiniMax-H3：把内容落到一个明确的本地目录，方便后面的服务指路。

反过来说，只跑 diffusers 的人根本不需要手动执行这一步。README 提到 ModularPipeline.from_pretrained("MiniMaxAI/MiniMax-H3") 会精确拉取它所需的组件。多少体积、多少 GB 这类数字官方没给，我们也没下过，不猜。

四、依赖里那个真会绊人的地方

仓库 requirements.txt 开头的官方注释信息量比依赖列表本身还大：模型是作为 Hugging Face diffusers pipeline 发布的，通过 trust_remote_code=True 使用，因此需要一个附带 MiniMax-H3 模型类的 diffusers 构建；官方建议 pin 一个已知可用的 diffusers 版本，以及一个带所需 CUDA / MPS wheel 的 torch 版本。

关键在 diffusers 这一行：约束写的是 >=0.32.2，但注释明说官方文档引用的是 diffusers 的 minimax-h3 分支，并给出在它进 PyPI 之前的安装方式：

pip install "git+https://github.com/huggingface/diffusers.git@minimax-h3"

这条注释的推论很直接：直接 pip install diffusers 装 PyPI 版本，可能拿不到 H3 的模型类。如果你在加载阶段遇到「找不到某个 H3 相关类」的情况，先回头核对装的是不是这个分支，别一头扎进权重文件里排查。

其余几条也顺带记一下判断依据：transformers >= 4.45.0 是为了 Qwen3-VL 的 text encoder / processor / tokenizer；accelerate >= 0.34.0 官方注释写明用于 33B Omni-Transformer 与 visual VAE 的 device_map 与多 GPU 加载；soundfile >= 0.12.0 是因为音频 VAE 返回 32 kHz 立体声张量，官方推荐用它写出。FL2VA/model_index.json 里 _class_name 是 MiniMaxH3Pipeline，_diffusers_version 是 0.32.2，text_encoder 指向 transformers 的 MiniMaxH3Qwen3VLHFEncoder，tokenizer 指向 Qwen2TokenizerFast——这几个值可以用来交叉核对你的环境版本是不是对得上。

五、四个推荐推理框架，先选路再敲命令

README 给了四个框架入口：

框架	官方给的入口
SGLang	docs.sglang.io，cookbook 路径 /cookbook/diffusion/MiniMax/MiniMax-H3
vLLM	github.com/vllm-project/vllm，recipes 路径 recipes.vllm.ai/MiniMaxAI/MiniMax-H3
diffusers	github.com/huggingface/diffusers，文档在 minimax-h3 分支的 docs/source/en/api/pipelines/minimax_h3.md
ComfyUI	github.com/Comfy-Org/ComfyUI，教程 docs.comfy.org/tutorials/video/minimax/minimax-h3

除了下面这段 SGLang 命令，我们没有取过任何一个 cookbook 或 recipe 页的正文，所以本文不会替 vLLM 或 diffusers 编启动参数——要用那两条路，请直接去上表的入口读官方文档。

六、SGLang 起服务：README 原样命令

FL2VA：

sglang serve \
  --model-path MiniMaxAI/MiniMax-H3 \
  --num-gpus 4 \
  --ulysses-degree 4 \
  --performance-mode speed \
  --host 0.0.0.0 \
  --port 30010 \
  --model-variant fl2va

Ref2VA：

sglang serve \
  --model-path MiniMaxAI/MiniMax-H3 \
  --num-gpus 4 \
  --ulysses-degree 4 \
  --performance-mode speed \
  --host 0.0.0.0 \
  --port 30011 \
  --model-variant ref2va

能讲的和不能讲的，这里分清楚：

• --model-variant 与 --port 是配对出现的。示例里 fl2va 走 30010、ref2va 走 30011。这说明两个变体是分别起服务、分别占端口的——你想同时提供 t2va/fl2va 与 ref2va 能力，就是两个服务实例，不是一个进程加个开关。规划机器和端口时按两个服务算。
• --num-gpus 4 与 --ulysses-degree 4 在示例里相等。这是我们能陈述的全部。--ulysses-degree 具体是什么含义、改成别的值会怎样，README 没说，我们不编。--performance-mode speed 同理，除了「示例里这么写」之外不展开。
• 这是「官方示例使用 4 GPU 配置」，不是「需要 4 张卡」。README 只是给了一个 4 卡的部署示例，并没有声明这是最低要求。看到这条命令就下结论说四卡起步，是把示例当成规格了。至于资源够不够、生成快不快，README 没有给出任何数据，我们也没有在本机部署过，一律不猜。想知道更细的部署配置，README 指的是 SGLang 那份 MiniMax-H3 部署指南，去那边读。
• README 自己注明：这里以 sglang 为部署示例，更多部署配置见 SGLang 的 MiniMax-H3 部署指南（docs.sglang.io/cookbook/diffusion/MiniMax/MiniMax-H3#3-serve-minimax-h3）。

七、产出物长什么样

按 README，每个 checkpoint 是一个自包含的 Hugging Face 风格仓库，结构是：

<TASK>/
├── model_index.json
├── processor/
├── tokenizer/
├── text_encoder/
├── transformer/
├── visual_vae/
└── audio_vae/

文件树里可见的情况是：FL2VA/ 与 Ref2VA/ 两个目录结构完全对称，各含 audio_vae/、video_vae/、带 config.json 与 model.safetensors.index.json 的 transformer/、以及 text_encoder/、tokenizer/、processor/、model_index.json。diffusers 格式则在仓库根目录另有一套 transformer/、transformer_ref/、vae/、scheduler/scheduler_config.json 等等——这也是前面说「不限定 --include 会重复下载」的直接来源。

服务侧我们有依据的部分只有一条：示例把 --host 设为 0.0.0.0，端口按变体分别是 30010 与 30011。启动日志里具体打印哪几行、返回体有哪些字段，我们没跑过，不描述。另外仓库 scripts/readme/ 目录下提供了三个可复现的 768p 脚本：reproducible-768p-t2va-request.sh、reproducible-768p-fl2va-request.sh、reproducible-768p-ref2va-request.sh——文件确实存在，但我们没读过内容，里面的请求体字段本文不描述，请以仓库为准。

八、怎么验收

按顺序检查这四处，出错基本都在这里面：

1. 下载范围。看本地目录里是不是同时有根级 model_index.json 和你要的任务族目录。如果发现根目录多出 transformer_ref/、scheduler/ 这类 diffusers 格式的内容，说明 --include 没生效，你多拉了一套。
2. diffusers 来源。核对装的是不是 minimax-h3 分支，这是最容易在加载阶段炸、又最容易往错误方向排查的一步。
3. 变体与端口对不对得上。fl2va 的服务不会响应 ref2va 的任务。起了服务先确认 --model-variant 和你要调的端口是同一套，两个进程都要起的场景尤其容易搞混。
4. 任务与 checkpoint 对不对。想做首尾帧却把请求发给 Ref2VA，属于选型阶段就错了，不是部署问题。

这四步里，前两步的代价最直观：一个让你多拉一整套用不上的文件、白占磁盘，一个让你在加载报错时往权重文件的方向白排查半天。后两步则属于「起来了但对不上」，症状不如前两步明显，起服务前先把变体、端口、任务三者的对应关系写在纸上，比事后翻日志省事。

九、什么情况不适用

• 你要 2K 输出。本地 H3-Base 产出的是 768p，2K 由 H3-Regenerate-2K 完成，而这个模块尚未开源。这种情况必须走 Full 2K Workflow，也就是本地服务加官方 API 的组合。
• 你要官方级的上下文理解。复杂多模态指令的理解精炼由 H3-Context-IR 负责，它同样未包含在本次开源发布中。你要么接它的 API，要么按 Prompting Guidance 自建一套预处理——README 的措辞是「强烈建议」，不是可选项。顺带一提，走官方 API 的路径会经过自动审核：README 的 Safety Guardrails 章节写明用户提交的文本、图像、视频以及增强后的提示词都要过审，并且坦承行业标准的过滤措施无法消除误判与漏判。纯本地路径和 API 路径在这一点上体验不同，做产品设计时要提前想清楚。
• 你只是想先看看效果再决定要不要投入。README 列了在线入口：API 在 platform.minimax.io（中国 platform.minimaxi.com），WebApp 在 hailuoai.video（中国 hailuoai.com）。先在线上试，比先花时间部署更划算。价格、额度、速率这些我们一个数字都没有，请以官方平台页为准。
• 你打算把它接进商业产品。许可证全称是 MiniMax H3 Community License Agreement，原文在 huggingface.co/MiniMaxAI/MiniMax-H3/blob/main/LICENSE。我们没有读过 LICENSE 正文，因此本文不解读任何商用边界、二次分发条件或产出物权属——请自行读原文，必要时找法务。

最后提醒一句本批反复强调的边界：H3 原生支持稀疏注意力是模型能力，而首个开源版本提供的推理路径是另一回事，别把能力表述直接当成你本地能跑的功能。同样，ComfyUI 那条路用的是量化权重，官方发布的是 BF16，两边不要混着评估。

延伸阅读

• MiniMax H3 的 Full 2K Workflow：本地 SGLang 服务 + 官方 API 怎么串成一条链
• 用官方 API 还是本地部署 H3：按你的实际处境倒推
• 用 diffusers 跑 MiniMax H3 的第一个坑：pip install diffusers 装到的版本可能没有 H3 模型类

---

本文依据 MiniMax H3 官方仓库（github.com/MiniMax-AI/MiniMax-H3）的 README、 模型配置文件与官方 h3-prompt-writing skill 文档整理，核对日 2026-08-09。 本文内容为官方仓库口径，未在本机部署或调用过 H3。 模型、部署方式与许可条款以官方最新说明为准。 许可条款请以官方 LICENSE 原文为准，本文不构成法律意见。