# Hunyuan3D 2.1

腾讯的 Hunyuan3D 2.1 是一个两阶段 3D 生成模型：它首先预测几何（形状），然后合成 PBR 贴图。它接受文本提示和参考图像作为输入，输出可用于生产的网格，格式为 GLB、OBJ 或 PLY。在 HuggingFace 上下载量超过 300 万次，是最广泛采用的开源 3D 生成模型之一。

{% hint style="success" %}
所有示例均在通过以下方式租用的 GPU 服务器上运行： [CLORE.AI 市场](https://clore.ai/marketplace).
{% endhint %}

## 主要特性

* **文本到 3D 和图像到 3D** — 两种输入模式合并在单一模型中
* **两阶段流水线** — 先生成形状，随后合成 PBR 贴图
* **高保真输出** — 具有反照率、法线和粗糙度贴图的细节几何
* **多种导出格式** — GLB、OBJ、PLY
* **Gradio 网络界面** — 基于浏览器的交互，无需编码
* **16–24 GB 显存** — 可在 RTX 3090 和 RTX 4090 上运行
* **300 万+ 次下载** 在 HuggingFace — 活跃的社区与持续更新

## 要求

| 组件     | 最低             | 推荐             |
| ------ | -------------- | -------------- |
| GPU    | RTX 3090 24 GB | RTX 4090 24 GB |
| 显存     | 16 GB          | 24 GB          |
| 内存     | 16 GB          | 32 GB          |
| 磁盘     | 50 GB          | 100 GB         |
| CUDA   | 11.8           | 12.1+          |
| Python | 3.10           | 3.11           |

**Clore.ai 价格：** RTX 4090 约 $0.5–2/天 · RTX 3090 约 $0.3–1/天

## 快速开始

### 1. 克隆并安装

```bash
git clone https://github.com/Tencent/Hunyuan3D-2.git
cd Hunyuan3D-2

# 创建环境
conda create -n hunyuan3d python=3.10 -y
conda activate hunyuan3d

# 安装 PyTorch
pip install torch torchvision --index-url https://download.pytorch.org/whl/cu121

# 安装依赖
pip install -r requirements.txt

# 下载模型权重（首次运行会自动下载，总约 15 GB）
python -c "from hy3dgen.shapegen import Hunyuan3DDiTFlowMatchingPipeline; Hunyuan3DDiTFlowMatchingPipeline.from_pretrained('tencent/Hunyuan3D-2')"
```

### 2. 启动 Gradio Web 界面

```bash
python gradio_app.py --port 7860 --share
```

该界面提供：

* 用于文本到 3D 生成的文本输入框
* 用于图像到 3D 生成的图像上传
* 用于推理步数、引导尺度和随机种子的滑块
* 带环绕控制的 3D 模型预览
* GLB/OBJ/PLY 下载按钮

### 3. 通过 Python API 生成

```python
from hy3dgen.shapegen import Hunyuan3DDiTFlowMatchingPipeline
from hy3dgen.texgen import Hunyuan3DPaintPipeline

# 第 1 阶段：形状生成
shape_pipeline = Hunyuan3DDiTFlowMatchingPipeline.from_pretrained(
    "tencent/Hunyuan3D-2",
    subfolder="shapegen",
)
shape_pipeline.to("cuda")

# 从文本生成网格
mesh = shape_pipeline(
    prompt="a detailed medieval sword with ornate handle",
    增加推理步数以提高稳定性
    guidance_scale=7.5,
    seed=42,
)[0]

mesh.export("sword_shape.glb")
```

### 4. 添加贴图（第 2 阶段）

```python
# 第 2 阶段：贴图合成
texture_pipeline = Hunyuan3DPaintPipeline.from_pretrained(
    "tencent/Hunyuan3D-2",
    subfolder="texgen",
)
texture_pipeline.to("cuda")

textured_mesh = texture_pipeline(
    mesh=mesh,
    prompt="a detailed medieval sword with ornate handle",
    num_inference_steps=20,
    seed=42,
)[0]

textured_mesh.export("sword_textured.glb")
```

## 使用示例

### 图像到 3D 生成

```python
from PIL import Image

# 加载参考图像
image = Image.open("reference_chair.png")

# 从图像生成形状
mesh = shape_pipeline(
    image=image,
    增加推理步数以提高稳定性
    guidance_scale=7.5,
    seed=42,
)[0]

# 应用贴图
textured = texture_pipeline(
    mesh=mesh,
    image=image,
    num_inference_steps=20,
    seed=42,
)[0]

textured.export("chair.glb")
```

### "专业影棚柔光箱"

```python
from pathlib import Path

prompts = [
    "a red sports car, low-poly game asset",
    "a wooden treasure chest, PBR material",
    "a sci-fi helmet with visor, hard surface",
]

output_dir = Path("/workspace/3d-output")
output_dir.mkdir(exist_ok=True)

for i, prompt in enumerate(prompts):
    mesh = shape_pipeline(prompt=prompt, num_inference_steps=30, seed=42)[0]
    textured = texture_pipeline(mesh=mesh, prompt=prompt, num_inference_steps=20, seed=42)[0]
    textured.export(str(output_dir / f"asset_{i:03d}.glb"))
    print(f"Generated: asset_{i:03d}.glb — {prompt[:40]}")
```

### 导出为多种格式

```python
# GLB（推荐 — 包含贴图，通用格式）
textured_mesh.export("model.glb")

# OBJ（带 MTL 材质文件）
textured_mesh.export("model.obj")

# PLY（顶点颜色，兼容点云）
textured_mesh.export("model.ply")
```

## 性能参考

| GPU      | 形状（30 步） | 贴图（20 步） | 总计     |
| -------- | -------- | -------- | ------ |
| 512x512  | \~20 秒   | \~15 秒   | \~35 秒 |
| 速度       | \~30 秒   | \~25 秒   | \~55 秒 |
| A100 40G | \~18 秒   | ≈12 秒    | \~30 秒 |

## 提示

* **移除图像背景** 在图像到 3D 之前 — 使用 `rembg` 以获得干净的分割
* **文本提示有利于具体化** — “a low-poly medieval sword with leather-wrapped handle” 比单独的 “sword” 能产生更好的结果
* **减少 `num_inference_steps`** 为更快的迭代预览将其降到 15–20
* **增加 `guidance_scale`** （8–12）以更强地遵循提示，但会牺牲多样性
* **GLB 是最佳导出格式** — 它将几何、贴图和材质打包在单一文件中
* **使用 `--share`** 在 Clore.ai 上启动 Gradio 以进行远程浏览器访问时使用
* **模型权重大约为 15 GB** — 首次运行前请确保有足够的磁盘空间
* **用于游戏资源时，**先以高质量生成，然后在 Blender 中简化以生成不同的 LOD 等级

## # 使用固定种子以获得一致结果

| 问题                         | 解决方案                                                        |
| -------------------------- | ----------------------------------------------------------- |
| `CUDA 内存不足（out of memory）` | 使用 RTX 3090+（24 GB）。减少批量大小或推理步数                             |
| 模型下载卡住                     | 检查磁盘空间。使用 `huggingface-cli download tencent/Hunyuan3D-2` 手动 |
| Gradio 界面无法访问              | 传递 `--share` 标志，或从 Clore.ai 仪表板转发 7860 端口                   |
| 几何质量差                      | 增加 `num_inference_steps` 到 40+，尝试不同的随机种子                    |
| 贴图伪影                       | 在贴图阶段前确保形状网格干净                                              |
| 全新安装时的导入错误                 | 运行 `pip install -r requirements.txt` 再次尝试 — 某些依赖会从源代码编译     |
| 首次运行时生成慢                   | 这是预期的 — 模型编译和权重加载在首次推理后会被缓存                                 |

## 资源

* [Hunyuan3D-2 GitHub](https://github.com/Tencent/Hunyuan3D-2)
* [HuggingFace 模型](https://huggingface.co/tencent/Hunyuan3D-2)
* [CLORE.AI 市场](https://clore.ai/marketplace)