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

MiniMax H3 的 Full 2K Workflow：本地 SGLang 服务 + 官方 API 怎么串成一条链

2026-08-09

拿到 MiniMax H3 的开源权重之后，很多人第一反应是「下下来跑一把，看看 2K 什么样」。这个预期从一开始就错了。

截至 2026-08-09 的官方仓库 README 把 H3 拆成三个模块：H3-Context-IR 负责把越来越复杂的多模态输入理解、精炼成一套中间表示（Context Intermediate Representation），H3-Base 拿这个中间表示生成音视频、产出 768p 结果，H3-Regenerate-2K 再把 768p 结果连同原始上下文送回去重新生成 2K。开源的只有中间那一层——H3-Base 的两个 checkpoint。前面的 H3-Context-IR 没有包含在本次开源发布中，后面的 H3-Regenerate-2K README 明说「Due to the complexity of the system, this module is not yet open-sourced. We will release it once it is ready.」，两者都只提供 API。

所以官方给了两条验证路径：一条叫 Local Deployment of H3-Base，纯本地，验证 768p 输出；另一条叫 Full 2K Workflow，把本地部署的 H3-Base 和官方开放平台的 API 组合起来，端到端复现 2K 的结果。这篇讲的就是后者——它是一条半本地半云的链路，链路上每一环放在哪一侧，是先要搞清楚的事。

一、先把「哪一段在本地」画清楚

Full 2K Workflow 的本质是：上下文理解走 API，视频生成走本地，2K 重生成再走 API。

  • H3-Context-IR：调官方 /video-generation-v2-h3-context-ir
  • H3-Base：调你自己起的 SGLang 服务
  • H3-Regenerate-2K：调官方 /video-generation-v2-regeneration

这个切分有一点反直觉：大家默认「本地部署 = 数据不出网」，但在这条工作流里，输入侧的多模态素材要送给 Context-IR，输出侧的 768p 视频要送给 Regenerate-2K，两头都要出网。README 的「Safety Guardrails」章节还写明，用户提交的文本、图像与视频，以及增强后的提示词，都会经过自动审核，疑似违法、色情或侵犯第三方权利的内容可能被拦截；官方同时承认这套过滤是行业标准措施，无法消除误判与漏判。也就是说，走 API 的那两段是带审核的，纯本地那条 768p 路径不涉及这一层。如果你的素材有合规或保密约束，这一点要在开工前就摆到桌面上。

另外 README 有一句必须带出来的强调：「H3-Context-IR is critical to the quality of the final output, so we strongly recommend incorporating it into your generation pipeline or following the “Prompting Guidance” to build your own context-processing system.」——官方明确说这一层对最终质量至关重要，要么接它的 API，要么照 Prompting Guidance 自己建一套上下文预处理系统。它不是可以随手跳过的一步。

二、本地那一端：先限定下载范围，再起服务

权重下载

仓库把原始 checkpoint（FL2VA/、Ref2VA/）与 diffusers 格式并排托管在同一个 Hugging Face 仓库里，所以 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 这个选项为什么在这：不加它就是全量拉取，会把原始格式和 diffusers 格式两套东西一起拽下来。从仓库文件树能直接看到证据——tokenizer 相关文件在两套格式里重复出现（tokenizer.json 约 7.0 MB、vocab.json 约 2.8 MB、merges.txt 约 1.7 MB）。跑 SGLang 或 vLLM 的人只需要 FL2VA/* 与/或 Ref2VA/*；只做文生视频和首尾帧的人，Ref2VA/* 那一份可以不下。至于总共多大，官方没给这个数字，本文不猜。

--local-dir MiniMax-H3 决定权重落到哪个目录。README 给的每个 checkpoint 目录结构是自包含的 Hugging Face 风格：

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

下完先看这一层——如果 FL2VA/ 下面缺了 transformer/ 或 text_encoder/，先回去逐字核对 --include 那条命令（尤其是引号在你的 shell 里有没有被原样传进去），而不是急着起服务。

起 SGLang 服务

README 用 SGLang 作为部署示例，两个变体分别起、分别占端口。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，逐项说一下哪些能讲、哪些不能讲：

  • --model-variant 是唯一区分两个 checkpoint 的开关，fl2va 对应 Text-to-Audio-Video 与 First/Last-Frame-to-Audio-Video，ref2va 对应 Reference-to-Audio-Video。想同时提供这两类能力，就是两个服务实例、两个端口（示例里 30010 与 30011），不是一个服务内部切换。
  • --num-gpus 4 与 --ulysses-degree 4 在示例里取值相同。这里要克制：README 只是给了一个 4 GPU 的示例配置，没有说这是最低要求，所以正确的说法是「官方示例使用 4 GPU 配置」，而不是「需要 4 张卡」。--ulysses-degree 究竟是什么、改成别的值会怎样，我们没有事实来源，能说的只有「README 示例中它与 --num-gpus 同为 4」，本文不替它解释。--performance-mode speed 同理，只能说「示例里这么写」。
  • --host 0.0.0.0 意味着服务对外监听。它是为了让后续调用方（包括你把 SGLang 地址填进 SGLANG_DEPLOYMENT_URL 的那一步）能连上，但对外监听本身就是要在网络层管住的事。

更多部署配置 README 指向 SGLang 的 MiniMax-H3 部署指南（docs.sglang.io/cookbook/diffusion/MiniMax/MiniMax-H3#3-serve-minimax-h3）。我们没有取过那个页面的正文，所以除了上面这两条命令，任何别的启动参数都不要从本文这里拿。

三、API 那一端：三个变量和三个端点

README 在 Full 2K Workflow 开始前要求配置这几个变量，原样如下：

# URL of your SGLang deployment
SGLANG_DEPLOYMENT_URL="<sglang-deployment-url>"

# MiniMax API endpoint (choose one)
# CN
MINIMAX_API_BASE="https://api.minimaxi.com"
# Global
# MINIMAX_API_BASE="https://api.minimax.io"

# API token obtained from the MiniMax platform
TOKEN="<token>"

三个变量，三件事：SGLANG_DEPLOYMENT_URL 把上一节起好的本地服务接进来；MINIMAX_API_BASE 在 CN 与 Global 两个域名之间二选一（注意国内域名是 api.minimaxi.com，多一个 i，看走眼是很常见的事）；TOKEN 从 MiniMax 平台获取，在任何文档、截图、提交记录里都写成 <token> 占位符，不要图省事贴真值。

三个 API 端点按用途分工：

用途端点文档路径
创建 H3-2K/video-generation-v2-createplatform.minimax.io / platform.minimaxi.com 的 api-reference/video-generation-v2-create
H3-Context-IR/video-generation-v2-h3-context-ir同上 .../video-generation-v2-h3-context-ir
H3-Regenerate-2K/video-generation-v2-regeneration同上 .../video-generation-v2-regeneration

端点路径的前缀跟着 MINIMAX_API_BASE 走，文档站则是 platform. 开头的另一组域名，两者别混。

base_video 怎么传：Base64 还是公开 URL

这是整条链路上最容易在自己项目里翻车的一环。README 说明：示例把本地 H3-Base 的输出文件编码成 Base64 Data URL 传给后续接口；生产场景推荐把视频上传到公开可访问的 URL，并把该 URL 作为 base_video 传入。

官方例子用 Base64 是为了让脚本自包含、复制就能跑，不依赖你有没有对象存储。但把一段视频塞进请求体，请求体积会随视频线性膨胀，代理、网关、超时这些环节都可能在中间某处把它挡下来，而报出来的错未必长得像「请求太大」（这一段是通用的工程常识，不是 README 的内容，README 只给了「示例用 Base64、生产推荐公开 URL」这个结论）。如果你打算把这条链路做成常驻服务，从一开始就按官方推荐走公开 URL，别等到 Base64 在某个网关上炸了才改。反过来，如果你的视频素材本身就不适合放到公开可访问的地址上，那这条推荐路径对你不成立，得先解决存储与访问控制，而不是硬用 Base64 顶着。

四、三个 case 与可复现脚本

README 给了三个 case 演示整条 Full 2K Workflow，规格分别是：

case任务类型时长宽高比
case-T2VA文生视频10 秒16:9
case-I2VA首帧图生视频8 秒adaptive
case-Ref2VA多模态参考生视频（视频 + 音频）5 秒adaptive

这三行值得对照系统规格读一遍：H3 的输出时长范围是 4–15 秒，输出帧率 24 FPS，音频是 32 kHz 立体声，输出短边默认设为 768 像素，2K 需要通过 H3-Regenerate-2K 实现。三个 case 的 10 秒、8 秒、5 秒都落在时长范围内，而「adaptive」说明宽高比可以跟随输入素材而不是写死——对照着看，没有图像输入的 case-T2VA 给的是固定的 16:9，另外两个有图像或视频作为输入的用的是 adaptive。至于 adaptive 具体依据什么推导宽高比，README 没有展开，本文不猜。

每个 case 在仓库 scripts/readme/ 目录下都有对应的 .sh 脚本，覆盖 h3-context-ir、h3-base、h3-regenerate-2k 以及直接调用开放平台 API 的 2K 与 768p 参考结果。同一个目录下还有三个纯 768p 的可复现脚本：reproducible-768p-t2va-request.sh、reproducible-768p-fl2va-request.sh、reproducible-768p-ref2va-request.sh。文件名可以照着去仓库里找，但本文不描述这些脚本里的请求体字段——我们没有读过它们的内容，请求参数以你实际打开的脚本和官方 API 文档为准。

五、怎么验收

按链路顺序，人要盯这几处：

  1. 权重目录。--local-dir 指定的目录下，用到的那个任务族（FL2VA/ 或 Ref2VA/）是否结构完整、model_index.json 是否在。顺带一提，FL2VA/model_index.json 里 _class_name 是 MiniMaxH3Pipeline，_diffusers_version 是 0.32.2，text_encoder 指向 transformers 的 MiniMaxH3Qwen3VLHFEncoder——这几项能帮你确认下到的确实是这套权重。
  2. 两个端口。示例里 30010 跑 fl2va、30011 跑 ref2va。如果你只起了一个实例却指望它同时接 ref2va 请求，那是配置理解错了，不是服务的问题。
  3. 三个环境变量。特别是 MINIMAX_API_BASE 有没有选对区域，以及 TOKEN 是不是还停留在 <token> 占位符没替换。
  4. base_video 的传法。Base64 还是公开 URL，跟你当前是「跑通一次」还是「做成服务」要对得上。
  5. 中间产物。这条链路是 Context-IR → 本地 768p → Regenerate-2K 三段接力，出问题时先分清是哪一段。本地那段能不能单独跑通，用纯 768p 那条路径（Local Deployment of H3-Base）就能验证，不必一上来就串全链。

按链路顺序数下来，几处最需要提前防住的：权重下载没限定范围，导致目录结构不是自己预期的那样；把两个变体当成一个服务；base_video 用 Base64 在网关处被截断。至于依赖侧，仓库 requirements.txt 的官方注释里还留了一个坑值得提前知道——H3 的 diffusers 支持在官方文档里指向的是 diffusers 的 minimax-h3 分支，注释给的安装方式是 pip install "git+https://github.com/huggingface/diffusers.git@minimax-h3"，并写明等它落到 PyPI 再收紧上界。这条主要影响 diffusers 路线，但如果你的环境里混装了 PyPI 版 diffusers 又去找 H3 的模型类，报错会指向一个很容易误判的方向。

六、什么情况别走这条路

  • 要求全程离线或数据不得出网。Full 2K Workflow 两头都要调官方 API，且 API 侧带自动审核。这种情况只能走 Local Deployment of H3-Base 那条纯本地路径，接受 768p 输出。
  • 只需要 768p。那就没必要串 Regenerate-2K，多两个网络往返只是增加失败点。
  • 完全不打算接 Context-IR，也不打算按 Prompting Guidance 自建预处理。官方把这一层称为对最终质量至关重要，跳过它以后再来评价「H3 效果怎么样」，评的其实不是官方那条工作流。
  • 拿 ComfyUI 里的 H3 跟这套本地部署互相印证。ComfyUI 侧走的是 Comfy-Org/MiniMax-H3 的量化权重（pruned_int8_convrot / nvfp4_awq），MiniMax 官方发布的 checkpoint 是 BF16，两边不是同一份东西，别混着评估，也别拿一边的结论去解释另一边的现象。
  • 涉及授权与商用判断。H3 的许可是「MiniMax H3 Community License Agreement」，原文在 huggingface.co/MiniMaxAI/MiniMax-H3/blob/main/LICENSE，请直接读原文，本文不做任何解读。

最后提醒一句关于「能力」和「发布状态」的区分，这在 H3 的讨论里被混淆得很频繁：模型具备某种能力，和当前这个开源版本提供了什么，是两码事。H3-Context-IR 与 H3-Regenerate-2K 就是典型——它们是系统的一部分，但现在只有 API，README 也说了 Regenerate-2K 会在准备好之后发布。规划自己的方案时，按「今天能拿到什么」来排，而不是按「系统总览里画了什么」来排。

延伸阅读

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

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

浏览课程 加入会员