> For the complete documentation index, see [llms.txt](https://docs.clore.ai/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.clore.ai/guides/guides_v2-zh/tu-xiang-sheng-cheng/hunyuan-image3.md).

# HunyuanImage 3.0

在 Clore.ai GPU 上运行 HunyuanImage 3.0——腾讯的 80B MoE 多模态图像生成与编辑模型

腾讯的 HunyuanImage 3.0 是 **全球最大的开源图像生成模型** 拥有80B总参数（推理时激活13B）。它于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) **许可证：** 腾讯 Hunyuan 社区许可协议（研究及商业用途免费，MAU 低于1亿）

## 主要特性

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

## 模型变体

| 模型                                   | 使用场景          | 步数    | 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` |

## 需求

{% hint style="warning" %}
**Clore.ai 市场上未列出多 GPU 的 80GB 级机型。** 目前列出的最大配置是 4× RTX PRO 6000 Blackwell（每张 96GB，共 380GB）以及 8–11× RTX 5090（每张 32GB）。A100 / H200 / B200 容量可按 [裸机](https://clore.ai/bare-metal) 需求提供。部署前请查看 [GPU 价格与可用性](/guides/guides_v2-zh/ru-men-zhi-nan/pricing.md) 。
{% endhint %}

| 配置   | 单 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.8+            | 12.8+        | 12.8+          |

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

* **市场上性价比最高的是：** 1× RTX PRO 6000 Blackwell 96GB（$0.92–1.38/小时）——无需卸载即可轻松运行完整模型。A100 80GB 是经典选择，但只以 [裸机](https://clore.ai/bare-metal)
* **预算方案：** 1× RTX 4090（$0.14–0.42/小时）——可配合 CPU 卸载使用（较慢，但可用）
* **快速生产：** 2× A100 80GB（[裸机](https://clore.ai/bare-metal)）——用于批量生成和 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/cu128

# 下载模型权重
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 Web 界面

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

```bash
cd HunyuanImage-3.0

# 安装 Gradio
pip install gradio

# 启动 Web 界面
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          | 扩散 Transformer  | 扩散 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. **96GB 显存的卡是最佳平衡点** — 单张 RTX PRO 6000 Blackwell（或通过一张 A100 80GB [裸机](https://clore.ai/bare-metal)）即可运行 Instruct 模型，无需任何卸载技巧。这比使用 CPU 卸载的 RTX 4090 快得多。
3. **预先下载模型** — 完整的 Instruct 检查点大约有160GB。将其一次性下载到持久化的 Clore.ai 卷中，可避免每次启动新实例时都重新下载。
4. **使用 SSH 隧道访问 Gradio** — 不要将7860端口公开暴露。使用 `ssh -L 7860:localhost:7860` 即可安全地从浏览器访问 Web 界面。
5. **批量工作时尝试 vLLM 后端** — 如果你要生成很多图像，vLLM 推理路径（位于 `vllm_infer/` 文件夹中）可提供明显更好的吞吐量。

## 故障排查

| 问题                       | 解决方案                                                                                                |
| ------------------------ | --------------------------------------------------------------------------------------------------- |
| `CUDA 内存不足` 在 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) — 架构细节与基准测试
* [ComfyUI 集成](https://github.com/bgreene2/ComfyUI-Hunyuan-Image-3) — 社区版 ComfyUI 自定义节点


---

# Agent Instructions
This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com.

## 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, and the optional `goal` query parameter:

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

`ask` is the immediate question: it should be specific, self-contained, and written in natural language.
`goal` is optional and describes the broader end goal you are ultimately trying to accomplish on behalf of the user. GitBook uses it to tailor the answer towards what is most useful for that goal.

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.