# Hunyuan3D 2.1

Hunyuan3D 2.1 de Tencent est un modèle de génération 3D en deux étapes : il prédit d'abord la géométrie (forme), puis synthétise des textures PBR. Il accepte à la fois des invites textuelles et des images de référence en entrée et produit des maillages prêts pour la production aux formats GLB, OBJ ou PLY. Avec plus de 3 millions de téléchargements sur HuggingFace, c'est l'un des modèles de génération 3D open-source les plus largement adoptés.

{% hint style="success" %}
Tous les exemples s'exécutent sur des serveurs GPU loués via le [CLORE.AI Marketplace](https://clore.ai/marketplace).
{% endhint %}

## Principales caractéristiques

* **Texte en 3D et image en 3D** — les deux modes d'entrée dans un seul modèle
* **Pipeline en deux étapes** — génération de la forme suivie de la synthèse de textures PBR
* **Sortie haute fidélité** — géométrie détaillée avec cartes d'albédo, normales et rugosité
* **Formats d'export multiples** — GLB, OBJ, PLY
* **Interface web Gradio** — interaction via le navigateur, aucun codage requis
* **16–24 GB VRAM** — fonctionne sur RTX 3090 et RTX 4090
* **3M+ téléchargements** sur HuggingFace — communauté active et mises à jour continues

## Exigences

| Composant | Minimum        | Recommandé     |
| --------- | -------------- | -------------- |
| GPU       | RTX 3090 24 GB | RTX 4090 24 Go |
| VRAM      | 16 Go          | 24 Go          |
| RAM       | 16 Go          | 32 Go          |
| Disque    | 50 Go          | 100 Go         |
| CUDA      | 11.8           | 12.1+          |
| Python    | 3.10           | 3.11           |

**Tarifs Clore.ai :** RTX 4090 ≈ 0,5–2 $/jour · RTX 3090 ≈ 0,3–1 $/jour

## Démarrage rapide

### 1. Cloner et installer

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

# Créer l'environnement
conda create -n hunyuan3d python=3.10 -y
conda activate hunyuan3d

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

# Installer les dépendances
pip install -r requirements.txt

# Télécharger les poids du modèle (téléchargés automatiquement au premier lancement, ~15 Go au total)
python -c "from hy3dgen.shapegen import Hunyuan3DDiTFlowMatchingPipeline; Hunyuan3DDiTFlowMatchingPipeline.from_pretrained('tencent/Hunyuan3D-2')"
```

### 2. Lancer l'interface web Gradio

```bash
python gradio_app.py --port 7860 --share
```

L'interface propose :

* Champ de saisie textuelle pour la génération texte→3D
* Téléversement d'image pour la génération image→3D
* Curseurs pour les étapes d'inférence, l'échelle de guidage et la graine
* Aperçu du modèle 3D avec contrôles d'orbite
* Boutons de téléchargement pour GLB/OBJ/PLY

### 3. Générer via l'API Python

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

# Étape 1 : génération de la forme
shape_pipeline = Hunyuan3DDiTFlowMatchingPipeline.from_pretrained(
    "tencent/Hunyuan3D-2",
    subfolder="shapegen",
)
shape_pipeline.to("cuda")

# Générer un maillage à partir du texte
mesh = shape_pipeline(
    prompt="une épée médiévale détaillée avec une poignée ornée",
    num_inference_steps=30,
    guidance_scale=7.5,
    seed=42,
)[0]

mesh.export("sword_shape.glb")
```

### 4. Ajouter des textures (Étape 2)

```python
# Étape 2 : synthèse de textures
texture_pipeline = Hunyuan3DPaintPipeline.from_pretrained(
    "tencent/Hunyuan3D-2",
    subfolder="texgen",
)
texture_pipeline.to("cuda")

textured_mesh = texture_pipeline(
    mesh=mesh,
    prompt="une épée médiévale détaillée avec une poignée ornée",
    num_inference_steps=20,
    seed=42,
)[0]

textured_mesh.export("sword_textured.glb")
```

## Exemples d'utilisation

### Génération image→3D

```python
from PIL import Image

# Charger l'image de référence
image = Image.open("reference_chair.png")

# Générer la forme à partir de l'image
mesh = shape_pipeline(
    image=image,
    num_inference_steps=30,
    guidance_scale=7.5,
    seed=42,
)[0]

# Appliquer la texture
textured = texture_pipeline(
    mesh=mesh,
    image=image,
    num_inference_steps=20,
    seed=42,
)[0]

textured.export("chair.glb")
```

### Traitement par lots

```python
from pathlib import Path

prompts = [
    "une voiture de sport rouge, asset low-poly pour jeu",
    "un coffre au trésor en bois, matériau PBR",
    "un casque sci-fi avec visière, surface dure",
]

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"Généré : asset_{i:03d}.glb — {prompt[:40]}")
```

### Exporter vers plusieurs formats

```python
# GLB (recommandé — inclut les textures, format universel)
textured_mesh.export("model.glb")

# OBJ (avec fichier de matériau MTL)
textured_mesh.export("model.obj")

# PLY (couleurs des sommets, compatible nuage de points)
textured_mesh.export("model.ply")
```

## Référence de performance

| GPU      | Forme (30 étapes) | Texture (20 étapes) | Total  |
| -------- | ----------------- | ------------------- | ------ |
| RTX 4090 | \~20 s            | \~15 s              | \~35 s |
| RTX 3090 | \~30 s            | \~25 sec            | \~55 s |
| A100 40G | \~18 s            | \~12 s              | \~30 s |

## Conseils

* **Supprimer les arrière-plans d'image** avant image→3D — utiliser `rembg` pour une segmentation propre
* **Les invites textuelles bénéficient de la spécificité** — "une épée médiévale low-poly avec poignée en cuir" produit de meilleurs résultats que "épée"
* **Réduire `num_inference_steps`** à 15–20 pour des aperçus plus rapides pendant l'itération
* **Augmentez `guidance_scale`** (8–12) pour une adhérence plus forte à l'invite au prix de la diversité
* **GLB est le meilleur format d'export** — il regroupe géométrie, textures et matériaux dans un seul fichier
* **Utilisez `--share`** lors du lancement de Gradio sur Clore.ai pour un accès distant via navigateur
* **Les poids du modèle font \~15 Go** — assurez-vous d'avoir suffisamment d'espace disque avant le premier lancement
* **Pour les assets de jeu**, générez en haute qualité puis décimatez dans Blender pour les niveaux de LOD

## Dépannage

| Problème                                      | Solution                                                                                                     |
| --------------------------------------------- | ------------------------------------------------------------------------------------------------------------ |
| `CUDA out of memory`                          | Utilisez RTX 3090+ (24 GB). Réduisez la taille de lot ou les étapes d'inférence                              |
| Le téléchargement du modèle bloque            | Vérifiez l'espace disque. Utilisez `huggingface-cli download tencent/Hunyuan3D-2` manuellement               |
| Interface Gradio inaccessible                 | Passer `--share` le drapeau, ou rediriger le port 7860 depuis le tableau de bord Clore.ai                    |
| Qualité de géométrie médiocre                 | Augmentez `num_inference_steps` à 40+, essayez d'autres graines                                              |
| Artéfacts de texture                          | Assurez-vous que le maillage de la forme est propre avant l'étape de texture                                 |
| Erreurs d'import sur une installation fraîche | Exécutez `pip install -r requirements.txt` à nouveau — certaines dépendances se compilent depuis les sources |
| Génération lente au premier lancement         | Attendu — la compilation du modèle et le chargement des poids sont mis en cache après la première inférence  |

## Ressources

* [Hunyuan3D-2 GitHub](https://github.com/Tencent/Hunyuan3D-2)
* [Modèle HuggingFace](https://huggingface.co/tencent/Hunyuan3D-2)
* [CLORE.AI Marketplace](https://clore.ai/marketplace)