Guía rápida de LTX Video 2¶

En este ejemplo, entrenaremos un LoRA de LTX Video 2 usando los VAE de video/audio de LTX-2 y el codificador de texto Gemma correspondiente a la versión de LTX-2 seleccionada.

Requisitos de hardware¶

LTX Video 2 es un modelo pesado de 19B. Combina: 1. Gemma3 / Gemma4: El codificador de texto. LTX-2.0 y LTX-2.3 usan Gemma3; LTX-2.5 usa Gemma4. 2. VAE de LTX-2 Video (más el VAE de audio cuando se condiciona con audio). 3. Video Transformer de 19B: Un backbone DiT grande.

Esta configuración es intensiva en VRAM, y el pre-caché del VAE puede disparar el uso de memoria.

• Nota: El pre-caché del VAE puede requerir más VRAM. Podrías necesitar offloading a CPU o una GPU más grande solo para la fase de caché.
• Consejo: Configura "offload_during_startup": true en tu config.json para asegurar que el VAE y el codificador de texto no se carguen en la GPU al mismo tiempo, lo que reduce mucho la presión de memoria durante el pre-caché.
• RAM del sistema: Se recomiendan 64GB+ para ejecuciones grandes; más RAM ayuda con el caché.

Rendimiento y memoria observados (reportes de campo)¶

• Configuración base: 480p, 17 frames, batch size 2 (mínima duración/resolución de video).
• RamTorch (incl. codificador de texto): ~13 GB de VRAM en AMD 7900XTX.
• NVIDIA 3090/4090/5090+ debería ver margen similar o mejor.
• Sin offload (int8 TorchAO): ~29-30 GB de VRAM; se recomienda hardware de 32 GB.
• Pico de RAM del sistema: ~46 GB al cargar el codificador de texto Gemma bf16 y luego cuantizar a int8 (~32 GB VRAM).
• Pico de RAM del sistema: ~34 GB al cargar el transformer LTX-2 bf16 y luego cuantizar a int8 (~30 GB VRAM).
• Sin offload (bf16 completo): ~48 GB de VRAM necesarios para entrenar el modelo sin offload.
• Rendimiento:
• ~8 s/step en A100-80G SXM4 (sin compilación).
• ~16 s/step en 7900XTX (ejecución local).
• ~30 min por 200 steps en A100-80G SXM4.

⚠️ Prueba la compilación regional antes de mantenerla activada. dynamo_use_regional_compilation no acelera universalmente LTX Video 2 y puede reducir el rendimiento estable incluso después del calentamiento de la compilación. Compara ejecuciones eager y compiladas con el mismo lote, número de frames y resolución fijos, y evalúa varios steps de entrenamiento posteriores al calentamiento en vez de los steps iniciales de compilación.

Requisitos previos¶

Asegúrate de que Python 3.12 esté instalado.

python --version

Instalación¶

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

Consulta INSTALL.md para opciones de instalación avanzadas.

Configuración del entorno¶

Interfaz web¶

simpletuner server

Configuración manual¶

Ejecuta el script de ayuda:

simpletuner configure

O copia el ejemplo y edita manualmente:

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

Parámetros de configuración¶

Ajustes clave para LTX Video 2:

• model_family: ltxvideo2
• model_flavour: dev (predeterminado), dev-fp4, dev-fp8, 2.3-dev, 2.3-distilled, 2.5-dev o 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 o un archivo .safetensors local.
• train_batch_size: 1. No aumentes esto a menos que tengas una A100/H100.
• validation_resolution:
• 512x768 es un valor seguro para pruebas.
• 720x1280 (720p) es posible pero pesado.
• validation_num_video_frames: Debe ser compatible con la compresión del VAE (4x).
• Para 5s (a ~12-24fps): Usa 61 o 49.
• Fórmula: (frames - 1) % 4 == 0.
• validation_guidance: 5.0.
• ltx2_validation_audio_guidance: Escala CFG de audio separada opcional para validation. Déjalo sin definir para reutilizar validation_guidance en audio; para validation AV de LTX-2.5, los valores por defecto del nodo dual CFG de ComfyUI son video CFG 3.0 y audio CFG 7.0.
• ltx2_validation_pipeline_mode: Mantén trained-stage para la validación normal. Usa spatial-upscale para ejecutar el flujo LTX-2 en dos etapas: generación latente a media resolución, upscaling latente espacial y re-denoising a resolución completa.
• spatial-upscale requiere que validation_resolution sea divisible por 64.
• Overrides opcionales: ltx2_validation_spatial_upsampler_model y ltx2_validation_spatial_upsampler_filename. Los valores por defecto son Lightricks/LTX-2.3 y ltx-2.3-spatial-upscaler-x2-1.1.safetensors.
• frame_rate: Por defecto es 25.

Las variantes LTX-2 2.0 se distribuyen como un único checkpoint .safetensors que incluye el transformer, el VAE de video, el VAE de audio y el vocoder. Para LTX-2.3, SimpleTuner carga el repositorio Diffusers correspondiente según model_flavour (2.3-dev o 2.3-distilled). Para LTX-2.5, SimpleTuner asume que el repo Diffusers es Lightricks/LTX-2.5 y enruta el codificador de texto por Gemma4. Si cargas un checkpoint local single-file de LTX-2.5, mantén model_flavour en 2.5-dev o 2.5-distilled; SimpleTuner usará Lightricks/LTX-2.5 como fuente de componentes/config salvo que lo sobrescribas con una ruta local.

Dual CFG para validation AV de LTX-2 usa las predicciones condicional e incondicional normales y aplica escalas separadas a los latentes de video y audio. No añade un pase extra del modelo por sí solo. Funciones extra como STG, modality guidance o reference-audio identity guidance sí añaden su propio pase adicional cuando están activadas.

Opcional: optimizaciones de VRAM¶

Si necesitas más margen de VRAM: - Block swap (Musubi): Establece musubi_blocks_to_swap (prueba 4-8) y opcionalmente musubi_block_swap_device (por defecto cpu) para stream de los últimos bloques del transformer desde CPU. Menor throughput, menor pico de VRAM. - Convolución de parches del VAE: Configura --vae_enable_patch_conv=true para habilitar chunking temporal en el VAE de LTX-2; espera una pequeña pérdida de velocidad pero menor pico de VRAM. - VAE temporal roll: Configura --vae_enable_temporal_roll=true para un chunking temporal más agresivo (mayor pérdida de velocidad). - VAE tiling: Configura --vae_enable_tiling=true para dividir el encode/decode del VAE en resoluciones grandes.

Opcional: regularizador temporal CREPA¶

Para reducir el parpadeo y mantener sujetos estables entre frames: - En Training → Loss functions, habilita CREPA. - Valores iniciales recomendados: Block Index = 8, Weight = 0.5, Adjacent Distance = 1, Temporal Decay = 1.0. - Mantén el codificador de visión por defecto (dinov2_vitg14, tamaño 518) a menos que necesites uno más pequeño (dinov2_vits14 + 224). - Requiere red (o un torch hub en caché) para obtener los pesos de DINOv2 la primera vez. - Solo habilita Drop VAE Encoder si entrenas completamente desde latentes en caché; de lo contrario déjalo desactivado.

Funciones experimentales avanzadas¶

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