MiniMax-H3 视频生成部署

vLLM-MUSA 0.31.0 通过 vllm-omni 支持 MiniMax-H3 视频生成。本文介绍基础版文生视频、FastH3 快速版文生视频以及首帧图生视频的部署和验证流程。

1. 功能范围

任务	版本	去噪步数	说明
T2VA 文生视频	基础版	50	画质优先
FL2VA 首帧图生视频	基础版	50	使用首帧图片引导视频生成
T2VA 文生视频	FastH3 快速版	4	需要先融合 LoRA，适合快速预览

FastH3 快速版只用于文生视频；首帧图生视频只支持基础版。

示例使用单机 8 张 S4000，默认生成 1344 × 768、24 FPS 的视频。实际耗时取决于视频时长、输入内容、去噪步数和运行配置。

2. 拉取镜像并启动容器

以下命令在宿主机执行。宿主机需要完成 Linux Driver、MTML 和容器工具链检查，详细要求见环境准备。

拉取支持 MiniMax-H3 的 vLLM-MUSA 0.31.0 镜像：

docker pull \
  registry.mthreads.com/mcconline/inference/vllm:v0.31.0-amd64-qy-musa5.2.0

使用 8 张 S4000 启动 MiniMax-H3 训练容器：

docker run -itd --privileged --net host --runtime=mthreads \
  --name minimax-h3-s4000 \
  -w /workspace \
  --shm-size=16g \
  -e MTHREADS_VISIBLE_DEVICES=all \
  -e MTHREADS_DRIVER_CAPABILITIES=compute,utility \
  -v /data:/data \
  --entrypoint /usr/bin/sleep \
  registry.mthreads.com/mcconline/inference/vllm:v0.31.0-amd64-qy-musa5.2.0 \
  infinity

进入容器：

docker exec -it minimax-h3-s4000 bash

如果宿主机包含不小于 256 GB 的内存，应提前确认 IOMMU 已开启，否则可能影响 S4000 推理性能。检查和配置方法见IOMMU 配置检查。

3. 进入脚本目录

进入 vLLM-MUSA 0.31.0 容器后，执行：

docker exec -it minimax-h3-s4000 bash
cd /workspace/h3-s4000-scripts

常用脚本及绝对路径如下：

文件	容器内绝对路径	用途
env.sh	/workspace/h3-s4000-scripts/env.sh	配置基础模型和 LoRA 路径
fuse.sh	/workspace/h3-s4000-scripts/fuse.sh	融合 FastH3 LoRA
launch.sh	/workspace/h3-s4000-scripts/launch.sh	启动基础版或快速版服务
validate.sh	/workspace/h3-s4000-scripts/validate.sh	检查服务并发送视频生成请求
stop_serve.sh	/workspace/h3-s4000-scripts/stop_serve.sh	停止当前 MiniMax-H3 服务

同一组 GPU 一次只能运行一个 MiniMax-H3 服务。切换基础版、快速版或端口前，先停止已有服务：

bash /workspace/h3-s4000-scripts/stop_serve.sh

4. 下载模型和 LoRA

类型	默认路径	用途
基础模型	/data/models/MiniMax-H3/FL2VA	基础版推理和快速版融合
LoRA 权重	/data/models/FastH3-Preview-v1-LoRA/dense-datafree/adapter_model.safetensors	快速版 LoRA 融合
融合模型	/data/models/FastH3-Dense-Fused/FL2VA	快速版推理

安装 Hugging Face CLI 并下载资源：

python3 -m pip install -U huggingface_hub
mkdir -p /data/models

hf download MiniMaxAI/MiniMax-H3 \
  --include "model_index.json" "FL2VA/*" \
  --local-dir /data/models/MiniMax-H3

hf download FastVideo/FastVideo-FastH3-4-step-Preview-v1-LoRA \
  dense-datafree/adapter_model.safetensors \
  --local-dir /data/models/FastH3-Preview-v1-LoRA

无法连接 Hugging Face 或下载超时时，可以临时设置镜像地址：

export HF_ENDPOINT=https://hf-mirror.com

使用自定义模型路径时，在当前终端加载环境：

source /workspace/h3-s4000-scripts/env.sh \
  /data/custom_models/MiniMax-H3/FL2VA \
  /data/custom_models/FastH3-Preview-v1-LoRA/dense-datafree

自定义路径只在当前终端有效，重新进入容器后需要再次执行 source /workspace/h3-s4000-scripts/env.sh。

5. 融合快速版 LoRA

fuse.sh 位于容器内的 /workspace/h3-s4000-scripts/ 目录。基础模型和 LoRA 下载完成后，进入脚本目录并检查文件：

cd /workspace/h3-s4000-scripts
ls -l fuse.sh

执行融合：

bash /workspace/h3-s4000-scripts/fuse.sh

默认输出目录为 /data/models/FastH3-Dense-Fused/FL2VA。指定其他输出目录：

bash /workspace/h3-s4000-scripts/fuse.sh /data/custom_models/FastH3-Dense-Fused

融合过程需要充足的主机内存和约 80 GB 额外磁盘空间。融合完成后保留基础模型和原始 LoRA，便于重新融合或切换版本。

6. 启动 FastH3 快速版

启动快速版服务：

bash /workspace/h3-s4000-scripts/launch.sh preview

服务默认监听 8000 端口。需要更换端口时，先停止旧服务：

bash /workspace/h3-s4000-scripts/stop_serve.sh
bash /workspace/h3-s4000-scripts/launch.sh preview --port 8001

服务在后台加载模型，脚本默认最多等待 1800 秒。发送 5 秒视频生成请求：

DURATION=5 bash /workspace/h3-s4000-scripts/validate.sh preview

validate.sh 每 5 秒检查 /health，收到 HTTP 200 后再提交视频生成请求。DURATION 支持 4～15 秒，默认 8 秒；实际时长可能因帧数对齐略有差异。

7. 启动基础版文生视频

停止快速版服务，启动基础版：

bash /workspace/h3-s4000-scripts/stop_serve.sh
bash /workspace/h3-s4000-scripts/launch.sh quality

生成 5 秒文生视频：

DURATION=5 bash /workspace/h3-s4000-scripts/validate.sh quality

8. 启动首帧图生视频

首帧图生视频复用 quality 服务。服务已启动时不需要重复执行 launch.sh。

使用内置示例图片和提示词：

DURATION=5 bash /workspace/h3-s4000-scripts/validate.sh fl2va

将实际首帧图片放到 /data/my_first_frame.png，再使用自定义提示词：

bash /workspace/h3-s4000-scripts/validate.sh fl2va \
  /data/my_first_frame.png \
  'Pull focus to the people in the background and add more steam to the ramen bowl.'

/data/my_first_frame.png 是示例路径，请替换为实际文件。首帧图片建议使用 1344 × 768 或其他 16:9 图片，格式为 PNG 或 JPEG。

9. 超时与输出

9.1 超时参数

变量	默认值	说明
WAIT_TIMEOUT	1800 秒	等待服务加载完成和 /health 返回 HTTP 200 的最长时间
REQUEST_TIMEOUT	7200 秒	等待视频生成请求完成的最长时间
DURATION	8 秒	生成视频时长，支持 4～15 秒

例如同时调整服务等待、请求等待和视频时长：

WAIT_TIMEOUT=3600 \
REQUEST_TIMEOUT=14400 \
DURATION=5 \
bash /workspace/h3-s4000-scripts/validate.sh preview

9.2 输出与日志

生成结果和响应头保存在：

/data/minimax-h3-runtime/output/

服务日志保存在：

/data/minimax-h3-runtime/logs/

快速版服务日志通常位于 /data/minimax-h3-runtime/logs/h3_serve_preview.log。请求超时或生成失败时，应同时检查服务日志、输出目录和 GPU 状态。

10. 使用限制与部署建议

10.1 使用限制

• 同一组 GPU 上不要并行启动多个 MiniMax-H3 服务。
• 切换基础版、快速版或端口前必须执行 bash /workspace/h3-s4000-scripts/stop_serve.sh。
• FastH3 快速版必须先完成 LoRA 融合；首帧图生视频必须使用基础版。

10.2 启动状态判断

服务会在后台加载模型。短时间没有生成结果不能直接判定任务挂起，应结合启动日志、服务健康检查和 WAIT_TIMEOUT 判断服务是否仍在加载。

10.3 部署建议

• 正式部署前应使用实际视频时长、首帧图片和提示词验证生成内容、等待时间和显存占用。