HunyuanImage-3.0

环境要求

• Python 3.12+（推荐且经过测试）
• CUDA 12.8（需与 PyTorch cu128 版本匹配）
• 可用的 NVIDIA GPU（README 示例默认使用 0,1,2,3 四张卡）
• 足够的磁盘空间存放预训练权重（权重下载命令在节选中被截断，请以官方仓库为准）

安装与启动步骤

1. 1克隆代码仓库

   把 HunyuanImage-3.0 官方仓库拉到本地并进入目录，后续所有命令都在该目录下执行。

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

   复制

2. 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. 3安装腾讯云 SDK

   仅 HunyuanImage-3.0（文生图版）的提示词增强 PE 需要，Instruct 版本可跳过这步。

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

   复制

4. 4安装其余依赖

   在仓库根目录执行，安装 requirements.txt 中列出的全部依赖。必须放在 PyTorch 之后装。

   pip install -r requirements.txt

   复制

5. 5下载模型权重

   从 HuggingFace 的 tencent/HunyuanImage-3.0、HunyuanImage-3.0-Instruct、HunyuanImage-3.0-Instruct-Distil 下载权重；README 节选中命令被截断

6. 6配置 GPU

   可选。不设置时默认使用 0,1,2,3 号卡，按自己机器实际卡号调整。

   export GPUS="0,1,2,3"

   复制

7. 7运行示例推理

   指定权重路径后运行 Distil 版 8 步采样示例脚本，生成样例图片。

   export MODEL_PATH="./HunyuanImage-3-Instruct-Distil"
   bash run_demo_instruct_Distil.sh

   复制

关键配置

如何确认成功

执行 bash run_demo_instruct_Distil.sh 后顺利完成 8 步推理并生成样例图片，即表示环境与权重均配置成功。

常见问题

注意事项

• 必须按顺序安装：先 PyTorch（cu128），再装 requirements.txt，否则可能装到 CPU 版 PyTorch。
• Python 版本建议 3.12+，CUDA 需为 12.8，与本例 PyTorch 版本严格对应。
• README 节选中模型权重下载命令被截断，请勿照搬猜测的命令，以官方仓库最新说明为准。
• 运行前确保 MODEL_PATH 指向的目录中已完整放好权重文件。