> For the complete documentation index, see [llms.txt](https://docs.clore.ai/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.clore.ai/guides/guides_v2-de/3d-generierung/hunyuan3d.md). # Hunyuan3D 2.1 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. {% hint style="success" %} Alle Beispiele laufen auf GPU-Servern, die über die [CLORE.AI Marketplace](https://clore.ai/marketplace). {% endhint %} ## 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 ```bash 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 ```bash 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 ```python 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) ```python # 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 ```python 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 ```python 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 ```python # 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](https://github.com/Tencent/Hunyuan3D-2) * [HuggingFace Modell](https://huggingface.co/tencent/Hunyuan3D-2) * [CLORE.AI Marketplace](https://clore.ai/marketplace) --- # Agent Instructions This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com. ## 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-de/3d-generierung/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.