LTX Video 2 快速入门¶
本示例将使用 LTX-2 视频/音频 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 offload 或更大 GPU 仅用于缓存阶段。
- 提示：在
config.json中设置"offload_during_startup": true，确保 VAE 与文本编码器不会同时加载到 GPU，可显著降低预缓存压力。 - 系统内存：大规模训练建议 64GB+，更多内存有助于缓存。
实测性能与内存（实测报告）¶
- 基准设置：480p、17 帧、batch size 2（最小视频长度/分辨率）。
- RamTorch（含文本编码器）：AMD 7900XTX 上 VRAM 约 13 GB。
- NVIDIA 3090/4090/5090+ 应有相近或更好的 VRAM 余量。
- 不使用 offload（int8 TorchAO）：VRAM 约 29-30 GB；建议 32 GB 显存。
- 系统内存峰值：先加载 bf16 Gemma 文本编码器再量化到 int8（VRAM ~32 GB）时约 46 GB。
- 系统内存峰值：先加载 bf16 LTX-2 transformer 再量化到 int8（VRAM ~30 GB）时约 34 GB。
- 不使用 offload（完整 bf16）：无任何 offload 训练约需 48 GB VRAM。
- 吞吐：
- A100-80G SXM4 约 8 秒/step（未启用编译）。
- 7900XTX 约 16 秒/step（本地运行）。
- A100-80G SXM4 跑 200 steps 约 30 分钟。
⚠️ 请先测试 regional compilation，再决定是否保留。
dynamo_use_regional_compilation并不一定能加速 LTX Video 2，即使编译预热完成后也可能降低稳定吞吐。请在相同的固定 batch、帧数和分辨率下比较 eager 与 compiled 运行，并根据预热后的多个训练 step 判断，而不是依据最初的编译 step。
前提条件¶
确保已安装 Python 3.12。
安装¶
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 界面¶
访问 http://localhost:8001。
手动配置¶
运行辅助脚本：
或复制示例并手动修改：
配置参数¶
LTX Video 2 的关键设置：
model_family:ltxvideo2model_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: 验证时可选的独立音频 CFG scale。未设置时音频会复用validation_guidance；LTX-2.5 AV validation 中，ComfyUI dual-CFG 节点默认 video CFG 为3.0、audio CFG 为7.0。ltx2_validation_pipeline_mode: 常规验证保持trained-stage。使用spatial-upscale可运行 LTX-2 两阶段 spatial upscaler 路径：半分辨率 latent 生成、spatial latent upscaling，然后以完整分辨率重新去噪。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 变体以单个 .safetensors checkpoint 形式发布，包含 transformer、视频 VAE、音频 VAE 和 vocoder。
对于 LTX-2.3，SimpleTuner 会根据 model_flavour 加载对应的 Diffusers 仓库
（2.3-dev 或 2.3-distilled）。
对于 LTX-2.5，SimpleTuner 假定 Diffusers 仓库路径为 Lightricks/LTX-2.5，并将文本编码器路由到 Gemma4。如果加载本地 single-file LTX-2.5 checkpoint，请保持 model_flavour 为 2.5-dev 或 2.5-distilled；除非用本地路径覆盖，SimpleTuner 会使用 Lightricks/LTX-2.5 作为组件/配置来源。
LTX-2 AV validation 的 dual CFG 使用普通的 conditional 与 unconditional predictions，并对视频和音频 latent stream 应用不同 scale。它本身不会增加额外的模型 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 编码/解码进行分块。
可选：CREPA 时间正则¶
为减少闪烁并保持主体跨帧稳定：
- 在 Training → Loss functions 中启用 CREPA。
- 推荐初始值：Block Index = 8, Weight = 0.5, Adjacent Distance = 1, Temporal Decay = 1.0。
- 保持默认视觉编码器（dinov2_vitg14，尺寸 518），除非需要更小的 dinov2_vits14 + 224。
- 首次需要联网（或已缓存 torch hub）以获取 DINOv2 权重。
- 仅在完全使用缓存 latents 训练时启用 Drop VAE Encoder；否则保持关闭。
高级实验功能¶
显示高级实验详情
SimpleTuner 包含可显著提高训练稳定性和性能的实验功能。 * **[计划采样（Rollout）](../experimental/SCHEDULED_SAMPLING.md)：**通过让模型在训练期间生成自己的输入来减少曝光偏差并提高输出质量。 > ⚠️ 这些功能会增加训练的计算开销。 #### 数据集注意事项 视频数据集需要仔细配置。创建 `config/multidatabackend.json`：[
{
"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
}
查看示例配置
查看 7900XTX 配置（最低 VRAM 使用）
{
"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
}
]