# 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)


---

# Agent Instructions: Querying This Documentation

If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter:

```
GET https://docs.clore.ai/guides/guides_v2-zh/3d-sheng-cheng/hunyuan3d.md?ask=<question>
```

The question should be specific, self-contained, and written in natural language.
The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.