---

概述

Hunyuan-PromptEnhancer 是一款提示重写工具，同时支持文生图生成和图生图编辑。它在保留原始意图的同时重构输入提示，为下游图像生成任务提供更清晰、结构化的提示。

主要特点：

• 双模支持：文生图提示增强与结合视觉上下文的图生图编辑指令优化
• 意图保留：在重写过程中保持所有关键要素（主体、动作、风格、布局、属性等）不变
• 鲁棒解析：多级回退机制确保输出可靠
• 灵活部署：支持全精度（7B/32B）、量化（GGUF）及视觉语言模型

🔥🔥🔥更新

• [2025-10-11] ✨ 发布 PromptEnhancer-32B gradio。
• [2025-09-30] ✨ 发布 PromptEnhancer-Img2Img 编辑模型。
• [2025-09-22] 🚀 感谢 @mradermacher 添加了 GGUF 模型支持，实现量化模型的高效推理！
• [2025-09-18] ✨ 尝试 PromptEnhancer-32B，以获得更高质量的提示增强！
• [2025-09-16] ✨ 发布 T2I-Keypoints-Eval 数据集。
• [2025-09-07] ✨ 发布 PromptEnhancer-7B 模型。
• [2025-09-07] ✨ 发布 技术报告。

安装

方法一：标准安装（推荐）

pip install -r requirements.txt

方法二：GGUF 安装（适用于支持 CUDA 的量化模型）

chmod +x script/install_gguf.sh && ./script/install_gguf.sh

💡 提示：如果您希望以更低的内存占用实现更快的推理，尤其是针对 32B 模型时，建议选择 GGUF 安装。

模型下载

🎯 快速入门

对于大多数用户，我们推荐从 PromptEnhancer-7B 模型开始：

# 下载 PromptEnhancer-7B（13GB）——质量和效率的最佳平衡
huggingface-cli download tencent/HunyuanImage-2.1/reprompt --local-dir ./models/promptenhancer-7b

📊 模型对比与选择指南

模型	大小	质量	内存	适用场景
PromptEnhancer-7B	13GB	高	8GB+	大多数用户，性能均衡
PromptEnhancer-32B	64GB	最高	32GB+	研究用途，对质量要求极高
32B-Q8_0（GGUF）	35GB	最高	35GB+	高端 GPU（H100、A100）
32B-Q6_K（GGUF）	27GB	优秀	27GB+	RTX 4090、RTX 5090
32B-Q4_K_M（GGUF）	20GB	良好	20GB+	RTX 3090、RTX 4080

标准模型（全精度）

# PromptEnhancer-7B（推荐给大多数用户）
huggingface-cli download tencent/HunyuanImage-2.1/reprompt --local-dir ./models/promptenhancer-7b

# PromptEnhancer-32B（用于最高质量）
huggingface-cli download PromptEnhancer/PromptEnhancer-32B --local-dir ./models/promptenhancer-32b

# PromptEnhancer-Img2img-Edit（用于图像编辑任务）
huggingface-cli download PromptEnhancer/PromptEnhancer-Img2img-Edit --local-dir ./models/promptenhancer-img2img-edit

GGUF 模型（量化——内存高效）

请根据您的 GPU 内存选择：

# Q8_0：最高质量（35GB）
huggingface-cli download mradermacher/PromptEnhancer-32B-GGUF PromptEnhancer-32B.Q8_0.gguf --local-dir ./models

# Q6_K：优秀质量（27GB）——推荐用于 RTX 4090
huggingface-cli download mradermacher/PromptEnhancer-32B-GGUF PromptEnhancer-32B.Q6_K.gguf --local-dir ./models

# Q4_K_M：良好质量（20GB） - 推荐用于 RTX 3090/4080
huggingface-cli download mradermacher/PromptEnhancer-32B-GGUF PromptEnhancer-32B.Q4_K_M.gguf --local-dir ./models

🚀 性能提示：GGUF 模型可在质量损失极小的情况下，将显存占用降低 50%-75%。若需在质量和显存占用之间取得最佳平衡，建议使用 Q6_K。

快速入门

使用 HunyuanPromptEnhancer（文本到图像）

from inference.prompt_enhancer import HunyuanPromptEnhancer

models_root_path = "./models/promptenhancer-7b"

enhancer = HunyuanPromptEnhancer(models_root_path=models_root_path, device_map="auto")

# 增强提示词（中文或英文）
user_prompt = "第三人称视角，一辆赛车正在城市赛道上飞驰..."
new_prompt = enhancer.predict(
    prompt_cot=user_prompt,
    # 默认系统提示专为图像提示改写设计；如有需要可覆盖
    temperature=0.7,   # >0 启用采样；0 使用确定性生成
    top_p=0.9,
    max_new_tokens=256,
)

print("增强后:", new_prompt)

使用 PromptEnhancerImg2Img（图像编辑）

适用于基于输入图像增强编辑指令的图像编辑任务：

from inference.prompt_enhancer_img2img import PromptEnhancerImg2Img

# 初始化图像到图像的提示增强器
enhancer = PromptEnhancerImg2Img(
    model_path="./models/your-model",
    device_map="auto"
)

# 在图像上下文中增强编辑指令
edit_instruction = "移除底部的水印"
image_path = "./examples/sample_image.png"

enhanced_prompt = enhancer.predict(
    edit_instruction=edit_instruction,
    image_path=image_path,
    temperature=0.1,
    top_p=0.9,
    max_new_tokens=2048
)

print("增强后的编辑提示:", enhanced_prompt)

使用 GGUF 模型（量化、更快速）

from inference.prompt_enhancer_gguf import PromptEnhancerGGUF

# 自动检测 models/ 文件夹中的 Q8_0 模型
enhancer = PromptEnhancerGGUF(
    model_path="./models/PromptEnhancer-32B.Q8_0.gguf",  // 可选：自动检测
    n_ctx=1024,        // 上下文窗口大小
    n_gpu_layers=-1,   // 使用所有 GPU 层
)

# 增强提示词
user_prompt = "丛林中的女人"
enhanced_prompt = enhancer.predict(
    user_prompt,
    temperature=0.3,
    top_p=0.9,
    max_new_tokens=512,
)

print("增强后:", enhanced_prompt)

命令行使用（GGUF）

# 简单用法 - 自动检测 models/ 文件夹中的模型
python inference/prompt_enhancer_gguf.py

# 或指定模型路径
GGUF_MODEL_PATH="./models/PromptEnhancer-32B.Q8_0.gguf" python inference/prompt_enhancer_gguf.py

GGUF 模型的优势

🚀 为什么使用 GGUF 模型？

• 内存高效：与全精度模型相比，显存占用减少 50%-75%
• 推理更快：针对 CPU 和 GPU 加速进行了优化，兼容 llama.cpp
• 质量保持：Q8_0 和 Q6_K 能够保持出色的输出质量
• 部署简便：单一文件格式，无需复杂依赖
• GPU 加速：全面支持 CUDA，实现高性能推理

模型	大小	质量	显存占用	适用场景
Q8_0	35GB	最高	~35GB	高端 GPU（H100、A100）
Q6_K	27GB	优秀	~27GB	RTX 4090、RTX 5090
Q4_K_M	20GB	良好	~20GB	RTX 3090、RTX 4080

使用对比

模型	输入类型	使用场景	模型后端
HunyuanPromptEnhancer	仅文本	文本到图像生成	Transformers（7B/32B）
PromptEnhancerImg2Img	文本 + 图像	图像编辑任务	Transformers（32B）
PromptEnhancerGGUF	仅文本	内存高效的 T2I	llama.cpp（量化）

参数说明

标准模型（Transformers）

• models_root_path：本地路径或仓库 ID；支持 trust_remote_code 模型。
• device_map：设备映射（默认为 auto）。
• predict(...)：
  • prompt_cot（str）：待改写的输入提示。
  • sys_prompt（str）：可选系统提示；图像提示改写时会提供默认值。
  • temperature（float）：>0 启用采样；0 表示确定性生成。
  • top_p（float）：核采样阈值（启用采样时有效）。
  • max_new_tokens（int）：最多生成的新标记数。

GGUF 模型

• model_path（str）：GGUF 模型文件路径（若位于 models/ 文件夹中则自动检测）。
• n_ctx（int）：上下文窗口大小（默认为 8192，短提示推荐 1024）。
• n_gpu_layers（int）：卸载到 GPU 的层数（-1 表示全部层）。
• verbose（bool）：启用来自 llama.cpp 的详细日志记录。

图像到图像模型（PromptEnhancerImg2Img）

• model_path（str）：预训练的 Qwen2.5-VL 模型路径。
• device_map（str）：模型加载时的设备映射（默认为 auto）。
• predict(...)：
  • edit_instruction（str）：原始编辑指令。
  • image_path（str）：输入图像文件路径。
  • sys_prompt（str）：可选系统提示（若未提供则使用默认值）。
  • temperature（float）：采样温度（默认为 0.1）。
  • top_p（float）：核采样阈值（默认为 0.9）。
  • max_new_tokens（int）：最多生成的新标记数（默认为 2048）。

引用

如果您觉得本项目有用，请考虑引用以下内容：

@article{promptenhancer,
  title={PromptEnhancer: A Simple Approach to Enhance Text-to-Image Models via Chain-of-Thought Prompt Rewriting},
  author={Wang, Linqing and Xing, Ximing and Cheng, Yiji and Zhao, Zhiyuan and Donghao, Li and Tiankai, Hang and Zhenxi, Li and Tao, Jiale and Wang, QiXun and Li, Ruihuang and Chen, Comi and Li, Xin and Wu, Mingrui and Deng, Xinchi and Gu, Shuyang and Wang, Chunyu and Lu, Qinglin},
  journal={arXiv preprint arXiv:2509.04545},
  year={2025}
}

致谢

我们衷心感谢以下开源项目和社区对开放研究与探索所作出的贡献：Transformers 和 HuggingFace。

联系方式

如您想向我们的研发和产品团队留言，欢迎联系我们的开源团队。您也可以通过电子邮件（hunyuan_opensource@tencent.com）与我们取得联系。

Github 星标历史

星标历史

PromptEnhancer 快速上手指南

PromptEnhancer 是由腾讯混元团队开源的提示词增强工具，基于思维链（Chain-of-Thought）重写技术，显著提升文生图（Text-to-Image）和图生图编辑（Image-to-Image）的效果。它能在保留用户原始意图的前提下，生成结构更清晰、细节更丰富的提示词。

环境准备

在开始之前，请确保您的开发环境满足以下要求：

• 操作系统: Linux 或 macOS (Windows 需使用 WSL2)
• Python: 3.8 或更高版本
• GPU (推荐): NVIDIA GPU 显存建议 8GB 以上（运行 7B 模型）；若运行量化版 32B 模型，建议显存 20GB+ 或使用 GGUF 格式降低显存占用。
• 依赖管理: 建议使用 conda 或 venv 创建独立虚拟环境。

安装步骤

1. 克隆项目与安装基础依赖

首先获取代码并安装标准依赖包：

git clone https://github.com/Tencent-Hunyuan/HunyuanImage-2.1.git
cd HunyuanImage-2.1
pip install -r requirements.txt

💡 提示：如果您希望使用量化模型（GGUF 格式）以节省显存并加速推理，请额外执行以下脚本安装 GGUF 支持：

chmod +x script/install_gguf.sh && ./script/install_gguf.sh

2. 下载模型

根据您的硬件条件选择合适的模型版本。国内用户若访问 HuggingFace 较慢，可配置镜像源或使用代理。

方案 A：推荐入门版 (PromptEnhancer-7B) 适合大多数用户，平衡了质量与显存占用（约需 8GB+ 显存）。

huggingface-cli download tencent/HunyuanImage-2.1/reprompt --local-dir ./models/promptenhancer-7b

方案 B：高性能量化版 (32B GGUF) 适合显存有限但需要高质量输出的用户（如 RTX 4090/3090），显存占用可降低 50%-75%。

# 下载 Q6_K 量化版本 (约 27GB，推荐 RTX 4090/5090)
huggingface-cli download mradermacher/PromptEnhancer-32B-GGUF PromptEnhancer-32B.Q6_K.gguf --local-dir ./models

# 或者下载 Q4_K_M 量化版本 (约 20GB，推荐 RTX 3090/4080)
# huggingface-cli download mradermacher/PromptEnhancer-32B-GGUF PromptEnhancer-32B.Q4_K_M.gguf --local-dir ./models

方案 C：图生图编辑专用版 用于基于图片的编辑指令优化。

huggingface-cli download PromptEnhancer/PromptEnhancer-Img2img-Edit --local-dir ./models/promptenhancer-img2img-edit

基本使用

场景一：文生图提示词增强 (Text-to-Image)

这是最常用的功能，将简单的自然语言描述转化为专业的绘图提示词。

from inference.prompt_enhancer import HunyuanPromptEnhancer

# 初始化模型 (指向下载的 7B 模型路径)
models_root_path = "./models/promptenhancer-7b"
enhancer = HunyuanPromptEnhancer(models_root_path=models_root_path, device_map="auto")

# 输入原始提示词 (支持中文或英文)
user_prompt = "Third-person view, a race car speeding on a city track..."

# 执行增强
new_prompt = enhancer.predict(
    prompt_cot=user_prompt,
    temperature=0.7,   # >0 开启采样，增加多样性；0 为确定性输出
    top_p=0.9,
    max_new_tokens=256,
)

print("Enhanced:", new_prompt)

场景二：使用量化模型 (GGUF - 更快更省显存)

如果您下载的是 .gguf 格式的 32B 模型，请使用此方式加载：

from inference.prompt_enhancer_gguf import PromptEnhancerGGUF

# 初始化 GGUF 模型
enhancer = PromptEnhancerGGUF(
    model_path="./models/PromptEnhancer-32B.Q6_K.gguf",  # 指定具体模型文件
    n_ctx=1024,        # 上下文窗口大小
    n_gpu_layers=-1,   # -1 表示将所有层卸载到 GPU 加速
)

# 执行增强
user_prompt = "woman in jungle"
enhanced_prompt = enhancer.predict(
    user_prompt,
    temperature=0.3,
    top_p=0.9,
    max_new_tokens=512,
)

print("Enhanced:", enhanced_prompt)

场景三：图生图编辑指令优化 (Image-to-Image)

当您需要根据参考图片优化编辑指令时使用：

from inference.prompt_enhancer_img2img import PromptEnhancerImg2Img

# 初始化图生图模型
enhancer = PromptEnhancerImg2Img(
    model_path="./models/promptenhancer-img2img-edit",
    device_map="auto"
)

# 准备图片和编辑指令
edit_instruction = "Remove the watermark from the bottom"
image_path = "./examples/sample_image.png"

# 执行优化
enhanced_prompt = enhancer.predict(
    edit_instruction=edit_instruction,
    image_path=image_path,
    temperature=0.1,
    top_p=0.9,
    max_new_tokens=2048
)

print("Enhanced editing prompt:", enhanced_prompt)