MiniMax H3本地部署避坑指南3大推理框架怎么选、768p到2K全流程实录【免费下载链接】MiniMax-H3MiniMax H3 是一个通用的全模态生成系统。它支持对由文本、图像、视频和音频组成的多模态上下文进行统一理解并能生成分辨率高达 2K、时长可达 15 秒的带原生立体声音频的视频。得益于面向任务泛化的系统设计H3 在预训练阶段就已具备广泛的多模态上下文理解与生成能力能够出色地执行复杂的多模态指令。项目地址: https://ai.gitcode.com/MiniMax-AI/MiniMax-H3把 MiniMax H3 真正跑起来远比装个依赖、跑个脚本要绕。这个全模态生成系统能同时理解文本、图像、视频和音频四类上下文并输出自带原生立体声的视频——分辨率最高 2K、时长最长 15 秒。但当你兴冲冲 clone 下仓库看到 FL2VA 和 Ref2VA 两套 checkpoint、transformer 与 transformer_ref 两排目录时大概率会懵在原地我到底该加载哪个这篇 MiniMax H3 本地部署实录不按说明书的套路来只讲我实际踩过的坑和最终跑通的路径从选框架到出片一次说清。第一课先建立正确心智H3 是一套三段式系统本地只占其中一段新手最容易犯的认知错误是把 H3 当成一个模型文件。实际上官方把完整系统拆成了三个模块H3-Context-IR负责把杂乱的多模态输入消化成模型看得懂的标准化指令对成片质量影响最大但它依赖多阶段托管服务没有随仓库开源只能通过官方 API 调用H3-Base真正在本地跑的生成主体输入 Context-IR 的输出产出 768p 分辨率的音视频H3-Regenerate-2K把 768p 结果和原始上下文一起喂回模型原地再生出 2K 高清版本同样暂未开源以 API 形式提供。换句话说本地部署 H3-Base2K 输出 本地 H3-Base 两个托管 API 的组合拳。先把这个心智建立起来后面所有操作都不会跑偏。第二课打开仓库别晕先分清 FL2VA 与 Ref2VA 再谈部署仓库里同时躺着两个任务专用 checkpoint它们的输入规格完全不同用错等于白跑。Checkpoint支持任务输入条件输出H3-BaseFL2VA文生视频t2va、首帧/尾帧生视频fl2va、首帧图生视频i2va文本可选 0/1/2 张图片视频 音频H3-BaseRef2VA参考生视频ref2va文本 参考素材≤9 张图、≤3 段视频、≤3 段音频每段 2–15 秒总长 ≤15 秒总文件数 ≤12视频 音频每个 checkpoint 都是一个自包含目录内部由 processor、tokenizer、text_encoder基于 Qwen3-VL-32B 的 H3-Encoder、visual_vae、audio_vae 和 transformer33B 稠密 Omni-Transformer组成。下载时务必按框架范围取用别全量拖下来白白占盘# SGLang / vLLM 用原版 checkpoint按任务族裁剪下载范围 hf download MiniMaxAI/MiniMax-H3 --include model_index.json FL2VA/* --local-dir MiniMax-H3 # 需要 ref2va 时再补 Ref2VA/* hf download MiniMaxAI/MiniMax-H3 --include Ref2VA/* --local-dir MiniMax-H3diffusers 用户更省心ModularPipeline.from_pretrained(MiniMaxAI/MiniMax-H3)会自动按需拉取所需组件无需手动挑选目录。第三课三套推理框架横向对比没有最好只有最合适官方推荐了 SGLang、vLLM、diffusers、ComfyUI 四条路它们的定位差异很大先看结论再动手维度SGLangvLLMdiffusersComfyUI上手难度中一条命令起服务中一条命令起服务低Python 直接调低节点拖拽服务形态OpenAI 风格/v1/videos接口OpenAI 风格接口进程内 API图形化工作流多卡支持--num-gpus Ulysses 并行多卡并行成熟需自行封装模板支持典型场景生产服务、复现官方 2K 流程高吞吐推理快速实验、二次开发可视化调试我自己选择了 SGLang 作为主路径理由很实际官方 2K 工作流脚本默认对接的就是 SGLang 的v1/videos接口用它能少走弯路。启动命令如下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注意两个关键参数--model-variant必须和你要跑的任务族一致fl2va 换 ref2va 时记得改--ulysses-degree控制序列切分并行度一般与 GPU 数量对齐。第四课踩坑实录五个坑一个都别错过坑一model-variant 传错任务直接拒收。用 FL2VA 的启动参数去发 ref2va 请求接口会报参数不匹配。先确认你要跑的是文生视频还是参考生视频再决定 variant。坑二prompt 太朴素出片效果判若两模型。H3-Base 吃的是 Context-IR 产出的那种分镜 音效 配乐结构化长提示词。官方脚本里一段 10 秒视频的展开提示词动辄上千 token。没有 API 环境时请务必研读 docs 目录下的提示词写作指南否则你会误以为模型能力不行。坑三显存不够不是少喂数据能解决的。Omni-Transformer 是 33B 稠密模型初始开源版本只支持 full attention原生稀疏注意力后续才会放出长序列计算量很大。好消息是约 13B 的 AdaLN 分支参数在推理时可预计算并缓存、无需加载。硬资源不够时的回退顺序是降到 768p → 缩短时长到 4–5 秒 → 换更小的 batch最后才考虑多卡并行。坑四以为本地能直接出 2K。本地 H3-Base 只能到 768p想复现 2K必须把本地生成的 768p 视频作为base_video上传再调用托管的 Regenerate-2K 接口。这个认知不清你会浪费大量时间找2K 开关。坑五验证无门。好消息是 scripts/readme 目录提供了三套完全可复现的 768p 请求脚本t2va / fl2va / ref2va仓库 assets 里还附了官方参考输出视频跑完直接对比立刻知道自己对不对。第五课从零到出片一条完整的动线把上面的认知串起来实际动手只需要六步拉取仓库git clone https://gitcode.com/MiniMax-AI/MiniMax-H3 cd MiniMax-H3装好requirements.txt。按框架下载模型SGLang/vLLM 按第二课的命令裁剪下载diffusers 直接走from_pretrained自动拉取。启动服务按第三课的 SGLang 命令起一个 768p 的 H3-Base 实例。跑官方可复现脚本验证bash scripts/readme/reproducible-768p-t2va-request.sh脚本内部依次做了 POST 创建任务、轮询状态、下载成片三件事返回的t2va.mp4就是你的第一支 768p 带声音视频。接入 2K 工作流先配置三个环境变量把本地服务和托管 API 接起来export SGLANG_DEPLOYMENT_URLhttp://localhost:30010 export MINIMAX_API_BASEhttps://api.minimaxi.com # 海外版用 api.minimax.io export TOKEN你的平台Token按阶段依次调用Context-IR 展开提示词 → 本地 H3-Base 出 768p → Regenerate-2K 再生成 2K三个阶段的脚本一一对应full-2k-t2va-h3-context-ir.sh # 阶段一展开提示词 full-2k-t2va-h3-base.sh # 阶段二本地 768p 生成 full-2k-t2va-h3-regenerate-2k.sh # 阶段三API 再生 2K每个阶段都有官方给出的参考结果2K 与 768p 各一份方便你逐步对照校准。第六课避坑速查清单先确认任务族再定--model-variant别混用 FL2VA / Ref2VA下载模型按--include裁剪范围diffusers 用户交给from_pretrained提示词走结构化长文格式务必先读 docs 下的 Prompting Guidance本地只有 768p2K 必须组合托管 Regenerate-2K API显存吃紧时按降分辨率 → 缩时长 → 减 batch → 上多卡顺序回退出片后与 assets 下的官方参考视频逐帧对比验证部署正确性商用前先过一遍 LICENSE 与 docs/QA-about-License.md社区许可有使用边界。最后给不同读者的决策建议如果你是产品方想稳定出 2K 成片别纠结本地全家桶——直接用本地 SGLang 出 768p把 2K 交给官方 API成本和效果最均衡如果你是研究者diffusers 是二次开发最顺手的入口模型结构、Attention 与 VAE 源码都摊在仓库里任你读如果你是内容创作者ComfyUI 的现成模板可能比任何命令行都香。MiniMax H3 的本地部署难点从来不在装环境而在理解系统边界。搞懂了哪段在本地、哪段在云端、提示词该怎么写剩下的就只是按部就班地调用而已。延伸阅读提示词写作指南基础版与参考版在 docs/VIDEO_PROMPT_WRITING_GUIDE_base_en.md 和 docs/VIDEO_PROMPT_WRITING_GUIDE_ref_en.md可复现脚本全部位于 scripts/readme/许可说明见 docs/QA-about-License.md。【免费下载链接】MiniMax-H3MiniMax H3 是一个通用的全模态生成系统。它支持对由文本、图像、视频和音频组成的多模态上下文进行统一理解并能生成分辨率高达 2K、时长可达 15 秒的带原生立体声音频的视频。得益于面向任务泛化的系统设计H3 在预训练阶段就已具备广泛的多模态上下文理解与生成能力能够出色地执行复杂的多模态指令。项目地址: https://ai.gitcode.com/MiniMax-AI/MiniMax-H3创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考