本地部署
进阶
🗓 2026-08-27
⏱ 阅读需约 25 分钟
MiniMax H3 本地部署实操完整教程 (ComfyUI 版)
MiniMax H3 本地部署的实操指南，这份教程基于目前最成熟、社区支持最好的 ComfyUI 生态方案，涵盖了从环境准备、模型下载、配置避坑到性能优化的全流程。
一：硬件与环境自检
请确认你的硬件是否满足“能跑”且“好用”的标准：
| 硬件组件 | 最低门槛 (勉强能跑) | 推荐配置 (流畅体验) | 备注 |
|---|---|---|---|
| GPU 显存 | 8GB (需极致量化+慢速) | 12GB - 16GB | 8GB 仅适合测试，生成速度慢且易 OOM；12GB+ 可运行 INT8/NVFP4 量化版。 |
| 系统内存 | 32GB | 64GB | 显存不足时会溢出到内存，内存小会导致系统卡死。 |
| 硬盘空间 | 100GB SSD | NVMe SSD (预留150GB+) | 严禁使用机械硬盘加载模型，否则读取极慢甚至超时失败。 a |
| 操作系统 | Windows 10/11 | Windows 10/11 或 Linux | 确保 NVIDIA 驱动更新至最新稳定版。 |
- 操作系统：优先选择Windows 10/11或搭载NVIDIA GPU的Linux系统，是目前文档和社区支持最完善的组合。
- GPU驱动：提前更新NVIDIA显卡驱动，已安装ComfyUI的用户需确认PyTorch和CUDA可正常识别GPU。
- 内存与存储：系统内存最低32GB，推荐64GB；NVMe固态硬盘至少预留80-100GB空间，完整官方FL2VA目录需预留150GB以上空间。
环境检查命令： 打开终端（CMD 或 PowerShell），输入以下命令确认 CUDA 可用：
python
python -c "import torch; print(torch.cuda.is_available()); print(torch.version.cuda)"
确认环境，如果返回 True 且版本号 ≥ 12.1，则环境基本合格，继续往下
二：安装 ComfyUI
MiniMax H3 需要较新版本的 ComfyUI 核心支持。
1. 全新安装用户：
- 下载 ComfyUI Portable (便携版：https://github.com/comfyanonymous/ComfyUI/releases ) 或推荐使用国内知名的“秋叶整合包”（已预配好环境）。
- 解压到全英文路径（例如 D:\ComfyUI，不要放在 D:\软件\AI 这种含中文或特殊字符的路径）。
2. 已有用户升级：
- 进入 ComfyUI 根目录，执行更新：
bash
git pull
- 关键要求：确保 ComfyUI 核心版本 ≥ 0.30.0。旧版本原生不支持 H3 节点，强行安装插件容易冲突。
- 更新依赖：
bash
pip install -r requirements.txt
- 解压安装包后运行对应启动脚本，浏览器会自动打开ComfyUI工作台。
三：下载核心模型文件
注意：MiniMax H3 不是单个大文件，而是由 4 个核心组件 组成。请务必将它们放入正确的文件夹。
推荐使用 NVFP4 量化版 或 INT8 量化版，它们在画质损失极小的情况下，大幅降低显存占用。
| 部署方案 | 显存要求 | 系统内存 | 适配说明 |
|---|---|---|---|
| NF4量化+磁盘卸载 | 约6GB | 32GB起 | 仅支持纯文生视频，权重按层从磁盘加载，生成速度极慢 |
| NF4量化（DiffSynth-Studio） | 7-8GB | 32GB起 | 框架自动管理显存，RTX 3060可正常运行 |
| INT8量化（ComfyUI） | 8-12GB | 32GB起 | 社区优化版本，平衡画质与生成速度，是个人用户主流选择 |
| 非量化原生部署 | 12GB+ | 64GB+ | 完整精度运行，适合有二次开发需求的用户 |
| 模型组件 | 文件名示例 (以量化版为例) | 存放路径 | 说明 |
|---|---|---|---|
| 扩散模型 (Diffusion) | minimax_h3_fl2va_pruned_int8_convrot.safetensors 或 minimax_h3_fl2va_pruned_nf4.safetensors | ComfyUI/models/diffusion_models/ | 核心生成引擎，约 8-15GB |
| 文本编码器 (Text Encoder) | qwen3vl_32b_minimax_h3_nvfp4_awq.safetensors | ComfyUI/models/text_encoders/ | 理解提示词，约 10-20GB (量化后较小) |
| 视频 VAE | minimax_h3_video_vae_fp16.safetensors | ComfyUI/models/vae/ | 必须用 FP16，约 4-5GB |
| 音频 VAE | minimax_h3_audio_vae_fp32.safetensors | ComfyUI/models/vae/ | 必须用 FP32，约 500MB-1GB |
下载地址指引：
- Hugging Face（ https://huggingface.co 国内镜像 https://hf-mirror.com ）: 搜索 MiniMaxAI/MiniMax-H3 或社区量化仓库 VantageWithAI/MiniMax-H3-comfyUI-GGUF (如果使用 GGUF 格式)。
- ModelScope (魔搭 https://www.modelscope.cn ): 国内用户推荐在此搜索 MiniMax-H3，下载速度更快。
注意：
- 音频 VAE 必须是 FP32 格式，如果是 FP16 会导致音画不同步或报错。
- 不要混用不同来源的模型版本（如官方原版权重与社区量化权重混用），建议全套使用同一套量化方案。
四：模型文件部署
- 打开ComfyUI左侧模板库，进入Video分类选择MiniMax H3模板，点击运行后模型会自动从HuggingFace下载，国内用户可切换为ModelScope镜像加速下载。
- 手动下载模型需将.safetensors文件放入对应目录：
- 扩散模型/视频模型：ComfyUI/models/diffusion_models/
- 文本编码器：ComfyUI/models/text_encoders/
- 音频VAE、视频VAE：ComfyUI/models/vae/
- 核对文件完整性：T2V模式需4个基础文件，R2V模式需额外下载参考权重，不要混用不同版本的模型文件。
SGLang API服务部署（开发者/企业场景）
- 执行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服务启动命令，将端口调整为30011，指定model-variant ref2va即可完成多服务部署。
五：低显存适配方案
- 8-16GB显存用户可采用分片推理+模型量化方案，用ClipProj将视觉编码器从32B替换为4B，可将显存占用从15.7GB压缩至5GB左右。
- 配置32GB swap分区，将vm.swappiness参数设置为10，缓解系统内存压力，避免模型加载时内存溢出。
- 切换使用pruned NF4量化模型，修改配置文件中dit_checkpoint字段指向minimax-h3-fl2va-pruned-nf4.safetensors。
四：解决常见“踩坑”
1. 🔴 高频故障：插件冲突
- 现象：启动日志报错 ModuleNotFoundError: No module named 'comfy.ldm.minimax.model'，且工作流中 CLIP 加载器下拉菜单没有 minimax 选项。
- 原因：第三方插件 comfyui-minimax-h3-audio-T8 与 ComfyUI-KJNodes 或其他 H3 辅助插件存在导入冲突。
- 解决方案：
- 关闭 ComfyUI。
- 进入 ComfyUI/custom_nodes/ 目录。
- 找到 comfyui-minimax-h3-audio-T8 文件夹，将其重命名为 _comfyui-minimax-h3-audio-T8 (前面加下划线以禁用) 或直接删除。
- 重启 ComfyUI。此时原生核心应能正确识别 H3 模型类型。
2.🔴 高频故障：显存溢出 (OOM)
- 现象：生成过程中报错 CUDA out of memory。
- 解决方案：
- 启用 Sage Attention：在 ComfyUI 管理器中安装 SageAttention 插件，或在启动参数中添加 --use-sage-attention (如果支持)。这能显著降低显存峰值。
- 降低分辨率：将生成分辨率设为 768P (如 1280x768)，不要直接尝试 1080P 或 2K。
- 关闭后台程序：关闭浏览器、游戏等其他占用显存的软件。
- 使用 NF4/INT8 模型：确保你下载的是量化版，而非原始 FP16/BF16 版。
五：加载工作流并生成
1. 获取工作流
- 在 ComfyUI 界面左侧点击 "Load" -> "Examples" -> "Video" -> 寻找 MiniMax H3 相关示例。
- 或者从社区下载专门的 .json 工作流文件，拖入 ComfyUI 界面。
2. 连接节点
- 确保 Load Diffusion Model 节点选择了你下载的 H3 扩散模型。
- 确保 Load CLIP 节点类型选择为 minimax (如果下拉菜单有此选项) 或对应编码器模型。
- 确保 Load VAE 节点分别加载了视频 VAE 和音频 VAE。
3. 生成测试
- 输入简单提示词，如："A cat sitting on a windowsill, raining outside, cozy atmosphere, high quality."
- 点击 "Queue Prompt"。
- 首次生成可能需要几分钟加载模型，后续生成速度会加快。
性能优化
- 加速采样：将采样步数 (Steps) 设置为 6-10 步，配合 DPM++ 2M Karras 或专用调度器，可在几乎不损失画质的前提下提升 3-5 倍速度。
- 磁盘缓存：确保 SSD 有足够的剩余空间（至少 50GB），用于存放临时缓存文件。
- Linux 用户：如果使用 Linux，建议设置 swap 分区至少 32GB，并将 vm.swappiness 设为 10，以防止内存不足时进程被杀。
最后确认清单：
[ ] ComfyUI 版本 ≥ 0.30.0
[ ] 4 个模型文件已放入正确文件夹
[ ] 音频 VAE 是 FP32 格式
[ ] 禁用了冲突的第三方音频插件
[ ] 显卡驱动已更新