# CogVideoX Video-Generierung

CogVideoX ist eine Familie von Open-Weight-Video-Diffusions-Transformern von Zhipu AI (Tsinghua). Die Modelle erzeugen kohärente 6-Sekunden-Clips in 720×480-Auflösung und 8 fps entweder aus einer Textvorgabe (T2V) oder aus einem Referenzbild plus Vorgabe (I2V). Zwei Modellgrößen sind verfügbar — 2B für schnelle Iteration und 5B für höhere Qualität — beide mit nativer `diffusers` Integration durch `CogVideoXPipeline`.

CogVideoX auf einer gemieteten GPU von [Clore.ai](https://clore.ai/) ermöglicht es Ihnen, lokale Hardwarebeschränkungen zu umgehen und Videos in großem Maßstab für Cent-Beträge pro Clip zu generieren.

## Hauptmerkmale

* **Text-zu-Video (T2V)** — beschreiben Sie eine Szene und erhalten Sie einen 6-Sekunden-720×480-Clip bei 8 fps (49 Frames).
* **Bild-zu-Video (I2V)** — liefern Sie ein Referenzbild plus Prompt; das Modell animiert es mit zeitlicher Konsistenz.
* **Zwei Größen** — CogVideoX-2B (schnell, \~12 GB VRAM) und CogVideoX-5B (höhere Qualität, \~20 GB VRAM).
* **Native diffusers-Unterstützung** — erstklassige `CogVideoXPipeline` und `CogVideoXImageToVideoPipeline` Klassen.
* **3D-kausaler VAE** — komprimiert 49 Frames in einen kompakten latenten Raum für effizientes Denoising.
* **Offene Gewichte** — Apache-2.0-Lizenz für die 2B-Variante; Forschungslizenz für 5B.

## Anforderungen

| Komponente | Minimum          | Empfohlen        |
| ---------- | ---------------- | ---------------- |
| GPU-VRAM   | 16 GB (2B, fp16) | 24 GB (5B, bf16) |
| System-RAM | 32 GB            | 64 GB            |
| Festplatte | 30 GB            | 50 GB            |
| Python     | 3.10+            | 3.11             |
| CUDA       | 12.1+            | 12.4             |

**Clore.ai GPU-Empfehlung:** Ein **RTX 4090** (24 GB, \~$0.5–2/Tag) bewältigt sowohl die 2B- als auch die 5B-Varianten problemlos. Ein **RTX 3090** (24 GB, \~$0.3–1/Tag) funktioniert ebenso gut für 5B in bf16 und ist die Budget-Wahl.

## Schnellstart

```bash
# Umgebung erstellen
pip install torch torchvision --index-url https://download.pytorch.org/whl/cu124
pip install diffusers transformers accelerate sentencepiece imageio[ffmpeg]

# GPU überprüfen
python -c "import torch; print(torch.cuda.get_device_name(0))"
```

## Beispielanwendungen

### Text-zu-Video (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()      # spart ~4 GB Spitzen-VRAM
pipe.vae.enable_tiling()             # erforderlich für 720x480 auf 24-GB-Karten

prompt = (
    "Ein Golden Retriever, der bei Sonnenuntergang durch ein Sonnenblumenfeld läuft, "
    "kinematische Beleuchtung, Zeitlupe, 4K-Qualität"
)

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")
```

### Bild-zu-Video (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="Die Kamera umkreist langsam das Motiv, sanfter Wind",
    image=image,
    num_frames=49,
    guidance_scale=6.0,
    num_inference_steps=50,
).frames[0]

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

### Schnelle Generierung mit der 2B-Variante

```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="Zeitraffer eines blühenden Kirschblütenbaums",
    num_frames=49,
    guidance_scale=6.0,
    num_inference_steps=30,       # weniger Schritte → schneller
).frames[0]
```

## Tipps für Clore.ai-Nutzer

1. **VAE-Tiling aktivieren** — ohne `pipe.vae.enable_tiling()` wird der 3D-VAE beim Decodieren auf 24-GB-Karten OOM verursachen.
2. **Verwenden Sie `enable_model_cpu_offload()`** — verschiebt inaktive Module automatisch in den RAM; fügt \~10 % Laufzeit hinzu, spart aber 4+ GB Spitzen-VRAM.
3. **bf16 für 5B, fp16 für 2B** — der 5B-Checkpoint wurde in bf16 trainiert; die Verwendung von fp16 kann NaN-Ausgaben verursachen.
4. **Modelle persistent speichern** — mounten Sie ein Clore.ai Persistent Volume nach `/models` und setzen Sie `HF_HOME=/models/hf` damit Gewichte Container-Neustarts überstehen.
5. **Über Nacht im Batch** — legen Sie lange Prompt-Listen mit einer einfachen Python-Schleife in eine Warteschlange; Clore.ai berechnet stundenweise, also sollten Sie die GPU auslasten.
6. **SSH + tmux** — führen Sie die Generierung innerhalb von `tmux` aus, damit eine abgebrochene Verbindung den Prozess nicht tötet.
7. **Wählen Sie die richtige GPU** — filtern Sie den Clore.ai-Marktplatz nach Karten mit ≥24 GB VRAM; sortieren Sie nach Preis, um die günstigste verfügbare RTX 3090 / 4090 zu finden.

## Fehlerbehebung

| Problem                                        | Behebe                                                                                                                                 |
| ---------------------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------- |
| `OutOfMemoryError` während des VAE-Decodierens | Rufen Sie `pipe.vae.enable_tiling()` vor der Inferenz auf                                                                              |
| NaN / schwarze Frames mit 5B                   | Wechseln Sie zu `torch.bfloat16`; fp16 wird für die 5B-Variante nicht unterstützt                                                      |
| `ImportError: imageio`                         | `pip install imageio[ffmpeg]` — das ffmpeg-Plugin wird für den MP4-Export benötigt                                                     |
| Sehr langsamer erster Lauf                     | Der Modelldownload ist \~20 GB; nachfolgende Läufe verwenden die zwischengespeicherten Gewichte                                        |
| CUDA-Versionskonflikt                          | Stellen Sie sicher, dass die PyTorch-CUDA-Version mit dem Treiber übereinstimmt: `python -c "import torch; print(torch.version.cuda)"` |
| Verzerrte Bewegung / Flimmern                  | Erhöhen Sie `num_inference_steps` auf 50; niedrigere `guidance_scale` auf 5.0                                                          |
| Container wurde während des Downloads beendet  | Setze `HF_HOME` auf ein persistenten Volume setzen und neu starten — partielle Downloads werden automatisch fortgesetzt                |