LTX-2 视频生成 Conditioning 完全指南图像/视频/EXR 条件注入与生成关键帧槽位机制【免费下载链接】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 官方推理仓库中 conditioning.md 为核心系统讲解ltx-pipelines各管线支持的图像、视频与 HDR/EXR 条件输入方法以及「生成关键帧槽位Generated Keyframe Slots」这一缓解时间压缩瓶颈的高级机制。读完本文你将掌握替换式/引导式图像条件的取舍、IC-LoRA 参考视频条件的注入原理、--hdrEXR 条件输入的 CLI 用法以及generated_keyframes的代价模型、适用管线与结果读取方式。1. Conditioning 在 LTX-2 推理体系中的位置在 LTX-2 中「Conditioning条件注入」指在扩散去噪开始之前把外部控制信号图像、视频、HDR 静态帧等写入LatentState的机制。ltx-pipelines是高层推理封装负责模型加载、编码、解码与文件 I/O而条件注入的具体数据结构和位置语义全部由底层包ltx-core实现参见 ltx-core conditioning 文档。所有条件注入都收敛到ltx-core中定义的ConditioningItem.apply_to(latent_state, latent_tools)接口。ltx-pipelines侧通过 helpers.py 的state_with_conditionings按列表顺序逐个把条件项应用到潜状态上最后交给noiser加噪进入去噪循环def state_with_conditionings( latent_state: LatentState, conditioning_items: list[ConditioningItem], latent_tools: LatentTools ) - LatentState: for conditioning in conditioning_items: latent_state conditioning.apply_to(latent_statelatent_state, latent_toolslatent_tools) return latent_statehelpers.pyLatentState中最关键的两个字段决定了条件的语义types.pyclean_latent去噪前的干净潜变量条件内容写在这里denoise_mask每个 token 的去噪强度1 完全去噪、0 不去噪。条件 token 的掩码被设置为1.0 - strengthstrength越接近 1.0 条件保持越干净越接近 0.0 条件越被重新去噪。2. 图像条件注入替换潜变量 vs 引导潜变量所有管线都支持图像条件注入但方式不同对应的构造函数都在 helpers.py 中。2.1 替换式image_conditionings_by_replacing_latentdef image_conditionings_by_replacing_latent( images: list[ImageConditioningInput], height: int, width: int, video_encoder: VideoEncoder, dtype: torch.dtype, device: torch.device, color_space: HDRColorSpace | None None, ) - list[ConditioningItem]: conditionings [] for img in images: image load_image_and_preprocess(...) encoded_image video_encoder(image) conditionings.append( VideoConditionByLatentIndex( latentencoded_image, strengthimg.strength, latent_idximg.frame_idx, ) ) return conditioningshelpers.py每个输入图像先用video_encoder编码为潜变量然后构造VideoConditionByLatentIndex把编码结果直接写入指定latent_idx潜帧索引对应的 clean_latent 位置。其核心实现latent_cond.pytokens latent_tools.patchifier.patchify(self.latent) start_token latent_tools.patchifier.get_token_count( latent_tools.target_shape._replace(framesself.latent_idx) ) stop_token start_token tokens.shape[1] latent_state.clean_latent[:, start_token:stop_token] tokens latent_state.denoise_mask[:, start_token:stop_token] 1.0 - self.strength注意它不新增任何 token而是就地覆盖既有潜帧的 token 区间因此在序列长度上零开销属于「占位替换」式注入。特点对指定帧有极强的控制力潜变量形状必须与目标一致否则抛出ConditioningError源码中显式校验了 batch/channel/height/width适合「首帧 若干指定帧」这种需要严格锚定的场景。2.2 引导式image_conditionings_by_adding_guiding_latentconditionings.append( VideoConditionByKeyframeIndex(keyframesencoded_image, frame_idximg.frame_idx, strengthimg.strength) )helpers.py引导式改为构造VideoConditionByKeyframeIndexkeyframe_cond.py它把条件当作追加的引导 token而非替换条件 token 被patchify后追加到序列末尾latent里放占位零、clean_latent里放条件内容frame_idx作为位置编码偏移写入positions当num_pixel_frames 1单像素帧时时间跨度被收窄为[start, start1)denoise_mask 1.0 - strength语义与替换式相同。由于引导 token 有自己的 RoPE 位置、与目标帧在时间上相邻模型可以在关键帧之间做平滑插值——这正是「引导」优于「替换」的典型场景替换只锁死单帧引导则让相邻帧的注意力自然过渡。2.3 两者如何选择维度替换潜变量replacing_latent引导潜变量adding_guiding_latent底层类VideoConditionByLatentIndexVideoConditionByKeyframeIndex注入方式就地覆盖既有 token追加新 token序列开销无每个条件增加一帧 token控制力对指定帧极强强且利于帧间平滑过渡典型场景首帧/精确锚定关键帧插值、多图引导另外值得注意在helpers.py中还有一种混合形态create_keyframe_conditionings附近的逻辑——首帧用VideoConditionByLatentIndex替换其余帧用VideoConditionByKeyframeIndex引导helpers.py兼顾首帧锁定与中间帧平滑实际管线中常用此组合。3. 视频条件注入IC-LoRA 参考视频视频条件注入目前仅由 ICLoraPipeline 系列提供用于 video-to-video 变换。它基于ltx-core的VideoConditionByKeyframeIndex以及专门的参考视频类VideoConditionByReferenceLatentreference_video_cond.py。其原理与 IC-LoRA 训练协议严格对齐IC-LoRA 训练时把「参考control signaltoken 目标 token」拼接让模型学会跨两者注意力推理时VideoConditionByReferenceLatent.apply_to复刻这一设置——参考视频潜变量作为 clean_latent 追加进序列latent对应位置放占位零denoise_mask由strength决定1.0 参考保持干净0.0 参考完全重新去噪。该实现还支持训练时使用的降采样参考例如 384px 参考配 768px 目标输出通过两个缩放因子把参考位置映射回目标坐标系downscale_factor目标/参考空间分辨率比如 2 半分辨率参考作用于高度、宽度轴temporal_scale_factor目标/参考时间比 S如 4 参考以 1/4 帧率采样作用于时间轴并在平移后 clamp 回[0, 1/target_fps)。这两个因子必须与 LoRA 元数据中训练时的取值一致否则位置关系错位会导致生成质量下降。参考 token 永远不会被标记为关键帧keyframes_mask置markedFalse——因为参考视频的首个潜帧虽然也覆盖单像素帧但它是条件内容而非生成槽位不能误用关键帧绝对位置嵌入。4. HDR / EXR 条件注入标准管线非 IC-LoRA接受 OpenEXR 静态帧.exr以及 EXR 帧序列文件夹作为图像/视频条件输入前提是用--hdr {SRGB_LINEAR,ACESCG,ACESCCT}声明源色彩空间。HDR 运行会解码输出半精度浮点 EXR 帧外加一条 BT.2020/HLG 母版视频。核心要点色彩空间声明--hdr接受SRGB_LINEAR、ACESCG、ACESCCT三种源色彩空间管线内部通过HDRColorSpace枚举传递到load_image_and_preprocess见 helpers.py 的color_space参数混合限制CLI 上禁止 EXR 与 SDR 输入混用retake 管线还有--frame-rate约束输出格式半精度浮点 EXR 帧保留 HDR 动态范围 BT.2020/HLG 母版方便下游调色与交付。完整的色彩空间语义、CLI 约束与示例请参阅 HDR Support 文档。5. 生成关键帧槽位Generated Keyframe Slots这是 LTX-2 conditioning 体系中最具特色的机制让模型在常规帧网格之外于你指定的内部位置额外生成像素帧。5.1 原理一个槽位 一个空白的完整去噪 token 槽生成关键帧是模型在常规帧网格之外额外产生的帧位于你选择的内部位置。每个槽位是一个空的、完全去噪的 token 槽被追加到序列末尾。关键区别在于一个普通潜帧latent frame编码8 个像素帧一个关键帧槽位只承载1 个像素帧。因此在槽位处有效时间压缩比被放宽——原本该位置 8 帧才分配一个潜帧 token现在 1 帧就分配一整套 token模型得以在运动过快、基础时间分辨率跟不上的地方补充细节。实现类为VideoGeneratedKeyframeSlotskeyframe_slots.py。apply_to的核心动作每个槽位在 RoPE 空间中占据恰好[t, t1)的单像素帧时间跨度_slot_positions显式把时间末边界设为start 1latent追加全零 token或initial_keyframes提供的种子内容clean_latent追加全零denoise_mask置 1让 noiser 从槽位 latent 向噪声插值、由去噪循环生成内容keyframes_mask标记markedTrue——槽位 token 会获得模型学到的关键帧绝对位置嵌入use_keyframes_abs_pos_embedding记录GeneratedKeyframeLayoutpixel_frame_indices、tokens_per_keyframe、first_token用于之后精确抽取槽位结果。GeneratedKeyframeLayouttypes.py专门解决「槽位 token 不一定在序列末尾」的定位问题条件项按列表顺序追加若槽位之外还有其他追加型条件如引导式图像尾部布局就不固定必须靠first_tokennum_tokens精确切片。槽位与普通图像引导VideoConditionByKeyframeIndex是刻意分离的后者追加给定内容、不标记关键帧前者追加空槽位、必须标记。参考实现只对关键帧类条件设置标记普通图像/首尾帧条件不得标记。5.2 前置要求必须有关键帧 checkpointVideoGeneratedKeyframeSlots的类注释明确要求checkpoint 的 transformer 配置必须设置use_keyframes_abs_pos_embedding。原因在于若 checkpoint 未训练该能力学到的「关键帧标记」不存在槽位会被当作未标记 token去噪额外算力被白白浪费因此管线在开头就校验assert_generated_keyframes_supported见 ti2vid_one_stage.py对旧 checkpoint直接抛错而非静默降级。LTX-2.5 系列 checkpoint 支持该特性旧 checkpoint 会得到显式错误提示。5.3 代价模型一个潜帧的 token 换一个像素帧每个关键帧消耗一个潜帧量的 token换来 1 个像素帧而不是 8 个。文档给出的量级参考配置5 个关键帧的开销512×768 / 241 帧约 16% token注意力约 1.35 倍1088×1920 / 121 帧约 31% token注意力约 1.72 倍--num-generated-keyframes的帮助文本也给出了经验公式N 个关键帧使序列长度约增加N / num_latent_frames。提高关键帧数量前必须先为这部分算力做预算。5.4 适用管线仅第一阶段生成关键帧槽位只适用于第一阶段支持以下管线及其多 GPU runnerTI2VidOneStagePipelineti2vid_one_stage.pyTI2VidTwoStagesPipelineti2vid_two_stages.pyTI2VidTwoStagesHQPipelineti2vid_two_stages_hq.pyDistilledPipelinedistilled.py对应的*_mgpu.py多 GPU runner第二阶段不需要槽位——效果已经烘焙进第一阶段的潜变量里。唯一的例外是DFRPipeline详见 pipelines.md它在第二阶段重新挂接已播种的槽位并在时间轮次中按 tile 发明新的槽位见 dfr_pipeline.py 中对generated_keyframes的反复处理阶段 1 抽出 → upsampler 放大 → 阶段 2 重新挂载。5.5 使用方式API 与 CLIAPI 调用向__call__传generated_keyframes参数int请求该数量的均匀间隔内部关键帧两端点排除序列如list[int]给出显式帧索引。位置归一化逻辑在 helpers.py 的resolve_generated_keyframes中实现。int走evenly_spaced_keyframe_positions使用torch.linspace(0, num_frames-1, num_keyframes2)后取中间段helpers.py序列则去重排序并校验边界[0, num_frames)。CLI 调用标志为--num-generated-keyframes N默认0关闭。该参数按管线单独注册add_generated_keyframes_argargs.py而不是共享参数——只有真正会把值转发给第一阶段扩散的 CLI 才注册该标志否则会出现「解析了却被静默忽略」的陷阱。DFRPipeline自己推导槽位位置因此不接受该参数。示例python -m ltx_pipelines.ti2vid_two_stages \ --checkpoint-path path/to/checkpoint.safetensors \ --prompt A fast-moving waterfall \ --num-generated-keyframes 5 \ --output-path output.mp4注意代码中专门提供了has_generated_keyframeshelpers.py来判断是否请求了槽位并要求调用方不要直接对参数做真值测试——因为序列可能是 tensor 或 array其真值判定有歧义甚至抛错。5.6 读取关键帧结果生成的关键帧会落在LatentState.generated_keyframes中形状为(B, C, K, H, W)K 关键帧数量见 types.py。在clear_conditioning时依据GeneratedKeyframeLayout从去噪后的序列中抽取并 unpatchify 得到。解码铁律每个关键帧必须作为独立的单帧片段解码。若把 K 帧当作一个连续视频做因果解码会把从未在时间上相邻的槽位混合在一起——槽位之间隔着常规潜帧因果 VAE 的时序因果性会让结果错误。在 DFR 场景下该规则同样成立且更复杂DFRPipeline把阶段 1 的generated_keyframes经 upsampler 放大后作为阶段 2 的初始关键帧重新挂载并在每个 tile 的时间轮次中各自检查tile_state.generated_keyframesdfr_pipeline.py最后拼回完整潜变量时显式把generated_keyframes置空。6. 小结条件类型底层实现关键参数适用管线图像替换式VideoConditionByLatentIndexlatent_idx、strength全部图像引导式VideoConditionByKeyframeIndexframe_idx、strength全部参考视频VideoConditionByReferenceLatentdownscale_factor、temporal_scale_factor、strengthICLoraPipeline 系列HDR/EXRload_image_and_preprocess--hdrSRGB_LINEAR/ACESCG/ACESCCT标准管线生成关键帧槽位VideoGeneratedKeyframeSlotspixel_frame_indices、initial_keyframes一阶段管线 DFR选择建议需要强锚定用替换式需要平滑插值用引导式追求运动细节补足用生成关键帧槽位——但务必先确认 checkpoint 支持use_keyframes_abs_pos_embedding并按 5.3 节的代价模型为 token 预算留出余量。更完整的管线选型对比可参考 Pipeline Selection Guide 与 Available Pipelines。【免费下载链接】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），仅供参考