# CogVideoX Diffusers ファインチューニングガイド

[中文阅读](./README_zh.md)

[Read in English](./README.md)

SATバージョンのファインチューニング手順については、[こちら](../sat/README_zh.md)をご確認ください。このバージョンのデータセットフォーマットは、こちらのバージョンとは異なります。

## ハードウェア要件

| モデル                      | トレーニングタイプ    | 分散戦略                          | 混合トレーニング精度 | トレーニング解像度（フレーム数×高さ×幅） | ハードウェア要件               |
|----------------------------|-------------------|----------------------------------|-----------------|-----------------------------|----------------------------|
| cogvideox-t2v-2b           | lora (rank128)    | DDP                              | fp16            | 49x480x720                  | 16GB VRAM (NVIDIA 4080)     |
| cogvideox-{t2v, i2v}-5b    | lora (rank128)    | DDP                              | bf16            | 49x480x720                  | 24GB VRAM (NVIDIA 4090)     |
| cogvideox1.5-{t2v, i2v}-5b | lora (rank128)    | DDP                              | bf16            | 81x768x1360                 | 35GB VRAM (NVIDIA A100)     |
| cogvideox-t2v-2b           | sft               | DDP                              | fp16            | 49x480x720                  | 36GB VRAM (NVIDIA A100)     |
| cogvideox-t2v-2b           | sft               | 1カード zero-2 + オプティマイゼーションオフロード  | fp16            | 49x480x720                  | 17GB VRAM (NVIDIA 4090)     |
| cogvideox-t2v-2b           | sft               | 8カード zero-2                   | fp16            | 49x480x720                  | 17GB VRAM (NVIDIA 4090)     |
| cogvideox-t2v-2b           | sft               | 8カード zero-3                   | fp16            | 49x480x720                  | 19GB VRAM (NVIDIA 4090)     |
| cogvideox-t2v-2b           | sft               | 8カード zero-3 + オプティマイゼーションとパラメータオフロード | bf16            | 49x480x720                  | 14GB VRAM (NVIDIA 4080)     |
| cogvideox-{t2v, i2v}-5b    | sft               | 1カード zero-2 + オプティマイゼーションオフロード  | bf16            | 49x480x720                  | 42GB VRAM (NVIDIA A100)     |
| cogvideox-{t2v, i2v}-5b    | sft               | 8カード zero-2                   | bf16            | 49x480x720                  | 42GB VRAM (NVIDIA 4090)     |
| cogvideox-{t2v, i2v}-5b    | sft               | 8カード zero-3                   | bf16            | 49x480x720                  | 43GB VRAM (NVIDIA 4090)     |
| cogvideox-{t2v, i2v}-5b    | sft               | 8カード zero-3 + オプティマイゼーションとパラメータオフロード | bf16            | 49x480x720                  | 28GB VRAM (NVIDIA 5090)     |
| cogvideox1.5-{t2v, i2v}-5b | sft               | 1カード zero-2 + オプティマイゼーションオフロード  | bf16            | 81x768x1360                 | 56GB VRAM (NVIDIA A100)     |
| cogvideox1.5-{t2v, i2v}-5b | sft               | 8カード zero-2                   | bf16            | 81x768x1360                 | 55GB VRAM (NVIDIA A100)     |
| cogvideox1.5-{t2v, i2v}-5b | sft               | 8カード zero-3                   | bf16            | 81x768x1360                 | 55GB VRAM (NVIDIA A100)     |
| cogvideox1.5-{t2v, i2v}-5b | sft               | 8カード zero-3 + オプティマイゼーションとパラメータオフロード | bf16            | 81x768x1360                 | 40GB VRAM (NVIDIA A100)     |



## 依存関係のインストール

関連するコードがまだ `diffusers` の公式リリースに統合されていないため、`diffusers` ブランチを基にファインチューニングを行う必要があります。以下の手順に従って依存関係をインストールしてください：

```shell
git clone https://github.com/huggingface/diffusers.git
cd diffusers # 現在は Main ブランチ
pip install -e .
```

## データセットの準備

まず、データセットを準備する必要があります。タスクの種類（T2V または I2V）によって、データセットのフォーマットが少し異なります：

```
.
├── prompts.txt
├── videos
├── videos.txt
├── images     # (オプション) I2Vの場合。提供されない場合、動画の最初のフレームが参照画像として使用されます
└── images.txt # (オプション) I2Vの場合。提供されない場合、動画の最初のフレームが参照画像として使用されます
```

各ファイルの役割は以下の通りです：
- `prompts.txt`: プロンプトを格納
- `videos/`: .mp4 動画ファイルを格納
- `videos.txt`: `videos/` フォルダ内の動画ファイルリストを格納
- `images/`: (オプション) .png 形式の参照画像ファイル
- `images.txt`: (オプション) 参照画像ファイルリスト

トレーニング中に検証データセットを使用する場合は、トレーニングデータセットと同じフォーマットで検証データセットを提供する必要があります。

## スクリプトを実行してファインチューニングを開始

トレーニングを開始する前に、以下の解像度設定要件に注意してください：

1. フレーム数は8の倍数 **+1** (つまり8N+1) でなければなりません。例：49, 81 ...
2. ビデオ解像度はモデルのデフォルトサイズを使用することをお勧めします：
   - CogVideoX: 480x720 (高さ×幅)
   - CogVideoX1.5: 768x1360 (高さ×幅)
3. トレーニング解像度に合わないサンプル（ビデオや画像）はコード内で自動的にリサイズされます。このため、サンプルのアスペクト比が変形し、トレーニング効果に影響を与える可能性があります。解像度に関しては、事前にサンプルを処理（例えば、アスペクト比を維持するためにクロップ＋リサイズを使用）してからトレーニングを行うことをお勧めします。

> **重要な注意**：トレーニング効率を高めるため、トレーニング前にビデオをエンコードし、その結果をディスクにキャッシュします。トレーニング後にデータを変更した場合は、`video`ディレクトリ内の`latent`ディレクトリを削除して、最新のデータを使用するようにしてください。

### LoRA

```bash
# train_ddp_t2v.sh の設定パラメータを変更
# 主に以下のパラメータを変更する必要があります:
# --output_dir: 出力ディレクトリ
# --data_root: データセットのルートディレクトリ
# --caption_column: テキストプロンプトのファイルパス
# --image_column: I2Vの場合、参照画像のファイルリストのパス（このパラメータを削除すると、デフォルトで動画の最初のフレームが画像条件として使用されます）
# --video_column: 動画ファイルのリストのパス
# --train_resolution: トレーニング解像度（フレーム数×高さ×幅）
# その他の重要なパラメータについては、起動スクリプトを参照してください

bash train_ddp_t2v.sh  # テキストから動画（T2V）微調整
bash train_ddp_i2v.sh  # 画像から動画（I2V）微調整
```

### SFT

`configs/`ディレクトリにはいくつかのZero構成テンプレートが提供されています。必要に応じて適切なトレーニング設定を選択してください（`accelerate_config.yaml`で`deepspeed_config_file`オプションを設定します）。

```bash
# 設定するパラメータはLoRAトレーニングと同様です

bash train_zero_t2v.sh  # テキストから動画（T2V）微調整
bash train_zero_i2v.sh  # 画像から動画（I2V）微調整
```

Bashスクリプトの関連パラメータを設定するだけでなく、Zeroの設定ファイルでトレーニングオプションを設定し、Zeroのトレーニング設定がBashスクリプト内のパラメータと一致していることを確認する必要があります。例えば、`batch_size`、`gradient_accumulation_steps`、`mixed_precision`など、具体的な詳細は[DeepSpeed公式ドキュメント](https://www.deepspeed.ai/docs/config-json/)を参照してください。

SFTトレーニングを使用する際に注意すべき点：

1. SFTトレーニングでは、検証時にモデルオフロードは使用されません。そのため、24GB以下のGPUでは検証時にVRAMのピークが24GBを超える可能性があります。24GB以下のGPUでは、検証を無効にすることをお勧めします。

2. Zero-3を有効にすると検証が遅くなるため、Zero-3では検証を無効にすることをお勧めします。

## ファインチューニングしたモデルの読み込み

+ ファインチューニングしたモデルを読み込む方法については、[cli_demo.py](../inference/cli_demo.py)を参照してください。

+ SFTトレーニングのモデルについては、まず`checkpoint-*`/ディレクトリ内の`zero_to_fp32.py`スクリプトを使用して、モデルの重みを統合してください。

## ベストプラクティス

+ 解像度が `200 x 480 x 720`（フレーム数 x 高さ x 幅）の70本のトレーニング動画を使用しました。データ前処理でフレームスキップを行い、49フレームおよび16フレームの2つの小さなデータセットを作成して実験速度を向上させました。CogVideoXチームの推奨最大フレーム数制限は49フレームです。これらの70本の動画は、10、25、50本の3つのグループに分け、概念的に類似した性質のものです。
+ 25本以上の動画を使用することで、新しい概念やスタイルのトレーニングが最適です。
+ `--id_token` で指定できる識別子トークンを使用すると、トレーニング効果がより良くなります。これはDreamboothトレーニングに似ていますが、このトークンを使用しない通常のファインチューニングでも問題なく動作します。
+ 元のリポジトリでは `lora_alpha` が1に設定されていますが、この値は多くの実行で効果が悪かったため、モデルのバックエンドやトレーニング設定の違いが影響している可能性があります。私たちの推奨は、`lora_alpha` を rank と同じか、`rank // 2` に設定することです。
+ rank は64以上に設定することをお勧めします。