> For the complete documentation index, see [llms.txt](https://docs.clore.ai/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.clore.ai/guides/guides_v2-zh/3d-sheng-cheng/hunyuan3d.md).

# Hunyuan3D 2.1

在 Clore.ai 上使用腾讯 Hunyuan3D 2.1 从文本或图像生成 3D 网格

腾讯的 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 网页 UI** ——基于浏览器的交互，无需编写代码
* **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   | 12.8+          | 12.8+          |
| Python | 3.10           | 3.11           |

**Clore.ai 价格：** RTX 4090 ≈ $0.14–0.42/小时 · RTX 3090 ≈ $0.07–0.21/小时

## 快速开始

### 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/cu128

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

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

### 2. 启动 Gradio 网页 UI

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

该 UI 提供：

* 用于文本生成 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="一把细节丰富的中世纪长剑，带有装饰性剑柄",
    num_inference_steps=30,
    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="一把细节丰富的中世纪长剑，带有装饰性剑柄",
    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,
    num_inference_steps=30,
    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 = [
    "一辆红色跑车，低多边形游戏资产",
    "一个木制宝箱，PBR 材质",
    "一顶带护目镜的科幻头盔，硬表面",
]

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"已生成：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 步） | 总计     |
| -------- | -------- | -------- | ------ |
| RTX 4090 | \~20 秒   | \~15 秒   | 约 35 秒 |
| RTX 3090 | 约 30 秒   | 约 25 秒   | 约 55 秒 |
| A100 40G | \~18 秒   | \~12 秒   | 约 30 秒 |

## 提示

* **移除图像背景** 在图像转 3D 之前——使用 `rembg` 进行干净的分割
* **文本提示越具体越有帮助** ——“一把低多边形中世纪长剑，带皮革缠绕剑柄”比“剑”效果更好
* **减少 `推理步数`** 降至 15–20，可在迭代时更快预览
* **增大 `guidance_scale`** （8–12）可更强地遵循提示，但会牺牲多样性
* **GLB 是最佳导出格式** ——它将几何、纹理和材质打包在一个文件中
* **使用 `--share`** 在 Clore.ai 上启动 Gradio 以获得远程浏览器访问时
* **模型权重约为 15 GB** ——首次运行前请确保有足够的磁盘空间
* **对于游戏资产**，先生成高质量版本，再在 Blender 中进行简化以制作不同 LOD 级别

## 故障排查

| 问题             | 解决方案                                                          |
| -------------- | ------------------------------------------------------------- |
| `CUDA 内存不足`    | 请使用 RTX 3090+（24 GB）。降低批大小或推理步数                               |
| 模型下载卡住         | 检查磁盘空间。手动使用 `huggingface-cli download tencent/Hunyuan3D-2` 下载 |
| Gradio UI 无法访问 | 传入 `--share` 该标志，或在 Clore.ai 仪表板中转发 7860 端口                   |
| 几何质量较差         | 增大 `推理步数` 提高到 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
This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com.

## 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, and the optional `goal` query parameter:

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

`ask` is the immediate question: it should be specific, self-contained, and written in natural language.
`goal` is optional and describes the broader end goal you are ultimately trying to accomplish on behalf of the user. GitBook uses it to tailor the answer towards what is most useful for that goal.

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.