Hunyuan3D 2.1

Generieren Sie 3D-Meshes aus Text oder Bildern mit Tencent Hunyuan3D 2.1 auf Clore.ai

Hunyuan3D 2.1 von Tencent ist ein zweistufiges 3D-Generierungsmodell: Es sagt zuerst die Geometrie (Form) voraus und synthetisiert dann PBR-Texturen. Es akzeptiert sowohl Texteingaben als auch Referenzbilder als Eingabe und gibt produktionstaugliche Meshes im GLB-, OBJ- oder PLY-Format aus. Mit über 3 Millionen Downloads auf HuggingFace ist es eines der am weitesten verbreiteten Open-Source-3D-Generierungsmodelle.

Alle Beispiele laufen auf GPU-Servern, die über die CLORE.AI Marketplace.

Hauptmerkmale

• Text-zu-3D und Bild-zu-3D — beide Eingabemodi in einem einzigen Modell

• Zweistufige Pipeline — Formgenerierung gefolgt von PBR-Textursynthese

• Hohe Wiedergabetreue — detaillierte Geometrie mit Albedo-, Normal- und Roughness-Maps

• Mehrere Exportformate — GLB, OBJ, PLY

• Gradio Web-UI — browserbasierte Interaktion, kein Programmieraufwand erforderlich

• 16–24 GB VRAM — läuft auf RTX 3090 und RTX 4090

• 3M+ Downloads auf HuggingFace — aktive Community und kontinuierliche Updates

Anforderungen

Komponente	Minimum	Empfohlen
GPU	RTX 3090 24 GB	RTX 4090 24 GB
VRAM	16 GB	24 GB
RAM	16 GB	32 GB
Festplatte	50 GB	100 GB
CUDA	11.8	12.1+
Python	3.10	3.11

Clore.ai-Preise: RTX 4090 ≈ $0.5–2/Tag · RTX 3090 ≈ $0.3–1/Tag

Schnellstart

1. Klonen und installieren

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

# Umgebung erstellen
conda create -n hunyuan3d python=3.10 -y
conda activate hunyuan3d

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

# Abhängigkeiten installieren
pip install -r requirements.txt

# Modellgewichte herunterladen (wird beim ersten Lauf automatisch heruntergeladen, insgesamt ~15 GB)
python -c "from hy3dgen.shapegen import Hunyuan3DDiTFlowMatchingPipeline; Hunyuan3DDiTFlowMatchingPipeline.from_pretrained('tencent/Hunyuan3D-2')"

2. Die Gradio Web-UI starten

python gradio_app.py --port 7860 --share

Die UI bietet:

• Texteingabefeld für Text-zu-3D-Generierung

• Bild-Upload für Bild-zu-3D-Generierung

• Schieberegler für Inferenzschritte, Guidance-Scale und Seed

• 3D-Modellvorschau mit Orbit-Steuerung

• Download-Buttons für GLB/OBJ/PLY

3. Generierung über die Python-API

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

# Stufe 1: Formgenerierung
shape_pipeline = Hunyuan3DDiTFlowMatchingPipeline.from_pretrained(
    "tencent/Hunyuan3D-2",
    subfolder="shapegen",
)
shape_pipeline.to("cuda")

# Mesh aus Text generieren
mesh = shape_pipeline(
    prompt="a detailed medieval sword with ornate handle",
    num_inference_steps=30,
    guidance_scale=7.5,
    seed=42,
)[0]

mesh.export("sword_shape.glb")

4. Texturen hinzufügen (Stufe 2)

# Stufe 2: Textursynthese
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")

Beispielanwendungen

Bild-zu-3D-Generierung

from PIL import Image

# Referenzbild laden
image = Image.open("reference_chair.png")

# Form aus Bild generieren
mesh = shape_pipeline(
    image=image,
    num_inference_steps=30,
    guidance_scale=7.5,
    seed=42,
)[0]

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

textured.export("chair.glb")

Batch-Verarbeitung

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]}")

Export in mehrere Formate

# GLB (empfohlen — beinhaltet Texturen, universelles Format)
textured_mesh.export("model.glb")

# OBJ (mit MTL-Materialdatei)
textured_mesh.export("model.obj")

# PLY (Vertex-Farben, punktewolkenkompatibel)
textured_mesh.export("model.ply")

Leistungsreferenz

GPU	Form (30 Schritte)	Textur (20 Schritte)	Gesamt
RTX 4090	~20 Sek	~15 Sek	~35 Sek
RTX 3090	~30 Sek.	~25 Sek.	~55 Sek
A100 40G	~18 Sek.	~12 Sek.	~30 Sek.

Tipps

• Bildhintergründe entfernen vor Bild-zu-3D — verwenden Sie rembg für saubere Segmentierung

• Text-Prompts profitieren von Spezifizität — "a low-poly medieval sword with leather-wrapped handle" liefert bessere Ergebnisse als "sword"

• Reduzieren num_inference_steps auf 15–20 für schnellere Vorschauen während der Iteration

• Erhöhen Sie guidance_scale (8–12) für stärkere Einhaltung des Prompts auf Kosten der Diversität

• GLB ist das beste Exportformat — es bündelt Geometrie, Texturen und Materialien in einer einzigen Datei

• Verwenden Sie --share beim Starten von Gradio auf Clore.ai für den entfernten Browserzugriff

• Modellgewichte sind ~15 GB — stellen Sie vor dem ersten Lauf ausreichend Festplattenspeicher sicher

• Für Spielassets, erzeugen Sie in hoher Qualität und dezimieren Sie dann in Blender für LOD-Stufen

Fehlerbehebung

Problem	Lösung
CUDA out of memory	Verwenden Sie RTX 3090+ (24 GB). Reduzieren Sie die Batch-Größe oder die Inferenzschritte
Modell-Download stockt	Überprüfen Sie den Festplattenspeicher. Verwenden Sie huggingface-cli download tencent/Hunyuan3D-2 manuell
Gradio-UI nicht erreichbar	Flagge übergeben, --share oder leiten Sie Port 7860 vom Clore.ai-Dashboard weiter
Schlechte Geometriequalität	Erhöhen Sie num_inference_steps auf 40+ erhöhen, versuchen Sie verschiedene Seeds
Texturartefakte	Stellen Sie sicher, dass das Form-Mesh vor der Texturstufe sauber ist
Importfehler bei frischer Installation	Ausführen pip install -r requirements.txt nochmals — einige Abhängigkeiten werden aus dem Quellcode kompiliert
Langsame Generierung beim ersten Lauf	Erwartet — Modellkompilierung und Laden der Gewichte werden nach der ersten Inferenz zwischengespeichert

Ressourcen

• Hunyuan3D-2 GitHub

• HuggingFace Modell

• CLORE.AI Marketplace