奇 奇连 AI
学习路线图课程工具计算器企业服务关于加入会员

用 SGLang 起 H3 服务：两条官方命令怎么抄、怎么验收

2026-08-09

MiniMax H3 的官方仓库 README（截至 2026-08-09 快照）在「Recommended Workflow」里列了四个推荐推理框架：SGLang、vLLM、diffusers、ComfyUI。四个里面只有 SGLang 这一条路，README 正文直接给出了完整的启动命令；vLLM 与 ComfyUI 只给了入口链接，diffusers 除了入口链接另给了一句 ModularPipeline.from_pretrained("MiniMaxAI/MiniMax-H3") 的用法。所以如果你想照着官方口径把 H3-Base 起成一个能被 HTTP 调用的服务，SGLang 是目前唯一有官方命令可抄的路径。

这篇就干一件事：把这两条命令拆开讲清楚，说明哪些选项我可以解释、哪些只能照抄，起完之后人要检查哪几处，以及什么情况下你压根不该走这条路。

先把话说在前头：我没有下载过权重，没有部署过，也没有向任何一个 H3 服务发过请求。下面所有内容都是仓库口径的转述与推理，不是运行记录。

一、动手之前：先想清楚下哪些权重

H3 的 Hugging Face 仓库 MiniMaxAI/MiniMax-H3 有个容易踩的设计——它把原始 checkpoint 与 diffusers 格式并排托管在同一个仓库里。原始格式是 FL2VA/ 和 Ref2VA/ 两个目录，diffusers 格式的组件散在仓库根目录（根目录下另有 transformer/、transformer_ref/、vae/、scheduler/、audio_scheduler/ 等）。

这意味着如果你不加 --include 直接全量拉，会同时把两套东西都拖下来。仓库里 tokenizer 相关文件在两套格式中重复出现（tokenizer.json 约 7.0 MB、vocab.json 约 2.8 MB、merges.txt 约 1.7 MB），这就是重复下载的直接证据。

所以 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

判断依据很简单：走 SGLang 或 vLLM 的人要的是原始 checkpoint，也就是 FL2VA/* 与 Ref2VA/*；model_index.json 是仓库级的公共入口，要一起带上。如果你这一阶段只打算做文生视频和首尾帧生视频，那第二条命令就够了——只下 FL2VA/*，不必下 Ref2VA/*。反过来，只跑 diffusers 的人根本不需要手动下载：README 里写了 ModularPipeline.from_pretrained("MiniMaxAI/MiniMax-H3") 会精确拉取它所需的组件。

至于这些目录到底占多大空间，官方没给数字，我也没下过，所以这里不写体积估算。

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

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

FL2VA/ 与 Ref2VA/ 两个目录结构完全对称。看一眼 FL2VA/model_index.json 能确认几件事：_class_name 是 MiniMaxH3Pipeline，_diffusers_version 是 0.32.2，text_encoder 指向 transformers 的 MiniMaxH3Qwen3VLHFEncoder，tokenizer 指向 Qwen2TokenizerFast。

二、两条 sglang serve 命令（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

README 明确注明：这里只是以 sglang 作为部署示例，更多部署配置见 SGLang 的 MiniMax-H3 部署指南，路径是 docs.sglang.io/cookbook/diffusion/MiniMax/MiniMax-H3#3-serve-minimax-h3。这一句很重要——它等于官方在说「这两条命令不是完整文档」，真要调配置得去 SGLang 那边看。我没有取过那个 cookbook 页面的正文，所以本文不会替它补细节。

三、逐个选项：哪些能解释，哪些只能照抄

这是本文最需要克制的一段。两条命令里的七个选项，我把它们分成三类。

第一类：语义清楚、可以解释的。

  • --model-path MiniMaxAI/MiniMax-H3：指向模型。注意两条命令用的是同一个 model path，差别不在模型仓库，而在下面的 --model-variant。
  • --host 0.0.0.0：绑定到所有网卡。这决定了服务能不能被本机以外访问。在后面的「Full 2K Workflow」里，README 要你配置一个 SGLANG_DEPLOYMENT_URL="<sglang-deployment-url>" 变量，把本地 SGLang 服务的地址交给后续流程用——--host 与 --port 组合出来的就是这个地址的来源。
  • --port 30010 / --port 30011：两个变体用了两个不同端口。

第二类：取值枚举清楚，是这条命令的关键区分。

--model-variant 在示例里出现了两个取值：fl2va 和 ref2va。它们分别对应 README 里的两个 checkpoint：

--model-variant对应 checkpoint支持任务
fl2vaMiniMax-H3 Base FL2VAText-to-Audio-Video（t2va）、First/Last-Frame-to-Audio-Video（fl2va）
ref2vaMiniMax-H3 Base Ref2VAReference-to-Audio-Video（ref2va）

第三类：我没有事实来源，只能说「官方示例里就是这么写的」。

--ulysses-degree 4 和 --performance-mode speed 属于这一类。我能说的全部事实只有两条：README 的两条示例命令里都带了它们；示例中 --ulysses-degree 的值与 --num-gpus 同为 4。除此之外，它们各自是什么含义、改成别的值会发生什么、performance-mode 还有哪些可选值——我没有依据，一个字都不编。真要动这两个参数，去看上面那份 SGLang 部署指南。

同样要克制的是 --num-gpus 4。README 给的是一个 4 GPU 配置的示例，它没有说这是最低要求，也没有给任何硬件门槛表。所以正确的说法是「官方示例使用 4 GPU 配置」，而不是「H3 需要 4 张卡」。这两句话在工程上差得很远：前者是可核实的事实，后者是我们编出来的结论。显存占用、推理速度这类数字，官方仓库里没有，本文也不会给。

四、最反直觉的一点：两个变体是两个服务

很多人第一次看这两条命令，会以为第二条是第一条的「另一种写法」，挑一条跑就行。不是的。

看端口就明白了：FL2VA 是 30010，Ref2VA 是 30011。两条命令是并列关系，不是二选一。也就是说，如果你既想要文生视频 / 首尾帧生视频（t2va、fl2va），又想要多模态参考生视频（ref2va），那就是两个独立的服务实例，各占一个端口，各自加载各自的 checkpoint。

这个结论对规划很关键。它意味着「同时提供两类能力」不是在一个进程里切个开关，而是资源上要按两份服务来考虑。如果你的验证目标只覆盖首尾帧和文生视频，那只起 30010 那一条就够，Ref2VA/* 连下都不用下——这也是第一节里那条「单一 task family」下载命令的用武之地。

五、依赖环境：一个高价值的坑

仓库根目录的 requirements.txt 带了大量官方注释，其中有一条特别值得单拎出来：diffusers 官方文档引用的是 minimax-h3 分支。requirements 里写着 diffusers>=0.32.2，注释明说在它进 PyPI 之前，安装方式是：

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

翻译成人话：直接 pip install diffusers 装 PyPI 版本，可能拿不到 H3 的模型类。这条不是我的推测，是 requirements.txt 官方注释本身写的。文件开头还交代了整体前提——模型作为 Hugging Face diffusers pipeline 发布，通过 trust_remote_code=True 使用，因此依赖一个附带 MiniMax-H3 模型类的 diffusers 构建，并建议 pin 住一个已知可用的 diffusers 版本和一个带所需 CUDA / MPS wheel 的 torch 版本。

其余几条依赖里，和「起服务」直接相关的是：torch>=2.4.0（注释举的收紧写法是 torch==2.4.1+cu121）、transformers>=4.45.0（提供 Qwen3-VL 的 text encoder / processor / tokenizer）、accelerate>=0.34.0（注释写明用于 33B Omni-Transformer 与 visual VAE 的 device_map / 多 GPU 加载）、huggingface_hub>=0.25.0（提供第一节那条 hf CLI）。soundfile>=0.12.0 那条也别忽略——注释说音频 VAE 返回的是 32 kHz 立体声张量，soundfile 是推荐的写出方式。

六、产出物：起完之后本地应该是什么样

先把边界说清楚：README 没有给 SGLang 的启动日志样例，我也没有跑过，所以这一节不会出现任何「你会看到这样一行日志」的描述——那种东西编不出来，也不该编。有依据可讲的产出物只有两类：磁盘上的目录，和端口上的服务。

磁盘上。 执行完带 --local-dir MiniMax-H3 的下载命令后，本地会出现一个 MiniMax-H3 目录，里面是仓库级的 model_index.json，加上你用 --include 圈定的 FL2VA/（和/或 Ref2VA/）。

这里有一个对不上的地方值得先讲：README 正文给的 <TASK>/ 结构里写的是 visual_vae/，而仓库文件树里实际可见的目录名是 video_vae/（下面有 klvae.py、vae_vit.py、vae_cnn.py、parallel.py、attention.py、flash.py 等文件）。也就是说，README 的示意结构和仓库实际内容在这个目录名上并不一致。核对的时候以你 ls 出来的实际结果为准，别因为没看到 visual_vae/ 就以为下漏了。audio_vae/ 侧是一组 dac_*.py 加 minimax_h3_audio_vae.py；transformer/ 下有 config.json 与 model.safetensors.index.json。这些文件名只适合作为「东西确实在」的核对项，别据文件名去猜它们的实现。

端口上。 两条命令各自绑 0.0.0.0，一个 30010、一个 30011。两条都起，那就是两个进程、两个端口、两份 checkpoint，不是一个服务的两个路由。

七、怎么验收

我没有跑过，所以这一节给的是「人该检查哪几处」，不是「你会看到什么日志」。

  1. 权重目录对不对。 --local-dir MiniMax-H3 之后，本地应该出现 FL2VA/（和/或 Ref2VA/）以及 model_index.json，展开后是上一节那套目录。如果 FL2VA/ 是空的或者只有零星几个文件，多半是 --include 的引号被 shell 吃掉了，回去核对命令。
  2. 端口与变体有没有对上。 最容易错的一步就在这儿：复制第一条命令改端口的时候忘了同步改 --model-variant，结果 30011 上跑的其实还是 fl2va。起完之后先确认 30010 对应 fl2va、30011 对应 ref2va。
  3. 两个服务是不是都需要。 如果你只起了一个却期望两类能力都可用，那是规划问题不是报错问题——服务本身不会替你提示。
  4. diffusers 来源。 装的到底是 PyPI 版还是 minimax-h3 分支，这一条建议在起服务之前就确认，别等到加载模型类时才发现。
  5. 端到端有没有跑通。 仓库 scripts/readme/ 目录下提供了三个可复现脚本：reproducible-768p-t2va-request.sh、reproducible-768p-fl2va-request.sh、reproducible-768p-ref2va-request.sh，分别对应 README 里的三个 768p 用例。我没有读取这些脚本的内容，所以不会描述里面的请求体字段——你自己打开看，它们是官方给的、最接近「验收标准」的东西。

顺带提醒：README 在讲 Full 2K Workflow 时给的环境变量里有 TOKEN="<token>"，这是 MiniMax 平台的 API token。写脚本、贴日志、发帖求助的时候一律用占位符，别把真值带出去。

八、什么情况不该走这条路

只想在单机上做小规模验证的时候。 官方给的是一个 4 GPU 配置的示例命令，而 --ulysses-degree、--performance-mode 这两个选项我们连含义都没有官方依据，等于你一开始就要在一套自己看不懂的参数上做调整。如果目标只是「先看看 H3 是个什么东西」，那更合适的入口是 ComfyUI 那条线——它用的是 Comfy-Org/MiniMax-H3 的量化权重（pruned_int8_convrot / nvfp4_awq），教程在 docs.comfy.org/tutorials/video/minimax/minimax-h3。但请注意：MiniMax 官方发布的 checkpoint 是 BF16，ComfyUI 那边是量化权重，两条线的结果不要混着评估，官方没有给任何两者之间的对比数据，我也不会瞎猜差多少。

只用 diffusers 做实验的时候。 前面说过，diffusers 用户不需要手动下权重，ModularPipeline.from_pretrained 会拉齐组件。这种情况下你既不需要 hf download --include，也不需要 sglang serve。

指望本地部署直接得到官方那种效果的时候。 这是 H3 最需要提前说清楚的结构性事实：完整系统由三个模块组成，开源的只有中间的 H3-Base，产出 768p；前面的 H3-Context-IR 与后面的 H3-Regenerate-2K 都没有随本次开源发布，官方只提供 API。README 还特别强调 H3-Context-IR 对最终输出质量至关重要，强烈建议要么把它接进你的生成流程，要么照「Prompting Guidance」自建一套上下文预处理系统。所以起好 SGLang 服务 = 你有了 768p 的 H3-Base，不等于你复现了官方的 2K 结果。要走 Full 2K Workflow，就得把本地 SGLang 服务与官方 API 组合起来，这是另一个话题了。

要评估「跑不跑得动」的时候。 官方仓库没有给显存、速度、体积一类数据，本文一个都没有。你需要的是拿 SGLang 那份部署指南对着自己的机器算，而不是照抄一篇文章里的数字。

延伸阅读

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

想系统学会用 AI？报名体系课或加入会员，照着学、照着用。

浏览课程 加入会员