# Generación de video CogVideoX

CogVideoX es una familia de transformadores de difusión de video con pesos abiertos de Zhipu AI (Tsinghua). Los modelos generan clips coherentes de 6 segundos a resolución 720×480 y 8 fps a partir de un prompt de texto (T2V) o de una imagen de referencia más prompt (I2V). Hay dos escalas de parámetros disponibles: 2B para iteración rápida y 5B para mayor fidelidad, ambas con `diffusers` integración a través de `CogVideoXPipeline`.

Ejecutar CogVideoX en una GPU alquilada desde [Clore.ai](https://clore.ai/) te permite omitir las limitaciones de hardware local y generar video a escala por centavos por clip.

## Características clave

* **Texto a Video (T2V)** — describe una escena y obtén un clip de 6 segundos 720×480 a 8 fps (49 fotogramas).
* **Imagen a Video (I2V)** — proporciona una imagen de referencia más un prompt; el modelo la anima con coherencia temporal.
* **Dos escalas** — CogVideoX-2B (rápido, \~12 GB VRAM) y CogVideoX-5B (mayor calidad, \~20 GB VRAM).
* **Soporte nativo de diffusers** — clases de `CogVideoXPipeline` y `CogVideoXImageToVideoPipeline` de primera clase.
* **VAE causal 3D** — comprime 49 fotogramas en un espacio latente compacto para un denoising eficiente.
* **Pesos abiertos** — licencia Apache-2.0 para la variante 2B; licencia de investigación para 5B.

## Requisitos

| Componente      | Mínimo           | Recomendado      |
| --------------- | ---------------- | ---------------- |
| VRAM de GPU     | 16 GB (2B, fp16) | 24 GB (5B, bf16) |
| RAM del sistema | 32 GB            | 64 GB            |
| Disco           | 30 GB            | 50 GB            |
| Python          | 3.10+            | 3.11             |
| CUDA            | 12.1+            | 12.4             |

**Recomendación de GPU de Clore.ai:** Un **RTX 4090** (24 GB, \~$0.5–2/día) maneja cómodamente tanto las variantes 2B como 5B. Un **RTX 3090** (24 GB, \~$0.3–1/día) funciona igual de bien para 5B en bf16 y es la opción económica.

## Inicio rápido

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

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

## Ejemplos de uso

### Texto a 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()      # ahorra ~4 GB de VRAM pico
pipe.vae.enable_tiling()             # requerido para 720x480 en tarjetas de 24 GB

prompt = (
    "Un golden retriever corriendo por un campo de girasoles al atardecer, "
    "iluminación cinematográfica, cámara lenta, calidad 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")
```

### Imagen a 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="La cámara orbita lentamente alrededor del sujeto, viento suave",
    image=image,
    num_frames=49,
    guidance_scale=6.0,
    num_inference_steps=50,
).frames[0]

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

### Generación rápida con 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="Timelapse de un cerezo en flor",
    num_frames=49,
    guidance_scale=6.0,
    num_inference_steps=30,       # menos pasos → más rápido
).frames[0]
```

## Consejos para usuarios de Clore.ai

1. **Habilitar tiling del VAE** — sin `pipe.vae.enable_tiling()` el VAE 3D causará OOM en tarjetas de 24 GB durante la decodificación.
2. **Usa `enable_model_cpu_offload()`** — mueve módulos inactivos a la RAM automáticamente; añade \~10 % de tiempo de ejecución pero ahorra más de 4 GB de VRAM pico.
3. **bf16 para 5B, fp16 para 2B** — el checkpoint 5B fue entrenado en bf16; usar fp16 puede causar salidas NaN.
4. **Persistir modelos** — monta un volumen persistente de Clore.ai en `/models` y configura `HF_HOME=/models/hf` para que los pesos sobrevivan a los reinicios del contenedor.
5. **Procesar por lotes durante la noche** — encola listas largas de prompts con un simple bucle en Python; la facturación de Clore.ai es por hora, así que satura la GPU.
6. **SSH + tmux** — ejecuta la generación dentro de `tmux` para que una conexión caída no termine el proceso.
7. **Selecciona la GPU correcta** — filtra el marketplace de Clore.ai por tarjetas con ≥24 GB de VRAM; ordena por precio para encontrar la RTX 3090 / 4090 más barata disponible.

## Solución de problemas

| Problema                                             | Solucionar                                                                                                                |
| ---------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------- |
| `OutOfMemoryError` durante la decodificación del VAE | Llama a `pipe.vae.enable_tiling()` antes de la inferencia                                                                 |
| NaN / fotogramas negros con 5B                       | Cambia a `torch.bfloat16`; fp16 no está soportado para la variante 5B                                                     |
| `ImportError: imageio`                               | `pip install imageio[ffmpeg]` — el plugin ffmpeg es necesario para la exportación a MP4                                   |
| Primera ejecución muy lenta                          | La descarga del modelo es \~20 GB; las ejecuciones posteriores usan los pesos en caché                                    |
| Incompatibilidad de versión de CUDA                  | Asegúrate de que la versión CUDA de PyTorch coincida con el driver: `python -c "import torch; print(torch.version.cuda)"` |
| Movimiento garabateado / parpadeo                    | Aumente `num_inference_steps` a 50; valores más bajos `guidance_scale` a 5.0                                              |
| Contenedor terminado a mitad de descarga             | Establecer `HF_HOME` a un volumen persistente y reinicia — las descargas parciales se reanudan automáticamente            |