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-TransformerBF16 精度下整包权重就要占掉大量显存。下面这张表直接给你两档标准项目最低配置能跑 768p推荐配置流畅跑 768p / 尝试多卡GPU单卡 24GB如 RTX 30904×24GB 或更高支持 NVLink 更好显存24GB4×24GBSGLang 官方示例即 4 卡内存32GB64GB系统盘20GB 可用50GB 可用模型盘100GB 可用200GB 可用网络能访问模型托管站下载速度建议 ≥20MB/s一句话结论单张 24GB 卡可以跑通但不要期待速度想要接近官方演示的体验4 卡起步。软件环境该用什么版本操作系统Ubuntu 20.04 / 22.04 LTS其他发行版也能跑但下面命令默认 apt/yum 系Python3.8–3.103.11 部分依赖可能编译报错CUDA11.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_URLhttp://localhost:30010 # 本地 SGLang 服务地址 MINIMAX_API_BASEhttps://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。如果你习惯手写请求核心就是一个 curlcurl --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控制短边像素默认 768duration_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.mdPrompt 写作指南基础版 / 参考版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创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考