# HunyuanImage 3.0

腾讯混元图像 HunyuanImage 3.0 是 **全球最大的开源图像生成模型** 总参数量 800 亿（推理时激活 130 亿）。于 2026 年 1 月 26 日发布，它通过将图像生成、编辑与理解统一到单一自回归模型中打破常规——不再需要文本到图像和图像到图像的分离管道。该模型能生成照片级真实感图像，执行精确的元素保留编辑，处理风格迁移，甚至进行多图像融合，所有功能均来自一个模型。

**HuggingFace：** [tencent/HunyuanImage-3.0-Instruct](https://huggingface.co/tencent/HunyuanImage-3.0-Instruct) **GitHub：** [Tencent-Hunyuan/HunyuanImage-3.0](https://github.com/Tencent-Hunyuan/HunyuanImage-3.0) **许可：** 腾讯混元社区许可（免费用于研究与商业用途，前提是月活用户少于 1 亿）

## 主要特性

* **总计 800 亿 / 推理时激活 130 亿 参数** — 最大的开源图像 MoE 模型；每次推理仅激活 130 亿参数
* **统一的多模态架构** — 在同一模型中实现文本到图像、图像编辑、风格迁移和多图像合成
* **指令驱动的编辑** — 用自然语言描述你想要更改的内容，保留未被触及的元素
* **提供蒸馏检查点** — `HunyuanImage-3.0-Instruct-Distil` 仅需 8 个采样步骤即可更快生成
* **vLLM 加速** — 原生 vLLM 支持，在生产环境中显著加速推理
* **自回归框架** — 与基于 DiT 的模型（FLUX、SD3.5）不同，使用统一的自回归方法同时用于理解与生成

## 1024x1024

| A100                                 | 模型变体             | 步数    | HuggingFace                                |
| ------------------------------------ | ---------------- | ----- | ------------------------------------------ |
| **HunyuanImage-3.0**                 | 仅文本到图像           | 30–50 | `tencent/HunyuanImage-3.0`                 |
| **HunyuanImage-3.0-Instruct**        | 文本到图像 + 编辑 + 多图像 | 30–50 | `tencent/HunyuanImage-3.0-Instruct`        |
| **HunyuanImage-3.0-Instruct-Distil** | 快速推理（8 步）        | 8     | `tencent/HunyuanImage-3.0-Instruct-Distil` |

## 要求

| 配置   | 单 GPU（可卸载）       | 推荐           | 多 GPU 生产环境     |
| ---- | ---------------- | ------------ | -------------- |
| GPU  | 1× RTX 4090 24GB | 1× A100 80GB | 2–3× A100 80GB |
| 显存   | 24GB（使用层卸载）      | 80GB         | 160–240GB      |
| 内存   | 128GB            | 128GB        | 256GB          |
| 磁盘   | 200GB            | 200GB        | 200GB          |
| CUDA | 12.0+            | 12.0+        | 12.0+          |

**推荐的 Clore.ai 配置：**

* **最佳性价比：** 1× A100 80GB（约 $2–4/天）— 可在不使用卸载的情况下舒适运行完整模型
* **预算选项：** 1× RTX 4090（约 $0.5–2/天）— 可使用 CPU 卸载（更慢，但可用）
* **快速生产：** 2× A100 80GB（约 $4–8/天）— 适用于批量生成和 Instruct 模型

## 快速开始

### 安装

```bash
# 克隆代码仓库
git clone https://github.com/Tencent-Hunyuan/HunyuanImage-3.0.git
cd HunyuanImage-3.0

# 创建环境
pip install -r requirements.txt
pip install torch torchvision --index-url https://download.pytorch.org/whl/cu121

# 下载模型权重
huggingface-cli download tencent/HunyuanImage-3.0-Instruct --local-dir ./ckpts/HunyuanImage-3-Instruct
```

### 使用 Transformers 进行文本到图像

```python
import torch
from transformers import AutoModelForCausalLM, AutoTokenizer

# 加载模型（完整版精度大约需要 ~80GB 显存）
model_path = "./ckpts/HunyuanImage-3-Instruct"
model = AutoModelForCausalLM.from_pretrained(
    model_path,
    torch_dtype=torch.bfloat16,
    device_map="auto",
    trust_remote_code=True,
)

# 从文本生成图像
prompt = "秋天宁静的日本庭院，锦鲤在清澈的池塘中游动，金色枫叶飘落，水彩画风格"
output = model.generate_image(prompt, num_inference_steps=30)
output.save("japanese_garden.png")
```

### 使用 Gradio 网络界面

体验所有功能最简单的方式：

```bash
cd HunyuanImage-3.0

# 安装 Gradio
pip install gradio

# 启动网页界面
python gradio_demo.py \
    --model-path ./ckpts/HunyuanImage-3-Instruct \
    --server-name 0.0.0.0 \
    --server-port 7860
```

然后通过 SSH 隧道访问： `ssh -L 7860:localhost:7860 root@<clore-ip>`

## 使用示例

### 1. 文本到图像生成（CLI）

```bash
cd HunyuanImage-3.0

python inference.py \
    --model-path ./ckpts/HunyuanImage-3-Instruct \
    --prompt "赛博朋克夜景，霓虹灯照亮的摩天大楼倒映在被雨水浸湿的街道上，飞行汽车，体积雾，8K" \
    --output-path output.png \
    --num-inference-steps 30 \
    --guidance-scale 5.0
```

### 2. 使用自然语言进行图像编辑

这是 HunyuanImage 3.0 的突出功能之一——通过描述更改来编辑现有图像：

```bash
python inference.py \
    --model-path ./ckpts/HunyuanImage-3-Instruct \
    --prompt "将季节改为冬季，树木被雪覆盖" \
    --image-path input_photo.jpg \
    --output-path edited_winter.png \
    --num-inference-steps 30
```

### 3. 使用蒸馏模型快速生成（8 步）

```bash
# 下载蒸馏检查点
huggingface-cli download tencent/HunyuanImage-3.0-Instruct-Distil \
    --local-dir ./ckpts/HunyuanImage-3-Instruct-Distil

# 仅用 8 步生成（快 5-6 倍）
python inference.py \
    --model-path ./ckpts/HunyuanImage-3-Instruct-Distil \
    --prompt "一名宇航员在火星上骑马的肖像，照片级真实感" \
    --output-path astronaut.png \
    --num-inference-steps 8
```

## 与其他图像模型的比较

| 特性       | HunyuanImage 3.0 | FLUX.2 Klein                 | SD 3.5 Large                 |
| -------- | ---------------- | ---------------------------- | ---------------------------- |
| 参数量      | 80B MoE（激活 13B）  | 32B DiT                      | 8B DiT                       |
| 架构       | 自回归 MoE          | 扩散变换器（Diffusion Transformer） | 扩散变换器（Diffusion Transformer） |
| 图像编辑     | ✅ 原生支持           | ❌ 需要 ControlNet              | ❌ 需要 img2img                 |
| 多图像融合    | ✅ 原生支持           | ❌                            | ❌                            |
| 风格迁移     | ✅ 原生支持           | ❌ 需要 LoRA                    | ❌ 需要 LoRA                    |
| 最小显存     | \~24GB（可卸载）      | 16GB                         | 8GB                          |
| 速度（A100） | \~15–30 秒        | \~0.3 秒                      | \~5 秒                        |
| 许可       | 腾讯社区             | Apache 2.0                   | Stability AI CL              |

## 给 Clore.ai 用户的提示

1. **为提速使用蒸馏模型** — `HunyuanImage-3.0-Instruct-Distil` 在 8 步而非 30–50 步中生成，将推理时间缩短 4–6 倍。质量仍然出乎意料地接近完整模型。
2. **A100 80GB 是最佳选择** — 单块 A100 80GB（在 Clore.ai 上约 $2–4/天）可在不使用任何卸载技巧的情况下运行 Instruct 模型。这比使用 CPU 卸载的 RTX 4090 快得多。
3. **预先下载模型** — 完整的 Instruct 检查点大约为 160GB。将其下载到持久化的 Clore.ai 卷中，以避免每次启动新实例时重复下载。
4. **对 Gradio 使用 SSH 隧道** — 不要将 7860 端口公开暴露。使用 `ssh -L 7860:localhost:7860` 从浏览器安全地访问网页界面。
5. **尝试使用 vLLM 后端进行批量工作** — 如果你要生成大量图像，vLLM 推理路径（在 `vllm_infer/` 文件夹中）能提供显著更好的吞吐量。

## # 使用固定种子以获得一致结果

| 问题                                      | 解决方案                                                                                               |
| --------------------------------------- | -------------------------------------------------------------------------------------------------- |
| `CUDA 内存不足（out of memory）` 在 RTX 4090 上 | 使用 `device_map="auto"` 以启用 CPU 卸载，或切换到 Distil 模型                                                   |
| 下载失败 / 非常慢                              | 设置 `HF_TOKEN` 环境变量；使用 `huggingface-cli download` 与 `--resume-download`                             |
| 无法通过 HF 模型 ID 加载模型                      | 由于名称中有点号，请先本地克隆： `huggingface-cli download tencent/HunyuanImage-3.0-Instruct --local-dir ./ckpts/` |
| 输出模糊或低质量                                | 增加 `--num-inference-steps` 到 40–50；增加 `--guidance-scale` 到 7.0                                     |
| 图像编辑忽略指令                                | 对要更改和要保留的内容要具体；使用简短、清晰的提示                                                                          |
| Gradio 界面无法启动                           | 确保已安装 `gradio>=4.0` ；检查模型路径是否指向正确的目录                                                               |

## 延伸阅读

* [GitHub 仓库](https://github.com/Tencent-Hunyuan/HunyuanImage-3.0) — 官方代码、推理脚本、Gradio 演示
* [HunyuanImage 3.0-Instruct（HuggingFace）](https://huggingface.co/tencent/HunyuanImage-3.0-Instruct) — 完整模型权重
* [蒸馏检查点](https://huggingface.co/tencent/HunyuanImage-3.0-Instruct-Distil) — 8 步快速推理
* [技术报告（arXiv）](https://arxiv.org/pdf/2509.23951) — 架构细节与基准测试
* [\["example.jpg", "戏剧性轮廓光，深色背景", 25, -1\],](https://github.com/bgreene2/ComfyUI-Hunyuan-Image-3) — 社区 ComfyUI 自定义节点


---

# Agent Instructions: Querying This Documentation

If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter:

```
GET https://docs.clore.ai/guides/guides_v2-zh/tu-xiang-sheng-cheng/hunyuan-image3.md?ask=<question>
```

The question should be specific, self-contained, and written in natural language.
The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.