必须使用 SGLang 源码版（v0.5.23-h3image）并严格对齐 BF16 权重、文本编码器及框架版本，单卡需 130GiB 显存或逐层 offload 配置；下载完整权重（135.38GB），不可删减文件；启动前验证路径结构与服务健康状态。
☞☞☞AI 智能聊天, 问答助手, AI 智能搜索, 多模态理解力帮你轻松跨越从0到1的创作门槛☜☜☜
要在本地运行 MiniMax H3-Image 图像生成与编辑模型，必须使用 SGLang 源码版并严格对齐 BF16 权重、文本编码器和框架版本，缺一不可——仅安装 pip 包或混用 diffusers/vLLM 会导致启动失败或输出乱码。
准备硬件与下载权重
先确认你手头的 GPU 显存是否满足最低要求：单卡至少需 【130GiB 可用显存】 才能启用 Auto 常驻模式；若用 RTX 4090（24GB）或双卡 48GB 配置，则必须启用逐层 offload，此时主存需 ≥256GB 且 NVMe 磁盘空间预留 ≥135GB 用于存放权重与缓存。
执行白名单下载命令，不跳过任何组件：
git clone https://github.com/MiniMax-AI/H3-Image.git && cd H3-Image && bash download_weights.sh --variant bf16
该脚本会拉取图像模型（68.65GB）、文本编码器（66.7GB）及可选提示词扩写模块 MiniMax-H3-Image-PE（17.9GB），总下载量约 135.38GB。注意：不要手动删减文件，【缺失 text_encoder/config.json 或 video_vae/model.safetensors 会导致服务启动后立即崩溃】。
安装支持 H3-Image 的 SGLang
必须从源码构建，不能用 pip install sglang 安装通用包：
git clone https://github.com/sg-lab/sglang.git && cd sglang && git checkout v0.5.23-h3image && pip install -e ".[diffusion]" --no-build-isolation
这一步会编译 diffusion 后端并绑定 H3-Image 专用算子。如果你跳过 checkout v0.5.23-h3image 直接装 main 分支，后续启动时会出现 “Unknown model type: h3_image” 错误。
验证安装是否成功：
python -c "import sglang; print(sglang.__version__)"; python -c "from sglang.srt.server_args import ServerArgs; print('OK')"
启动 H3-Image 服务
第一步：进入权重目录，确保路径结构为：
./H3-Image/
├── image_model/
├── text_encoder/
├── image_vae/
└── tokenizer/
第二步：单卡 H200 启动命令（2048×2048 输出）：
sglang serve \
--model-path ./H3-Image \
--num-gpus 1 \
--dtype bfloat16 \
--attention-backend flashinfer \
--port 30001
第三步：检查服务是否就绪：
curl http://localhost:30001/health
返回 {"status":"healthy"} 即表示服务已加载全部权重并完成初始化。若卡在 “Loading text encoder…” 超过 90 秒，大概率是 text_encoder/pytorch_model.bin 权重损坏，需重新下载。
