# Генерация видео CogVideoX

CogVideoX — это семейство видеодиффузионных трансформеров с открытыми весами от Zhipu AI (Цинхуа). Модели генерируют связные 6-секундные клипы с разрешением 720×480 и частотой 8 fps из текстового подсказа (T2V) или из эталонного изображения и подсказа (I2V). Доступны два масштаба параметров — 2B для быстрой итерации и 5B для более высокого качества — оба с нативной `поддержкой diffusers` интеграции через `CogVideoXPipeline`.

Запуск CogVideoX на арендованной GPU от [Clore.ai](https://clore.ai/) позволяет вам обойти локальные аппаратные ограничения и генерировать видео в масштабе за копейки за клип.

## Ключевые особенности

* **Текст в видео (T2V)** — опишите сцену и получите 6‑секундный клип 720×480 при 8 fps (49 кадров).
* **Изображение в видео (I2V)** — предоставьте эталонное изображение и подсказ — модель анимирует его с временной согласованностью.
* **Два масштаба** — CogVideoX-2B (быстрый, \~12 ГБ VRAM) и CogVideoX-5B (более высокое качество, \~20 ГБ VRAM).
* **Нативная поддержка diffusers** — первоклассная `CogVideoXPipeline` и `CogVideoXImageToVideoPipeline` классы.
* **3D каузальный VAE** — сжимает 49 кадров в компактное латентное пространство для эффективного денойзинга.
* **Открытые веса** — лицензия Apache-2.0 для варианта 2B; исследовательская лицензия для 5B.

## Требования

| Компонент   | Минимум          | Рекомендуется    |
| ----------- | ---------------- | ---------------- |
| VRAM GPU    | 16 ГБ (2B, fp16) | 24 ГБ (5B, bf16) |
| ОЗУ системы | 32 ГБ            | 64 ГБ            |
| Диск        | 30 GB            | 50 ГБ            |
| Python      | 3.10+            | 3.11             |
| CUDA        | 12.1+            | 12.4             |

**Рекомендация Clore.ai по GPU:** Один **RTX 4090** (24 ГБ, \~$0.5–2/день) с лёгкостью справляется как с вариантом 2B, так и с 5B. Один **RTX 3090** (24 ГБ, \~$0.3–1/день) одинаково хорошо подходит для 5B в bf16 и является бюджетным вариантом.

## Быстрый старт

```bash
# Создайте окружение
pip install torch torchvision --index-url https://download.pytorch.org/whl/cu124
pip install diffusers transformers accelerate sentencepiece imageio[ffmpeg]

# Проверить GPU
python -c "import torch; print(torch.cuda.get_device_name(0))"
```

## Примеры использования

### Текст в видео (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()      # сохраняет ~4 ГБ пикового VRAM
pipe.vae.enable_tiling()             # требуется для 720x480 на 24 ГБ картах

prompt = (
    "Золотистый ретривер, бегущий по полю с подсолнухами на закате, "
    "кинематографическое освещение, замедленная съёмка, качество 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("Сохранён retriever_sunset.mp4")
```

### Изображение в видео (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="Камера медленно обходит объект, лёгкий ветер",
    image=image,
    num_frames=49,
    guidance_scale=6.0,
    num_inference_steps=50,
).frames[0]

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

### Быстрая генерация с вариантом 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="Таймлапс цветущей сакуры",
    num_frames=49,
    guidance_scale=6.0,
    num_inference_steps=30,       # меньше шагов → быстрее
).frames[0]
```

## Советы для пользователей Clore.ai

1. **Включите плитинг VAE** — без `pipe.vae.enable_tiling()` трёхмерный VAE приведёт к OOM на 24 ГБ картах при декодировании.
2. **Используйте `enable_model_cpu_offload()`** — автоматически переносит неактивные модули в ОЗУ; добавляет \~10 % к общему времени, но экономит 4+ ГБ пикового VRAM.
3. **bf16 для 5B, fp16 для 2B** — контрольная точка 5B была обучена в bf16; использование fp16 может привести к выходам NaN.
4. **Сохранение моделей** — примонтируйте постоянный том Clore.ai к `/models` и установите `HF_HOME=/models/hf` чтобы веса сохранялись при перезапусках контейнера.
5. **Пакетная обработка на ночь** — ставьте в очередь длинные списки подсказов простым Python‑циклом; тарификация Clore.ai почасовая, поэтому полностью загружайте GPU.
6. **SSH + tmux** — запускайте генерацию внутри `tmux` чтобы разорванное соединение не убило процесс.
7. **Выберите подходящую GPU** — фильтруйте маркетплейс Clore.ai по картам с ≥24 ГБ VRAM; сортируйте по цене, чтобы найти самое дешёвое доступное RTX 3090 / 4090.

## Устранение неполадок

| Проблема                                      | Исправить                                                                                                                     |
| --------------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------- |
| `OutOfMemoryError` во время декодирования VAE | Вызовите `pipe.vae.enable_tiling()` перед инференсом                                                                          |
| NaN / чёрные кадры с 5B                       | Переключитесь на `torch.bfloat16`; fp16 не поддерживается для варианта 5B                                                     |
| `ImportError: imageio`                        | `pip install imageio[ffmpeg]` — нужен плагин ffmpeg для экспорта в MP4                                                        |
| Очень медрый первый запуск                    | Скачивание модели ≈20 ГБ; последующие запуски используют кэшированные веса                                                    |
| Несоответствие версии CUDA                    | Убедитесь, что версия PyTorch с поддержкой CUDA соответствует драйверу: `python -c "import torch; print(torch.version.cuda)"` |
| Искажённое движение / мерцание                | Увеличьте `num_inference_steps` до 50; меньшие `guidance_scale` до 5.0                                                        |
| Контейнер убит во время загрузки              | Установите `HF_HOME` на постоянный том и перезапустите — частичные загрузки возобновляются автоматически                      |