使用 SGLang 部署 MiniMax-H3
本文记录在单机 NVIDIA GPU 服务器上使用 SGLang Diffusion 部署 MiniMax-H3 的过程，包括模型检查、运行环境、服务配置、Web 页面、Spectrum 加速和常见问题。
一、环境与目录
MiniMax-H3 是联合生成视频和音频的大型模型。完整权重约 500 GB，除了模型本身，还需要为 Python 依赖、量化缓存、SGLang 缓存和生成结果预留空间。
单卡部署可使用约 120 GiB 或更多的统一内存或主机内存。内存不足以让全部权重常驻时，SGLang 会逐层读取权重，因此磁盘吞吐会明显影响生成速度。
本文使用以下通用目录：
<DEPLOY_ROOT>/ ├── .venv/ Python 虚拟环境 ├── bin/ FFmpeg 和 FFprobe ├── compat/ 必要的兼容模块 ├── outputs/ 生成结果 ├── sglang-src/ 固定版本的 SGLang 源码 ├── last_prompt.txt 上次使用的提示词 ├── start.sh ├── stop.sh └── service.log <MODEL_ROOT>/MiniMax-H3/下载模型后，应检查文件数量、总大小及空文件：
find<MODEL_ROOT>/MiniMax-H3-typef|wc-ldu-sh<MODEL_ROOT>/MiniMax-H3find<MODEL_ROOT>/MiniMax-H3-typef-size0模型根目录应包含完整配置，以及 FL2VA 分区所需的 transformer、text encoder、video VAE、audio VAE、processor 和 tokenizer。下载工具提供校验值时，建议对全部文件执行 SHA-256 校验。
二、安装 SGLang 运行环境
创建独立环境，避免影响服务器上的其他推理服务：
python3-mvenv --system-site-packages<DEPLOY_ROOT>/.venv<DEPLOY_ROOT>/.venv/bin/python-mpipinstall--upgradepip<DEPLOY_ROOT>/.venv/bin/python-mpipinstall"sglang[diffusion]"gradio<DEPLOY_ROOT>/.venv/bin/python-mpipinstallcomfy-kitchen ninjacomfy-kitchen用作 ConvRot INT8 的兼容计算后端。若继承的系统环境出现 NumPy 与 SciPy ABI 冲突，可固定兼容版本，例如：
<DEPLOY_ROOT>/.venv/bin/python-mpipinstall"numpy==1.26.4"如果稳定版尚未包含所需的 MiniMax-H3 功能，可以安装固定提交的 SGLang 源码：
gitclone https://github.com/sgl-project/sglang.git<DEPLOY_ROOT>/sglang-srccd<DEPLOY_ROOT>/sglang-srcgitcheckout<VERIFIED_COMMIT>SGLANG_BUILD_RUST_EXTS=none\<DEPLOY_ROOT>/.venv/bin/python-mpipinstall\--no-build-isolation --no-deps-epython生产环境应记录提交号和完整依赖版本，升级前重新执行端到端生成测试。
三、启动 MiniMax-H3 服务
下面的配置加载 FL2VA 分区，同时提供文生视频和首尾帧控制。ConvRot INT8 用于降低 DiT 权重占用，DiT 与文本编码器采用逐层卸载，以适应单卡内存容量。
#!/usr/bin/env bashset-euopipefailAPP_DIR="<DEPLOY_ROOT>"MODEL_DIR="<MODEL_ROOT>/MiniMax-H3"PID_FILE="$APP_DIR/service.pid"LOG_FILE="$APP_DIR/service.log"mkdir-p"$APP_DIR/outputs"if[[-f"$PID_FILE"]]&&kill-0"$(cat"$PID_FILE")"2>/dev/null;thenecho"Service is already running"exit0ficd"$APP_DIR"nohupenv\PATH="$APP_DIR/.venv/bin:$APP_DIR/bin:$PATH"\PYTHONPATH="$APP_DIR/compat"\PYTORCH_CUDA_ALLOC_CONF=expandable_segments:True\"$APP_DIR/.venv/bin/sglang"serve\--model-path"$MODEL_DIR"\--model-variant fl2va\--num-gpus1\--quantizationconvrot_int8\--attention-backend fa\--performance-mode memory\--layerwise-offload-components dit text_encoder\--dit-offload-prefetch-size1\--dit-layerwise-resident-layers0\--enable-torch-compilefalse\--host127.0.0.1\--port30010\--webuitrue\--webui-port7860\--output-path"$APP_DIR/outputs"\>"$LOG_FILE"2>&1&echo$!>"$PID_FILE"停止服务时读取 PID 文件并正常结束进程：
#!/usr/bin/env bashset-euopipefailPID_FILE="<DEPLOY_ROOT>/service.pid"if[[-f"$PID_FILE"]];thenPID="$(cat"$PID_FILE")"ifkill-0"$PID"2>/dev/null;thenkill"$PID"wait"$PID"2>/dev/null||truefirm-f"$PID_FILE"fi启动后可检查服务状态：
curl-ihttp://127.0.0.1:30010/livenesscurl-ihttp://127.0.0.1:30010/healthcurl-Ihttp://127.0.0.1:7860//liveness返回 200 表示进程存活；/health在模型加载和预热期间可能返回 503，预热结束后应变为 200。首次启动需要完成权重映射、INT8 转换、VAE 加载和生成预热，通常需要数分钟。
相关资料：
- SGLang MiniMax-H3 官方指南
- SGLang Diffusion 安装说明
- MiniMax-H3 ModelScope 模型页
