# HunyuanImage 3.0

HunyuanImage 3.0 par Tencent est le **plus grand modèle open-source de génération d'images au monde** avec 80 milliards de paramètres au total (13 milliards actifs pendant l'inférence). Publié le 26 janvier 2026, il brise les conventions en unifiant génération d'images, édition et compréhension dans un seul modèle autorégressif — plus besoin de pipelines séparés pour texte→image et image→image. Il génère des images photoréalistes, effectue des modifications précises en préservant les éléments, gère les transferts de style et réalise même la fusion multi-images, le tout avec un seul modèle.

**HuggingFace :** [tencent/HunyuanImage-3.0-Instruct](https://huggingface.co/tencent/HunyuanImage-3.0-Instruct) **GitHub :** [Tencent-Hunyuan/HunyuanImage-3.0](https://github.com/Tencent-Hunyuan/HunyuanImage-3.0) **Licence :** Licence Communautaire Tencent Hunyuan (gratuite pour la recherche et l'usage commercial sous 100M MAU)

## Principales caractéristiques

* **80 milliards au total / 13 milliards de paramètres actifs** — plus grand modèle MoE open-source pour images ; n'active que 13 milliards de paramètres par inférence
* **Architecture multimodale unifiée** — texte→image, édition d'image, transfert de style et composition multi-image dans un seul modèle
* **Édition pilotée par instructions** — décrivez ce que vous voulez modifier en langage naturel, en préservant les éléments non touchés
* **Point de contrôle distillé disponible** — `HunyuanImage-3.0-Instruct-Distil` fonctionne en seulement 8 étapes d'échantillonnage pour une génération plus rapide
* **accélération vLLM** — support natif vLLM pour une inférence en production significativement plus rapide
* **Cadre autorégressif** — contrairement aux modèles basés sur DiT (FLUX, SD3.5), utilise une approche AR unifiée pour la compréhension et la génération

## Variantes de modèle

| Modèle                               | Cas d'utilisation                   | Pas   | HuggingFace                                |
| ------------------------------------ | ----------------------------------- | ----- | ------------------------------------------ |
| **HunyuanImage-3.0**                 | Texte→image uniquement              | 30–50 | `tencent/HunyuanImage-3.0`                 |
| **HunyuanImage-3.0-Instruct**        | Texte→image + édition + multi-image | 30–50 | `tencent/HunyuanImage-3.0-Instruct`        |
| **HunyuanImage-3.0-Instruct-Distil** | Inférence rapide (8 étapes)         | 8     | `tencent/HunyuanImage-3.0-Instruct-Distil` |

## Exigences

| Configuration | GPU unique (déchargement)           | Recommandé   | Production multi-GPU |
| ------------- | ----------------------------------- | ------------ | -------------------- |
| GPU           | 1× RTX 4090 24GB                    | 1× A100 80GB | 2–3× A100 80GB       |
| VRAM          | 24GB (avec déchargement de couches) | 80Go         | 160–240GB            |
| RAM           | 128Go                               | 128Go        | 256GB                |
| Disque        | 200GB                               | 200GB        | 200GB                |
| CUDA          | 12.0+                               | 12.0+        | 12.0+                |

**Configuration Clore.ai recommandée :**

* **Meilleur rapport qualité/prix :** 1× A100 80GB (\~2–4$/jour) — exécute le modèle complet confortablement sans déchargement
* **Option économique :** 1× RTX 4090 (\~0,5–2$/jour) — fonctionne avec déchargement sur CPU (plus lent, mais fonctionnel)
* **Production rapide :** 2× A100 80GB (\~4–8$/jour) — pour génération par lots et le modèle Instruct

## Démarrage rapide

### Installation

```bash
# Cloner le dépôt
git clone https://github.com/Tencent-Hunyuan/HunyuanImage-3.0.git
cd HunyuanImage-3.0

# Créer l'environnement
pip install -r requirements.txt
pip install torch torchvision --index-url https://download.pytorch.org/whl/cu121

# Télécharger les poids du modèle
huggingface-cli download tencent/HunyuanImage-3.0-Instruct --local-dir ./ckpts/HunyuanImage-3-Instruct
```

### Texte→Image avec Transformers

```python
import torch
from transformers import AutoModelForCausalLM, AutoTokenizer

# Charger le modèle (nécessite ~80GB de VRAM pour la précision complète)
model_path = "./ckpts/HunyuanImage-3-Instruct"
model = AutoModelForCausalLM.from_pretrained(
    model_path,
    torch_dtype=torch.bfloat16,
    device_map="auto",
    trust_remote_code=True,
)

# Générer une image à partir d'un texte
prompt = "Un jardin japonais serein en automne, des carpes koi nageant dans un étang cristallin, des feuilles d'érable dorées qui tombent, style peinture aquarelle"
output = model.generate_image(prompt, num_inference_steps=30)
output.save("japanese_garden.png")
```

### Utiliser l'interface Web Gradio

La manière la plus simple d'expérimenter toutes les fonctionnalités :

```bash
cd HunyuanImage-3.0

# Installer Gradio
pip install gradio

# Lancer l'interface web
python gradio_demo.py \
    --model-path ./ckpts/HunyuanImage-3-Instruct \
    --server-name 0.0.0.0 \
    --server-port 7860
```

Puis accéder via un tunnel SSH : `ssh -L 7860:localhost:7860 root@<clore-ip>`

## Exemples d'utilisation

### 1. Génération Texte→Image (CLI)

```bash
cd HunyuanImage-3.0

python inference.py \
    --model-path ./ckpts/HunyuanImage-3-Instruct \
    --prompt "Paysage urbain cyberpunk la nuit, gratte-ciels éclairés au néon se reflétant dans des rues baignées de pluie, voitures volantes, brouillard volumétrique, 8K" \
    --output-path output.png \
    --num-inference-steps 30 \
    --guidance-scale 5.0
```

### 2. Édition d'image avec langage naturel

Une des fonctionnalités remarquables de HunyuanImage 3.0 — modifiez des images existantes en décrivant les changements :

```bash
python inference.py \
    --model-path ./ckpts/HunyuanImage-3-Instruct \
    --prompt "Changer la saison en hiver avec de la neige recouvrant les arbres" \
    --image-path input_photo.jpg \
    --output-path edited_winter.png \
    --num-inference-steps 30
```

### 3. Génération rapide avec le modèle distillé (8 étapes)

```bash
# Télécharger le point de contrôle distillé
huggingface-cli download tencent/HunyuanImage-3.0-Instruct-Distil \
    --local-dir ./ckpts/HunyuanImage-3-Instruct-Distil

# Générer avec seulement 8 étapes (5–6× plus rapide)
python inference.py \
    --model-path ./ckpts/HunyuanImage-3-Instruct-Distil \
    --prompt "Portrait d'un astronaute chevauchant un cheval sur Mars, photoréaliste" \
    --output-path astronaut.png \
    --num-inference-steps 8
```

## Comparaison avec d'autres modèles d'images

| Fonction           | HunyuanImage 3.0     | FLUX.2 Klein               | SD 3.5 Large               |
| ------------------ | -------------------- | -------------------------- | -------------------------- |
| Paramètres         | 80B MoE (13B actifs) | 32B DiT                    | 8B DiT                     |
| Architecture       | MoE autorégressif    | Transformeur par diffusion | Transformeur par diffusion |
| Édition d'image    | ✅ Natif              | ❌ Nécessite ControlNet     | ❌ Nécessite img2img        |
| Fusion multi-image | ✅ Natif              | ❌                          | ❌                          |
| Transfert de style | ✅ Natif              | ❌ Nécessite LoRA           | ❌ Nécessite LoRA           |
| VRAM min           | \~24GB (déchargé)    | 16Go                       | 8 Go                       |
| Vitesse (A100)     | \~15–30 sec          | \~0.3 sec                  | \~5 sec                    |
| Licence            | Communauté Tencent   | Apache 2.0                 | Stability AI CL            |

## Conseils pour les utilisateurs de Clore.ai

1. **Utilisez le modèle distillé pour la vitesse** — `HunyuanImage-3.0-Instruct-Distil` génère en 8 étapes au lieu de 30–50, réduisant le temps d'inférence par 4–6×. La qualité reste étonnamment proche du modèle complet.
2. **A100 80GB est le point idéal** — Une seule A100 80GB (\~2–4$/jour sur Clore.ai) exécute le modèle Instruct sans aucun artifice de déchargement. C'est beaucoup plus rapide qu'une RTX 4090 avec déchargement CPU.
3. **Pré-téléchargez les modèles** — Le point de contrôle Instruct complet fait \~160GB. Téléchargez-le une fois sur un volume persistant Clore.ai pour éviter de le retélécharger à chaque nouvelle instance.
4. **Utilisez le tunneling SSH pour Gradio** — N'exposez pas le port 7860 publiquement. Utilisez `ssh -L 7860:localhost:7860` pour accéder à l'interface web en toute sécurité depuis votre navigateur.
5. **Essayez le backend vLLM pour le travail par lots** — Si vous générez de nombreuses images, le chemin d'inférence vLLM (dans le `vllm_infer/` dossier) offre un débit nettement meilleur.

## Dépannage

| Problème                                    | Solution                                                                                                                                      |
| ------------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------- |
| `CUDA out of memory` sur RTX 4090           | Utilisez `device_map="auto"` pour activer le déchargement sur CPU, ou passez au modèle Distil                                                 |
| Le téléchargement échoue / très lent        | Définir `HF_TOKEN` variable d'environnement ; utilisez `huggingface-cli download` avec `--resume-download`                                    |
| Impossible de charger le modèle via l'ID HF | En raison du point dans le nom, clonez d'abord localement : `huggingface-cli download tencent/HunyuanImage-3.0-Instruct --local-dir ./ckpts/` |
| Sorties floues ou de faible qualité         | Augmentez `--num-inference-steps` à 40–50 ; augmentez `--guidance-scale` à 7.0                                                                |
| L'édition d'image ignore les instructions   | Soyez précis sur ce qu'il faut changer et ce qu'il faut préserver ; utilisez des prompts courts et clairs                                     |
| L'interface Gradio ne démarre pas           | Assurez-vous que `gradio>=4.0` est installé ; vérifiez que le chemin du modèle pointe vers le bon répertoire                                  |

## Lectures complémentaires

* [Dépôt GitHub](https://github.com/Tencent-Hunyuan/HunyuanImage-3.0) — Code officiel, scripts d'inférence, démo Gradio
* [HunyuanImage 3.0-Instruct (HuggingFace)](https://huggingface.co/tencent/HunyuanImage-3.0-Instruct) — Poids du modèle complet
* [Point de contrôle distillé](https://huggingface.co/tencent/HunyuanImage-3.0-Instruct-Distil) — Inférence rapide en 8 étapes
* [Rapport technique (arXiv)](https://arxiv.org/pdf/2509.23951) — Détails d'architecture et benchmarks
* [Intégration ComfyUI](https://github.com/bgreene2/ComfyUI-Hunyuan-Image-3) — Nœud personnalisé Community ComfyUI