LTX-2 ltx-pipelines 推理管线完全指南从 Pipeline 选型、引导策略到生成关键帧的源码级解析【免费下载链接】LTX-2Official Python inference and LoRA trainer package for the LTX-2 audio–video generative model.项目地址: https://gitcode.com/GitHub_Trending/lt/LTX-2ltx-pipelines是 LTX-2 音频-视频生成模型的官方推理管线集合所有管线实现位于 packages/ltx-pipelines/src/ltx_pipelines/依赖ltx-core提供模型定义、扩散组件与加载逻辑。本文以仓库维护文档 packages/ltx-pipelines/CLAUDE.md 为骨架结合utils/blocks.py、utils/denoisers.py、utils/constants.py、utils/samplers.py等源码实现系统讲解 10 条管线的选型依据、三类引导机制CFG/STG/模态引导、Sigma 调度与步数约定、LoRA 使用规范、共享构建块的内存生命周期管理、去噪器实现原理以及生成关键帧这一降低时间压缩的特殊能力。读完本文你将掌握如何在文本/图像/音频/关键帧等不同输入条件下选择正确的管线、理解每一步去噪与引导的底层机制并能直接上手配置 CLI 参数与 LoRA。一、Pipeline 选型一张表看懂 10 条推理管线CLAUDE.md 用一张选型表概括了当前仓库中全部管线的适用场景。下表完整继承自该文档并补充了文件位置信息Pipeline文件Stages模型采样器适用场景TI2VidOneStagePipelineti2vid_one_stage.py1FullEuler简单文本/图像生成视频T2AOneStagePipelinet2a_one_stage.py1FullEuler文本生成音频纯音频输出无视频分支TI2VidTwoStagesPipelineti2vid_two_stages.py2Full 蒸馏 LoRAEuler生产级质量TI2VidTwoStagesHQPipelineti2vid_two_stages_hq.py2Full 蒸馏 LoRA两个阶段Res2s最高质量、步数更少A2VidPipelineTwoStagea2vid_two_stage.py2Full 蒸馏 LoRAEuler音频条件生成视频KeyframeInterpolationPipelinekeyframe_interpolation.py2Full 蒸馏 LoRAEuler关键帧插值DFRPipelinedfr_pipeline.py2可选 tiled temporal关键帧槽 SFT 蒸馏 LoRA 可选 stage 2 细节 IC-LoRAEuler关键帧槽 → 空间细节化 → 可选时间 2 倍上采样DistilledPipelinedistilled.py2仅蒸馏模型Eulerstage 1 在 2.5 用 ancestral最快推理ICLoraPipelineic_lora.py2仅蒸馏模型Euler带 IC-LoRA 控制的视频到视频DubItPipelinedubit.py2仅蒸馏模型Euler带 IC-LoRA 与参考音频条件的配音RetakePipelineretake.py1Full 或蒸馏模型Euler视频区域重生成选型时遵循三条主线是否蒸馏Full 模型需要更多步数、带引导蒸馏模型用固定 8 步调度、无引导参数、是否两阶段stage 1 半分辨率生成 stage 2 空间 2 倍上采样精修、输入模态文本/图像、音频、关键帧、参考视频、参考音频。需要强调蒸馏与非蒸馏在 API 上有关键差异蒸馏管线没有num_inference_steps参数固定 8 步详见下文 Sigma 调度章节。关于模型路径组织可参考 docs/pipeline-selection.md多 GPU 变体*_mgpu.py的选型与部署见 docs/multigpu/README.md。二、三类引导机制CFG、STG 与模态引导所有非蒸馏管线的 stage 1 都支持三类引导stage 2 一律使用SimpleDenoiser不做引导CFGClassifier-Free Guidance将条件预测与无条件预测按权重混合。默认值为cfg_scale3.0视频、7.0音频。CLAUDE.md 中的这些默认值对应 utils/constants.py 中PipelineParams的MultiModalGuiderParams定义视频与音频的 guider 参数各自独立video_guider_params/audio_guider_params。STGSelf-Temporal Guidance扰动 transformer 块中的自注意力。默认stg_scale1.0STG 作用块为stg_blocks[28]LTX-2.3 及 2.4或[29]LTX-2。在 constants.py 中可以看到LTX-2 默认stg_blocks[29]而LTX_2_3_PARAMS通过replace(..., stg_blocks[28])覆盖为 28。HQ 管线显式关闭 STGstg_scale0.0、stg_blocks[]见LTX_2_3_HQ_PARAMS。模态引导Modality Guidance跨模态注意力缩放modality_scale3.0通过a2v_guidance_scale音频→视频与v2a_guidance_scale视频→音频分别控制另有rescale_scaleCFG 后的重缩放系数LTX-2 默认 0.7HQ 视频 0.45、音频 1.0与skip_step跳过引导的起始步数。2.1 参数从 CLI 到 guider 的传递以 ti2vid_one_stage.py 的main()为例CLI 的--video-cfg-guidance-scale、--video-stg-guidance-scale、--video-rescale-scale、--a2v-guidance-scale、--video-skip-step、--video-stg-blocks等参数被组装为MultiModalGuiderParams再通过create_multimodal_guider_factory生成按 sigma 分段的 guider 工厂。从源码结构看MultiModalGuiderParams定义于 packages/ltx-core/src/ltx_core/components/guiders.py是引导参数的统一载体。2.2 引导 pass 的批量化一次 transformer 调用完成多路预测这是引导机制最值得注意的实现细节见 utils/denoisers.py 的模块级_guided_denoise函数引导去噪器将所有引导 pass 合并进单次 transformer 调用——states 沿 batch 维重复contexts 拼接用BatchedPerturbationConfig控制每个样本跳过哪些 attention 算子。Pass 数量是动态的仅 CFGB2cond uncondCFG STG追加 ptb pass扰动视频/音频自注意力通过PerturbationType.SKIP_VIDEO_SELF_ATTN/SKIP_AUDIO_SELF_ATTNCFG STG 模态隔离最多 B4追加 mod pass通过SKIP_A2V_CROSS_ATTN/SKIP_V2A_CROSS_ATTN跳过跨模态注意力结果按 pass 切分回all_v.chunk(n)后由 guider 的calculate(cond, uncond, ptb, mod)混合。PerturbationConfig会在初始化时基于transformer.num_blocks预计算逐块 mask 张量编译后的前向把扰动当作运行时张量而非在图中查询 config避免不同扰动配置触发重编译。2.3 无条件 pass 的强制开关GuidedDenoiser与FactoryGuidedDenoiser都接受force_uncond_passTrue即使在cfg_scale1.0时也运行无条件 pass。这是 CFG 采样器见下文采样器章节的硬性要求——引导强度为 1 时 ODE 导数仍需要无条件预测。前提是 guider 已设置negative_context开启后DenoisedLatentResult.uncond会从None变为实际张量。默认负向提示词模板定义在 utils/constants.py 的DEFAULT_NEGATIVE_PROMPT中。三、Sigma 调度与步数约定3.1 基于调度器的完整模型非蒸馏管线持有self._scheduler LTX2Scheduler()定义于 packages/ltx-core/src/ltx_core/components/schedulers.py通过execute(stepsN)生成 sigma 序列默认步数30 步LTX-2.3 与 2.4、40 步LTX-2、15 步HQHQ 在execute(stepsN)时还会传入latent使 sigma 调度依赖 token 数量temporal 维度越长shift 越大在PipelineParamsconstants.py中可以看到这些默认值num_inference_steps40LTX-2、302.3/2.4、15HQ且 stage_1 分辨率默认 1088/2 × 1920/2即半分辨率 544×960Retake 默认num_inference_steps40当distilledTrue时忽略该参数固定 8 步3.2 蒸馏模型固定 sigma 值无步数参数蒸馏管线使用写死的 sigma 常量见 utils/constants.pyDISTILLED_SIGMA_VALUES [1.0, 0.99375, 0.9875, 0.98125, 0.975, 0.909375, 0.725, 0.421875, 0.0] # 9 个值 → 8 步 STAGE_2_DISTILLED_SIGMA_VALUES [0.909375, 0.725, 0.421875, 0.0] # 4 个值 → 3 步Stage 1DISTILLED_SIGMAS8 步Stage 2STAGE_2_DISTILLED_SIGMAS3 步用于半分辨率→全分辨率的上采样精修多 GPU TDP runner 另有TDP_DISTILLED_SIGMAS [0.625, 0.4, 0.0]2 步蒸馏管线没有num_inference_steps参数因为步数由 sigma 序列长度决定3.3 逐调用覆盖Overrides所有管线在__call__中都接受可选的 sigma 张量覆盖单阶段管线传sigmas两阶段管线传stage_1_sigmasstage_2_sigmas。例如DistilledPipeline.__call__的签名中这两个参数默认就是DISTILLED_SIGMAS与STAGE_2_DISTILLED_SIGMAS见 distilled.py。3.4 采样器实现全景所有去噪循环集中在 utils/samplers.pyeuler_denoising_loop确定性一阶 Euler最通用。DiffusionStage的默认stepper就是EulerDiffusionStep()见 blocks.py 第 526-527 行。res2s_audio_video_denoising_loop二阶 Res2sRK2采样器步内先在中间点评估带 SDE 噪声注入substep 固定 eta0.5再以 RK 系数合并两端评估支持锚点精化bongmath当步长 h0.5 且 sigma0.03 时迭代至多 100 次主步噪声注入由eta控制默认 0.50 为确定性1 为最大随机性子步种子默认noise_seed 10000。HQ 管线两阶段均使用该采样器。euler_ancestral_denoising_loop祖先SDEEuler每步先确定性走到sigma_down再按方差保持比例重新加噪eta0时退化为普通 Euler。LTX-2.5 的蒸馏 stage 1 使用它。euler_cfg_pp_denoising_loopCFG 修正 EulerODE 导数基于无条件预测而非标准速度在缩放后的 sigma 空间做祖先 DDIM 加噪要求DenoisedLatentResult.uncond为张量。gradient_estimating_euler_denoising_loop梯度估计采样用ge_gamma默认 2.0修正速度项。四、LoRA 约定CLAUDE.md 明确了以下 LoRA 规则无默认 LoRAloras参数默认是空列表/空元组DEFAULT_LORA_STRENGTH 1.0constants.py 第 117 行。两阶段非蒸馏管线要求distilled_lora且该 LoRA只作用于 stage 2TI2Vid、A2Vid、Keyframe 皆是如此。HQ 例外对两个阶段都施加蒸馏 LoRA并分别用distilled_lora_strength_stage_1/distilled_lora_strength_stage_2控制强度。DFR 例外stage 1及 temporal rounds共享同一 stage 对象施加蒸馏 LoRA强度 1.0stage 2 可通过with_loras附加细节化 IC-LoRA默认无需--detailing-lora显式开启。从源码层面看LoRA 以LoraPathStrengthAndSDOps元组形式传入DiffusionStage.from_checkpoint(..., loras...)。DiffusionStage还提供函数式 APIwith_loras(loras)/with_builder(builder)返回换掉 LoRA 集合或 builder 的新 stage 实例无需重新指定其他配置见 utils/blocks.py。CLI 通过LoraAction解析--lora PATH [STRENGTH]args.py 第 153-173 行LoRA 的 state-dict 键映射使用LTXV_LORA_COMFY_RENAMING_MAP。五、共享构建块每个块自管模型生命周期所有管线都由 utils/blocks.py 中的共享块拼装而成。核心设计哲学写在该文件 docstring 中每个块在__call__时构建模型、用完即释放替代了过去每条管线手写del model; cleanup_memory()的重复模式。5.1 DiffusionStage——transformer 生命周期的所有者DiffusionStage持有预构建的 transformer builder在调用时构建模型、退出时通过gpu_model()上下文管理器释放将参数移到meta设备立即释放存储AllocatorTrimStrategy.TRIM还会执行cleanup_memory()清理 CUDA 缓存。入口管线通常用类方法DiffusionStage.from_checkpoint(checkpoint_path, ..., loras...)构造——它把 checkpoint 路径 LoRA 集合转换成标准SingleGPUModelBuilder当offload_mode ! OffloadMode.NONE时换成StreamingModelBuilder流式/块流式路径。model_configurator/model_sd_ops允许调用方如纯音频 T2A 管线覆盖模型类配置器与 state-dict 键映射量化策略若自带 configurator 则优先于传入值。可组合性with_attention(...)钉住某种 attention kernel、with_builder(...)、with_loras(...)均为函数式 API不修改自身。__call__默认行为loop默认为euler_denoising_loopstepper默认为EulerDiffusionStep()可传stepper与loop覆盖蒸馏的 ancestral 采样就是这么注入的。内部用VideoLatentTools/AudioLatentTools构造加噪状态包上BatchSplitAdapter后执行联合音视频去噪循环最后clear_conditioningunpatchify返回干净的 latent。5.2 PromptEncoder——Gemma 文本编码器 嵌入处理器加载 Gemma 文本编码器视频 4096 维、音频 2048 维嵌入可选地对首个 prompt 做增强enhance_first_prompt然后经 embeddings processor 输出。增强与编码可共享同一 checkpoint同一 builder 别名或分离prompt_enhancer_gemma_root指向独立的生成式 instruct checkpoint如 gemma3/gemma4 E2B-it此时增强器与编码器顺序加载。编码根模型的model_type必须在{gemma3, gemma4, gemma4_unified}集合内。文本编码器也支持流式卸载StreamingModelBuilder。5.3 ImageConditioner / AudioConditioner——临时编码器作用域构建视频/音频编码器 → 调用传入的可调用对象 → 释放。ImageConditioner还是图像条件 H.264 CRF 的唯一决策者resolve_crf(images)每条管线__call__开头都会调用读取 checkpoint 的model_versiondetect_params惰性且缓存为任何未设 CRF 的ImageConditioningInput补上默认值。因此省略crf 使用与该模型匹配的值LTX-2.3 及更早为33DEFAULT_IMAGE_CRF2.4 起为18LTX_2_4_IMAGE_CRF显式传crf包括0 不重新压缩则始终被尊重这一逻辑在 utils/constants.py 与 utils/args.pyImageConditioningInput的crf: int | None None中均有体现。5.4 VideoUpsampler——2 倍空间上采样视频编码器 潜在空间上采样器LatentUpsamplerConfigurator/upsample_video两阶段管线的 stage 2 用它把半分辨率 latent 放大到全分辨率。5.5 VideoDecoder / AudioDecoder——latent 到像素VideoDecoder接收单一解码器checkpoint_path与diffvae_optimizationDiffVAEMode默认CHUNKED_EAGER返回迭代器逐块解码迭代耗尽后自动释放解码器_cleanup_iter包装。解码器类型conv vs diffusion由 checkpoint 元数据is_diffusion_video_vae决定蒸馏型 DiffVAE 使用固定的 2 步 Euler 解码。解码可传tiling_config自动分块、generator与dtype覆盖如 HDR 场景传 float32。AudioDecoderVAE 解码器 vocoder。vocoder 始终以 fp32 运行bf16 累积会劣化频谱指标CUDA/CPU 上以 bf16 存储并在每个算子处 autocast 提升MPS 上直接 fp32 存储。CLI 中--video-vae-path同时是单体与拆分模式下视频 VAE 的槽位可选覆盖默认经ModelPaths.from_monolith解析--diffvae-optimization各模式的编译/运行/显存含义见 docs/optimization.md#diffusion-vae-decoder。多 GPU 管线*_mgpu.py接受相同参数并把解码器包装进DistributedVideoDecoder。5.6 DurationPredictor——自动时长预测通过ltx_core.duration_head的DurationHead从PromptEncoder的连接器 token 输出预测帧数再对齐到 VAE 的时间网格8k 1。与其它块不同它直接持有模型而非按需构建释放DurationHead 只有几 MB无需 build-on-call/free-on-exitfrom_checkpoint返回None当 checkpoint 不含duration_head.*权重时即 LTX-2.5 / gemma4 之前的 checkpoint。调用约定(video_encoding, audio_encoding, frame_rate...)两者可为None但不能同时为None。预测秒数默认被夹在[min_seconds1.0, max_seconds20.0]结果折算帧数并对齐 VAE 网格seconds_to_clamped_num_frameshelpers.py 第 565-585 行。已接入TI2VidOneStagePipeline、TI2VidTwoStagesPipeline、TI2VidTwoStagesHQPipeline、DistilledPipeline、DFRPipeline、T2AOneStagePipeline纯音频video_encodingNone及其 MGPU runnerrequire_num_frames_source__call__最开头、任何工作之前调用当num_framesNoneAutoDuration且没有可用的DurationPredictor时立即抛出避免在无谓的工作之后才发现不可行两阶段管线及其 MGPU runner 会把解析后的num_frames作为__call__返回元组的第三个元素调用方据此计算get_video_chunks_number用于进度条无需复制自动时长的回退逻辑CLI 侧由--auto-duration MIN_SECONDS MAX_SECONDS触发AutoDurationActionargs.py 第 108-122 行六、内存管理模型生命周期、块流式与批切分6.1 模型生命周期所有块都是调用时构建、退出时释放无模型在调用间驻留。gpu_model()在退出时把参数移到meta设备立即释放存储——这消除了手工del的样板代码也让单条进程可以串行跑完文本编码→扩散→解码的完整链路而不会峰值显存叠加。6.2 块流式Block Streaming启用卸载offloading时DiffusionStage把 transformer 包装进BlockStreamingWrapperltx_core.block_streaming块常驻固定 CPU 内存同一时刻 GPU 上只缓冲2 个块一个用于计算一个用于在独立 CUDA 流上异步 H2D 拷贝。StreamingModelBuilder通过cpu_slots_count选择内存流式还是磁盘流式DISK_CPU_SLOTS对应OffloadMode.DISK。_streaming_model上下文管理器保证teardown()一定执行释放前向 hooks、磁盘 I/O 工作线程、打开的文件句柄等 GC 不会及时回收的非内存资源。注意限制WeightsProvider目前只支持 bf16 与 fp8_cast 两种 LoRA 融合规则产生伴生键如.weight_scale的量化策略尚不能流式化——from_checkpoint会在量化策略不是fp8_cast_fuse_rule时直接抛错。6.3 批切分Batch SplittingBatchSplitAdapterltx_core.batch_split包装 transformer把超过max_batch_size的输入切分成顺序子块例如引导需要 B4 但max_batch_size1则跑 4 次串行的 B1 前向。增大max_batch_size能减少层流式的 PCIe 传输次数但会抬高峰值显存——这是流式卸载场景下显存与带宽的经典权衡。七、去噪器三种实现的职责划分所有去噪器返回(video_result, audio_result)元组元素类型为DenoisedLatentResult定义于 utils/types.py任一模态可为None。DenoisedLatentResult.denoised是最终混合张量引导型去噪器还会填充逐 pass 字段.cond、.uncond、.ptb、.modSimpleDenoiser将这些字段留为None。去噪器行为使用管线SimpleDenoiser单次前向B1无引导所有蒸馏管线 所有 stage 2GuidedDenoiser静态MultiModalGuider实例CFG/STGHQ、A2Vid、Retake非蒸馏FactoryGuidedDenoiser按步 sigma 经工厂创建 guiderOneStageTI2Vid、TwoStagesTI2Vid、Keyframe实现要点utils/denoisers.py三者都遵循Denoiser协议denoiser(transformer, video_state, audio_state, sigmas, step_index)transformer 在调用时传入而非存储在去噪器上。缺失模态用模块级_POSITIVE_ONLY_GUIDER替换cfg_scale1.0, stg_scale0.0, modality_scale1.0只跑条件 pass 且原样返回 cond。引导去噪器内部共享_guided_denoise上文 2.2 节已述每次调用后缓存last_denoised若某步 guider 判定跳过should_skip_step直接沿用上一步结果不调用 transformer。FactoryGuidedDenoiser首次调用时把 sigma 序列缓存到 CPU之后按step_index取出标量经工厂build_from_sigma生成对应 guider——支持按 sigma 分段使用不同引导强度的调度策略。八、各管线独有特性8.1 HQ最高质量预设两阶段均使用Res2s 二阶采样器latent 依赖的 sigma 调度execute(steps15, latent...)token 数越多 shift 越大蒸馏 LoRA 同时用于两个阶段强度分别由distilled_lora_strength_stage_1/_stage_2控制关闭 STGrescale_scale视频 0.45 / 音频 1.08.2 A2Vid音频冻结音频在两个阶段都冻结frozenTrue, noise_scale0.0——这会把denoise_mask置零并强制音频Modality.sigma0对应 prompt AdaLN / a2v gate见 helpers.py 中modality_from_latent_state对state.frozen的处理。返回原始音频不经过AudioDecoder即音频来自输入而非生成因此管线内没有AudioDecoder。8.3 IC-LoRA参考视频控制使用VideoConditionByReferenceLatentreference_downscale_factor从 LoRA 元数据读取支持skip_stage_2并对参考特征做 attention mask 下采样。Stage 2不使用 IC-LoRA条件改用combined_image_conditionings即普通图像条件。8.4 Dub-It参考音频配音独立管线IC 参考视频辅助函数在 iclora_utils.pyDub-It 专用的音频 patchify 与负位置逻辑在 dubit.py。通过AudioConditionByReferenceLatentltx-core追加冻结的参考音频 tokentoken 顺序与视频一致[target | ref]同时保持参考 RoPE 位置为负与训练兼容。单一 IC-LoRA 同时用于两个阶段stage 2 音频以 stage 1 latent 为初始状态并冻结使用 stage 1 派生的参考最终音频从 stage 1 latent 解码。注意Dub-It CLI 不暴露--conditioning-attention-mask需要空间 IC attention 掩码时请改用 ic_lora.py。8.5 Keyframe全帧关键帧引导两阶段都使用image_conditionings_by_adding_guiding_latent所有图像都作为关键帧引导不做替换——这与 TI2Vid 的combined_image_conditioningsframe_idx0的图像替换 latent其余引导形成对照。两函数的差异见 utils/helpers.py。8.6 Retake时间窗口重生成TemporalRegionMask实现选择性时间窗口重生成配regenerate_video/regenerate_audio开关支持条件化的蒸馏/完整模型行为切换。8.7 Distilled最快推理单个self.stage复用于两个阶段而非stage_1/stage_2两个对象Stage 1 采样器在__init__中根据 checkpoint 代数解析should_use_ancestral_sampler(path)即detect_model_version(...) (2, 5)设置self.use_ancestral_samplerLTX-2.5 使用EulerAncestralDiffusionStep(eta1.0, s_noise1.0)参考采样器自身的默认值euler_ancestral_denoising_loop更早的 checkpoint 保持普通 Euler。相关常量见 distilled.pyANCESTRAL_SAMPLER_SINCE_VERSION (2, 5)、ANCESTRAL_ETA 1.0、ANCESTRAL_S_NOISE 1.0。没有逐调用覆盖想固定采样器需在调用前给实例赋值use_ancestral_sampler例如在同一 checkpoint 上做 A/B 对比。distilled_mgpu.py对每个 rank 从同一 checkpoint 独立检测保证各 rank 对称。Stage 2 永远是普通 Euler——它的 3 步调度太短无法消除新注入的噪声见_stage_1_sampler_kwargs的注释。去噪循环的噪声种子带偏移ANCESTRAL_NOISE_SEED_OFFSET 10000使其第一次抽样的噪声与初始GaussianNoiser的噪声不逐位相同否则两者会在相同形状/dtype/设备上从全新种子生成器各抽一次torch.randn得到完全相同的结果。8.8 DFRDiffusion Fidelity Renderingdfr_pipeline.py 侧车 dfr_layout.py基于关键帧槽 SFT 底座蒸馏 LoRA强度 1.0的蒸馏调度管线。Stage 1半分辨率在x8 边界段网格上生成视频 关键帧槽把(num_frames - 1)向上取整到 S 的倍数优先 S32除非 S24 时 padding 更少槽位置为S, 2S, …, N-1。半分辨率视频预留给 IC-LoRA视频与槽关键帧都做空间 latent 上采样。Stage 2联合去噪使用蒸馏 LoRA 可选 x2 细节化 IC-LoRA无默认需--detailing-lora开启在预留的半分辨率 stage-1 视频上使用VideoConditionByReferenceLatentsigma 用STAGE_2_DISTILLED_SIGMAS。交付的音频是 stage 1 的stage 2 仍跑音频 pass视频需要跨模态注意力但在细节化 LoRA 下对音频重新加噪且 temporal rounds 传audioNone之后不再精化。可选temporal_upsample_rounds0–2每轮做时间 2 倍上采样划分成2**round个关键帧接缝瓦片非首瓦片带一段 lead-in为每瓦片发明段中槽并用 ancestral Eulerη0.5加密。_TEMPORAL_ANCESTRAL_ETA 0.5、_MAX_CONDITIONING_FPS 60.0定义在 dfr_pipeline.py。接触 temporal rounds 前必须知道的三个不变量接缝交接恰好在共享关键帧处瓦片的 local latent 0 是图像latent1 像素帧local latent 1 是相对它去噪的——两者都不能被拼进中画布流。较早的瓦片保留到其尾接缝 latent较晚的瓦片在 KF 之后严格续接drop_latent_prefix覆盖 lead-in 共享接缝。在 KF之前交接会丢失同步点表现为接缝前出现跳变。条件 fps 上限 60_MAX_CONDITIONING_FPS与播放 fps 无关。RoPE 时间是pixel_frame / fps120 fps 的时间基准会把每个 token 的时间跨度减半相对训练分布模型无法再在 latent 内排布 8 个像素帧——会解码成每个 8 帧 latent 边界处的运动尖峰 停滞。只有解码/编码使用播放 fps。图像条件按瓦片局部解释frame_idx0指的是该瓦片的首帧因此在非首瓦片上重贴开场图会钉错接缝处的帧只有落在窗口内的图像才会被重新附着并重映射为局部索引。画布与输出契约画布可能把尾部 padding 到整段但调用方总是拿到(requested_frames - 1) * 2**rounds 1帧——多余部分在解码前裁掉总在 latent 边界上因为requested - 1是 VAE 时间尺度的倍数音频裁到视频时长。CLI 参数--detailing-lora、--temporal-upsampler-path、--temporal-upsample-rounds没有--num-generated-keyframesDFR 固定使用 x8 边界段网格槽由dfr_layout.resolve_canvas决定。九、图像条件辅助函数utils/helpers.py 提供三种图像条件构建方式combined_image_conditionings()frame_idx0的图像替换latentVideoConditionByLatentIndex其余引导VideoConditionByKeyframeIndex。TI2Vid 系列与 Distilled 使用。image_conditionings_by_adding_guiding_latent()所有图像无论frame_idx都变成关键帧引导。Keyframe 管线使用。image_conditionings_by_replacing_latent()所有图像都替换对应latent_idx的 latent源码中存在但 CLAUDE.md 未提及从源码结构看属于补充路径。evenly_spaced_keyframe_positions()生成等间距的内部位置两端点排除——torch.linspace(0, num_frames - 1, num_keyframes 2)[1:-1]。十、生成关键帧Generated Keyframes用 token 换时间分辨率生成关键帧是降低有效时间压缩的可选能力在内部帧位置追加空的、已完全去噪的单像素帧 token 槽让模型在这些位置额外生成帧。大多数管线默认关闭需要 checkpoint 的 transformer config 设置use_keyframes_abs_pos_embeddingDiffusionStage.supports_generated_keyframes从 checkpoint 配置读取见 utils/blocks.py。槽可携带initial_keyframeslatent 种子写入追加的latenttokendenoise_mask1仍生效。位置与 API第一阶段TI2VidOneStagePipeline、TI2VidTwoStagesPipeline、TI2VidTwoStagesHQPipeline、DistilledPipeline、DFRPipeline及三个*_mgpurunner。TI2Vid/Distilled 的stage 2 永远不加槽效果已烘进 stage-1 latentDFR 是例外——stage 2 重新附加带种子的槽空间上采样的 stage-1 KF latent可选 tiled temporal rounds 再为每瓦片附加段中槽。API 形态generated_keyframes: int | Sequence[int] 0TI2Vid/Distilled 的__call__参数——int请求等间距内部关键帧序列给出显式索引。CLI--num-generated-keyframes经add_generated_keyframes_arg添加。resolve_generated_keyframes/generated_keyframe_conditionings在 utils/helpers.py 负责把参数归一化为像素帧索引并生成VideoGeneratedKeyframeSlots条件所有槽放进单个 slots 对象token 构成连续、可精确定位的一段。校验与代价__call__在请求槽但 checkpoint 不支持时直接抛错assert_generated_keyframes_supported在构建任何模型之前失败——每个关键帧要花一整帧 latent 的 token静默降级会浪费16%–31% 的 token 预算。具体代价每个关键帧消耗一个 latent 帧的 token产出 1 个像素帧而非 8 个512×768/241f 下 5 个关键帧约 16% token注意力约 1.35 倍1088×1920/121f 下为 31%约 1.72 倍。读回关键帧LatentState.generated_keyframes形状(B, C, K, H, W)由clear_conditioning依据记录在 state 上的generated_keyframe_layout精确提取非位置切片。管线外部可把RecordingDiffusionStage替换到pipeline.stage上blocks.py 第 585-621 行调用一次后从pipeline.stage.generated_keyframes读取——它委托所有其它属性给被包装的 stage因此替换后仍可在原位置使用。解码时每个关键帧作为独立的单帧片段解码K 帧因果解码会混合从未相邻的槽。诊断脚本见internal/scripts/generated_keyframe_diagnostics.py仓库未内置文档所述。两个不变式槽是追加的在 B1 下同种子 keyframes/无 keyframes 的 A/B 对比能保持目标噪声一致槽传attention_maskNone稠密(B, T, T)掩码在 30k token 时约 1.8 GB且会禁用 FA3/FA4。十一、关键默认参数速查以下默认值来自 utils/constants.py 的PipelineParams与各代参数集可直接作为调参起点参数LTX-2LTX-2.3 / 2.4HQ2.3num_inference_steps403015视频cfg_scale3.03.03.0音频cfg_scale7.07.07.0stg_scale1.01.00.0关闭stg_blocks[29][28][]modality_scale3.03.03.0rescale_scale视频/音频0.7 / 0.70.7 / 0.70.45 / 1.0默认图像 CRF33332.4 为 18由 checkpoint 解析参数检测机制detect_params(checkpoint_path)读取 safetensors 元数据的model_version字段返回该版本及以上最新一代的参数集_PARAMS_SINCE_VERSION表中(2,4)、(2,3)两条未设置/不可读时回退到LTX_2_PARAMS2.4从2.3派生保留 30 步与 STG 块 28仅移动图像 CRF。这就是 CLAUDE.md 所述2.4 继续 2.3 血统的代码依据。十二、维护约定仓库要求修改 src/ltx_pipelines/ 下任何管线类时同步更新 CLAUDE.md 以反映以下变更——__init__/__call__签名、sigma 处理或步数、去噪器类型或引导、新增或移除的管线并用ls src/ltx_pipelines/*.py检查新管线文件。本文所述的选型表、引导默认值、sigma 约定与各管线独有特性均以该文档与当前仓库源码为准。【免费下载链接】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），仅供参考