LTX Video 2 クイックスタート¶

この例では、LTX-2 の Video/Audio VAE と、選択した LTX-2 バージョンに対応する Gemma テキストエンコーダを使って LTX Video 2 LoRA をトレーニングします。

ハードウェア要件¶

LTX Video 2 は重量級の 19B モデルです。以下を組み合わせます: 1. Gemma3 / Gemma4: テキストエンコーダ。LTX-2.0 と LTX-2.3 は Gemma3、LTX-2.5 は Gemma4 を使います。 2. LTX-2 Video VAE（音声条件付きの場合は Audio VAE も使用）。 3. 19B Video Transformer: 大規模な DiT バックボーン。

この構成は VRAM を大量に消費し、VAE の事前キャッシュでメモリ使用量が跳ね上がることがあります。

• 注意: 初期の VAE 事前キャッシュでより多くの VRAM が必要になる場合があります。キャッシュ時だけ CPU オフロードやより大きな GPU が必要になる可能性があります。
• ヒント: config.json に "offload_during_startup": true を設定し、VAE とテキストエンコーダが同時に GPU に載らないようにすると、事前キャッシュ時のメモリ圧力を大きく下げられます。
• システム RAM: 大きめの実行では 64GB+ を推奨します。RAM が多いほどキャッシュが安定します。

実測パフォーマンスとメモリ（現場報告）¶

• ベース設定: 480p / 17 フレーム / バッチサイズ 2（最小構成）。
• RamTorch（テキストエンコーダ含む）: AMD 7900XTX で VRAM 約 13GB。
• NVIDIA 3090/4090/5090+ は同等以上の余裕が見込めます。
• オフロードなし（int8 TorchAO）: VRAM 約 29-30GB、32GB 機材推奨。
• Gemma テキストエンコーダ bf16 を読み込み→int8 量子化（VRAM 約 32GB）でシステム RAM ピーク約 46GB。
• LTX-2 transformer bf16 を読み込み→int8 量子化（VRAM 約 30GB）でシステム RAM ピーク約 34GB。
• オフロードなし（bf16 フル）: オフロード無しで学習する場合、VRAM 約 48GB 必要。
• スループット:
• A100-80G SXM4 で ~8 秒/step（コンパイルなし）。
• 7900XTX で ~16 秒/step（ローカル実行）。
• A100-80G SXM4 で 200 steps あたり ~30 分。

⚠️ Regional compilation は有効のままにする前にテストしてください。 dynamo_use_regional_compilation は LTX Video 2 で常に高速化するとは限らず、コンパイルのウォームアップ後でも定常スループットを低下させる場合があります。同じ固定バッチ、フレーム数、解像度で eager 実行と compiled 実行を比較し、最初のコンパイル step ではなくウォームアップ後の複数の training step で判断してください。

前提条件¶

Python 3.12 がインストールされていることを確認してください。

python --version

インストール¶

pip install 'simpletuner[cuda]'

# CUDA 13 / Blackwell users (NVIDIA B-series GPUs)
pip install 'simpletuner[cuda13]' --extra-index-url https://download.pytorch.org/whl/cu130

詳細は INSTALL.md を参照してください。

環境のセットアップ¶

Web インターフェース¶

simpletuner server

http://localhost:8001 でアクセスできます。

手動設定¶

ヘルパースクリプトを実行:

simpletuner configure

またはサンプルをコピーして手動編集:

cp config/config.json.example config/config.json

設定パラメータ¶

LTX Video 2 の主要設定:

• model_family: ltxvideo2
• model_flavour: dev (デフォルト)、dev-fp4、dev-fp8、2.3-dev、2.3-distilled、2.5-dev、2.5-distilled。
• pretrained_model_name_or_path: Lightricks/LTX-2、dg845/LTX-2.3-Diffusers、dg845/LTX-2.3-Distilled-Diffusers、Lightricks/LTX-2.5、またはローカル .safetensors ファイル。
• train_batch_size: 1。A100/H100 以外では増やさないでください。
• validation_resolution:
• 512x768 がテスト向けの安全なデフォルト。
• 720x1280 (720p) は可能ですが重いです。
• validation_num_video_frames: VAE の圧縮 (4x) に一致する必要があります。
• 5 秒 (約 12-24fps) の場合は 61 か 49。
• 公式: (frames - 1) % 4 == 0。
• validation_guidance: 5.0。
• ltx2_validation_audio_guidance: validation 用の任意の個別 audio CFG scale。未設定の場合は audio にも validation_guidance を使います。LTX-2.5 AV validation では、ComfyUI の dual-CFG node の既定値は video CFG 3.0、audio CFG 7.0 です。
• ltx2_validation_pipeline_mode: 通常の validation では trained-stage のままにします。spatial-upscale にすると、半解像度 latent 生成、spatial latent upscaling、フル解像度 re-denoising の LTX-2 2 段 spatial upscaler path を使います。
• spatial-upscale では validation_resolution が 64 で割り切れる必要があります。
• 任意の上書き: ltx2_validation_spatial_upsampler_model と ltx2_validation_spatial_upsampler_filename。既定値は Lightricks/LTX-2.3 と ltx-2.3-spatial-upscaler-x2-1.1.safetensors です。
• frame_rate: デフォルトは 25。

LTX-2 2.0 系は transformer / video VAE / audio VAE / vocoder を含む .safetensors 単体チェックポイントで配布されます。 LTX-2.3 では、SimpleTuner は model_flavour に応じた Diffusers リポジトリ (2.3-dev または 2.3-distilled) を読み込みます。 LTX-2.5 では、SimpleTuner は Diffusers repo path を Lightricks/LTX-2.5 とみなし、テキストエンコーダは Gemma4 にルーティングします。ローカル single-file LTX-2.5 checkpoint を読み込む場合は、model_flavour を 2.5-dev または 2.5-distilled にしてください。ローカル path で上書きしない限り、SimpleTuner は Lightricks/LTX-2.5 を component/config source として使います。

LTX-2 AV validation の dual CFG は通常の conditional / unconditional predictions を使い、video latent stream と audio latent stream に別々の scale を適用します。これ自体は追加の model pass を増やしません。STG、modality guidance、reference-audio identity guidance などの追加 guidance は、有効化した場合にそれぞれ追加 pass を使います。

任意: VRAM 最適化¶

VRAM 余裕が必要なら: - Musubi ブロックスワップ: musubi_blocks_to_swap（4-8 を試す）と必要なら musubi_block_swap_device（既定 cpu）で、最後の Transformer ブロックを CPU からストリーミング。スループットは下がるがピーク VRAM が減る。 - VAE パッチ畳み込み: --vae_enable_patch_conv=true で LTX-2 VAE の時間方向チャンクを有効化。小さな速度低下と引き換えにピーク VRAM を削減。 - VAE temporal roll: --vae_enable_temporal_roll=true でより積極的な時間分割（速度低下は大きめ）。 - VAE タイリング: --vae_enable_tiling=true で高解像度の VAE encode/decode をタイル分割。

任意: CREPA 時間方向正則化¶

ちらつきを抑え、被写体をフレーム間で安定させるには: - Training → Loss functions で CREPA を有効化。 - 推奨初期値: Block Index = 8, Weight = 0.5, Adjacent Distance = 1, Temporal Decay = 1.0。 - 既定のビジョンエンコーダ (dinov2_vitg14, サイズ 518) を使い、必要なら dinov2_vits14 + 224 へ。 - 初回は DINOv2 重み取得のためネットワーク (またはキャッシュ済み torch hub) が必要。 - Drop VAE Encoder はキャッシュ済み latent だけで学習する場合のみ有効にし、それ以外はオフ。

高度な実験的機能¶

[
  {
    "id": "my-video-dataset",
    "type": "local",
    "dataset_type": "video",
    "instance_data_dir": "datasets/videos",
    "caption_strategy": "textfile",
    "resolution": 512,
    "video": {
        "num_frames": 61,
        "min_frames": 61,
        "frame_rate": 25,
        "bucket_strategy": "aspect_ratio"
    },
    "repeats": 10
  },
  {
    "id": "text-embeds",
    "type": "local",
    "dataset_type": "text_embeds",
    "default": true,
    "cache_dir": "cache/text/ltxvideo2",
    "disabled": false
  }
]

"audio": {
    "auto_split": true,
    "sample_rate": 16000,
    "channels": 1,
    "duration_interval": 3.0,
    "allow_zero_audio": false
}

mkdir -p datasets/videos
</details>

# .mp4 / .mov をここに配置
# キャプション用の .txt を同名で配置

wandb login
huggingface-cli login

simpletuner train

{
  "tread_config": {
    "routes": [
      {
        "selection_ratio": 0.5,
        "start_layer_idx": 2,
        "end_layer_idx": -2
      }
    ]
  }
}

{
  "base_model_precision": "int8-quanto",
  "checkpoint_step_interval": 100,
  "data_backend_config": "config/ltx2/multidatabackend.json",
  "disable_benchmark": true,
  "dynamo_mode": "",
  "evaluation_type": "none",
  "hub_model_id": "simpletuner-ltxvideo2-19b-t2v-lora-test",
  "learning_rate": 0.00006,
  "lr_warmup_steps": 50,
  "lycoris_config": "config/lycoris_config.json",
  "max_grad_norm": 0.1,
  "max_train_steps": 200,
  "minimum_image_size": 0,
  "model_family": "ltxvideo2",
  "model_flavour": "dev",
  "model_type": "lora",
  "num_train_epochs": 0,
  "offload_during_startup": true,
  "optimizer": "adamw_bf16",
  "output_dir": "output/examples/ltxvideo2-19b-t2v.peft-lora",
  "override_dataset_config": true,
  "ramtorch": true,
  "ramtorch_text_encoder": true,
  "report_to": "none",
  "resolution": 480,
  "scheduled_sampling_reflexflow": false,
  "seed": 42,
  "skip_file_discovery": "",
  "tracker_project_name": "lora-training",
  "tracker_run_name": "example-training-run",
  "train_batch_size": 2,
  "vae_batch_size": 1,
  "vae_enable_patch_conv": true,
  "vae_enable_slicing": true,
  "vae_enable_temporal_roll": true,
  "vae_enable_tiling": true,
  "validation_disable": true,
  "validation_disable_unconditional": true,
  "validation_guidance": 5,
  "validation_num_inference_steps": 40,
  "validation_num_video_frames": 81,
  "validation_prompt": "🟫 is holding a sign that says hello world from ltxvideo2",
  "validation_resolution": "768x512",
  "validation_seed": 42,
  "validation_using_datasets": false
}

[
  {
    "id": "my-audio-dataset",
    "type": "local",
    "dataset_type": "audio",
    "instance_data_dir": "datasets/audio",
    "caption_strategy": "textfile",
    "audio": {
      "sample_rate": 16000,
      "channels": 2,
      "duration_interval": 3.0,
      "truncation_mode": "beginning"
    },
    "repeats": 10
  },
  {
    "id": "text-embeds",
    "type": "local",
    "dataset_type": "text_embeds",
    "default": true,
    "cache_dir": "cache/text/ltxvideo2",
    "disabled": false
  }
]