执行摘要

• 一句话：将 TopK 捕获器从 layers/ 移至 state_capturer/
• 推荐动作：作为纯重构，值得开发人员关注其设计动机：将不同职责的代码（计算层 vs 观测层）分离到对应的包层级。命名上避免与已有概念冲突的思考也值得借鉴。此 PR 展示了团队对代码组织一致性的追求。

功能与动机

捕获器本质上是可观测性基础设施（side-effect observer），而不是计算层组件。将它们放在 layers/ 下混淆了职责。sglang 现有的观测模块（eplb/、metrics/、debug_utils/）均位于 srt/ 根目录。此外，为了避免与 CUDA graph capture 术语冲突，选择 state_capturer/ 而非 capture/。

实现拆解

1. 创建新目录和基础文件。在 srt/state_capturer/ 下创建 init.py，并从 layers/ 移动三个文件：layers/topk_capturer_base.py → state_capturer/base.py，layers/moe/routed_experts_capturer.py → state_capturer/routed_experts.py，layers/attention/indexer_topk_capturer.py → state_capturer/indexer_topk.py。仅更新内部交叉导入（如 routed_experts.py 中 import base 的路径）。
2. 更新消费端导入。修改 model_runner.py、scheduler_output_processor_mixin.py、forward_mla.py、nsa_indexer.py、hardware_backend/npu/moe/topk.py、layers/moe/topk.py、managers/utils.py 等文件中所有从旧路径的导入，替换为新路径。
3. 更新测试文件导入。修改 test/registered/8-gpu-models/test_return_indexer_topk.py 中的导入声明。
4. 验证无行为变化。类名、方法名、调用模式均未动；仅导入路径更新，确保通过 CI 并维持一致性。

关键文件：

• python/sglang/srt/state_capturer/base.py（模块 状态捕获器；类别 source；类型 rename-or-move；符号 BaseTopkCapturer, TopkCaptureOutput）: 捕获器基类被搬迁到新目录，是整个重构的基石。
• python/sglang/srt/state_capturer/indexer_topk.py（模块 状态捕获器；类别 source；类型 rename-or-move；符号 IndexerTopkCapturer, maybe_capture_indexer_topk, create_indexer_capturer, get_global_indexer_capturer）: NSA 索引器 TopK 捕获器，DeepSeek 模型关键功能，搬迁至新目录。
• python/sglang/srt/state_capturer/routed_experts.py（模块 状态捕获器；类别 source；类型 rename-or-move；符号 RoutedExpertsCapturer, get_global_experts_capturer, set_global_experts_capturer）: 路由专家捕获器，MoE 模型关键组件，搬迁至新目录。
• python/sglang/srt/state_capturer/__init__.py（模块 状态捕获器；类别 source；类型 core-logic）: 新包标识文件，使 state_capturer 成为可导入模块。
• python/sglang/srt/model_executor/model_runner.py（模块 模型执行器；类别 source；类型 dependency-wiring）: 核心模型运行器，消费所有三个捕获器，导入路径更新。
• python/sglang/srt/managers/scheduler_output_processor_mixin.py（模块 调度器；类别 source；类型 dependency-wiring）: 调度输出处理器，消费捕获器，导入路径更新。
• python/sglang/srt/models/deepseek_common/attention_forward_methods/forward_mla.py（模块 模型前向；类别 source；类型 dependency-wiring）: DeepSeek MLA 前向方法，调用 maybe_capture_indexer_topk，导入路径更新。

关键符号：BaseTopkCapturer, IndexerTopkCapturer, RoutedExpertsCapturer, create_indexer_capturer, maybe_capture_indexer_topk

关键源码片段

python/sglang/srt/state_capturer/indexer_topk.py

NSA 索引器 TopK 捕获器，DeepSeek 模型关键功能，搬迁至新目录。

# python/sglang/srt/state_capturer/indexer_topk.py
# 原路径：sglang/srt/layers/attention/indexer_topk_capturer.py
# 本次移动仅更新了导入路径，其余代码无变化。
import logging
from typing import Optional
​
import numpy as np
import pybase64
import torch
​
from sglang.srt.layers.dp_attention import get_attention_tp_size
from sglang.srt.state_capturer.base import BaseTopkCapturer # 基类已搬迁到 state_capturer
​
logger = logging.getLogger(__name__)
​
​
class IndexerTopkCapturer(BaseTopkCapturer):
    """用于捕获 NSA 索引器 Top-K 索引结果。"""
    def __init__(
        self,
        num_tokens: int,
        num_indexer_layers: int,
        index_topk: int,
        max_running_requests: int,
        device: str,
    ):
        from sglang.srt.server_args import get_global_server_args
        self.num_indexer_layers = num_indexer_layers
        self.index_topk = index_topk
        attn_tp_size = get_attention_tp_size()
        assert attn_tp_size == 1, "IndexerTopkCapturer now only supports DP attention"
        # DP-attention capture is per-rank-local
        server_args = get_global_server_args()
        max_batch_size = max(server_args.chunked_prefill_size, max_running_requests)
        super().__init__(
            num_tokens=num_tokens,
            max_batch_size=max_batch_size,
            num_layers=self.num_indexer_layers,
            topk_size=self.index_topk,
        )

python/sglang/srt/model_executor/model_runner.py

核心模型运行器，消费所有三个捕获器，导入路径更新。

# python/sglang/srt/model_executor/model_runner.py 中的部分导入
# 原导入：from sglang.srt.layers.attention.indexer_topk_capturer import ...
# 原导入：from sglang.srt.layers.moe.routed_experts_capturer import ...
# 原导入：from sglang.srt.layers.topk_capturer_base import TopkCaptureOutput
from sglang.srt.state_capturer.base import TopkCaptureOutput
from sglang.srt.state_capturer.indexer_topk import (
    create_indexer_capturer,
    get_global_indexer_capturer,
    set_global_indexer_capturer,
)
from sglang.srt.state_capturer.routed_experts import (
    RoutedExpertsCapturer,
    get_global_experts_capturer,
    set_global_experts_capturer,
)

评论区精华

本 PR 无实质性技术讨论，作者在 PR body 中解释了命名的设计考量：为避免与 CUDA graph capture 混淆，选用 state_capturer/ 而非 capture/。这一命名决策得到了合入者的认可。

• 暂无高价值评论线程

风险与影响

• 风险：风险极低。由于所有变更仅为文件移动和导入路径更新，不涉及逻辑修改。最大风险是遗漏某处导入未更新，导致 ImportError。本 PR 通过 CI 且合入前检查无误。无回归、性能或安全风险。
• 影响：对用户透明，对外部 API 无影响。对开发者而言，捕获器模块不再混在 layers/ 下，结构更清晰，符合 'observability infrastructure' 的定位。新增的 state_capturer/ 目录未来可收纳更多状态捕获相关代码。
• 风险标记：低风险, 纯文件移动

关联脉络

• PR #24392 add indexer-topk capture (V3.2 NSA + infra): 引入了 indexer_topk_capturer 文件，本 PR 将其搬迁至新目录。
• PR #24403 consolidate routed-experts capturer onto reusable base: 重构了 routed_experts_capturer 和 base 类，本 PR 将这两个文件移至 state_capturer/。