HunyuanImage-3.0 多模态图像生成大模型

HunyuanImage-3.0是一个开创性的原生多模态模型，在一个统一的自回归框架下整合了多模态理解和生成能力，让文本到图像生成性能达到或超越了领先的闭源模型。HunyuanImage-3.0 作为目前规模最大的开源图像生成专家混合（MoE）模型，拥有800亿总参数和130亿活跃参数，能生成兼具语义准确性、视觉卓越性、照片级真实感及精细细节的高质量图像，高度遵循用户提示，具备智能世界知识推理能力，能够自动理解并丰富用户提供的简短提示，支持多种图像分辨率设置，通过开源的推理代码、模型权重和提示词自动重写功能（如通过Instruct模型或集成DeepSeek）提供强大的、可定制的图像创作。

统一多模态架构：打破主流DiT架构局限，采用统一自回归框架。这种设计让文本与图像模态的建模更直接、更融合，生成的图像不仅效果出色，还能承载更丰富的上下文信息。

最大规模图像生成MoE模型：作为当前开源领域规模最大的混合专家（MoE）图像生成模型，它配备64个专家，总参数量达800亿，每个令牌激活130亿参数，大幅提升模型容量与性能。

卓越图像生成性能：通过严格的数据集筛选与先进的强化学习后训练，在语义准确性与视觉效果间找到最佳平衡。模型能精准贴合提示要求，生成的图像兼具照片级真实感、出色美学效果与精细细节。

智能世界知识推理：统一多模态架构赋予模型强大推理能力。依托丰富世界知识，模型可智能解读用户意图，对简洁提示自动补充上下文相关细节，生成更优质、更完整的视觉成果。

HunyuanImage-3.0安装和使用

系统要求

• 操作系统：Linux • GPU：支持CUDA的NVIDIA显卡 • 磁盘空间：170GB（用于存储模型权重） • GPU内存：≥3×80GB（推荐4×80GB以获得更优性能）

环境配置

• Python：3.12及以上（推荐版本，已完成测试） • PyTorch：2.7.1 • CUDA：12.8

安装依赖

1、首先安装PyTorch（CUDA 12.8版本）

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

2、接着安装腾讯云SDK

pip install -i https://mirrors.tencent.com/pypi/simple/ --upgrade tencentcloud-sdk-python

3、最后安装其他依赖

pip install -r requirements.txt

性能优化

要让推理速度提升最高3倍，可安装以下优化工具： 1、FlashAttention（加速注意力计算）

pip install flash-attn==2.8.3 --no-build-isolation

2、FlashInfer（优化MoE推理，已测试v0.3.1版本）

pip install flashinfer-python

注意事项

• 安装提示：PyTorch使用的CUDA版本必须与系统CUDA版本匹配，FlashInfer在运行时编译内核需依赖这种兼容性。已测试PyTorch 2.7.1+cu128版本，推荐使用≥9版本的GCC编译FlashAttention与FlashInfer。

• 性能提示：这些优化工具能显著加快推理速度。

• 注意事项：启用FlashInfer后，首次推理可能因内核编译变慢（约10分钟），同一机器后续推理速度会大幅提升。

HunyuanImage-3.0使用

通过Transformers快速开始

1、下载模型权重

# 从HuggingFace下载并重新命名目录
# 注意：目录名称不能包含句点，否则可能导致Transformers加载失败
hf download tencent/HunyuanImage-3.0 --local-dir ./HunyuanImage-3

2、使用Transformers运行

from transformers import AutoModelForCausalLM

# 加载模型
model_id = "./HunyuanImage-3"
# 目前无法直接使用HF模型ID“tencent/HunyuanImage-3.0”加载模型
# 原因是名称中包含句点

kwargs = dict(
    attn_implementation="sdpa",     # 若已安装FlashAttention，可使用“flash_attention_2”
    trust_remote_code=True,
    torch_dtype="auto",
    device_map="auto",
    moe_impl="eager",   # 若已安装FlashInfer，可使用“flashinfer”
)

model = AutoModelForCausalLM.from_pretrained(model_id, **kwargs)
model.load_tokenizer(model_id)

# 生成图像
prompt = "一只棕白相间的狗在草地上奔跑"
image = model.generate_image(prompt=prompt, stream=True)
image.save("image.png")

本地安装

1、克隆仓库

git clone https://github.com/Tencent-Hunyuan/HunyuanImage-3.0.git
cd HunyuanImage-3.0/

2、下载模型权重

# 从HuggingFace下载
hf download tencent/HunyuanImage-3.0 --local-dir ./HunyuanImage-3

3、运行演示 预训练检查点不会自动重写或优化输入提示，目前为获得最佳效果，推荐社区伙伴使用DeepSeek重写提示。可前往腾讯云申请API密钥。

# 设置环境变量
export DEEPSEEK_KEY_ID="你的deepseek_key_id"
export DEEPSEEK_KEY_SECRET="你的deepseek_key_secret"

python3 run_image_gen.py --model-id ./HunyuanImage-3 --verbose 1 --sys-deepseek-prompt "universal" --prompt "一只棕白相间的狗在草地上奔跑"

4、命令行参数说明

交互式Gradio演示

搭建交互式网页界面，方便进行文本到图像生成操作。 1、安装Gradio

pip install gradio>=4.21.0

2、配置环境

# 设置模型路径
export MODEL_ID="你的模型路径"

# 可选：配置GPU使用（默认：0,1,2,3）
export GPUS="0,1,2,3"

# 可选：配置主机与端口（默认：0.0.0.0:443）
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（或你配置的端口）即可访问网页界面。

模型卡片

注意事项

1、安装性能优化工具（FlashAttention、FlashInfer）可加快推理速度。

2、基础模型推荐使用多GPU推理。

HunyuanImage-3.0 使用提示指南

手动编写提示

预训练检查点不会自动重写或优化输入提示，Instruct检查点可通过推理功能重写或优化输入提示。目前为获得最佳效果，推荐社区伙伴参考官方指南编写有效提示。 参考资料：《混元Image 3.0提示手册》

自动重写提示的系统提示

仓库的PE文件夹中包含两个系统提示，可借助DeepSeek自动优化用户输入：

1、system_prompt_universal：将摄影风格、艺术风格提示转换为详细提示。

2、system_prompt_text_rendering：将UI/海报/文本渲染类提示转换为适合模型的详细提示。

注意：这些系统提示为中文，因DeepSeek在中文系统提示下表现更优。若需用于面向英文的模型，可将其翻译为英文，或参考PE文件中的注释。

同时，我们还搭建了元气工作流实现通用提示优化，你可直接尝试使用。

进阶技巧

1、内容优先级：先描述主体与动作，再补充环境与风格细节。通用描述框架为：主体与场景 + 图像质量与风格 + 构图与视角 + 光线与氛围 + 技术参数，可在该结构前后添加关键词。

2、图像分辨率：模型支持多种分辨率，提供自动与指定两种分辨率选择。自动模式下，模型根据输入提示自动预测图像分辨率；指定模式（类似传统DiT）下，模型输出的图像分辨率严格匹配用户选择。