Hunyuan3D 2.1

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

Hunyuan3D 2.1 von Tencent ist ein zweistufiges 3D-Generierungsmodell: Zuerst sagt es die Geometrie (Form) voraus, dann synthetisiert es PBR-Texturen. Es akzeptiert sowohl Text-Prompts als auch Referenzbilder als Eingabe und gibt produktionsreife 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-Marktplatz.

Hauptfunktionen

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

• Zweistufige Pipeline — Formgenerierung gefolgt von PBR-Textursynthese

• Ausgabe mit hoher Wiedergabetreue — detaillierte Geometrie mit Albedo-, Normalen- und Rauigkeitskarten

• Mehrere Exportformate — GLB, OBJ, PLY

• Gradio-Weboberfläche — browserbasierte Interaktion, kein Code erforderlich

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

• 3 Mio.+ 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	12.8+	12.8+
Python	3.10	3.11

Clore.ai-Preise: RTX 4090 ≈ 0,14–0,42 $/Std. · RTX 3090 ≈ 0,07–0,21 $/Std.

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

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

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

2. Die Gradio-Weboberfläche starten

python gradio_app.py --port 7860 --share

Die Oberfläche bietet:

• Text-Eingabefeld für die Text-zu-3D-Generierung

• Bild-Upload für die 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. Über die Python-API generieren

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

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

# Mesh aus Text generieren
mesh = shape_pipeline(
    prompt="ein detailliertes mittelalterliches Schwert mit kunstvollem Griff",
    num_inference_steps=30,
    guidance_scale=7.5,
    seed=42,
)[0]

mesh.export("sword_shape.glb")

4. Texturen hinzufügen (Phase 2)

# Phase 2: Textursynthese
texture_pipeline = Hunyuan3DPaintPipeline.from_pretrained(
    "tencent/Hunyuan3D-2",
    subfolder="texgen",
)
texture_pipeline.to("cuda")

textured_mesh = texture_pipeline(
    mesh=mesh,
    prompt="ein detailliertes mittelalterliches Schwert mit kunstvollem Griff",
    num_inference_steps=20,
    seed=42,
)[0]

textured_mesh.export("sword_textured.glb")

Anwendungsbeispiele

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 = [
    "ein roter Sportwagen, Low-Poly-Game-Asset",
    "eine hölzerne Schatztruhe, PBR-Material",
    "ein Sci-Fi-Helm mit Visier, 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"Erstellt: asset_{i:03d}.glb — {prompt[:40]}")

In mehrere Formate exportieren

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

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

# PLY (Vertex-Farben, mit Punktwolken kompatibel)
textured_mesh.export("model.ply")

Leistungsreferenz

GPU	Geometrie (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

• Bildehintergründe entfernen vor Bild-zu-3D — verwende rembg für eine saubere Segmentierung

• Text-Prompts profitieren von Spezifität — „ein Low-Poly-mittelalterliches Schwert mit lederumwickeltem Griff“ liefert bessere Ergebnisse als „Schwert“

• Reduziere 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 Vielfalt

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

• Verwende --share beim Starten von Gradio auf Clore.ai für den Remote-Browserzugriff

• Modellgewichte sind ca. 15 GB groß — stelle vor dem ersten Lauf ausreichend Speicherplatz sicher

• Für Game-Assets, mit hoher Qualität generieren und dann in Blender für LOD-Stufen reduzieren

Fehlerbehebung

Problem	Lösung
CUDA-Speicher erschöpft	Verwende RTX 3090+ (24 GB). Verringere die Batch-Größe oder die Inferenzschritte
Modelldownload hängt fest	Prüfe den Speicherplatz. Verwende huggingface-cli download tencent/Hunyuan3D-2 manuell
Gradio-Oberfläche nicht erreichbar	Übergebe --share den --share-Schalter oder leite Port 7860 vom Clore.ai-Dashboard weiter
Schlechte Geometriequalität	Erhöhen Sie num_inference_steps auf 40+, probiere verschiedene Seeds
Texturartefakte	Stelle sicher, dass das Shape-Mesh vor der Texturphase sauber ist
Importfehler bei frischer Installation	Ausführen pip install -r requirements.txt erneut — einige Abhängigkeiten werden aus dem Quellcode kompiliert
Langsame Generierung beim ersten Lauf	Erwartet — Modellkompilierung und das Laden der Gewichte werden nach der ersten Inferenz zwischengespeichert

Ressourcen

• Hunyuan3D-2 GitHub

• HuggingFace-Modell

• CLORE.AI-Marktplatz