# 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) --- # 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-es/generacion-3d/hunyuan3d.md?ask= ``` 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.