# Génération vidéo CogVideoX

CogVideoX est une famille de transformeurs de diffusion vidéo à poids ouverts de Zhipu AI (Tsinghua). Les modèles génèrent des clips cohérents de 6 secondes en 720×480 et 8 ips à partir soit d'une invite textuelle (T2V), soit d'une image de référence plus une invite (I2V). Deux échelles de paramètres sont disponibles — 2B pour des itérations rapides et 5B pour une fidélité supérieure — toutes deux avec un `intégration` via `CogVideoXPipeline`.

Faire tourner CogVideoX sur un GPU loué depuis [Clore.ai](https://clore.ai/) vous permet d'éviter les contraintes matérielles locales et de générer de la vidéo à grande échelle pour quelques centimes par clip.

## Principales caractéristiques

* **Texte vers Vidéo (T2V)** — décrivez une scène et obtenez un clip de 6 secondes en 720×480 à 8 ips (49 images).
* **Image vers Vidéo (I2V)** — fournissez une image de référence plus une invite ; le modèle l'anime avec une cohérence temporelle.
* **Deux échelles** — CogVideoX-2B (rapide, \~12 Go de VRAM) et CogVideoX-5B (qualité supérieure, \~20 Go de VRAM).
* **Support natif des diffusers** — `CogVideoXPipeline` et `CogVideoXImageToVideoPipeline` classes.
* **VAE causal 3D** — compresse 49 images en un espace latent compact pour un débruitage efficace.
* **Poids ouverts** — licence Apache-2.0 pour la variante 2B ; licence de recherche pour la 5B.

## Exigences

| Composant   | Minimum          | Recommandé       |
| ----------- | ---------------- | ---------------- |
| VRAM GPU    | 16 Go (2B, fp16) | 24 Go (5B, bf16) |
| RAM système | 32 Go            | 64 Go            |
| Disque      | 30 Go            | 50 Go            |
| Python      | 3.10+            | 3.11             |
| CUDA        | 12.1+            | 12.4             |

**Recommandation GPU Clore.ai :** Un **RTX 4090** (24 Go, \~0,5–2 $/jour) gère confortablement les variantes 2B et 5B. Un **RTX 3090** (24 Go, \~0,3–1 $/jour) fonctionne tout aussi bien pour la 5B en bf16 et est le choix économique.

## Démarrage rapide

```bash
# Créer l'environnement
pip install torch torchvision --index-url https://download.pytorch.org/whl/cu124
pip install diffusers transformers accelerate sentencepiece imageio[ffmpeg]

# Vérifier le GPU
python -c "import torch; print(torch.cuda.get_device_name(0))"
```

## Exemples d'utilisation

### Texte vers Vidéo (5B)

```python
import torch
from diffusers import CogVideoXPipeline
from diffusers.utils import export_to_video

pipe = CogVideoXPipeline.from_pretrained(
    "THUDM/CogVideoX-5b",
    torch_dtype=torch.bfloat16,
)
pipe.to("cuda")
pipe.enable_model_cpu_offload()      # économise ~4 Go de VRAM au pic
pipe.vae.enable_tiling()             # requis pour 720x480 sur des cartes 24 Go

prompt = (
    "Un golden retriever courant dans un champ de tournesols au coucher du soleil, "
    "éclairage cinématographique, ralenti, qualité 4K"
)

video_frames = pipe(
    prompt=prompt,
    num_frames=49,
    guidance_scale=6.0,
    num_inference_steps=50,
    generator=torch.Generator("cuda").manual_seed(42),
).frames[0]

export_to_video(video_frames, "retriever_sunset.mp4", fps=8)
print("Saved retriever_sunset.mp4")
```

### Image vers Vidéo (5B)

```python
import torch
from PIL import Image
from diffusers import CogVideoXImageToVideoPipeline
from diffusers.utils import export_to_video

pipe = CogVideoXImageToVideoPipeline.from_pretrained(
    "THUDM/CogVideoX-5b-I2V",
    torch_dtype=torch.bfloat16,
)
pipe.to("cuda")
pipe.enable_model_cpu_offload()
pipe.vae.enable_tiling()

image = Image.open("reference.png").resize((720, 480))

video_frames = pipe(
    prompt="La caméra orbite lentement autour du sujet, vent léger",
    image=image,
    num_frames=49,
    guidance_scale=6.0,
    num_inference_steps=50,
).frames[0]

export_to_video(video_frames, "animated.mp4", fps=8)
```

### Génération rapide avec la variante 2B

```python
from diffusers import CogVideoXPipeline
import torch

pipe = CogVideoXPipeline.from_pretrained(
    "THUDM/CogVideoX-2b",
    torch_dtype=torch.float16,
)
pipe.to("cuda")
pipe.vae.enable_tiling()

frames = pipe(
    prompt="Time-lapse d'un cerisier en fleurs",
    num_frames=49,
    guidance_scale=6.0,
    num_inference_steps=30,       # moins d'étapes → plus rapide
).frames[0]
```

## Conseils pour les utilisateurs de Clore.ai

1. **Activer le tiling du VAE** — sans `pipe.vae.enable_tiling()` le VAE 3D provoquera un OOM sur des cartes 24 Go pendant le décodage.
2. **Utilisez `enable_model_cpu_offload()`** — déplace automatiquement les modules inactifs vers la RAM ; ajoute \~10 % au temps mur mais économise plus de 4 Go de VRAM au pic.
3. **bf16 pour 5B, fp16 pour 2B** — le point de contrôle 5B a été entraîné en bf16 ; utiliser fp16 peut provoquer des sorties NaN.
4. **Persister les modèles** — montez un volume persistant Clore.ai sur `/models` et définissez `HF_HOME=/models/hf` pour que les poids survivent aux redémarrages du conteneur.
5. **Traitement par lot pendant la nuit** — mettez en file d'attente de longues listes d'invites avec une simple boucle Python ; la facturation Clore.ai se fait à l'heure, donc saturer le GPU.
6. **SSH + tmux** — lancez la génération à l'intérieur de `tmux` pour qu'une connexion interrompue ne tue pas le processus.
7. **Sélectionnez le bon GPU** — filtrez le marketplace Clore.ai pour des cartes ≥24 Go de VRAM ; triez par prix pour trouver le RTX 3090 / 4090 le moins cher disponible.

## Dépannage

| Problème                                   | Corriger                                                                                                                 |
| ------------------------------------------ | ------------------------------------------------------------------------------------------------------------------------ |
| `OutOfMemoryError` pendant le décodage VAE | Appelez `pipe.vae.enable_tiling()` avant l'inférence                                                                     |
| NaN / images noires avec la 5B             | Passez à `torch.bfloat16`; fp16 n'est pas pris en charge pour la variante 5B                                             |
| `ImportError : imageio`                    | `pip install imageio[ffmpeg]` — le plugin ffmpeg est nécessaire pour l'export MP4                                        |
| Première exécution très lente              | Le téléchargement du modèle fait \~20 Go ; les exécutions suivantes utilisent les poids en cache                         |
| Incompatibilité de version CUDA            | Assurez-vous que la version CUDA de PyTorch correspond au pilote : `python -c "import torch; print(torch.version.cuda)"` |
| Mouvement brouillé / scintillement         | Augmentez `num_inference_steps` à 50 ; diminuer `guidance_scale` à 5.0                                                   |
| Conteneur tué en cours de téléchargement   | Définir `HF_HOME` sur un volume persistant et redémarrez — les téléchargements partiels reprennent automatiquement       |