执行摘要

• 一句话：默认启用非分页索引器提升大块预填充性能
• 推荐动作：值得精读，尤其是 indexer.py 中阈值检查的插入位置和测试的边界覆盖设计，可供类似性能优化 PR 参考。建议关注未来是否将阈值调整为动态自适应。

功能与动机

非分页索引器对大块本地预填充查询有性能提升，但固定的 gather 开销会拖慢小查询。通过默认启用并在安全阈值内保留分页路径，可以在不影响小查询的情况下获得长上下文收益。

实现拆解

1. 环境变量默认值切换（python/sglang/srt/environ.py）：将 SGLANG_OPT_DSV4_NONPAGED_INDEXER 默认值从 False 改为 True，并新增 SGLANG_OPT_DSV4_NONPAGED_INDEXER_MIN_QUERY_TOKENS = EnvInt(8192)，定义触发非分页路径的最小本地查询行数。

2. 计划生成逻辑添加阈值检查（python/sglang/srt/layers/attention/dsv4/indexer.py）：在 _get_nonpaged_indexer_plan 方法最前面增加检查 if query_rows < envs.SGLANG_OPT_DSV4_NONPAGED_INDEXER_MIN_QUERY_TOKENS.get(): return None，确保小查询回退到分页路径。该检查在原有 fail-closed 守卫之前执行。

3. 测试覆盖边界条件和行为（test/registered/unit/layers/test_dsv4_nonpaged_indexer.py）：

   • 更新 test_eligibility_is_fail_closed 验证新的默认值为 True 且默认阈值为 8192。
   • 在 test_single_request_plan_contract 和 test_extreme_plan_metadata_is_bounded_and_fail_closed 中添加显式的阈值 override，确保测试在默认阈值下预期行为正确。
   • 新增 test_query_threshold_boundary，测试 query_rows = 8191、8192、8193 时分别返回 None、非 None、非 None，验证边界逻辑。

关键文件：

• python/sglang/srt/environ.py（模块 环境配置；类别 source；类型 core-logic）: 核心配置变更：切换默认启用并新增最小查询 token 阈值环境变量，直接控制非分页路径的开关和触发条件。
• python/sglang/srt/layers/attention/dsv4/indexer.py（模块 索引器；类别 source；类型 core-logic）: 核心逻辑变更：在计划生成入口添加阈值检查，直接决定是否走非分页路径。代码量虽小，但影响执行路径选择。
• test/registered/unit/layers/test_dsv4_nonpaged_indexer.py（模块 索引器测试；类别 test；类型 test-coverage；符号 test_query_threshold_boundary, build_plan）: 测试覆盖新增边界检查，确保阈值逻辑正确性，包括默认值验证和 8191/8192/8193 边界测试。

关键符号：_get_nonpaged_indexer_plan

关键源码片段

python/sglang/srt/layers/attention/dsv4/indexer.py

核心逻辑变更：在计划生成入口添加阈值检查，直接决定是否走非分页路径。代码量虽小，但影响执行路径选择。

# 在 _get_nonpaged_indexer_plan 方法中，最前面添加的阈值检查
# 确保小查询不走非分页路径，避免 gather 开销
if query_rows < envs.SGLANG_OPT_DSV4_NONPAGED_INDEXER_MIN_QUERY_TOKENS.get():
    return None
# 后续的 fail-closed 守卫保持不变
if not self._can_use_nonpaged_indexer(...):
    return None

test/registered/unit/layers/test_dsv4_nonpaged_indexer.py

测试覆盖新增边界检查，确保阈值逻辑正确性，包括默认值验证和 8191/8192/8193 边界测试。

# 新增的阈值边界测试
class TestNonPagedIndexerThreshold(unittest.TestCase):
    def test_query_threshold_boundary(self):
        can_use_nonpaged_indexer = MagicMock(return_value=True)
        backend = SimpleNamespace(_can_use_nonpaged_indexer=can_use_nonpaged_indexer)
        # ... 省略 setup ...
        # 验证边界：8191 应返回 None，8192 和 8193 应返回非 None
        for query_rows, expected in ((8191, False), (8192, True), (8193, True)):
            with self.subTest(query_rows=query_rows):
                metadata.nonpaged_plan = None
                result = build_plan(query_rows)
                if expected:
                    self.assertIsNotNone(result)
                else:
                    self.assertIsNone(result)

评论区精华

无讨论记录。PR 由 Fridge003 批准，无 review 评论。

• 暂无高价值评论线程

风险与影响

• 风险：风险较低。变更基于详细的基准测试数据，边界选择有实证支持。非分页和分页路径的 logits 和 top-k 已通过精度测试（bit-exact）。但需注意：

  • 阈值是硬编码环境变量，若用户场景中本地查询行数频繁接近但略低于 8192，可能无法获得收益；可通过设置 SGLANG_OPT_DSV4_NONPAGED_INDEXER_MIN_QUERY_TOKENS 覆盖。
  • 测试中新增的阈值检查位于计划生成入口，不影响其他 fail-closed 守卫，回归风险小。
  • 影响：对用户：默认行为变更，长上下文预填充性能提升（实测 8K-128K ISL 吞吐量提升 0.3%-4%），小查询无退化。用户可通过环境变量回退。
    对系统：仅影响 DeepSeek-V4 模型推理路径，不涉及其他模型或模块。
    对团队：需要更新相关文档或配置说明，标注默认值变更。影响范围限于 DeepSeek-V4 大块预填充场景。

• 风险标记：默认值变更, 硬编码阈值

关联脉络

• PR #29619 [DeepSeek-V4] Add an opt-in non-paged indexer for long-context prefill: 此 PR 是实现非分页索引器的基础，引入 opt-in 功能并验证精度和性能。本 PR 将其默认启用并添加阈值保护。