LTX-2 训练运行计划（plan.md）编写指南：以训练计划模板为契约的 Agent 驱动 LoRA 训练工作流

LTX-2 训练运行计划plan.md编写指南以训练计划模板为契约的 Agent 驱动 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 官方开源仓库ltx-trainer中train-model技能的训练计划模板展开讲解如何在训练启动前编写一份可执行、可审计、可回溯的plan.md——它既是用户与 Agent 之间的正式契约也是任何重度训练任务LoRA / 全量微调开工前的最后一道门禁。读完本文你将掌握 LTX-2 训练计划的完整章节骨架、每个字段的取值来源与默认值、VRAM 分层与配置选型方法、Sanity Check 与 Autotune 机制以及如何用可验证的数字而非形容词来约束训练预期。训练计划在 LTX-2 训练流程中的位置在 LTX-2 仓库中train-model技能入口见 .claude/skills/train-model/SKILL.md负责把用户从我想训练一个模型带到正在运行并被监控的训练任务。整个编排流程分为 9 个阶段Phase 0–9其中Phase 4Plan专门负责把训练计划写入workspace/run-name/plan.md并等待用户显式批准后才允许进入后续任何重型工作。该模板原文位于 .claude/skills/train-model/references/plan-template.md其核心定位一句话即可概括The plan is the users contract with the agent — its the gate before any heavy work runs.计划是用户与 Agent 的契约是任何重型工作运行之前的门禁。所谓重型工作按 SKILL.md 中的 Hard Invariant #2 定义包括打标captioning、预处理preprocessing、训练training与自动调参autotune——这些操作在plan.md获批之前一律不得启动。而探测文件系统、运行nvidia-smi这类只读探针不受此限制。模板同时给出了一条重要弹性规则各章节的篇幅按相关性缩放不适用的子章节可以跳过例如数据已有打标则不再写打标步骤但Assumptions假设与Cost/time estimate成本/时间估算两个章节永远不可省略。这条规则保证了计划既能聚焦、又不丢失对用户最重要的透明性。模板整体骨架12 个章节的契约结构plan-template.md定义了一份完整plan.md应包含的 12 个章节#章节一句话作用1Goal用用户自己的话重述其意图2Mode模式名 配置基座 条件 训练模式3Dataset数据来源、打标、音频、IC-LoRA 参考4Preprocessing分辨率桶、预估耗时、输出位置5Training Config训练超参总表6HardwareGPU 清单、启动方式、VRAM 分层7Sanity Check Autotune单样本干跑与调参扫描机制8MonitoringWB 跟踪状态9Outputs运行产物路径清单10Assumptions所有被静默采用的默认值11Cost / Time Estimate可落地的估算标注 rough12Approve to Proceed用户批准门槛下面逐节结合仓库源码展开。Goal用用户的语言固化意图Goal只需要一段话但要在用户自己的术语体系中重述用户的意图而不是复述技术方案。例如用户说我想给这个角色做一个 LoRA让它在各种场景里都能出现Goal 就应写成训练一个 X 角色的概念 LoRA使其可在多种场景中稳定生成而非运行i2v_lora配置 2000 步。这一节的价值在于它是后续所有技术决策模式选择、数据集、提示词的锚点也是训练结束后写入 run-summary.md 模板 中What this LoRA does部分的直接来源。Mode意图到配置基座的单行映射Mode章节必须给出三样东西模式名 一行理由把用户意图与模式关联起来Config base该模式对应的具体示例配置文件名用真实文件名不用占位符Conditions条件列表或noneTraining modelora或full。模式选择不是凭感觉而是查表。完整的意图→模式映射表见 .claude/skills/train-model/references/mode-selector.md其核心决策表摘录如下用户说法大意模式示例配置生成模态条件从文本生成视频 / T2V LoRAT2Vconfigs/t2v_lora.yamlvideo audionone从起始图生成视频 / I2VI2Vconfigs/i2v_lora.yamlvideo audiofirst_framevideo普通概念/风格 LoRA无特定任务默认 I2Vconfigs/i2v_lora.yamlvideo audiofirst_frameprobability: 0.5向前扩展视频视频扩展prefixconfigs/video_extend_lora.yamlvideo audioprefixvideo向后扩展视频视频扩展suffixconfigs/video_suffix_lora.yamlvideo audiosuffixvideo填充视频遮罩区域视频修补configs/video_inpainting_lora.yamlvideomaskvideo视频外扩边界视频外扩configs/video_outpainting_lora.yamlvideospatial_cropvideo参考视频风格迁移 / IC-LoRA / 深度/姿态/Canny 控制V2V IC-LoRAconfigs/v2v_ic_lora.yamlvideoreferencevideo生成与音频匹配的视频A2Vconfigs/a2v_lora.yamlvideo gen, audio frozennoneaudiois_generated: false给无声视频加音效 / 拟音 / V2AV2Aconfigs/v2a_lora.yamlvideo frozen, audio gennonevideois_generated: false从文本生成音频 / T2AT2Aconfigs/t2a_lora.yamlaudionone向前/向后扩展音频音频扩展configs/audio_extend_lora.yaml、configs/audio_suffix_lora.yamlaudioprefix/suffixaudio填充音频遮罩区域音频修补configs/audio_inpainting_lora.yamlaudiomaskaudio参考音频风格迁移 / A2A IC-LoRAA2A IC-LoRAconfigs/a2a_ic_lora.yamlaudioreferenceaudio联合视频音频参考控制AV2AV IC-LoRAconfigs/av2av_ic_lora.yamlvideo audioreferenceboth上述任一的全量微调Full FT 变体同上设model.training_mode: full随模式随模式值得特别注意的是为什么普通概念/风格 LoRA 默认落到 I2VLoRA 权重与推理流水线无关——同一份 LoRA 权重在 T2V 和 I2V 推理中都可加载两者共用TI2VidOneStagePipeline/TwoStages见 packages/ltx-pipelines/src/ltx_pipelines/。而i2v_lora配置以probability: 0.5训练first_frame条件使模型在一次运行中同时学会首帧条件I2V与非条件T2V生成且首帧自动取自每个训练片段、无需额外数据准备。因此 I2V 是兼得两者的超集普通 LoRA 默认选它、只有用户确认纯文本生成时才降级到t2v_lora。从源码看所有这些模式都由单一策略承载training_strategy.name: flexible区别只在于生成的模态与挂载的条件实现位于 packages/ltx-trainer/src/ltx_trainer/training_strategies/flexible.py。若意图无法映射到任何flexible条件组合则必须走 SKILL.md 的 Escape Hatch而不是静默挑一个最接近的模式。Dataset数据契约的四要素Dataset章节用四行清单回答四个问题Source绝对路径N 个样本Captionsalready present已有打标或will be generated with backend将用某后端生成Audiopresent音频已存在、absent — using --skip-audio无音频、跳过提取或to be paired with --audio-durations将配对音频时长IC-LoRA referencespresent已有参考或to be generated via compute_reference.py用该脚本生成或n/a不适用。这些字段与数据准备阶段的真实约束一一对应详见 .claude/skills/train-model/phases/prepare-dataset.md元数据文件dataset.json的列按约定检测媒体列可以是video或audio当有video列且含音轨、又没有独立audio列时音频会自动从视频中提取除非--skip-audio视频生成类模式必填videocaption视频修补需video_maskV2V IC-LoRA 需reference_videoAV2AV IC-LoRA 需reference_videoreference_audio纯音频类模式T2A、音频扩展、音频修补、A2A IC-LoRA的媒体列是audio不出现video列别名media_path等价videoref_media_path等价reference_video。计划中还应记录**触发词trigger word**的决策。注意触发词不写进打标文本而是在预处理阶段通过process_dataset.py --lora-trigger word传入由process_captions.py在每条 caption 前追加——这是固定的实现细节计划里只需记录用哪个词不涉及注入方式的讨论。Preprocessing分辨率桶的硬约束与产物位置Preprocessing章节声明三件事目标分辨率桶WxHxF其中帧数满足frames % 8 1即 1, 9, 17, 25, 33, 41, 49, 57, ...宽高必须能被 32 整除预估耗时~duration基于已探测硬件输出workspace/run-name/dataset/.precomputed/。这两个数值约束不是建议而是硬性门槛。参考 .claude/skills/train-model/references/config-patching.md 的 Schema Constraints 一节validation.video_dims[2]必须满足frames % 8 1[0]、[1]必须能被 32 整除对应 VAE 的时间因子 8 与空间因子 32违反会在 Pydantic 校验或运行时直接报错。仓库自带示例中的两个典型桶分别是标准配置的[960, 544, 89]与低显存配置的[576, 576, 49]见 packages/ltx-trainer/configs/t2v_lora.yaml 与 packages/ltx-trainer/configs/t2v_lora_low_vram.yaml。预处理产物结构以preprocessed_data_root为根为preprocessed_data_root/ ├── latents/ # 视频潜变量VAE 编码后的视频 ├── conditions/ # 每个视频的文本嵌入 └── audio_latents/ # 音频潜变量VAE 编码后的音频conditions/与audio_latents/目录名由training_strategy.video.latents_dir与training_strategy.audio.latents_dir控制默认latents/audio_latents。值得在计划中注明预计算的文本特征是检查点 Gemma组合特有的切换模型版本如 LTX-2.3 → LTX 2.5时必须预处理到全新输出目录或加--overwrite见 packages/ltx-trainer/docs/quick-start.md。Training Config训练超参总表与源码默认值模板要求以表格形式给出训练配置的核心字段。结合两份官方示例配置各字段的合法取值与典型默认值如下字段模板占位合法取值 / 源码默认Optimizeradamw / adamw8bitadamw标准配置默认adamw8bit低显存配置默认优化器状态省 ~75%Mixed precisionbf16 / fp16bf16为两示例默认另有nofp32可选Quantizationnull / int8-quanto / ...null标准配置默认int8-quanto低显存默认基座模型省 ~50%还有int4-quanto、int2-quanto、fp8-quanto、fp8uz-quantoGradient checkpointingon / off两示例均trueBatch sizeN两示例均1Gradient accumulationN两示例均1有效批次 batch_size × gradient_accumulation_steps × num_gpusStepsN示例为2000小型 LoRA 数据集常用默认 2000Learning ratevalue示例1e-4LoRA 典型范围1e-5 ~ 1e-4LoRA rank / alphaN / N标准配置32 / 32低显存配置16 / 16保持alpha rank有效缩放 alpha / rankLoRA target moduleslist默认[to_k, to_q, to_v, to_out.0]匹配全部注意力视频 音频 跨模态可按需追加ff.net.0.proj、ff.net.2等前馈层LoRA trigger wordword仅风格/概念 LoRA无则n/aValidation intervaleveryNsteps示例100Sanity Check 用50Checkpoint intervaleveryNsteps示例250null表示禁用中间检查点两份示例配置的对照本身就是选择配置基座的依据完整字段见 t2v_lora.yaml 与 t2v_lora_low_vram.yaml关键差异项t2v_lora.yaml80GB 标准t2v_lora_low_vram.yaml32GB 低显存optimizer_typeadamwadamw8bitquantizationnullint8-quantoload_text_encoder_in_8bitfalsetrueoffload_optimizer_during_validationfalsetruelora.rank/lora.alpha32/3216/16validation.video_dims[960, 544, 89][576, 576, 49]LoRA rank 的选取还要结合使用场景详见 mode-selector.md 的 LoRA Rank by Use Case 一节单角色/单物体/单风格建议 32–64多角色世界/复杂多概念 96–128镜头运动、转场等行为型信号 8–16高秩只会记忆帧内容IC-LoRA 结构控制深度/姿态/边缘16–32。rank 是质量旋钮而非步时旋钮Autotune 扫描不碰 rank——如果 32GB 显存下用户选了更高 rank计划中必须明示取舍因为过高的 rank 会在训练时直接 OOM。HardwareVRAM 分层与启动方式Hardware章节记录 GPU 清单、启动命令与 VRAM 分层。分层依据是 .claude/skills/train-model/references/hardware-profiles.md其探测命令为nvidia-smi --query-gpuname,memory.total --formatcsv,noheader分层规则取可见 GPU 中最小的显存档位多卡只增吞吐、不放松单卡显存上限 32 GB停止运行。LTX-2 训练器的最低要求是 32GB见 packages/ltx-trainer/docs/quick-start.md标准配置推荐 80GB。仓库不提供 32GB 以下的已测试配置不允许自造更低档位32GB 档训练器最低门槛典型卡 RTX 5090、V100 32GB。直接以t2v_lora_low_vram.yaml为基座adamw8bit、int8-quanto、rank 16、梯度检查点、文本编码器 8bit40–60GB 档中档从低显存配置自动调优典型卡 A40、A6000 48GB、L40、RTX 6000 Ada。仓库未为此区间提供已测试配置应从 32GB 档起步由 Autotune 依据实测余量放宽量化/优化器/批次80GB 档推荐典型卡 A100 80GB、H100 80GB、H200、B200。直接以t2v_lora.yaml为基座adamw、无量化、rank 32。对 ≥140GB 的 H200/B200FA3/FA4 注意力后端可选加速但默认的 PyTorch SDPA 无需额外设置即可工作。启动方式二选一单卡uv run python scripts/train.py workspace/run-name/config.yaml在packages/ltx-trainer目录下执行多卡LoRA 用默认 DDP——uv run accelerate launch scripts/train.py config全量微调用 FSDP——uv run accelerate launch --config_file configs/accelerate/fsdp.yaml scripts/train.py config见 .claude/skills/train-model/phases/launch-and-monitor.md。全量微调model.training_mode: full另有硬性要求需多卡 80GB 档 FSDP且必须开启acceleration.offload_optimizer_during_validation: true全量微调下优化器状态巨大。若用户硬件明显撑不起请求的模式例如单卡 32GB 消费卡跑全量微调计划中必须直说并给出替代方案LoRA、多卡等而不是静默降级。Sanity Check Autotune用两分钟干跑换掉数小时失败模板要求这一节用通俗语言说明机制原文给出了可直接复用的表述在投入完整运行之前我先在目标分辨率下对单个片段做一次快速干跑用约 2 分钟捕获显存溢出OOM或配置错误而不是数小时后才失败然后尝试几个配置变体挑出在你的 GPU 上最快且能跑通的版本。机制要点来自 SKILL.md Phase 61 个样本、完整目标分辨率、50 步 1 次验证临时配置把data.preprocessed_data_root指向overfit/.precomputedoptimization.steps: 50validation.interval: 50checkpoints.interval: nullAutotune 扫描最多 5 次试验每次 当前最优 一个变更遇到首个 OOM 或无改进即停试验 2显存有余则quantization: null关掉 Transformer 量化试验 3有余则optimizer_type: adamw关掉 8bit 优化器试验 4上调batch_size1 → 2 → 4并按比例调低gradient_accumulation_steps保持有效批次不变——但单样本集测不出批次效果小型概念 LoRA 数据集保留batch_size: 1反而更优不扫描分辨率用户决策、load_text_encoder_in_8bit一次性成本、不影响步时、enable_gradient_checkpointing22B 模型关掉梯度检查点即便有几十 GB 余量通常也 OOM32GB 档绝不可关成功判据全部满足无 OOM、无 NaN loss、无崩溃50 步全部完成第 50 步验证样本成功生成验证本身是真实的 OOM 风险点不可跳过音频运行还要确认audio_latents/非空。Loss 不是成功判据——训练健康时 loss 也可能非单调每轮记录步时与峰值显存优先采用训练器自身在运行结束时打印的总时间/步时与峰值 GPU 内存统计追加到workspace/run-name/autotune.log胜出试验的差异 patch 进正式config.yaml并在计划/汇报中按每试验一行 胜者格式总结。基线试验失败时参考 .claude/skills/train-model/references/troubleshooting.md 提出修复并重跑绝不带着失败的 sanity check 进入全量预处理。MonitoringWB 状态与一次性 8bit 标志辨析Monitoring章节只需二选一WB 可用enabled: true记录项目名name、entityentity-or-default训练开始后给出 URLWB 未登录写明训练前运行wandb login以启用跟踪否则训练照常进行但不做远程日志。凭证探测必须用 wandb 自身的凭据解析覆盖环境变量、netrc 与 wandb 配置文件命令为uv run python -c import wandb; print(bool(wandb.Api().api_key)) # True 已登录明确不要用wandb status——它在 netrc 登录时也会误导性地报告api_key: null。若检查报错或结果含糊应询问用户而不是静默关掉跟踪。计划中还应留意两个同名但作用层不同的load_text_encoder_in_8bit标志详见 SKILL.mdThe Twoload_text_encoder_in_8bitFlags一节不要把二者混淆标志作用层效果process_dataset.py --load-text-encoder-in-8bit预处理 CLI打标嵌入预计算阶段Phase 7的显存每数据集一次acceleration.load_text_encoder_in_8bit训练 YAML训练器配置训练启动时验证提示词嵌入缓存Phase 8每运行一次两者都是一次性成本都不影响每步训练速度默认按档位32GB 档 ON、80GB 档 OFF。Outputs产物路径的确定性契约模板固定了训练运行的全部产物位置这正是 SKILL.md 工作区布局Workspace Layout的落地workspace/run-name/ plan.md # 已批准的计划 config.yaml # 生成的训练配置不在 packages/ltx-trainer/configs/ 内 autotune.log # 逐试验扫描结果 dataset/ dataset.json # 打标 媒体路径训练划分 holdout.jsonl # 留出划分如有 videos/ # 源媒体副本不含任何派生文件 .precomputed/ # latents/ audio_latents/ conditions/按模式还有 references/masks outputs/ checkpoints/ # 训练检查点 状态 samples/ # 训练中验证样本step_* eval/ # Phase 9in-distribution/ out-of-distribution/ held-out/ prompts.json run-summary.md # 完成后写入 logs/ # 全部运行日志 overfit/ # Phase 6 临时区单样本预处理 sanity/autotune 运行Outputs章节必须列出四行训练配置config.yaml、检查点目录outputs/checkpoints/、验证样本目录outputs/samples/、Autotune 日志autotune.log。运行名默认格式为mode-dataset-name-YYYYMMDD-HHMM在计划中明示、用户可改。检查点命名规则Phase 2 探测依据lora_weights_step_*.safetensors或model_weights_step_*.safetensors启用恢复状态时还会带配套的training_state_step_*.pt。注意训练器不会从output_dir自动恢复——恢复必须显式设置model.load_checkpoint详见下文 Assumptions 与 config-patching。Assumptions把所有静默默认值摆上台面Assumptions是模板明令永不塌缩的两个章节之一。它要求列出 Agent 静默选择的每一个非平凡默认值用户只需回复新值即可覆盖。典型条目包括精度mixed_precision_mode: bf16调度器类型scheduler_type: linear可选constant、cosine、cosine_with_restarts、polynomial随机种子seed: 42示例默认验证提示词示例配置自带两条占位提示词风格/概念 LoRA 须至少替换一条为包含触发词的提示词任何含音频生成模态的运行验证提示词必须像训练打标一样描述音频转写语音或刻画音效如gentle clicking of keyboard keys否则音频分支得不到引导检查点保留策略checkpoints.keep_last_n示例-1 全保留、保存精度bfloat16默认文件更小或float32WB 项目名 / 输出目录等次要默认值。Ask-vs-Assume速查表SKILL.md给出了边界精度/量化/优化器/梯度检查点从匹配的 VRAM 档位推断并列入 Assumptions目标分辨率/帧数、步数、LoRA 触发词、模型路径等必须询问任何能用ls、nvidia-smi或 WB 凭据检查回答的问题绝不询问、直接探测。若某个章节暴露出还需要再问用户一个问题先停下问完再定稿计划——计划是最后一道门禁不是第一道。Cost / Time Estimate只写能落地的估算模板对这一节立下了最严格的事实纪律直接对应 Hard Invariant #5不得编造训练结果或数据充分性预测只给出能站得住脚的估算未实测的一律标注(rough)在 sanity check 实测出真实步时之前不得声称确定的训练时长——必须写训练时长待 sanity check 测出步时后确定TBD并在其后填入实测步时 × 步数各子项打标~duration (rough)、预处理~duration (rough)、sanity check autotune~duration (rough)、完整训练sanity check 之后实测总墙钟估算在步时测出前一律为 roughsanity check 后精化。这与 Phase 8 状态汇报的 ETA 规则一脉相承ETA 只能用训练器实际输出的数字计算即(总步数 - 当前步数) × 近期稳态平均步时并剔除一次性开销模型加载、第 0 步验证、周期性验证在真实步时出现前报告measuring step time…而非猜测。Approve to Proceed批准即开工模板的收尾章节写明回复approve或带修改意见即开始在批准之前不打标、不预处理、不自动调参、不训练。这与 Hard Invariant #2未经计划批准不做重型工作互为表里。编写计划的原则与事实纪律模板末尾的 Notes on Writing the Plan 给出了三条写作原则可作为任何训练计划的质量检查清单用数字不用形容词~3 hours胜过fairly long把每个若出错就会浪费用户时间的假设都摆出来宁可多列用户可快速略读若某章节暴露出需要追问的问题先停下再定稿若用户硬件撑不起所请求的模式要在计划中直说并提出替代方案LoRA、多卡等而不是静默降级。此外结合 SKILL.md 的 Hard Invariants计划本身还受以下纪律约束不变量 #1运行工作区之外不进行任何文件变更工作区为./projects/run-name/不得静默覆盖/移动/删除用户文件不变量 #3无静默假设——每个非平凡默认都出现在计划的 Assumptions 中不变量 #4未经明确同意不得改动packages/ltx-trainer/代码——意图映射不到受支持配置时走 Escape Hatch典型改动是 flexible.py 中新增Condition子类 config.py 的 schema 接线先征得用户同意再动代码不变量 #5不得断言训练效果会如何数据集是否太小多少秒音频才够之类的预测——只陈述可证实的事实训练器/文档实际说明、观测数字loss、步时、显存、数量与用户自己陈述的目标。从计划到运行的闭环一份合格的plan.md获批后会按以下链路闭环执行对应各阶段程序文档Phase 5 数据准备把媒体暂存到dataset/videos/用符号链接或副本路径相对dataset.json所在目录长视频用split_scenes.py切场景--filter-shorter-than 2s过滤短于 2 秒的场景--min-scene-length是整数帧数不是秒数打标先做 3 样本抽查并硬性等待用户批准再做全量详见 phases/prepare-dataset.mdPhase 6 sanity autotune如前所述在overfit/临时区单样本干跑并扫描Phase 7 全量预处理process_dataset.py按计划中的分辨率桶生成.precomputed/已有.precomputed/时先校验张量形状与模态覆盖不匹配则停下询问绝不静默覆盖Phase 8 启动与监控单卡uv run python scripts/train.py config多卡uv run accelerate launch ...后台运行时必须传--disable-progress-barsRich 进度条用回车覆写单行、不向重定向日志冲刷可解析换行训练结束写入outputs/run-summary.md详见 phases/launch-and-monitor.mdPhase 9 训练后验证用最终 LoRA 对分布内 / 分布外 / 留出三类提示词渲染仅向用户呈现结果路径不索取评判结论详见 phases/post-train-validate.md。贯穿全程的一个关键事实训练器不从output_dir自动恢复。恢复中断运行的唯一方式是 patchconfig.yaml的model.load_checkpoint指向最新检查点文件配套的training_state_step_*.pt必须与检查点同目录恢复优化器/调度器/步数状态只想加载权重而跳过状态恢复则设checkpoints.no_resume: true。这些恢复语义应在计划的 Assumptions 或备注中说明避免运行中断后误判。最后提醒训练配置的 schema 是 Pydantic 且extraforbid——未知字段会被直接拒绝任何对config.yaml的字段级修改都应遵循 config-patching.md 的补丁工作流与自检清单路径存在性、帧数/分辨率约束、生成模态有匹配潜变量目录、条件模式有 references/masks 目录在train.py启动前完成校验——启动前的失败远比启动后的失败便宜。输出文章【免费下载链接】LTX-2Official Python inference and LoRA trainer package for the LTX-2 audio–video generative model.项目地址: https://gitcode.com/GitHub_Trending/lt/LTX-2创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考