企业官网建设流程全解析

LTX-2 训练指南：从单卡 LoRA 到多卡分布式训练与模型上线的完整实战

【免费下载链接】LTX-2Official Python inference and LoRA trainer package for the LTX-2 audio–video generative model.项目地址: https://gitcode.com/GitHub_Trending/lt/LTX-2

导读

本文是 LTX-2 官方 Python 推理与 LoRA 训练包（ltx-trainer）的训练实战指南，覆盖从数据预处理完成后启动训练，到单卡 LoRA 微调、多卡 DDP/FSDP 分布式训练、自动上传 Hugging Face Hub、W&B 实验跟踪的完整链路。读完本文，你将掌握scripts/train.py的正确调用方式、四套预置 Accelerate 配置的选用原则、训练产物文件结构，以及如何让训练出的 LoRA 直接接入ltx-pipelines做生产级推理。

一、单卡基础训练：一条命令启动

完成数据集预处理（见 dataset-preparation.md）并准备好配置文件后，即可用训练脚本启动：

uv run python scripts/train.py configs/t2v_lora.yaml

1.1 train.py 的命令行入口

入口脚本位于 scripts/train.py，基于typer构建，其核心参数非常简单：

脚本启动后依次执行：

1. 校验配置文件路径：文件不存在会直接报错退出（Error: Configuration file ... does not exist.）。
2. 解析 YAML 并做严格校验：通过LtxTrainerConfig(**config_data)（Pydantic 模型，见 config.py）实例化配置对象，任何非法字段或非法取值都会在此阶段被拦截并打印错误，而不是在训练中途才暴露。
3. 初始化训练器：调用LtxvTrainer(trainer_config)完成模型加载、优化器设置、加速器初始化。
4. 进入训练循环：执行trainer.train(disable_progress_bars=...)。

从源码看，LtxvTrainer在构造阶段（trainer.py）就完成了一系列关键准备工作：读取模型路径、创建ValidationRunner、加载 transformer 模型、设置 Accelerator、收集可训练参数、恢复检查点（如果存在）等。训练期间主进程会打印配置摘要（print_config），并以进度条形式展示训练进度。

1.2 训练器实际做的事情

训练循环（trainer.py）的核心流程为：

• 采样 timestep：按flow_matching.timestep_sampling_mode指定的模式采样噪声时间步（LTX-2 推荐shifted_logit_normal）。
• 前向与反向：对 batch 计算 loss，accelerator.backward(loss.mean())反向传播。
• 梯度裁剪：当max_grad_norm > 0时，对可训练参数执行梯度裁剪，保证训练稳定性。
• 优化器与调度器步进：optimizer.step()+zero_grad()，随后推进学习率调度器。
• 周期性验证：当validation.interval配置了且达到间隔步数时，调用_run_validation生成验证视频。
• 周期性保存检查点：当checkpoints.interval达到时，调用_save_checkpoint()落盘。

整个过程中训练配置会在启动时被复制保存为training_config.yaml，便于追溯每次运行的参数。

1.3 输出文件

LoRA 训练产出的文件：

• checkpoints/lora_weights_step_00000.safetensors—— LoRA 检查点权重，文件名中带有当前训练步数；
• training_config.yaml—— 训练配置的副本；
• samples/—— 生成的验证样本（若启用验证）；
• checkpoints/training_state_step_00000.pt—— 可选的中断恢复状态文件，取决于checkpoints.save_training_state。

**全量微调（full fine-tuning）**产出的文件：

• checkpoints/model_weights_step_00000.safetensors—— 完整模型检查点权重，文件名中带有步数；
• training_config.yaml—— 训练配置副本；
• samples/—— 生成的验证样本（若启用）；
• checkpoints/training_state_step_00000.pt—— 可选恢复状态文件。

提示：train.py支持自动恢复——当加载的检查点旁边存在训练状态文件时会自动续训；如需从零开始，可在配置中设置checkpoints.no_resume: true。

1.4 Agent 辅助训练

如果你的环境支持仓库技能（repository skills），train-model技能提供了端到端的训练编排器：它会询问你想让模型学习什么，将意图映射到 training-modes.md 中记载的训练模式之一，探测你的文件系统与 GPU，准备/预处理数据集，编写针对本次运行的配置，启动训练并监控任务。该技能以训练器文档为事实来源，并在执行打标（captioning）、预处理或启动昂贵训练前会停下来请求用户批准。

二、分布式 / 多 GPU 训练

多卡场景下，LTX-2 训练器基于 Hugging Face 🤗 Accelerate 实现 DDP 与 FSDP。

2.1 配置 Accelerate

先运行一次交互式向导，设置环境（DDP / FSDP、GPU 数量等）：

uv run accelerate config

向导结果会保存到~/.cache/huggingface/accelerate/default_config.yaml。

2.2 使用预置 Accelerate 配置（推荐）

仓库在configs/accelerate/下提供了四套开箱即用的配置：

使用--config_file指定配置启动：

# DDP（以 2 卡为例） CUDA_VISIBLE_DEVICES=0,1 \ uv run accelerate launch --config_file configs/accelerate/ddp.yaml \ scripts/train.py configs/t2v_lora.yaml # DDP + torch.compile CUDA_VISIBLE_DEVICES=0,1 \ uv run accelerate launch --config_file configs/accelerate/ddp_compile.yaml \ scripts/train.py configs/t2v_lora.yaml # FSDP（以 4 卡为例） CUDA_VISIBLE_DEVICES=0,1,2,3 \ uv run accelerate launch --config_file configs/accelerate/fsdp.yaml \ scripts/train.py configs/t2v_lora.yaml # FSDP + torch.compile CUDA_VISIBLE_DEVICES=0,1,2,3 \ uv run accelerate launch --config_file configs/accelerate/fsdp_compile.yaml \ scripts/train.py configs/t2v_lora.yaml

注意事项：

• 进程数取自 Accelerate 配置中的num_processes；可用--num_processes X覆盖，或用CUDA_VISIBLE_DEVICES限制可见 GPU。
• compile 变体通过 Accelerate 的dynamo_config启用 Inductor 后端（见 ddp_compile.yaml）。
• FSDP 配置通过fsdp_transformer_layer_cls_to_wrap: BasicAVTransformerBlock自动包裹 transformer 块；同时启用了fsdp_cpu_ram_efficient_loading（CPU 内存高效加载）、fsdp_state_dict_type: SHARDED_STATE_DICT（分片状态字典）、fsdp_reshard_after_forward: FULL_SHARD（前向后全量分片）等选项，详见 fsdp.yaml。

2.3 使用你自己的默认 Accelerate 配置

如果你更想用默认的 Accelerate 配置：

# 使用默认 accelerate 配置中的设置 uv run accelerate launch scripts/train.py configs/t2v_lora.yaml # 运行时覆盖进程数（例如 2 卡） uv run accelerate launch --num_processes 2 scripts/train.py configs/t2v_lora.yaml # 指定使用哪些 GPU CUDA_VISIBLE_DEVICES=0,1 uv run accelerate launch scripts/train.py configs/t2v_lora.yaml

[!TIP] 如需关闭终端内的进度条，可在训练器 CLI 中加--disable-progress-bars标志。非主进程（LOCAL_RANK != 0）的进度条也会被自动禁用（见 trainer.py）。

2.4 分布式训练收益

• 更快的训练：把工作负载分散到多张 GPU 上；
• 更大的有效 batch：聚合多卡梯度，有效 batch size 变为batch_size × num_processes；
• 内存效率：每张 GPU 只处理 batch 的一部分。

[!NOTE] 分布式训练要求所有 GPU 都有足够的显存容纳模型与 batch。有效 batch size 为batch_size × num_processes。例如在 t2v_lora.yaml 中，batch_size: 1、gradient_accumulation_steps: 1，在 4 卡 DDP 下有效 batch 即为 4。

三、推送模型到 Hugging Face Hub

在配置文件中加入如下配置即可自动上传训练好的模型：

hub: push_to_hub: true hub_model_id: "your-username/your-model-name"

3.1 前置条件

1. 拥有 Hugging Face 账号；
2. 已登录：通过huggingface-cli login登录，或设置HUGGING_FACE_HUB_TOKEN环境变量；
3. 对目标仓库有写权限（仓库不存在时会自动创建）。

3.2 登录方式

方式一：交互式登录

uv run huggingface-cli login

方式二：环境变量

export HUGGING_FACE_HUB_TOKEN="your_token_here"

3.3 会上传什么

训练器会自动完成：

• 创建模型卡片（model card），包含训练细节与样本输出；
• 上传模型权重；
• 将样本视频作为 GIF 推送到模型卡片；
• 附带训练配置与提示词（prompts）。

上传逻辑由 hf_hub_utils.py 中的push_to_hub实现，在训练结束时被训练器调用。

四、Weights & Biases 实验跟踪

在配置中加入如下内容启用 W&B：

wandb: enabled: true project: "ltx-2-trainer" entity: null # 你的 W&B 用户名或团队名 tags: [ "ltx2", "lora" ] log_validation_videos: true

这会记录：

• 训练 loss 与学习率；
• 验证视频；
• 模型配置；
• 训练进度。

从源码看（trainer.py），W&B 的初始化被放在状态恢复成功之后，这样断点续训时可以复用training_state.wandb_run_id继续同一条 run，避免日志碎片化。

五、训练模式与配置速览

在动手训练前，建议先选定训练模式。训练器采用统一的flexible训练策略（training_strategy.name: "flexible"），所有模式（T2V、I2V、V2V、A2V、V2A、扩展、修补等）都通过配置表达：每个模态（video/audio）设置is_generated并追加可选 conditions，无需切换策略类。完整模式清单与条件组合方式见 training-modes.md。

5.1 一个完整的 T2V LoRA 配置示例

以 t2v_lora.yaml 为例，配置分为以下核心小节：

• model：model_path（统一检查点为一个 .safetensors 文件；split 包则需另指video_vae_path/audio_vae_path）、text_encoder_path（Gemma 文本编码器）、training_mode（"lora"或"full"）、load_checkpoint（续训路径）；
• lora：rank: 32、alpha: 32（有效缩放为 alpha/rank=1.0）、dropout: 0.0，以及target_modules—— 短模式"to_k"/"to_q"/"to_v"/"to_out.0"会同时命中视频、音频与音视频交叉注意力分支（attn1.*、audio_attn1.*、audio_to_video_attn.*、video_to_audio_attn.*）；
• training_strategy：name: "flexible"，video/audio 两个模态块各自设置is_generated: true与latents_dir（视频为latents，音频为audio_latents）；
• optimization：learning_rate: 1e-4、steps: 2000、batch_size: 1、gradient_accumulation_steps: 1、max_grad_norm: 1.0、optimizer_type: "adamw"、scheduler_type: "linear"、enable_gradient_checkpointing: true；
• acceleration：mixed_precision_mode: "bf16"（推荐）、quantization: null（可选int8-quanto、int4-quanto、int2-quanto、fp8-quanto、fp8uz-quanto）、load_text_encoder_in_8bit: false、offload_optimizer_during_validation: false；
• data：preprocessed_data_root（含latents/、conditions/、audio_latents/）、num_dataloader_workers: 2；
• validation：自描述的samples（每条含 prompt 与可选 conditions）、negative_prompt、video_dims: [960, 544, 89]（宽高需被 VAE 空间因子整除，帧数需满足frames % T == 1）、frame_rate: 24.0、inference_steps: 30、interval: 100、视频/音频 CFG 与 STG 缩放、generate_audio: true等；
• checkpoints：interval: 250、keep_last_n: -1（保留全部）、precision: "bfloat16"；
• flow_matching：timestep_sampling_mode: "shifted_logit_normal"；
• hub / wandb：如前文所述；
• 顶层seed: 42与output_dir: "outputs/t2v_lora"。

全部字段的完整说明见 configuration-reference.md，其中还包含统一布局（unified）与 split 布局两种检查点形态下各路径字段的差异对照表，以及 LoRAtarget_modules的详细模块表（视频/音频/交叉注意力三张表）。

六、训练完成后的下一步

训练结束后：

• 用训练好的 LoRA 跑推理：ltx-pipelines包提供生产级推理管线，支持通过loras参数加载自定义 LoRA，可选管线包括 text-to-video、image-to-video、IC-LoRA video-to-video 等。模式与管线对应关系（如 T2V/I2V/A2V 用TI2VidOneStagePipeline或TI2VidTwoStagesPipeline，IC-LoRA 用ICLoraPipeline）见 training-modes.md。
• 用验证提示词测试模型；
• 根据验证结果迭代优化；
• 推送到 Hugging Face Hub 分享成果。

七、成功训练的小贴士

• 从小处着手：先用小数据集 + 几百步验证整条链路跑通；
• 盯紧验证：持续观察验证样本，及时发现过拟合；
• 调低学习率：更小的学习率往往带来更好结果（LoRA 典型区间 1e-5 ~ 1e-4）；
• 启用梯度检查点：显存受限时至关重要（enable_gradient_checkpointing: true）；
• 定期保存检查点：checkpoints.interval让中断后可以从最近检查点恢复。

八、遇到问题怎么办

训练中遇到问题，请查阅 troubleshooting.md，其中覆盖了常见的配置错误、显存不足、数据加载异常等排查思路；也可以在社区 Discord 中实时求助。

【免费下载链接】LTX-2Official Python inference and LoRA trainer package for the LTX-2 audio–video generative model.项目地址: https://gitcode.com/GitHub_Trending/lt/LTX-2