MiniMax H3 本地部署完整指南：从环境校验到多卡推理

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

如果你正在寻找一个能真正"多模态一把抓"的开源模型，MiniMax H3 值得你花一个下午来折腾。它是一个通用的全模态生成系统，能同时理解文本、图像、视频和音频组成的混合上下文，并直接生成带原生立体声的视频——最高支持 2K 分辨率、15 秒时长、32kHz 双声道音频。这篇本地部署教程会带你从零开始，把 H3 跑在自己的机器上，并给出可落地的 MiniMax H3 性能优化手段。读完你不仅能复现官方示例，还能按需扩展多卡推理与 2K 工作流。

动手之前，先回答三个问题

本地部署最大的敌人不是代码，而是"想当然"。在敲第一条命令前，先对照这份清单自查一遍，能省下后面 80% 的排查时间。

你的机器够不够格？

H3 的完整链路包含文本编码器、视觉 VAE、音频 VAE 和一个 33B 参数的 Omni-Transformer，BF16 精度下整包权重就要占掉大量显存。下面这张表直接给你两档标准：

一句话结论：单张 24GB 卡可以跑通，但不要期待速度；想要接近官方演示的体验，4 卡起步。

软件环境该用什么版本？

• 操作系统：Ubuntu 20.04 / 22.04 LTS（其他发行版也能跑，但下面命令默认 apt/yum 系）
• Python：3.8–3.10（3.11 部分依赖可能编译报错）
• CUDA：11.7 及以上，驱动版本与 PyTorch 匹配即可
• 容器（可选）：Docker 20.10+，如果你不想污染宿主环境

要不要提前准备密钥？

取决于你的目标：

• 只想本地生成 768p 视频：不需要任何 API 密钥，纯离线可跑。
• 想复现官方 2K 工作流：需要 MiniMax 开放平台的 API Token，因为 H3-Context-IR 和 H3-Regenerate-2K 目前以托管 API 形式提供，本地只负责跑 H3-Base。

两条路线：一条命令到位，还是逐环掌控？

安装模型依赖这事，社区里永远有两种流派，我们不妨先看清各自的适用场景再选。

路线 A：一键脚本，快速验证

如果你只是想"先看看这东西能不能出片"，用框架自带的拉取机制最省心。比如 diffusers 用户甚至不需要手动下载权重，一句from_pretrained就能把需要的组件按需拉齐。这条路的优点是零配置、出错面小；缺点是黑盒，遇到问题不好定位。

路线 B：手动分步，全程可控

如果你打算把它做成服务、接进业务线，或者要折腾多卡并行、自定义预处理，那就老老实实走"克隆仓库 → 安装依赖 → 下载权重 → 启动服务"这条链路。每一步都知道发生了什么，后续调优才有抓手。

我们的推荐：第一次跑，用路线 B 把流程完整走一遍（本文核心章节就是为它写的）；等环境稳定后，再固化成一个脚本供团队复用。

把家当备齐：权重、目录与凭据

第一步：拿到代码

# 克隆仓库（含全部脚本与示例） git clone https://gitcode.com/MiniMax-AI/MiniMax-H3 cd MiniMax-H3

仓库里的scripts/readme/目录存放着所有官方复现脚本，后面会反复用到，先混个脸熟。

第二步：装依赖

官方推荐用 SGLang / vLLM / diffusers 三种框架之一来推理，三者任选即可，不必全装：

# 基础依赖 pip install -r requirements.txt # 推理框架三选一（或都装，方便对比） pip install sglang # 官方示例默认用它 pip install vllm # 偏好 vLLM 生态就选它 pip install diffusers transformers accelerate # 面向 Python 脚本调用

第三步：下载模型权重

H3 以两种任务化 checkpoint 发布：FL2VA（文生视频 / 首尾帧生视频）和Ref2VA（多模态参考生视频）。每个 checkpoint 都是自包含的目录，结构长这样：

FL2VA/ ├── model_index.json ├── processor/ # 图像/视频预处理 ├── tokenizer/ # 分词器（含 H3 专用特殊 token） ├── text_encoder/ # 文本编码器 ├── transformer/ # Omni-Transformer 主模型 ├── video_vae/ # 视觉 VAE └── audio_vae/ # 音频 VAE（独立声道编码）

下载时可以用 HF 官方工具，也可以按你的网络环境选国内镜像：

# 只拉一个任务族，省流量 hf download MiniMaxAI/MiniMax-H3 --include "model_index.json" "FL2VA/*" --local-dir MiniMax-H3

第四步：预填配置项

编辑项目根目录的config.json，把路径和生成参数一次设好，避免每次启动都带一堆参数：

{ "text_encoder_path": "text_encoder/", "video_vae_path": "video_vae/", "audio_vae_path": "audio_vae/", "transformer_path": "transformer/", "device": "cuda", "batch_size": 2, "num_inference_steps": 50 }

如果你要走 2K 工作流，还需要准备好三个环境变量：

SGLANG_DEPLOYMENT_URL="http://localhost:30010" # 本地 SGLang 服务地址 MINIMAX_API_BASE="https://api.minimaxi.com" # 中国区；海外区用 api.minimax.io TOKEN="<你的开放平台 API Token>" # 去 MiniMax 平台申请

正式开跑：先让 768p 动起来

最小可用配置的目标只有一个：让一条 T2VA 请求成功返回一个 mp4。这里我们以官方示例主用的 SGLang 为例。

启动推理服务

sglang serve \ --model-path MiniMaxAI/MiniMax-H3 \ # 或指向本地权重目录 --num-gpus 4 \ # 显存足够时先写 1 --ulysses-degree 4 \ # 序列并行度，单卡时改为 1 --performance-mode speed \ --host 0.0.0.0 \ --port 30010 \ --model-variant fl2va # 换 Ref2VA 任务时改成 ref2va

看到服务监听 30010 端口且日志无报错，说明第一步成功。

这一步很容易翻车：如果只有单张 24GB 卡，把--num-gpus和--ulysses-degree都改成 1，先把流程跑通再谈性能。

提交第一条生成请求

仓库里已经备好了可直接复用的脚本，不用自己拼 JSON：

# 文生视频（T2VA），脚本内 prompt 与官方示例完全一致 bash scripts/readme/reproducible-768p-t2va-request.sh # 首尾帧（FL2VA）、多模态参考（Ref2VA）同样有对应脚本 bash scripts/readme/reproducible-768p-fl2va-request.sh bash scripts/readme/reproducible-768p-ref2va-request.sh

脚本内部做的事情就三步：POST 创建任务 → 轮询状态直到completed→ GET 下载视频，输出为当前目录下的t2va.mp4。如果你习惯手写请求，核心就是一个 curl：

curl --request POST \ --url http://localhost:30010/v1/videos \ --header 'Content-Type: application/json' \ --data '{ "task": "t2va", "prompt": "A cinematic shot of a starship bridge, camera slowly pushing in...", "conditions": [], "target": {"short_edge": 768, "aspect_ratio": "16:9", "duration_seconds": 10}, "seed": 0 }'

请求参数值得单独说两句：short_edge控制短边像素，默认 768；duration_seconds支持 4–15 秒；seed固定后可复现同一条输出，调试时非常有用。

进阶：多卡并行与 2K 工作流

768p 跑通只是及格线。如果你想让 H3 真正"能打"，下面两件事值得继续做。

多卡部署的正确姿势

H3 的 Omni-Transformer 支持张量并行（tensor parallel）与序列并行（ulysses）。官方 4 卡示例的要点是：张量并行度与序列并行度的乘积要等于总卡数。也就是说 4 卡时通常配--tensor-parallel-size 2 --ulysses-degree 2，或直接按官方示例全走 ulysses。

换用 vLLM 时思路一致，只是参数名换成 vLLM 的约定写法。如果你两套框架都装了，建议同一条 prompt 各跑一次对比延迟，再决定生产环境用哪个。

复刻官方 2K 全流程

官方完整的 H3 系统由三个模块构成：H3-Context-IR（理解并改写多模态输入）、H3-Base（本地 768p 生成）、H3-Regenerate-2K（基于原上下文再生 2K）。其中 IR 与 2K 模块以 API 形式提供，所以 2K 工作流 =本地 SGLang + 开放平台 API：

# 第 1 步：调 Context-IR 把原始输入翻译成 H3 能吃的结构化 prompt bash scripts/readme/full-2k-t2va-h3-context-ir.sh # 第 2 步：把上一步得到的 prompt 交给本地 H3-Base 生成 768p bash scripts/readme/full-2k-t2va-h3-base.sh # 第 3 步：调用 2K 再生接口，产出 2K 视频 bash scripts/readme/full-2k-t2va-h3-regenerate-2k.sh

每个用例（T2VA / I2VA / Ref2VA）在scripts/readme/下都有一整套同名脚本，并且附了直接用 API 生成的 2K 与 768p 参考视频，方便你校验本地结果的质量差距。

跑顺之后，再谈优化：速度、显存与稳定性

能出片只是开始。把这节三个维度过一遍，你的服务才算真正"可交付"。

速度：先把序列并行拉满

原理是 33B 模型单卡推理时，长序列的注意力计算是绝对瓶颈；张量/序列并行能把这部分摊到多卡上。操作建议：GPU 数量越多，ulysses-degree优先调高；同时确认启动了 Flash Attention 等高效注意力内核，这一步对长视频序列的提速往往以倍数计。

显存：从精度和批大小两头挤

原理是 BF16 已经是当前 release 的官方精度，再往下压精度会损伤画面质量，性价比不高。所以更推荐的杠杆是批大小：先确认单条请求的峰值显存，再把batch_size提到不触发 OOM 的上限。操作建议：显存吃紧时先砍batch_size，而不是动精度。

稳定性：控制并发与输入长度

原理是 15 秒视频的 token 序列非常长，参考输入过多时（Ref2VA 最多 12 个文件）会让服务端负载陡增，表现就是偶发超时。操作建议：给服务套一层请求排队，限制同时进行的生成任务数；对超长 prompt 先做裁剪再提交。

踩坑锦囊：高频问题与对应解药

下面这几个问题，基本是每个部署 H3 的人都会撞上的，提前打个预防针。

症状 1：服务启动直接 OOM，进程被杀原因：单卡显存装不下 33B 模型加长序列。解药：把--num-gpus降不下去的话，先确认没有别的进程占着显存（nvidia-smi看一眼），再尝试最小配置——单卡 +--ulysses-degree 1+ 768p + 短时长，能跑通再逐步加码。

症状 2：请求提交后一直pending，迟迟不出结果原因：多半是 prompt 过长导致序列超限，或 batch 里积压了太多任务。解药：先用仓库自带脚本的原版 prompt 验证环境，确认无误后再换自己的长 prompt；同时检查是否多个请求并发挤在同一服务上。

症状 3：模型加载时报权重缺失或路径错误原因：权重没下全，或model_index.json与子目录不匹配。解药：用hf download重新完整拉取对应任务族，确认FL2VA/、Ref2VA/下各子目录齐全；diffusers 用户优先用ModularPipeline.from_pretrained(...)让它自动补齐组件。

症状 4：同样 prompt 每次结果不一样，难以复现原因：seed 未固定，或推理框架的随机性没有关闭。解药：请求里显式带上"seed": 0，并在服务端保持--performance-mode一致。

症状 5：下载脚本提示连接被拒（connection refused）原因：服务没起来，或端口没对上。解药：确认sglang serve的--port与脚本里的localhost:30010一致；多卡场景下还要确认所有 GPU 都被成功分配，而不是其中一张卡悄悄掉线。

收尾：你已经能独立交付一条 H3 生成链路

到这里，你应该已经完成了从环境校验、依赖安装、权重下载到服务启动、请求提交、多卡扩展、以及基于三个维度的性能优化——一套完整的 MiniMax H3 本地部署闭环。如果只让你记住三件事，那就是：先跑通单卡 768p，再谈并行；调优优先动序列并行和批大小，别轻易动精度；2K 工作流依赖 API，密钥提前备好。

想继续深入，可以从这几份材料入手：

• 官方复现脚本全集：scripts/readme/，每个用例都带注释
• 授权与合规问答：docs/QA-about-License.md
• Prompt 写作指南（基础版 / 参考版）：docs/VIDEO_PROMPT_WRITING_GUIDE_base_en.md、docs/VIDEO_PROMPT_WRITING_GUIDE_ref_en.md

如果你在部署过程中踩到了本文没写到的坑，欢迎带着你的日志和配置来交流；如果你有更巧妙的调优思路，也欢迎分享出来，我们一起把这份指南越磨越顺。

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