# CogVideoX

CogVideoX, bir istemle daha tutarlı videolar oluşturulmasına odaklanan metinden videoya üretim modelidir. Bunu çeşitli yöntemler kullanarak başarır.

- videoları uzamsal ve zamansal olarak sıkıştıran, sıkıştırma oranını ve video doğruluğunu iyileştiren 3B varyasyonel oto-encoder

- metin ve videoyu hizalamaya yardımcı olmak için uzman bir transformer bloğu ve uzamsal ve zamansal olarak doğru videoları yakalamak ve oluşturmak için 3B tam dikkat modülü.

Video talimat boyutunun gerçek testi, CogVideoX'in tutarlı tema, dinamik bilgi, tutarlı arka plan, nesne bilgisi, akıcı hareket, renk, sahne, görünüm stili ve zamansal stil konularında iyi sonuçlar verdiğini, ancak insan eylemi, uzamsal ilişki ve birden fazla nesne konularında iyi sonuçlar elde edemediğini ortaya koymuştur.

Diffusers ile ince ayar yapmak, bu kötü sonuçları telafi etmeye yardımcı olabilir.

## Veri Hazırlama

Eğitim betikleri veriyi iki formatta kabul eder.

İlk format küçük ölçekli eğitim için uygundur, ikinci format ise büyük ölçekli eğitimde veri akışı için daha uygun olan CSV formatını kullanır. Gelecekte Diffusers, `<Video>` etiketini destekleyecektir.

### Küçük format

Bir dosyada satır satır ayrılmış istemler, diğer dosyada ise satır satır ayrılmış video verisi yolları içeren iki dosya (video dosyalarının yolları, `--instance_data_root` belirtirken geçirdiğiniz yola göre göreli olmalıdır). Bunu daha iyi anlamak için bir örneğe bakalım!

`--instance_data_root` parametresini `/dataset` olarak belirttiğinizi ve bu dizinin `prompts.txt` ile `videos.txt` dosyalarını içerdiğini varsayalım.

`prompts.txt` dosyası satır satır ayrılmış istekler içermelidir:

```
A black and white animated sequence featuring a rabbit, named Rabbity Ribfried, and an anthropomorphic goat in a musical, playful environment, showcasing their evolving interaction.
A black and white animated sequence on a ship's deck features a bulldog character, named Bully Bulldoger, showcasing exaggerated facial expressions and body language. The character progresses from confident to focused, then to strained and distressed, displaying a range of emotions as it navigates challenges. The ship's interior remains static in the background, with minimalistic details such as a bell and open door. The character's dynamic movements and changing expressions drive the narrative, with no camera movement to distract from its evolving reactions and physical gestures.
...
```

`videos.txt` dosyası, video dosyalarına giden satır satır yolları içermelidir. Yolun `--instance_data_root` dizinine _göreli_ olması gerektiğini unutmayın.

```
videos/00000.mp4
videos/00001.mp4
...
```

Genel olarak, veri seti kök dizininde `tree` komutunu çalıştırdığınızda veri setiniz aşağıdaki gibi görünür:

```
/dataset
├── prompts.txt
├── videos.txt
├── videos
    ├── videos/00000.mp4
    ├── videos/00001.mp4
    ├── ...
```

Bu formatı kullanırken `--caption_column` `prompts.txt` ve `--video_column` `videos.txt` olmalıdır.

### Akış biçimi

Tek bir CSV dosyası kullanabilirsiniz. Bu örneğin amacı için `metadata.csv` adında bir dosyanız olduğunu varsayalım. Beklenen biçim şudur:

```
<CAPTION_COLUMN>,<PATH_TO_VIDEO_COLUMN>
"""A black and white animated sequence featuring a rabbit, named Rabbity Ribfried, and an anthropomorphic goat in a musical, playful environment, showcasing their evolving interaction.""","""00000.mp4"""
"""A black and white animated sequence on a ship's deck features a bulldog character, named Bully Bulldoger, showcasing exaggerated facial expressions and body language. The character progresses from confident to focused, then to strained and distressed, displaying a range of emotions as it navigates challenges. The ship's interior remains static in the background, with minimalistic details such as a bell and open door. The character's dynamic movements and changing expressions drive the narrative, with no camera movement to distract from its evolving reactions and physical gestures.""","""00001.mp4"""
...
```

Bu durumda, `--instance_data_root` videoların saklandığı konum olmalı ve `--dataset_name` yerel bir klasöre giden bir yol veya Hub üzerinde barındırılan [load_dataset](https://huggingface.co/docs/datasets/main/en/package_reference/loading_methods#datasets.load_dataset) ile uyumlu bir veri seti olmalıdır. Minecraft oyun videolarınızın `https://huggingface.co/datasets/my-awesome-username/minecraft-videos` adresinde olduğunu varsayarsak, `my-awesome-username/minecraft-videos` değerini belirtmeniz gerekir.

Bu formatı kullanırken `--caption_column` `<CAPTION_COLUMN>` ve `--video_column` `<PATH_TO_VIDEO_COLUMN>` olmalıdır.

CSV formatına kesin olarak bağlı değilsiniz. `load_dataset` yöntemi, temel bir `<PATH_TO_VIDEO_COLUMN>` ve `<CAPTION_COLUMN>` yüklemek için dosya formatını desteklediği sürece herhangi bir format işe yarar. Video verilerini yüklemek için bu veri seti organizasyon jimnastiğinden geçme nedeni, `load_dataset`'in tüm video formatlarını tam olarak desteklememesidir.

> [!NOTE]
> CogVideoX, video üretimi için uzun ve açıklayıcı, LLM destekli istemlerle en iyi sonucu verir. Videolarınızı ön işlemeye tabi tutmanızı, önce bir VLM kullanarak özet üretip ardından istemleri bir LLM ile zenginleştirmenizi öneririz. Yukarıdaki altyazıları üretmek için [MiniCPM-V-26](https://huggingface.co/openbmb/MiniCPM-V-2_6) ve [Llama-3.1-8B-Instruct](https://huggingface.co/meta-llama/Meta-Llama-3.1-8B-Instruct) kullanıyoruz. Bunun için çok sade ve gereksiz detaylardan arındırılmış bir örnek [burada](https://gist.github.com/a-r-r-o-w/4dee20250e82f4e44690a02351324a4a) mevcuttur. İstemleri zenginleştirmek için resmi öneri [ChatGLM](https://huggingface.co/THUDM?search_models=chatglm)'dir ve 50-100 kelimelik uzunluk iyi kabul edilir.

>![NOTE] Veri setinizin zaten ön işlenmiş olması beklenir. Değilse, aşağıdaki parametrelerle oynayarak bazı temel ön işlemler yapılabilir: `--height`, `--width`, `--fps`, `--max_num_frames`, `--skip_frames_start` ve `--skip_frames_end`. Şu anda, eğitim parti boyutu > 1 olduğunda veri setinizdeki tüm videoların aynı sayıda video karesi içermesi gerekir.

## Eğitim

Geliştirme ortamınızı gerekli gereksinimleri kurarak yapılandırmanız gerekir. Aşağıdaki paketler gereklidir:
- Kullandığınız eğitim özelliklerine bağlı olarak Torch 2.0 veya üzeri (kuantize/deepspeed eğitimi için en son veya nightly sürümleri gerekebilir)
- Modelleme ve eğitimle ilgili her şey için `pip install diffusers transformers accelerate peft huggingface_hub`
- Video eğitim verilerini yüklemek için `pip install datasets decord`
- Bellek optimizasyonlu eğitim için 8-bit Adam veya AdamW optimizatörlerini kullanmak için `pip install bitsandbytes`
- eğitim günlüklerini izlemek için isteğe bağlı olarak `pip install wandb`
- `pip install deepspeed` isteğe bağlı olarak [DeepSpeed](https://github.com/microsoft/DeepSpeed) eğitimi için
- Eğitim için Prodigy optimizatörünü kullanmak isterseniz isteğe bağlı olarak `pip install prodigyopt`

Örnek betiklerinin en güncel sürümlerini başarıyla çalıştırabildiğinizden emin olmak için, örnek betiklerini sık sık güncellediğimiz ve bazı örnek özel gereksinimleri yüklediğimiz için **kaynaktan kurulum** yapmanızı ve kurulumu güncel tutmanızı şiddetle öneririz. Bunu yapmak için yeni bir sanal ortamda aşağıdaki adımları uygulayın:

Betik çalıştırmadan önce, kütüphanenin kaynak kodundan yüklendiğinden emin olun:
```bash
git clone https://github.com/huggingface/diffusers
cd diffusers
pip install -e .
```

 

Ardından, eğitim betiğini içeren örnek klasörüne gidin ve kullandığınız betik için gerekli bağımlılıkları yükleyin:

- PyTorch

```bash
cd examples/cogvideo
pip install -r requirements.txt
```

Ve bir [🤗 Accelerate](https://github.com/huggingface/accelerate/) ortamını şu şekilde başlatın:

```bash
accelerate config
```

Ya da ortamınızla ilgili soruları yanıtlamadan varsayılan bir accelerate yapılandırması için

```bash
accelerate config default
```

Ya da ortamınız etkileşimli bir kabuğu desteklemiyorsa (örneğin, bir defter)

```python
from accelerate.utils import write_basic_config
write_basic_config()
```

`accelerate config` çalıştırıldığında, torch.compile kullanılıyorsa dramatik hızlanmalar görülebilir. PEFT kütüphanesi LoRA eğitimi için bir arka uç olarak kullanıldığından, ortamınızda `peft>=0.6.0` yüklü olduğundan emin olun.

Eğitim tamamlandıktan sonra modelinizi düzenli bir model kartıyla Hub'a göndermek istiyorsanız, oturum açtığınızdan emin olun:

```bash
hf auth login

# Alternatively, you could upload your model manually using:
# hf upload my-cool-account-name/my-cool-lora-name /path/to/awesome/lora
```

Verilerinizin [Veri Hazırlama](#data-preparation) bölümünde belirtildiği gibi hazır olduğundan emin olun. Hazır olduğunuzda eğitime başlayabilirsiniz!

Benzer bir kavramın 50 videosu üzerinde eğitim yaptığınızı varsayarsak, 1500-2000 adımın iyi çalıştığını tespit ettik. Ancak resmi öneri, toplam 4000 adım ile 100 videodur. Tek bir GPU üzerinde `--train_batch_size` değeri `1` olacak şekilde eğitim yaptığınızı varsayarsak:
- 50 videoda 1500 adım, `30` eğitim epokuna karşılık gelir
- 100 videoda 4000 adım, `40` eğitim epokuna karşılık gelir

```bash
#!/bin/bash

GPU_IDS="0"

accelerate launch --gpu_ids $GPU_IDS examples/cogvideo/train_cogvideox_lora.py \
  --pretrained_model_name_or_path THUDM/CogVideoX-2b \
  --cache_dir <CACHE_DIR> \
  --instance_data_root <PATH_TO_WHERE_VIDEO_FILES_ARE_STORED> \
  --dataset_name my-awesome-name/my-awesome-dataset \
  --caption_column <CAPTION_COLUMN> \
  --video_column <PATH_TO_VIDEO_COLUMN> \
  --id_token <ID_TOKEN> \
  --validation_prompt "<ID_TOKEN> Spiderman swinging over buildings:::A panda, dressed in a small, red jacket and a tiny hat, sits on a wooden stool in a serene bamboo forest. The panda's fluffy paws strum a miniature acoustic guitar, producing soft, melodic tunes. Nearby, a few other pandas gather, watching curiously and some clapping in rhythm. Sunlight filters through the tall bamboo, casting a gentle glow on the scene. The panda's face is expressive, showing concentration and joy as it plays. The background includes a small, flowing stream and vibrant green foliage, enhancing the peaceful and magical atmosphere of this unique musical performance" \
  --validation_prompt_separator ::: \
  --num_validation_videos 1 \
  --validation_epochs 10 \
  --seed 42 \
  --rank 64 \
  --lora_alpha 64 \
  --mixed_precision fp16 \
  --output_dir /raid/aryan/cogvideox-lora \
  --height 480 --width 720 --fps 8 --max_num_frames 49 --skip_frames_start 0 --skip_frames_end 0 \
  --train_batch_size 1 \
  --num_train_epochs 30 \
  --checkpointing_steps 1000 \
  --gradient_accumulation_steps 1 \
  --learning_rate 1e-3 \
  --lr_scheduler cosine_with_restarts \
  --lr_warmup_steps 200 \
  --lr_num_cycles 1 \
  --enable_slicing \
  --enable_tiling \
  --optimizer Adam \
  --adam_beta1 0.9 \
  --adam_beta2 0.95 \
  --max_grad_norm 1.0 \
  --report_to wandb
```

Eğitim deneylerimizi daha iyi izleyebilmek için yukarıdaki komutta aşağıdaki bayrakları kullanıyoruz:
* `--report_to wandb`, eğitim çalıştırmalarının Weights and Biases üzerinde izlenmesini sağlar. Bunu kullanmak için `wandb` paketini `pip install wandb` komutuyla kurduğunuzdan emin olun.
* `validation_prompt` ve `validation_epochs` parametrelerini ekleyerek betiğin birkaç doğrulama çıkarım çalışması yapmasını sağlayın. Bu sayede eğitimin beklenen şekilde ilerleyip ilerlemediğini nitel olarak kontrol edebiliriz.

`<ID_TOKEN>` ayarlamak zorunlu değildir. Sınırlı deneyimlerimizde, [Dreambooth](https://huggingface.co/docs/diffusers/en/training/dreambooth) eğitimine benzediği için, bu belirtecin kullanılmadığı duruma kıyasla kullanıldığında daha iyi sonuç verdiğini gözlemledik. Sağlandığında, `<ID_TOKEN>` her istemin başına eklenir. Dolayısıyla, `<ID_TOKEN>` değeriniz `"DISNEY"` ve isteminiz `"Spiderman swinging over buildings"` ise, eğitimde kullanılan etkili istem `"DISNEY Spiderman swinging over buildings"` olur. Sağlanmadığında, ek bir belirteç olmadan eğitim yapabilir veya eğitime başlamadan önce belirteci istediğiniz yere uygulamak için veri setinizi genişletebilirsiniz.

> [!NOTE]
> Eğitimin bellek gereksinimlerini azaltmak için `--use_8bit_adam` parametresini iletebilirsiniz.

> [!IMPORTANT]
> CogVideoX LoRA eğitim desteği eklendiğinde aşağıdaki ayarlar test edilmiştir: - Testlerimiz ağırlıklı olarak CogVideoX-2b üzerinde yapıldı. Yakında CogVideoX-5b ve CogVideoX-5b-I2V üzerinde de çalışacağız - Bir veri seti, `200 x 480 x 720` (F x H x W) çözünürlüğünde 70 eğitim videosundan oluşuyordu. Bundan, veri ön işlemede kare atlama kullanarak, daha hızlı deneyler için ve CogVideoX ekibinin önerdiği maksimum sınırın 49 kare olması nedeniyle, 49 karelik ve 16 karelik iki daha küçük veri seti oluşturduk. 70 videodan, 10, 25 ve 50 videodan oluşan üç grup oluşturduk. Tüm videolar, eğitilen kavramın doğası açısından benzerdi. - Yeni kavramlar ve stiller için eğitimde 25+ video en iyi sonucu verdi. - `--id_token` olarak belirtilebilen bir tanımlayıcı jetonu ile eğitmenin daha iyi olduğunu tespit ettik. Bu, Dreambooth benzeri eğitime benzer, ancak bu tür bir jeton olmadan normal ince ayar da işe yarar. - Eğitilen kavram, tamamen ilgisiz istemlerle birleştirildiğinde makul derecede iyi çalıştı. CogVideoX-5B ince ayarından daha iyi sonuçlar bekliyoruz. - Orijinal depo `lora_alpha` değerini `1` olarak kullanıyor. Birçok çalışmada bunun uygun olmadığını, muhtemelen modelleme arka uçlarındaki ve eğitim ayarlarındaki farklılıklardan kaynaklandığını tespit ettik. Önerimiz, `lora_alpha` değerini `rank` veya `rank // 2` olarak ayarlamaktır. - Orijinal modelde kötü sonuçlar üreten açıklamalara sahip veriler üzerinde eğitim yapıyorsanız, 64 ve üzeri bir `rank` değerinin iyi olduğunu ve CogVideoX arkasındaki ekibin de bunu önerdiğini belirtmek isteriz. Üretimler eğitim açıklamalarınızda zaten orta düzeyde iyiyse, 16/32 `rank` değeri işe yarayacaktır. Rank değerinin çok düşük ayarlanmasının, örneğin `4`, ideal olmadığını ve umut verici sonuçlar üretmediğini tespit ettik. - CogVideoX yazarları, en iyi sonucu elde etmek için 4000 eğitim adımı ve genel olarak 100 eğitim videosu önermektedir. Bu, en iyi sonuçları verebilirken, sınırlı deneyimlerimizden 2000 adım ve 25 videonun da yeterli olabileceğini tespit ettik. - Eğitim için Prodigy optimizatörü kullanıldığında, [bu](https://huggingface.co/blog/sdxl_lora_advanced_script) blogdaki önerilere uyulabilir. Prodigy hızla aşırı uyarlanır. Çok sınırlı testlerimden, `--prodigy_use_bias_correction`, `prodigy_safeguard_warmup` ve `--prodigy_decouple` ile birlikte `0.5` öğrenme hızının uygun olduğunu buldum. - CogVideoX yazarlarının önerdiği ve Adam/AdamW ile deneyimlerimizden elde edilen önerilen öğrenme hızı, 25+ videodan oluşan bir veri seti için `1e-3` ile `1e-4` arasındadır.
>
> Keşif için sınırlı zaman nedeniyle testlerimizin kapsamlı olmadığını belirtmek isteriz. Verileriniz için en iyi ayarları bulmak amacıyla farklı ayarları denemenizi öneririz.

## Çıkarım

Bir lora modeli eğittikten sonra, çıkarım işlemi, lora ağırlıklarını `CogVideoXPipeline` içine yükleyerek basitçe yapılabilir.

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

pipe = CogVideoXPipeline.from_pretrained("THUDM/CogVideoX-2b", dtype=torch.float16)
# pipe.load_lora_weights("/path/to/lora/weights", adapter_name="cogvideox-lora") # Or,
pipe.load_lora_weights("my-awesome-hf-username/my-awesome-lora-name", adapter_name="cogvideox-lora") # If loading from the HF Hub
pipe.to("cuda")  # or "mps", "xpu", "cpu"

# Assuming lora_alpha=32 and rank=64 for training. If different, set accordingly
pipe.set_adapters(["cogvideox-lora"], [32 / 64])

prompt = "A vast, shimmering ocean flows gracefully under a twilight sky, its waves undulating in a mesmerizing dance of blues and greens. The surface glints with the last rays of the setting sun, casting golden highlights that ripple across the water. Seagulls soar above, their cries blending with the gentle roar of the waves. The horizon stretches infinitely, where the ocean meets the sky in a seamless blend of hues. Close-ups reveal the intricate patterns of the waves, capturing the fluidity and dynamic beauty of the sea in motion."
frames = pipe(prompt, guidance_scale=6, use_dynamic_cfg=True).frames[0]
export_to_video(frames, "output.mp4", fps=8)
```

## Bellek kullanımını azaltın

diffusers kütüphanesini kullanarak testler yapılırken, diffusers kütüphanesindeki tüm optimizasyonlar etkinleştirildi. Bu şema, **NVIDIA A100 / H100** mimarileri dışındaki cihazlarda gerçek bellek kullanımı açısından test edilmemiştir. Genel olarak bu şema, **NVIDIA Ampere mimarisi** ve üzerindeki tüm cihazlara uyarlanabilir. Optimizasyonlar devre dışı bırakılırsa bellek tüketimi katlanarak artar ve tepe bellek kullanımı, tablodaki değerin yaklaşık 3 katı olur. Ancak hız yaklaşık 3-4 kat artar. Aşağıdakiler dahil olmak üzere bazı optimizasyonları seçici olarak devre dışı bırakabilirsiniz:

```
pipe.enable_sequential_cpu_offload()
pipe.vae.enable_slicing()
pipe.vae.enable_tiling()
```

+ Çoklu GPU çıkarımı için `enable_sequential_cpu_offload()` optimizasyonunun devre dışı bırakılması gerekir.
+ INT8 modelleri kullanmak, düşük bellekli GPU'ları desteklemek ve video kalitesinde minimal kayıpla çalışmak amacıyla yapılır; ancak bu durum, çıkarım hızının önemli ölçüde düşmesine neden olur.
+ CogVideoX-2B modeli `FP16` hassasiyetinde eğitildi ve tüm CogVideoX-5B modelleri `BF16` hassasiyetinde eğitildi. Çıkarım için modelin eğitildiği hassasiyetin kullanılmasını öneririz.
+ [PytorchAO](https://github.com/pytorch/ao) ve [Optimum-quanto](https://github.com/huggingface/optimum-quanto/), CogVideoX'in bellek gereksinimlerini azaltmak için metin kodlayıcı, dönüştürücü ve VAE modüllerini nicelleştirmek (quantize) için kullanılabilir. Bu, modelin ücretsiz T4 Colab'larında veya daha küçük belleğe sahip GPU'larda çalışmasına olanak tanır! Ayrıca, TorchAO nicelleştirmesinin `torch.compile` ile tam uyumlu olduğunu ve bunun çıkarım (inference) hızını önemli ölçüde artırabileceğini unutmayın. FP8 hassasiyeti, NVIDIA H100 ve üzeri cihazlarda kullanılmalıdır; bu, `torch`, `torchao`, `diffusers` ve `accelerate` Python paketlerinin kaynak kodundan kurulmasını gerektirir. CUDA 12.4 önerilir.
+ Çıkarım hızı testleri de yukarıdaki bellek optimizasyonu şemasını kullandı. Bellek optimizasyonu olmadan çıkarım hızı yaklaşık %10 artar. Sadece `diffusers` sürümü modelin kuantizasyonunu destekler.
+ Model yalnızca İngilizce girdiyi destekler; diğer diller, büyük model iyileştirmesi yoluyla kullanılmak üzere İngilizceye çevrilebilir.
+ Model ince ayarının bellek kullanımı `8 * H100` ortamında test edilir ve program `Zero 2` optimizasyonunu otomatik olarak kullanır. Tabloda belirli bir GPU sayısı belirtilmişse, ince ayar için bu sayı veya daha fazla GPU kullanılmalıdır.

 | **Öznitelik**                        | **CogVideoX-2B**                                                       | **CogVideoX-5B**                                                       |
| ------------------------------------ | ---------------------------------------------------------------------- | ---------------------------------------------------------------------- |
| **Model Adı**                       | CogVideoX-2B                                                           | CogVideoX-5B                                                           |
| **Çıkarım Hassasiyeti**              | FP16* (Önerilen), BF16, FP32, FP8*, INT8, Desteklenmiyor INT4         | BF16 (Önerilen), FP16, FP32, FP8*, INT8, INT4 desteklenmiyor         |
| **Tek GPU Çıkarım VRAM**        | FP16: diffusers kullanılarak 12.5GB* INT8: torchao ile diffusers kullanılarak 7.8GB* | BF16: diffusers kullanılarak 20.7GB* INT8: torchao ile diffusers kullanılarak 11.4GB* |
| **Çoklu GPU Çıkarım VRAM**         | FP16: diffusers kullanılarak 10GB*                                             | BF16: diffusers kullanılarak 15GB*                                             |
| **Çıkarım Hızı**                  | Tek A100: ~90 saniye, Tek H100: ~45 saniye                      | Tek A100: ~180 saniye, Tek H100: ~90 saniye                     |
| **Hassas Ayar Hassasiyeti**            | FP16                                                                   | BF16                                                                   |
| **İnce Ayar VRAM Tüketimi**     | 47 GB (bs=1, LORA) 61 GB (bs=2, LORA) 62 GB (bs=1, SFT)                 | 63 GB (bs=1, LORA) 80 GB (bs=2, LORA) 75 GB (bs=1, SFT)                 |