Guia de Início Rápido do LTX Video 2¶

Neste exemplo, vamos treinar um LoRA do LTX Video 2 usando os VAEs de vídeo/áudio do LTX-2 e o encoder de texto Gemma correspondente à versão selecionada do LTX-2.

Requisitos de hardware¶

LTX Video 2 é um modelo pesado de 19B. Ele combina: 1. Gemma3 / Gemma4: O encoder de texto. LTX-2.0 e LTX-2.3 usam Gemma3; LTX-2.5 usa Gemma4. 2. LTX-2 Video VAE (mais o Audio VAE quando há condicionamento por áudio). 3. Video Transformer de 19B: Um backbone DiT grande.

Este setup é intensivo em VRAM, e o pré-cache do VAE pode aumentar o uso de memória.

• Nota: O passo inicial de pré-cache do VAE pode exigir mais VRAM. Talvez seja necessário offload para CPU ou uma GPU maior apenas na fase de cache.
• Dica: Defina "offload_during_startup": true no seu config.json para garantir que o VAE e o encoder de texto não sejam carregados na GPU ao mesmo tempo, reduzindo bastante a pressão de memória do pré-cache.
• RAM do sistema: 64GB+ é recomendado para execuções maiores; mais RAM ajuda no cache.

Desempenho e memória observados (relatos de campo)¶

• Configuração base: 480p, 17 frames, batch size 2 (mínima duração/resolução).
• RamTorch (incl. encoder de texto): ~13 GB de VRAM em AMD 7900XTX.
• NVIDIA 3090/4090/5090+ deve ter folga similar ou melhor.
• Sem offload (int8 TorchAO): ~29-30 GB de VRAM; hardware de 32 GB recomendado.
• Pico de RAM do sistema: ~46 GB ao carregar o encoder de texto Gemma bf16 e depois quantizar para int8 (~32 GB VRAM).
• Pico de RAM do sistema: ~34 GB ao carregar o transformer LTX-2 bf16 e depois quantizar para int8 (~30 GB VRAM).
• Sem offload (bf16 completo): ~48 GB de VRAM necessários para treinar o modelo sem offload.
• Throughput:
• ~8 s/step em A100-80G SXM4 (sem compilação).
• ~16 s/step em 7900XTX (execução local).
• ~30 min para 200 steps em A100-80G SXM4.

⚠️ Teste a compilação regional antes de mantê-la ativada. dynamo_use_regional_compilation não acelera universalmente o LTX Video 2 e pode reduzir o throughput estável mesmo após o aquecimento da compilação. Compare execuções eager e compiladas com o mesmo batch, número de frames e resolução fixos, e avalie vários steps de treinamento após o warmup em vez dos steps iniciais de compilação.

Pré-requisitos¶

Garanta que o Python 3.12 esteja instalado.

python --version

Instalação¶

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

Veja INSTALL.md para opções avançadas de instalação.

Configurando o ambiente¶

Interface web¶

simpletuner server

Configuração manual¶

Execute o script auxiliar:

simpletuner configure

Ou copie o exemplo e edite manualmente:

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

Parâmetros de configuração¶

Configurações-chave para LTX Video 2:

• model_family: ltxvideo2
• model_flavour: dev (padrão), dev-fp4, dev-fp8, 2.3-dev, 2.3-distilled, 2.5-dev ou 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 ou um arquivo .safetensors local.
• train_batch_size: 1. Não aumente isso a menos que você tenha um A100/H100.
• validation_resolution:
• 512x768 é um padrão seguro para testes.
• 720x1280 (720p) é possível, mas pesado.
• validation_num_video_frames: Deve ser compatível com a compressão do VAE (4x).
• Para 5s (em ~12-24fps): Use 61 ou 49.
• Fórmula: (frames - 1) % 4 == 0.
• validation_guidance: 5.0.
• ltx2_validation_audio_guidance: Escala CFG de áudio separada opcional para validation. Deixe sem definir para reutilizar validation_guidance no áudio; para validation AV do LTX-2.5, os padrões do nó dual CFG do ComfyUI são video CFG 3.0 e audio CFG 7.0.
• ltx2_validation_pipeline_mode: Mantenha trained-stage para validação normal. Use spatial-upscale para rodar o caminho LTX-2 em dois estágios: geração latente em meia resolução, upscaling latente espacial e re-denoising em resolução completa.
• spatial-upscale exige que validation_resolution seja divisível por 64.
• Overrides opcionais: ltx2_validation_spatial_upsampler_model e ltx2_validation_spatial_upsampler_filename. Os padrões são Lightricks/LTX-2.3 e ltx-2.3-spatial-upscaler-x2-1.1.safetensors.
• frame_rate: O padrão é 25.

As variantes LTX-2 2.0 são distribuídas como um único checkpoint .safetensors que inclui o transformer, o VAE de vídeo, o VAE de áudio e o vocoder. Para o LTX-2.3, o SimpleTuner carrega o repositório Diffusers correspondente ao model_flavour (2.3-dev ou 2.3-distilled). Para LTX-2.5, o SimpleTuner assume que o repo Diffusers é Lightricks/LTX-2.5 e roteia o encoder de texto por Gemma4. Se você carregar um checkpoint local single-file do LTX-2.5, mantenha model_flavour como 2.5-dev ou 2.5-distilled; o SimpleTuner usará Lightricks/LTX-2.5 como fonte de componentes/config, a menos que você sobrescreva com um caminho local.

Dual CFG para validation AV do LTX-2 usa as predições condicional e incondicional normais e aplica escalas separadas aos latentes de vídeo e áudio. Ele não adiciona um passe extra do modelo por si só. Recursos extras como STG, modality guidance ou reference-audio identity guidance adicionam seu próprio passe adicional quando habilitados.

Opcional: otimizações de VRAM¶

Se precisar de mais folga de VRAM: - Block swap (Musubi): Defina musubi_blocks_to_swap (tente 4-8) e opcionalmente musubi_block_swap_device (padrão cpu) para streamar os últimos blocos do transformer da CPU. Menor throughput, menor pico de VRAM. - Convolução por patches do VAE: Defina --vae_enable_patch_conv=true para habilitar chunking temporal no VAE do LTX-2; espere uma pequena perda de velocidade, mas menor pico de VRAM. - Temporal roll do VAE: Defina --vae_enable_temporal_roll=true para um chunking temporal mais agressivo (perda de velocidade maior). - VAE tiling: Defina --vae_enable_tiling=true para dividir o encode/decode do VAE em resoluções grandes.

Opcional: regularizador temporal CREPA¶

Para reduzir flicker e manter assuntos estáveis entre frames: - Em Training → Loss functions, habilite CREPA. - Valores iniciais recomendados: Block Index = 8, Weight = 0.5, Adjacent Distance = 1, Temporal Decay = 1.0. - Mantenha o encoder de visão padrão (dinov2_vitg14, tamanho 518) a menos que você precise de um menor (dinov2_vits14 + 224). - Requer rede (ou um torch hub em cache) para buscar os pesos do DINOv2 na primeira vez. - Só habilite Drop VAE Encoder se você estiver treinando inteiramente a partir de latentes em cache; caso contrário, deixe desligado.

Recursos experimentais avançados¶

[
  {
    "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>

# Place .mp4 / .mov files here.
# Place corresponding .txt files with same filename for captions.

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
  }
]