# Hunyuan3D 2.1

Hunyuan3D 2.1 de Tencent es un modelo de generación 3D en dos etapas: primero predice la geometría (forma) y luego sintetiza texturas PBR. Acepta tanto indicaciones de texto como imágenes de referencia como entrada y produce mallas listas para producción en formato GLB, OBJ o PLY. Con más de 3 millones de descargas en HuggingFace, es uno de los modelos de generación 3D de código abierto más adoptados.

{% hint style="success" %}
Todos los ejemplos se ejecutan en servidores GPU alquilados a través de [CLORE.AI Marketplace](https://clore.ai/marketplace).
{% endhint %}

## Características clave

* **De texto a 3D y de imagen a 3D** — ambos modos de entrada en un solo modelo
* **Canalización en dos etapas** — generación de forma seguida de síntesis de texturas PBR
* **Salida de alta fidelidad** — geometría detallada con mapas de albedo, normales y rugosidad
* **Múltiples formatos de exportación** — GLB, OBJ, PLY
* **Interfaz web Gradio** — interacción en el navegador, no se requiere programación
* **16–24 GB de VRAM** — funciona en RTX 3090 y RTX 4090
* **Más de 3M descargas** en HuggingFace — comunidad activa y actualizaciones continuas

## Requisitos

| Componente | Mínimo         | Recomendado    |
| ---------- | -------------- | -------------- |
| GPU        | RTX 3090 24 GB | RTX 4090 24 GB |
| VRAM       | 16 GB          | 24 GB          |
| RAM        | 16 GB          | 32 GB          |
| Disco      | 50 GB          | 100 GB         |
| CUDA       | 11.8           | 12.1+          |
| Python     | 3.10           | 3.11           |

**Precios de Clore.ai:** RTX 4090 ≈ $0.5–2/día · RTX 3090 ≈ $0.3–1/día

## Inicio rápido

### 1. Clonar e instalar

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

# Crear entorno
conda create -n hunyuan3d python=3.10 -y
conda activate hunyuan3d

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

# Instalar dependencias
pip install -r requirements.txt

# Descargar pesos del modelo (se descargan automáticamente en la primera ejecución, ~15 GB en total)
python -c "from hy3dgen.shapegen import Hunyuan3DDiTFlowMatchingPipeline; Hunyuan3DDiTFlowMatchingPipeline.from_pretrained('tencent/Hunyuan3D-2')"
```

### 2. Lanzar la interfaz web Gradio

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

La interfaz ofrece:

* Campo de entrada de texto para generación de 3D desde texto
* Subida de imagen para generación de 3D desde imagen
* Deslizadores para pasos de inferencia, escala de guía y semilla
* Vista previa del modelo 3D con controles de órbita
* Botones de descarga para GLB/OBJ/PLY

### 3. Generar mediante la API de Python

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

# Etapa 1: Generación de forma
shape_pipeline = Hunyuan3DDiTFlowMatchingPipeline.from_pretrained(
    "tencent/Hunyuan3D-2",
    subfolder="shapegen",
)
shape_pipeline.to("cuda")

# Generar malla desde texto
mesh = shape_pipeline(
    prompt="una espada medieval detallada con empuñadura ornamentada",
    num_inference_steps=30,
    guidance_scale=7.5,
    seed=42,
)[0]

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

### 4. Añadir texturas (Etapa 2)

```python
# Etapa 2: Síntesis de texturas
texture_pipeline = Hunyuan3DPaintPipeline.from_pretrained(
    "tencent/Hunyuan3D-2",
    subfolder="texgen",
)
texture_pipeline.to("cuda")

textured_mesh = texture_pipeline(
    mesh=mesh,
    prompt="una espada medieval detallada con empuñadura ornamentada",
    num_inference_steps=20,
    seed=42,
)[0]

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

## Ejemplos de uso

### Generación de 3D desde imagen

```python
from PIL import Image

# Cargar imagen de referencia
image = Image.open("reference_chair.png")

# Generar forma desde imagen
mesh = shape_pipeline(
    image=image,
    num_inference_steps=30,
    guidance_scale=7.5,
    seed=42,
)[0]

# Aplicar textura
textured = texture_pipeline(
    mesh=mesh,
    image=image,
    num_inference_steps=20,
    seed=42,
)[0]

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

### Procesamiento por lotes

```python
from pathlib import Path

prompts = [
    "un coche deportivo rojo, activo de juego low-poly",
    "un cofre del tesoro de madera, material PBR",
    "un casco de ciencia ficción con visera, superficie dura",
]

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"Generado: asset_{i:03d}.glb — {prompt[:40]}")
```

### Exportar a múltiples formatos

```python
# GLB (recomendado — incluye texturas, formato universal)
textured_mesh.export("model.glb")

# OBJ (con archivo de material MTL)
textured_mesh.export("model.obj")

# PLY (colores por vértice, compatible con nubes de puntos)
textured_mesh.export("model.ply")
```

## Referencia de rendimiento

| GPU      | Forma (30 pasos) | Textura (20 pasos) | Total    |
| -------- | ---------------- | ------------------ | -------- |
| RTX 4090 | \~20 seg         | \~15 seg           | \~35 seg |
| RTX 3090 | \~30 seg         | \~25 s             | \~55 seg |
| A100 40G | \~18 seg         | \~12 seg           | \~30 seg |

## Consejos

* **Eliminar fondos de imágenes** antes de imagen-a-3D — usar `rembg` para una segmentación limpia
* **Las indicaciones de texto se benefician de la especificidad** — "una espada medieval low-poly con empuñadura envuelta en cuero" produce mejores resultados que "espada"
* **Reducir `num_inference_steps`** a 15–20 para vistas previas más rápidas durante la iteración
* **Aumente `guidance_scale`** (8–12) para mayor adherencia a la indicación a costa de la diversidad
* **GLB es el mejor formato de exportación** — agrupa geometría, texturas y materiales en un único archivo
* **Usa `--share`** al lanzar Gradio en Clore.ai para acceso remoto desde el navegador
* **Los pesos del modelo son \~15 GB** — asegúrate de tener suficiente espacio en disco antes de la primera ejecución
* **Para activos de juego**, genera a alta calidad y luego decima en Blender para niveles LOD

## Solución de problemas

| Problema                                    | Solución                                                                                                        |
| ------------------------------------------- | --------------------------------------------------------------------------------------------------------------- |
| `CUDA fuera de memoria`                     | Usa RTX 3090+ (24 GB). Reduce el tamaño de lote o los pasos de inferencia                                       |
| La descarga del modelo se detiene           | Comprueba el espacio en disco. Usa `huggingface-cli download tencent/Hunyuan3D-2` manualmente                   |
| Interfaz Gradio no accesible                | Pasa `--share` el flag, o reenvía el puerto 7860 desde el panel de Clore.ai                                     |
| Mala calidad de geometría                   | Aumente `num_inference_steps` a 40+, prueba con semillas diferentes                                             |
| Artefactos en las texturas                  | Asegúrate de que la malla de la forma esté limpia antes de la etapa de texturizado                              |
| Errores de importación en instalación nueva | Ejecuta `pip install -r requirements.txt` de nuevo — algunas dependencias se compilan desde la fuente           |
| Generación lenta en la primera ejecución    | Esperado — la compilación del modelo y la carga de pesos se almacenan en caché después de la primera inferencia |

## Recursos

* [Hunyuan3D-2 GitHub](https://github.com/Tencent/Hunyuan3D-2)
* [Modelo en HuggingFace](https://huggingface.co/tencent/Hunyuan3D-2)
* [CLORE.AI Marketplace](https://clore.ai/marketplace)