HunyuanImage-3.0 保姆级部署教程：腾讯 80B MoE 原生多模态图像生成模型，从环境搭建到 Gradio 界面

HunyuanImage-3.0 是腾讯混元团队开源的原生多模态图像生成模型，总参数 80B（MoE，64 个专家，每 token 激活 13B），采用统一自回归架构而非传统 DiT。它支持文生图、图生图（智能编辑）、多图融合、CoT 推理增强 prompt。官方基准显示其性能可与闭源顶级模型媲美。本文按官方 README，从 Python/CUDA 环境、依赖安装、模型下载、命令行生成到 Gradio Web 界面全流程讲清楚。

一、项目介绍与适用场景

HunyuanImage-3.0 由腾讯混元团队开发，2025 年 9 月开源。它有三个版本： - HunyuanImage-3.0：纯文生图（T2I），≥3×80GB 显存； - HunyuanImage-3.0-Instruct：带推理的图生图（I2I），支持智能 prompt 增强、图片编辑、多图融合，≥8×80GB 显存； - HunyuanImage-3.0-Instruct-Distil：蒸馏版，8 步采样即可出图，≥8×80GB 显存。

与站点此前写过的 FLUX、Qwen-Image 相比，HunyuanImage-3.0 的特点是：80B MoE 大模型（比 FLUX 大得多）、统一自回归架构（不是 DiT）、中文 prompt 理解强（腾讯出品）。代价是显存需求极高——Instruct 版需要 8 张 80GB 显卡。

什么是"统一自回归架构"？主流图像生成模型（SD、FLUX）都用 DiT（Diffusion Transformer）架构——先加噪再去噪。HunyuanImage-3.0 走的是自回归路线，像大语言模型一样逐 token 生成图像，把图像和文本放在同一个序列里建模。这种架构的好处是天然支持多模态理解（看图说话），同时生成图片；坏处是参数量大、推理慢。官方说这是"最大的开源图像生成 MoE 模型"——64 个专家，80B 总参数，每 token 只激活 13B，靠 MoE 在保持质量的同时控制推理成本。

适用场景： - 高质量中文文生图：腾讯对中文 prompt 做了优化； - 图片智能编辑：Instruct 版支持"基于图一的 logo，参考图二的材质，生成新图"； - 研究：80B MoE 图像生成模型的架构研究。

硬件门槛说明：80B MoE 模型即使是 13B 激活，也需要多卡。T2I 版最少 3 张 80GB（如 A100/H100 80GB），Instruct 版 8 张。这意味着普通个人用户（单卡 4090）基本跑不起来——本文更多是给有 GPU 集群的团队/研究机构看的。个人用户建议直接用腾讯混元官网的在线版（https://hunyuan.tencent.com/chat/）。

二、核心功能逐条拆解

1. 文生图（T2I）：从文字 prompt 生成图片。
2. 图生图（I2I）：Instruct 版支持图片编辑、多图融合。
3. CoT 推理：Instruct 版自动思考并增强 prompt（think_recaption）。
4. Prompt 自改写：自动把模糊 prompt 扩展成专业描述。
5. 多图融合：最多输入 3 张参考图，合成新图。
6. MoE 架构：64 专家，80B 总参数，13B 激活。
7. FlashInfer 加速：装好后推理快 3 倍。
8. Distil 蒸馏版：8 步采样出图，速度快。
9. Gradio Web UI：内置交互式界面。
10. vLLM 加速：官方支持 vLLM 推理。
11. Prompt Handbook：官方提供 Prompt Handbook（中文），教你怎么写 prompt。
12. 多语言：中英文 prompt 都支持。

三、全套官方链接

四、硬件与环境前置要求

官方 README 明确：

• Python：3.12+（推荐并测试过）；
• CUDA：12.8；
• GPU 显存：
• HunyuanImage-3.0（T2I）：≥3×80GB（如 3 张 A100/H100 80GB）；
• Instruct 版：≥8×80GB；
• Distil 版：≥8×80GB；
• 磁盘：模型权重约几百 GB，留足空间；
• GCC：≥9（编译 FlashAttention/FlashInfer 用）。

官方出处：README "Environment Setup" 和 Models Cards 表格。

补充说明：普通个人用户能跑吗？T2I 版最少 3×80GB，普通单卡 4090（24GB）跑不起来。Instruct 版需要 8×80GB，更夸张。这不是给个人玩家的项目——它是给有 GPU 集群的团队/研究机构准备的。个人用户建议直接用腾讯混元官网的在线版（https://hunyuan.tencent.com/chat/HunyuanDefault?modelId=Hunyuan-Image-3.0-Instruct），免费试用。如果你只有单卡且想玩开源图像生成，推荐 FLUX.1-schnell 或 SDXL，它们对显存友好得多。

五、多平台部署步骤

5.1 环境安装（官方）

第 1 步：装 PyTorch（CUDA 12.8）：

pip install torch==2.8.0 torchvision==0.23.0 torchaudio==2.8.0 --index-url https://download.pytorch.org/whl/cu128

第 2 步：装其他依赖：

pip install -r requirements.txt

第 3 步（可选，加速 3 倍）：装 FlashInfer：

pip install flashinfer-python==0.5.0

注意：FlashInfer 首次推理会编译 kernel（约 10 分钟），之后会快很多。CUDA 版本必须和 PyTorch 匹配。GCC ≥9 是编译 FlashAttention 和 FlashInfer 的必要条件。

补充：如果你只想快速试试不装 FlashInfer，把 --moe-impl 设为 eager 即可。eager 模式不需要 FlashInfer，能跑但慢一些。生产环境强烈建议装 FlashInfer，官方说能快 3 倍。

5.2 下载模型权重（官方）

# T2I 版
hf download tencent/HunyuanImage-3.0 --local-dir ./HunyuanImage-3

# 或 Instruct 版
hf download tencent/HunyuanImage-3.0-Instruct --local-dir ./HunyuanImage-3-Instruct

# 或 Distil 蒸馏版（8步采样）
hf download tencent/HunyuanImage-3.0-Instruct-Distil --local-dir ./HunyuanImage-3-Instruct-Distil

注意：目录名不要带点（HunyuanImage-3.0 会导致 Transformers 加载问题），所以本地目录名改成 HunyuanImage-3。

5.3 命令行生成（官方）

T2I 版：

export MODEL_PATH="./HunyuanImage-3"
python3 run_image_gen.py \
    --model-id $MODEL_PATH \
    --verbose 1 \
    --prompt "A brown and white dog is running on the grass" \
    --bot-task image \
    --image-size "1024x1024" \
    --save ./image.png \
    --moe-impl flashinfer

Instruct 版：

export MODEL_PATH="./HunyuanImage-3-Instruct"
bash run_demo_instruct.sh

Distil 版（8 步采样）：

export MODEL_PATH="./HunyuanImage-3-Instruct-Distil"
bash run_demo_instruct_Distil.sh

5.4 Gradio Web 界面（官方）

第 1 步：装 Gradio：

pip install gradio>=4.21.0

第 2 步：配置环境变量：

export MODEL_ID="path/to/your/model"
export GPUS="0,1,2,3"
export HOST="0.0.0.0"
export PORT="443"

第 3 步：启动：

sh run_app.sh

# 带加速
sh run_app.sh --moe-impl flashinfer --attn-impl flash_attention_2

第 4 步：浏览器打开 http://localhost:443。

六、配置文件全部参数解释

按官方 README 命令行参数表整理：

补充说明：--bot-task 是 Instruct 版的关键参数。image 是直接生成；recaption 是先改写 prompt 再生成；think_recaption 是先思考（CoT）再改写 prompt 再生成——这个模式效果最好但最慢。日常用 think_recaption，追求速度用 image。--use-system-prompt 推荐 en_unified，这是官方默认优化过的系统提示词。

七、启动、后台常驻与开机自启

Gradio 方式用 systemd：

[Unit]
Description=HunyuanImage Gradio
After=network.target

[Service]
User=your_user
WorkingDirectory=/your/path/HunyuanImage-3.0
Environment=MODEL_ID=/path/to/model
ExecStart=/usr/bin/sh run_app.sh --moe-impl flashinfer
Restart=always

[Install]
WantedBy=multi-user.target

sudo systemctl daemon-reload
sudo systemctl enable --now hunyuanimage

修改端口：改 PORT 环境变量。

八、功能实操教程

第 1 步：装好 PyTorch cu128 和依赖，下载 T2I 模型权重。

第 2 步：跑文生图：

python3 run_image_gen.py \
    --model-id ./HunyuanImage-3 \
    --prompt "一只橘猫坐在窗台上晒太阳，暖色调，高清" \
    --image-size "1024x1024" \
    --save ./cat.png

第 3 步：用 Distil 版快速生成（8 步）：

python3 run_image_gen.py \
    --model-id ./HunyuanImage-3-Instruct-Distil \
    --prompt "一只赛博朋克风格的猫" \
    --diff-infer-steps 8 \
    --save ./cyber_cat.png

第 4 步：Instruct 版图生图（多图融合）：

python3 run_image_gen.py \
    --model-id ./HunyuanImage-3-Instruct \
    --prompt "基于图一的logo，参考图二的材质，制作新冰箱贴" \
    --image "logo.png,material.png" \
    --save ./fridge_magnet.png

第 5 步：启动 Gradio 界面：

export MODEL_ID=./HunyuanImage-3
sh run_app.sh

浏览器打开 http://localhost:443，在网页里输入 prompt 生成。

第 6 步：调整步数和尺寸。50 步是默认质量，8 步（Distil 版）是速度优先。尺寸从 1024x1024 到 1280x768 都可以，太大显存会爆。

第 7 步：vLLM 加速。官方 README 提到 vLLM 支持（见 vllm_infer/README.md），能显著提升推理速度。如果你的部署量大，建议看官方 vLLM 文档。

第 8 步：Prompt 改写。T2I 版可以开启 --rewrite 1，用 DeepSeek API 自动改写 prompt（需要腾讯云 DeepSeek Key）。Instruct 版自带 think_recaption，不需要外部 API。

第 9 步：多图融合。Instruct 版最多输入 3 张参考图：

python3 run_image_gen.py \
    --model-id ./HunyuanImage-3-Instruct \
    --prompt "融合图一的人物和图二的背景，生成新图" \
    --image "person.png,background.png" \
    --save ./fused.png

第 10 步：批量生成。写个 shell 脚本循环跑：

for prompt in "一只猫" "一只狗" "一只鸟"; do
    python3 run_image_gen.py --model-id ./HunyuanImage-3 --prompt "$prompt" --save "./output_$prompt.png"
done

第 11 步：使用官方 Prompt Handbook。官方提供了中文 Prompt Handbook（https://docs.qq.com/doc/DUVVadmhCdG9qRXBU），里面详细教你怎么写 prompt 才能出好图。写 prompt 时建议参考：主体+场景+光线+风格+质量词。

第 12 步：调整随机种子。设 --seed 42 可以复现结果，方便调试 prompt。不设 seed 则每次随机。

九、全套报错故障排查

1. 报错：CUDA out of memory。 原因分析：80B 模型需要 3-8 张 80GB 显卡。 分步解决方案：确认你有足够的 GPU（T2I 至少 3×80GB）；用 Distil 版；减小图片尺寸；关掉其他占显存的程序。

2. 报错：FlashInfer 安装失败。 原因分析：CUDA 版本不匹配，或 GCC 版本太低。 分步解决方案：确认 PyTorch 用的是 cu128；GCC ≥9；先跑 eager 模式不用 flashinfer。

3. 报错：模型加载时报错目录名带点。 原因分析：官方说目录名不能有 .。 分步解决方案：把 HunyuanImage-3.0 重命名为 HunyuanImage-3。

4. 报错：首次推理很慢（10 分钟）。 原因分析：FlashInfer 在编译 kernel。 分步解决方案：正常现象，等它编译完，之后就快了。

5. 报错：Gradio 界面打不开。 原因分析：端口 443 需要 root 权限，或被占用。 分步解决方案：改 export PORT=7860；或用 sudo 启动。

6. 报错：生成的图片全黑或噪点。 原因分析：采样步数太少，或 prompt 有问题。 分步解决方案：把 --diff-infer-steps 从 8 调到 50；检查 prompt 描述。

7. 报错：ImportError: cannot import name 'AutoModelForCausalLM'。 原因分析：transformers 版本太旧，不支持 HunyuanImage 架构。 分步解决方案：pip install -U transformers，确保是最新版。

8. 报错：多卡推理时某张卡 OOM。 原因分析：模型并行不均。 分步解决方案：确认所有 GPU 都是 80GB；用 --moe-impl eager 代替 flashinfer；减小 batch size。

9. 报错：Gradio 启动后外网访问不了。 原因分析：防火墙没开端口，或 HOST 没设 0.0.0.0。 分步解决方案：确认 export HOST=0.0.0.0；云服务器安全组放行端口。

10. 报错：模型下载很慢或中断。 原因分析：HuggingFace 访问慢。 分步解决方案：用 HF_ENDPOINT=https://hf-mirror.com 走国内镜像；或用 hf download 的断点续传。

11. 报错：生成图片尺寸不对。 原因分析：--image-size 参数格式不对。 分步解决方案：支持 auto、1024x1024、16:9 等格式。Instruct 版用 infer_align_image_size=True 会自动对齐输入图尺寸。

12. 报错：torch.cuda.OutOfMemoryError 在模型加载阶段。 原因分析：8 张卡没认全，或显存碎片。 分步解决方案：nvidia-smi 确认 8 张卡都在；重启进程清空显存；确认没有其他进程占显存。

十、升级、回滚与卸载

升级：git pull + 重新下载最新模型权重。HunyuanImage 更新很快（2026 年 1 月刚出 Distil 版）。升级时注意 transformers 版本是否兼容——新模型可能需要最新版 transformers。

备份建议：模型权重几百 GB，不要随便删；自己的 prompt 和生成结果备份；FlashInfer 编译的 kernel 缓存可以保留，下次启动不用重新编译（省 10 分钟）。

回滚：git checkout <旧tag>。HunyuanImage 的版本在 GitHub Releases 里有记录。

卸载：删文件夹 + pip uninstall 相关包；模型权重目录单独删除（几百 GB）。

十一、商用许可与合规风险提示

HunyuanImage-3.0 的模型权重许可证需要查看 HuggingFace 模型卡（腾讯混元系列通常使用腾讯混元开源许可，允许商用但有使用限制）。商用前务必阅读模型卡上的 LICENSE。生成图片的版权归属按你所在地法律判断。本教程不构成法律意见。

附录：HunyuanImage-3.0 vs FLUX vs SDXL 怎么选

一句话：有 GPU 集群、研究 MoE 架构、需要中文理解，用 HunyuanImage-3.0；个人用户追求高质量生成，用 FLUX.1-dev；快速原型和轻量部署，用 SDXL。

附录：新手常见问题 FAQ

Q1：我只有一张 4090，能跑 HunyuanImage-3.0 吗？ A：基本不能。T2I 版最少 3×80GB，Instruct 版 8×80GB。单卡 24GB 差太远。个人用户建议用腾讯混元官网在线版，或本地跑 FLUX.1-schnell。

Q2：Distil 版和原版有什么区别？ A：Distil 是蒸馏版，8 步就能出图（原版 50 步），速度快 6 倍。质量略降但日常够用。显存需求一样（都是 8×80GB）。

Q3：HunyuanImage 和 Qwen-Image 是什么关系？ A：都是腾讯出品，但不同团队。HunyuanImage 是混元团队的 80B MoE 模型；Qwen-Image 是通义千问团队的模型。两者独立。

Q4：生成一张图要多久？ A：取决于 GPU 和步数。H100 集群上 50 步大约几十秒；Distil 版 8 步大约 10 秒。首次运行要加 FlashInfer kernel 编译时间（约 10 分钟）。

Q5：支持中文 prompt 吗？ A：支持，而且优化得很好。腾讯出品，中文 prompt 理解是强项。官方还有中文 Prompt Handbook。

Q6：三个版本（T2I / Instruct / Distil）怎么选？ A：只做文生图、GPU 少（3×80GB），选 T2I；要做图生图/多图融合，选 Instruct；追求速度、8 步出图，选 Distil（显存需求和 Instruct 一样）。

Q7：和在线版有什么区别？ A：本地部署的数据不出你的服务器，但需要自己出 GPU 钱。在线版（腾讯混元官网）免费额度、不用管基础设施，但数据要上传到腾讯。

参考链接

• GitHub 仓库：https://github.com/Tencent-Hunyuan/HunyuanImage-3.0
• 官网：https://hunyuan.tencent.com/image
• HuggingFace：https://huggingface.co/tencent/HunyuanImage-3.0
• 技术报告：https://arxiv.org/pdf/2509.23951