Hunyuan3D 2.1

Genera mallas 3D a partir de texto o imágenes con Tencent Hunyuan3D 2.1 en Clore.ai

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.

Todos los ejemplos se ejecutan en servidores GPU alquilados a través de CLORE.AI Marketplace.

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

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

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

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)

# 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

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

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

# 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

• Modelo en HuggingFace

• CLORE.AI Marketplace