# PR #28533 完整报告

- 仓库：`sgl-project/sglang`
- 标题：[diffusion] chore: remove ltx2 snapshot mode
- 合并时间：2026-06-18 10:20
- 原文链接：http://prhub.com.cn/sgl-project/sglang/pull/28533

---

# 执行摘要

- 一句话：移除 LTX2 snapshot 两阶段驻留模式
- 推荐动作：值得精读：重点关注其向后兼容策略（弃用别名 + 弃用窗口）、代码清理的范围以及 review 中提及的默认值一致性建议。如果团队有其他类似需要清理的遗留功能，可参考此 PR 的实践。

# 功能与动机

LTX2 snapshot 模式已不再需要，移除可以简化代码维护，降低两阶段管线的模式选择负担。PR body 明确指出这是从 auto-tuning 和 LTX2 residency 选择中移除 snapshot 实现。

# 实现拆解

### 步骤拆解
1. **配置层面（server_args.py）**：将 `LTX2_TWO_STAGE_DEVICE_MODES` 从 `("original", "snapshot", "resident")` 改为 `("original", "resident")`，新增 `LTX2_TWO_STAGE_DEVICE_MODE_CHOICES = (*LTX2_TWO_STAGE_DEVICE_MODES, "snapshot")` 以保证 CLI 解析仍接受 snapshot。在 `_normalize_ltx2_two_stage_device_mode` 中添加 snapshot 到 original 的映射，并输出弃用警告。默认解析方法 `_resolve_default_ltx2_two_stage_device_mode` 由返回 snapshot 改为返回 original。
2. **管线层（ltx_2_pipeline.py）**：删除整个 `LTX2SnapshotResidencyStrategy` 类及其辅助方法 `_module_is_on_gpu`、`_resolve_snapshot_low_vram_mode` 等，消除约 250 行代码。`LTX2TwoStageResidencyController` 简化，不再需要处理 snapshot 逻辑。同时清理不再需要的导入（如 `SnapshotStrategy`、`SnapshotModuleResidency`、`current_platform` 等）。
3. **组件管理器（component_manager.py）**：移除 `enabled` 属性、`register_strategy` 方法、`manager_mode` 和 `trace_enabled` 状态字段，简化 `begin_request` 和 `finish_request` 流程，删除对 `_T` 类型变量等未使用元素。
4. **Pipeline 执行器（pipeline_executor.py）**：删除 `after_stage` 空方法钩子。
5. **测试与文档**：更新 `test_server_args.py`，将原有的 snapshot 测试改为 original 测试，新增 snapshot 别名测试；调整 `gpu_cases.py` 中的配置；更新性能基线 JSON 以匹配 original 模式的新时序；更新部署代码片段和文档中的模式说明。

关键文件：
- `python/sglang/multimodal_gen/runtime/pipelines/ltx_2_pipeline.py`（模块 扩散管线；类别 source；类型 dependency-wiring；符号 _module_is_on_gpu, LTX2SnapshotResidencyStrategy, __init__, _module_name_for_phase）: 核心文件，删除了 LTX2SnapshotResidencyStrategy 类及其约 284 行代码，简化了策略层次结构。
- `python/sglang/multimodal_gen/runtime/managers/memory_managers/component_manager.py`（模块 组件管理；类别 source；类型 core-logic；符号 enabled, register_strategy, after_stage, before_use）: 组件管理器移除了 enabled 属性、register_strategy 方法以及 trace 字段，简化了 begin_request 流程，删除约 160 行代码。
- `python/sglang/multimodal_gen/test/unit/test_server_args.py`（模块 参数测试；类别 test；类型 test-coverage；符号 test_auto_ltx_snapshot_keeps_dit_offload_and_replaces_encoder_cpu_offload, test_auto_ltx_original_replaces_component_cpu_offload, test_ltx23_snapshot_device_mode_is_deprecated_alias_for_original, test_ltx23_snapshot_device_mode_cli_alias_is_accepted）: 测试覆盖更新：原 snapshot 测试改为 original 测试，新增 snapshot 别名兼容性测试，确保向后兼容。
- `python/sglang/multimodal_gen/runtime/server_args.py`（模块 服务参数；类别 source；类型 core-logic；符号 _uses_ltx23_snapshot_two_stage_residency）: 服务参数定义中修改了设备模式常量和标准化函数，添加 snapshot 弃用别名，调整默认值。
- `python/sglang/multimodal_gen/runtime/pipelines_core/executors/pipeline_executor.py`（模块 执行器；类别 source；类型 core-logic；符号 after_stage）: 移除了空的 after_stage 钩子方法，简化执行器接口。
- `python/sglang/multimodal_gen/test/server/perf_baselines.json`（模块 性能基线；类别 test；类型 test-coverage）: 性能基线更新，反映 original 模式的时间数据。

关键符号：LTX2_TWO_STAGE_DEVICE_MODES, _normalize_ltx2_two_stage_device_mode, _resolve_default_ltx2_two_stage_device_mode, LTX2TwoStageResidencyStrategy.prepare_after_request, LTX2ResidentResidencyStrategy.initialize, ComponentResidencyManager.begin_request, ComponentResidencyManager.register_strategy

## 关键源码片段

### `python/sglang/multimodal_gen/runtime/server_args.py`

服务参数定义中修改了设备模式常量和标准化函数，添加 snapshot 弃用别名，调整默认值。

```python
# 定义真实模式（snapshot 已移除，仅保留 original 和 resident）
LTX2_TWO_STAGE_DEVICE_MODES = ("original", "resident")
# 定义 CLI 可接受的选项（包含已弃用的 snapshot）
LTX2_TWO_STAGE_DEVICE_MODE_CHOICES = (*LTX2_TWO_STAGE_DEVICE_MODES, "snapshot")
LTX2_TWO_STAGE_PIPELINE_NAMES = ("LTX2TwoStagePipeline", "LTX2TwoStageHQPipeline")
# H200-class GPUs (>=130 GiB total) can usually keep both LTX2 DiTs resident
LTX2_RESIDENT_AUTO_ENABLE_MEM_GB = 130

def _normalize_ltx2_two_stage_device_mode(mode: str | None) -> str | None:
    if mode is None:
        return None
    mode = mode.lower()
    if mode == "snapshot":
        logger.warning(
            "ltx2_two_stage_device_mode=snapshot is deprecated and is treated "
            "as original. Please use ltx2_two_stage_device_mode=original or "
            "resident instead. This alias may be removed after two release cycles."
        )
        return "original"  # 标准化为 original
    return mode

```

# 评论区精华

在 review 中，gemini-code-assist[bot] 指出在 `ltx_2_pipeline.py` 的 `_resolve_mode` 方法中，当 `server_args.ltx2_two_stage_device_mode` 为 None 且环境变量未设置时，默认值从 'snapshot' 直接改为 'original'，这与 `ServerArgs._resolve_default_ltx2_two_stage_device_mode` 的自动解析逻辑不一致（高内存 GPU 应默认为 resident）。建议使用 `server_args._resolve_default_ltx2_two_stage_device_mode()` 确保一致性。此评论尚未被处理或合并后状态不明，但建议被采纳可能是合理的。此外，PR 描述中提到了已有 CI 状态，但未涉及深度技术争论。

- 默认模式解析不一致 (design): 未明确解决，但建议合理，可能有后续处理。

# 风险与影响

- 风险：
 - **向后兼容风险**：原有 snapshot 用户会收到弃用警告并实际运行 original 模式，如果 original 模式与 snapshot 性能差异大（snapshot 使用快照预取，original 只依赖标准卸载），可能导致用户感知的变慢或 OOM。尽管有文档，仍需谨慎。
 - **代码删除风险**：大量代码删除可能隐藏未覆盖的依赖路径，例如某些自定义策略可能依赖 `register_strategy`。不过静态分析显示无外部引用，风险可控。
 - **性能基线更新**：测试使用了新的性能基线 JSON，如果 CI 未运行 LTX2 相关测试，可能无法发现回归。
- 影响：
 - **用户**：使用 `--ltx2-two-stage-device-mode snapshot` 的用户将收到警告并运行 original 模式，需调整配置。其他用户无影响。
 - **系统**：代码库减少约 500+ 行（删除 + 新增），维护性提高。行为简化，减少两阶段驻留模式的潜在 bug。
 - **团队**：清理技术债务，降低后续开发的心智负担。
 - 风险标记：向后兼容行为变更 , 大量代码删除 , 性能基线更新

# 关联脉络

- 暂无明显关联 PR