本仓库包含我们关于混元图像 2.1 的 PyTorch 模型定义、预训练权重，以及推理/采样代码。更多可视化示例请访问我们的项目主页。
- 2025 年 9 月 8 日：🚀 发布混元图像 2.1 的推理代码与模型权重。
我们提出了混元图像 2.1（HunyuanImage-2.1），这是一个能够生成 2K（2048 × 2048）分辨率图像的高效文本到图像模型。通过利用大规模数据集和涉及多个专家模型的结构化标注，我们显著增强了文本-图像对齐能力。该模型采用高表达性的 VAE，具有（32 × 32）的空间压缩比，大幅降低了计算成本。
我们的架构包含两个阶段：
- 基础文本到图像模型：第一阶段是一个文本到图像模型，利用两个文本编码器：一个多模态大语言模型（MLLM）来改善图像-文本对齐，以及一个多语言、字符感知编码器来增强各种语言的文本渲染。该阶段具有 170 亿参数的单流和双流 Diffusion Transformer。为了优化美学和结构连贯性，我们应用了人类反馈强化学习（RLHF）。
- 精修模型：第二阶段引入了一个精修模型，进一步提升了图像质量和清晰度。
此外，我们开发了 PromptEnhancer 模块来进一步提升模型性能，并采用 MeanFlow 蒸馏进行高效推理。混元图像 2.1 展现了强大的语义对齐和跨场景泛化能力，提升了文本与图像之间的一致性，增强了对场景细节、人物姿态和表情的控制，并能够生成具有不同描述的多个物体。
结构化标注在短、中、长和超长级别提供分层语义信息，显著增强了模型对复杂语义的响应能力。创新性地引入了 OCR 专家模型和 IP RAG 来解决通用 VLM 标注器在密集文本和世界知识描述方面的不足，而双向验证策略确保了标注的准确性。
核心组件：
- 高压缩 VAE 与 REPA 训练加速：
- 具有 32× 压缩率的 VAE 大幅减少了 DiT 模型的输入 token 数量。其特征空间与 DINOv2 特征对齐，便于高压缩 VAE 的训练。这显著提高了推理效率，使得HunyuanImage 2.1 生成 2K 图像的时间与其他模型生成 1K 图像的时间相同。
- 多桶、多分辨率 REPA 损失将 DiT 特征与高维语义特征空间对齐，加速模型收敛。
- 双文本编码器：
- 采用视觉-语言多模态编码器来更好地理解场景描述、人物动作和详细要求。
- 引入多语言 ByT5 文本编码器，专门用于文本生成和多语言表达。
- 网络：具有 170 亿参数的单流和双流 Diffusion Transformer。
两阶段后训练与强化学习：监督微调（SFT）和强化学习（RL）在两个后训练阶段中顺序应用。我们引入了奖励分布对齐算法，创新性地将高质量图像作为选定样本，确保稳定和改进的强化学习结果。
- 首个系统性工业级改写模型：SFT 训练结构化地重写用户文本指令以丰富视觉表达，而 GRPO 训练采用细粒度语义 AlignEvaluator 奖励模型来大幅提升从重写文本生成的图像语义。AlignEvaluator 涵盖 6 个主要类别和 24 个细粒度评估点。PromptEnhancer 支持中英文重写，并在增强开源和专有文本到图像模型的语义方面展现了通用适用性。
我们提出了一种基于 MeanFlow 的新型蒸馏方法，解决了标准均值流训练固有的不稳定性和低效率的关键挑战。这种方法能够仅用少量采样步骤生成高质量图像。据我们所知，这是 MeanFlow 在工业级模型上的首次成功应用。
- 高质量生成：可生成超高清（2K）图像，具电影级构图
- 多语言支持：原生支持中文与英文提示词
- 先进架构：基于多模态的先进单双流结合的 DiT（Diffusion Transformer）骨干网络
- 字形感知：结合 ByT5 的文本渲染能力，提升嵌字/文本生成准确性
- 灵活的宽高比：支持多种图像宽高比（1:1, 16:9, 9:16, 4:3, 3:4, 3:2, 2:3）
- 提示词增强：自动重写提示词，提高描述精度与画面质量
为了提升生成图像的质量和细节，我们引入了提示词增强模型。该模型能够自动丰富用户提供的文本提示，添加丰富的描述性细节。
SSAE（结构化语义对齐评估）是一种基于先进多模态大语言模型（MLLMs）的图文对齐智能评测指标。我们在 12 个类别中共提取了 3500 个关键要点，然后利用多模态大语言模型，基于图像的视觉内容，将生成的图像与这些关键要点进行比对，自动完成评估与打分。平均图像准确率（Mean Image Accuracy）表示以图像为单位在所有关键要点上的平均得分，而全局准确率（Global Accuracy） 则直接对所有关键要点的平均得分进行计算。
| 模型 | 开源 | 平均图像准确率 | 全局准确率 | 主体 | 次要主体 | 场景 | 其他 | ||||||||
|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|
| 名词 | 关键属性 | 其他属性 | 动作 | 名词 | 属性 | 动作 | 名词 | 属性 | 镜头 | 风格 | 构图 | ||||
| FLUX-dev | ✅ | 0.7122 | 0.6995 | 0.7965 | 0.7824 | 0.5993 | 0.5777 | 0.7950 | 0.6826 | 0.6923 | 0.8453 | 0.8094 | 0.6452 | 0.7096 | 0.6190 |
| Seedream-3.0 | ❌ | 0.8827 | 0.8792 | 0.9490 | 0.9311 | 0.8242 | 0.8177 | 0.9747 | 0.9103 | 0.8400 | 0.9489 | 0.8848 | 0.7582 | 0.8726 | 0.7619 |
| Qwen-Image | ✅ | 0.8854 | 0.8828 | 0.9502 | 0.9231 | 0.8351 | 0.8161 | 0.9938 | 0.9043 | 0.8846 | 0.9613 | 0.8978 | 0.7634 | 0.8548 | 0.8095 |
| GPT-Image | ❌ | 0.8952 | 0.8929 | 0.9448 | 0.9289 | 0.8655 | 0.8445 | 0.9494 | 0.9283 | 0.8800 | 0.9432 | 0.9017 | 0.7253 | 0.8582 | 0.7143 |
| HunyuanImage 2.1 | ✅ | 0.8888 | 0.8832 | 0.9339 | 0.9341 | 0.8363 | 0.8342 | 0.9627 | 0.8870 | 0.9615 | 0.9448 | 0.9254 | 0.7527 | 0.8689 | 0.7619 |
从 SSAE 的评估结果上看，我们的模型在语义对齐上目前达到了开源模型上最优的效果，并且非常接近闭源商业模型 (GPT-Image) 的效果。
硬件和操作系统要求：
- 支持 CUDA 的 NVIDIA GPU。
- 最低要求： 59 GB 显存用于 2048x2048 图像生成（batch size = 1）。
- 支持的操作系统：Linux。
注意： 上述内存要求是在启用模型 CPU offloading 的情况下测量的。如果您的 GPU 有足够的显存，可以禁用 CPU offloading 以提高推理速度。
- 克隆仓库：
git clone https://github.com/Tencent-Hunyuan/HunyuanImage-2.1.git
cd HunyuanImage-2.1
- 安装依赖：
pip install -r requirements.txt pip install flash-attn==2.7.3 --no-build-isolation
模型的下载与说明请参考这里。
HunyuanImage-2.1 仅支持 2K 分辨率图像生成（如 1:1 时为 2048x2048，16:9 时为 2560x1536 等）。 使用其1K分辨率生成图像可能会带来画质下降与瑕疵。 此外，我们建议使用完整的生成流程以获得更高画质（即启用提示词增强和精修功能）。
import torch
from hyimage.diffusion.pipelines.hunyuanimage_pipeline import HunyuanImagePipeline
# 支持的 model_name：hunyuanimage-v2.1, hunyuanimage-v2.1-distilled
model_name = "hunyuanimage-v2.1"
pipe = HunyuanImagePipeline.from_pretrained(model_name=model_name, torch_dtype='bf16')
pipe = pipe.to("cuda")
prompt = "A cute, cartoon-style anthropomorphic penguin plush toy with fluffy fur, standing in a painting studio, wearing a red knitted scarf and a red beret with the word “Tencent” on it, holding a paintbrush with a focused expression as it paints an oil painting of the Mona Lisa, rendered in a photorealistic photographic style."
image = pipe(
prompt=prompt,
# HunyuanImage-2.1 支持的分辨率与宽高比示例：
# 16:9 -> width=2560, height=1536
# 4:3 -> width=2304, height=1792
# 1:1 -> width=2048, height=2048
# 3:4 -> width=1792, height=2304
# 9:16 -> width=1536, height=2560
# 建议使用上述长宽组合以获得最佳效果。
width=2048,
height=2048,
use_reprompt=True, # 启用提示词增强
use_refiner=True, # 启用精修模型, 以获得更高画质
# 对于蒸馏版模型，建议使用 8 步以加快推理速度；
# 对于非蒸馏版模型，建议使用 50 步以获得更高画质
num_inference_steps=8 if "distilled" in model_name else 50,
guidance_scale=3.5,
shift=5,
seed=649151,
)
image.save("generated_image.png")
如果本项目对你的研究或应用有帮助，请引用：
@misc{HunyuanImage-2.1, title={HunyuanImage 2.1: An Efficient Diffusion Model for High-Resolution (2K) Text-to-Image Generation}, author={Tencent Hunyuan Team}, year={2025}, howpublished={\url{https://github.com/Tencent-Hunyuan/HunyuanImage-2.1}}, }
感谢以下开源项目与社区为开放研究和探索所做的贡献：Qwen、 FLUX、diffusers 与 HuggingFace。
