项目预览
项目数据
项目介绍
Star 增长趋势
本站每日记录该项目 GitHub 星标变化,观测越久曲线越完整
数据来源:GitHub API 逐日快照 · 收录于 2026-08-09 · 当前星标 ★ 3302
技术标签
使用教程
ℹ 本教程由 AI 依据该项目 README 整理,个别步骤可能需要按你的环境微调。
环境要求
- Python 3.12+(推荐且经过测试)
- CUDA 12.8(需与 PyTorch cu128 版本匹配)
- 可用的 NVIDIA GPU(README 示例默认使用 0,1,2,3 四张卡)
- 足够的磁盘空间存放预训练权重(权重下载命令在节选中被截断,请以官方仓库为准)
安装与启动步骤
-
1克隆代码仓库
把 HunyuanImage-3.0 官方仓库拉到本地并进入目录,后续所有命令都在该目录下执行。
git clone https://github.com/Tencent-Hunyuan/HunyuanImage-3.0.git cd HunyuanImage-3.0/ -
2安装 PyTorch
先单独安装 CUDA 12.8 版本的 PyTorch 三件套,避免后面依赖安装把它覆盖成 CPU 版。
pip install torch==2.8.0 torchvision==0.23.0 torchaudio==2.8.0 --index-url https://download.pytorch.org/whl/cu128 -
3安装腾讯云 SDK
仅 HunyuanImage-3.0(文生图版)的提示词增强 PE 需要,Instruct 版本可跳过这步。
pip install -i https://mirrors.tencent.com/pypi/simple/ --upgrade tencentcloud-sdk-python -
4安装其余依赖
在仓库根目录执行,安装 requirements.txt 中列出的全部依赖。必须放在 PyTorch 之后装。
pip install -r requirements.txt -
5下载模型权重
从 HuggingFace 的 tencent/HunyuanImage-3.0、HunyuanImage-3.0-Instruct、HunyuanImage-3.0-Instruct-Distil 下载权重;README 节选中命令被截断
-
6配置 GPU
可选。不设置时默认使用 0,1,2,3 号卡,按自己机器实际卡号调整。
export GPUS="0,1,2,3" -
7运行示例推理
指定权重路径后运行 Distil 版 8 步采样示例脚本,生成样例图片。
export MODEL_PATH="./HunyuanImage-3-Instruct-Distil" bash run_demo_instruct_Distil.sh
关键配置
| 配置项 | 必填 | 说明 | 示例 |
|---|---|---|---|
MODEL_PATH | 是 | 指向本地下载好的模型权重目录,供运行脚本读取。 | ./HunyuanImage-3-Instruct-Distil |
GPUS | 否 | 指定使用的 GPU 编号,默认 0,1,2,3。 | 0,1,2,3 |
如何确认成功
执行 bash run_demo_instruct_Distil.sh 后顺利完成 8 步推理并生成样例图片,即表示环境与权重均配置成功。
常见问题
Q:必须安装 tencentcloud-sdk-python 吗?
A:不是必须。README 说明该 SDK 仅用于 HunyuanImage-3.0 文生图版的提示词增强(PE),HunyuanImage-3.0-Instruct 无需安装。
Q:需要多少显存、几张卡?
A:README 只给出默认使用 0,1,2,3 四张 GPU,未列明最低显存要求,请以官方仓库和模型卡说明为准。
Q:如何让推理更快?
A:README 提到安装优化组件后推理最高可提速 3 倍,但该段命令在节选中被截断,请查看官方仓库原文。
Q:权重从哪里下载?
A:README 给出三个 HuggingFace 仓库:tencent/HunyuanImage-3.0、tencent/HunyuanImage-3.0-Instruct、tencent/HunyuanImage-3.0-Instruct-Distil。
Q:能只做文生图吗?
A:可以。README 保留了上一版纯文生图(Pure Text-to-Image)的安装与快速开始说明,可对应选择该版本权重。
注意事项
- 必须按顺序安装:先 PyTorch(cu128),再装 requirements.txt,否则可能装到 CPU 版 PyTorch。
- Python 版本建议 3.12+,CUDA 需为 12.8,与本例 PyTorch 版本严格对应。
- README 节选中模型权重下载命令被截断,请勿照搬猜测的命令,以官方仓库最新说明为准。
- 运行前确保 MODEL_PATH 指向的目录中已完整放好权重文件。
核心亮点
- 原生多模态架构,语义理解更准,复杂提示词还原度高
- 支持多轮编辑,可对生成图像进行局部修改和风格调整
- 中英文双语优化,对中文用户友好,生成质量稳定
不足之处
- 模型体积较大,推理资源需求高,普通硬件难以流畅运行
- 文档/社区待观察:生态和第三方教程相对较少
适用场景
- 营销海报和广告创意快速出图
- 游戏和影视概念设计
- 电商产品图生成与编辑
替代项目
Stable Diffusion、FLUX.1、DALL-E 3
同类项目推荐
ComfyUI-TiledDiffusion
开源
大图生成不爆显存,细节更丰富
Tiled Diffusion, MultiDiffusion, Mixture of Diffusers, and optimized VAE
MagicDrive
开源
用3D几何控制生成自动驾驶街景,解决数据稀缺
[ICLR24] Official implementation of the paper “MagicDrive: Street View Generation w···
FreeScale
开源
免训练提升扩散模型分辨率,一张图生成高清细节
[ICCV 2025] Code for FreeScale, a tuning-free method for higher-resolution visual ge···
automatic1111-webui-nix
开源
NixOS 上一键部署 Stable Diffusion WebUI,支持 CUDA 和 ROCm
AUTOMATIC1111/stable-diffusion-webui for CUDA and ROCm on NixOS
sdnext
开源
出图、打标、修后期一条龙,一个页面全搞定
SD.Next: All-in-one WebUI for AI generative image and video creation, captioning and···
sd-webui-bmab
开源
自动修复手脸崩坏,一键局部重绘提升出图质量
Auto masking and inpainting for person, face, hand. Resizing image using detection m···
swift-diffusion
开源
用 Swift 在苹果设备上跑扩散模型,本地生成图片
Compositional_Neural_Painter
开源
让AI像画家一样动态规划区域,逐笔画出图像
[MM 2023] Stroke-based Neural Painting and Stylization with Dynamically Predicted Pa···
Awesome-AI-Images-Prompts
开源
一站式获取各大AI生图模型的精选提示词,直接复制出图
2026年11月更新,精选适用于 GPT Image 2、2.5、Gemini Nano-banana Pro 2.1 Image Prompt···
