# Генерация видео 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` на постоянный том и перезапустите — частичные загрузки возобновляются автоматически                      |


---

# Agent Instructions: Querying This Documentation

If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter:

```
GET https://docs.clore.ai/guides/guides_v2-ru/generaciya-video/cogvideox.md?ask=<question>
```

The question should be specific, self-contained, and written in natural language.
The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.