执行摘要

本 PR 对扩散模型的去噪阶段进行了重构，引入 DenoisingContext 数据类以封装状态，并将 LTX-2 特定逻辑提取为独立模块，提高了代码可维护性和序列并行支持，但 review 中指出了重复逻辑和潜在崩溃风险，需关注后续改进。

功能与动机

为什么做：根据 PR body，动机是去除模型特定逻辑、使用数据类替代原始字典、简化原本仅针对 LTX 模型系列的 denoising_av.py。这旨在解决代码耦合问题，提升扩散管道的模块化和可维护性，便于未来添加新模型支持。

实现拆解

按模块拆解改动：

1. 核心去噪阶段（denoising.py）：
   • 新增 DenoisingContext 和 DenoisingStepState 数据类，用于封装去噪循环状态。
   • 重构去噪流程为钩子驱动架构，通过 _before_denoising_loop、_run_denoising_step 等方法实现模块化。
2. LTX-2 特定阶段（ltx_2_denoising.py）：
   • 新增文件，继承自 DenoisingStage，处理视频和音频联合生成的去噪逻辑。
   • 包含 LTX2DenoisingContext 扩展数据类，添加音频相关字段。
3. LTX-2 AV 去噪阶段（denoising_av.py）：
   • 大幅简化，从 1957 行缩减至 33 行，现继承自 LTX2DenoisingStage，专注于音频轨迹收集和最终解包。
4. 管道配置基础（base.py 和 ltx_2.py）：
   • 添加 _gather_sp_tensor 和 _trim_sp_gather_padding 方法，优化序列并行中的张量处理，减少代码重复。
5. 模型特定辅助（wan_ti2v.py）：
   • 新增辅助函数，如 should_apply_wan_ti2v 和 prepare_wan_ti2v_latents，支持 WAN TI2V 模型的特殊处理。

评论区精华

提炼 review 讨论中最有价值的交锋：

• 设计权衡：gemini-code-assist[bot] 指出 LTX2DenoisingStage.forward 重复了基类逻辑，建议使用钩子：> "LTX2DenoisingStage.forward re-implements the entire denoising loop, duplicating logic... This duplication increases technical debt."
• 正确性风险：同一评论者提到 audio_latents 为 None 的崩溃风险：> "Potential crash when batch.audio_latents is None... This will cause a failure for LTX-2 models running in video-only mode."
• 性能建议：建议 DenoisingContext 使用 slots=True：> "The DenoisingContext dataclass should use slots=True to improve performance and reduce memory overhead."
• 代码重复：指出 _post_denoising_loop 中的重复逻辑和日志移除问题。

风险与影响

具体说明风险和影响：

• 回归风险：重构可能导致 bug，例如 ltx_2_denoising.py 中缺少空值检查，在音频为空时可能崩溃。
• 性能影响：DenoisingContext 未使用 slots=True 可能轻微增加内存使用，但影响有限。
• 兼容性：内部接口变化可能影响依赖的扩展代码，但用户 API 保持不变。
• 维护负担：代码重复（如 LTX2DenoisingStage.forward）增加了未来维护和调试的复杂度。
• 正面影响：提高代码可读性和扩展性，支持更清晰的模型分离和序列并行优化。

关联脉络

与历史 PR 和关联 Issue 的关系：

• #22182（[diffusion] model: support LTX2.3 two stage）：本 PR 的去噪重构为 LTX-2.3 两阶段生成提供了模块化基础，显示扩散管道向更灵活架构演进。
• #21206（[RaidxTree Refactor]）：同是重构主题，体现仓库中代码组织改进的持续趋势，本 PR 延续了组件化设计理念。
• #22574（[Diffusion] Add FLUX.1-dev ModelOpt NVFP4 support）：扩散模型量化支持相关，本 PR 的去噪阶段重构可能影响量化模型的集成和性能优化。
  整体看，这些 PR 共同推动 sglang 扩散模块向高性能、可维护方向演进。