feat: add topology-aware sparse MLA candidate policy

[teerthsharma]

Summary

I made this a code/test/build-only stacked follow-up to #1160 for topology-aware sparse MLA candidate rewriting.

This PR is intentionally draft until #1160 lands. It includes no docs, README, plan, or spec files in the remote diff.

What changed

• Added topology_kv_policy.py for opt-in topology-aware candidate merge modes.
• Kept default behavior disabled with RTP_LLM_TOPOLOGY_KV_POLICY=disabled.
• Applied the policy only to ragged and CP prefill top-k results.
• Left decode _get_topk_paged unchanged because that path returns page-table / physical block IDs, not token offsets.
• Added absolute-coordinate validation with production fallback on mismatch.
• Normalized policy and coordinate-mismatch env/config strings case-insensitively.
• Restricted policy input indices to torch.int32 / torch.int64, so -1 padding and absolute offsets remain representable.
• Added separate Python-path guards for total policy tokens, topk_indices.numel(), and top-k width.
• Made topology_only consume the full structural budget so available structural tokens fill min(topk_width, length) instead of being capped by merge-mode structural fraction.
• Moved optional drift scores onto the same detached CPU policy path before structural selection.
• Added CUDA-sync and long-prefill guards so the Python policy path cannot silently run on hot CUDA paths.
• Added learned-retention counters and capped structural injection by budget fraction for merge modes.
• Removed shared per-layer fingerprint/counter state; compression-hit semantics now require caller-provided per-request fingerprint context.
• Added Bazel runfiles declarations for benchmark:topology_kv_policy_test and its CUDA manual variant.

Policy modes

• disabled: passthrough, default.
• topology_sparse_merge: merge topology sink/local/witness candidates with learned top-k candidates.
• topology_compress_sparse: sparse merge plus stable scaffold/output-contract counters.
• topology_only: topology candidates only, using the full structural budget.

Coordinate contract

apply_topology_kv_policy requires learned non-padding top-k indices to already be absolute token indices in the downstream sparse-attention coordinate system.

For ragged and CP prefill rows:

valid row interval = [topk_indices_offset, topk_indices_offset + length)

row_starts is only a row-count alignment guard here. It is not added to returned top-k coordinates.

Decode is intentionally bypassed because _get_topk_paged returns page-table / physical block IDs, not token-space offsets.

Validation I ran

Windows / local Python:

• python -m unittest benchmark.test_topology_kv_policy -v: 35 tests run, 34 passed, 1 CUDA-manual test skipped by default.
• python -m unittest benchmark.test_topology_kv_candidate_schedule -v: 22 tests run, 21 passed, 1 CUDA-manual test skipped by default.
• Static BUILD/runfiles check for benchmark:topology_kv_policy_test: passed.
• python -m py_compile ...: passed.
• python -m black --check ...: passed.

Docker / Linux GPU image:

• python -m unittest benchmark.test_topology_kv_policy -v: 35 tests run, 34 passed, 1 CUDA-manual test skipped by default.

I cannot run Bazel in this Windows shell because neither bazel nor bazelisk is installed here. I also cannot run final H20 validation because I do not own that GPU.

Dependency

Blocked by #1160. This branch remains stacked and should be rebased after #1160 lands.

[LLLLKKKK]

AI Code Review - PR #1162

Status: BLOCKING

Summary: P0/0 · P1/1 · P2/3 · P3/1

Blocking Issues

P1

• 生产接线缺集成测试且 topk 坐标系假设未验证，启用后可能静默产生错误索引 @ rtp_llm/models_py/modules/hybrid/indexer.py:173
  • 建议：补一个经由 Indexer._compute_topk（或 mock indexer_op._get_topk_* 返回已知坐标约定的张量）驱动 decode / ragged / cp 三条路径的集成测试，断言合并后索引落在合法范围且与下游 sparse attention 消费约定一致；并在 apply_topology_kv_policy 文档/断言中显式声明 learned topk 的坐标系契约（绝对 vs 行内相对、是否含 offset），对越界值 fail-fast 而非静默丢弃。

Non-blocking Suggestions

P2

• 策略在 decode 热路径上使用 Python 逐行循环与多次 GPU→CPU 同步 @ rtp_llm/models_py/modules/hybrid/topology_kv_policy.py:130
  • 建议：将结构块选择与合并改写为张量化实现（在目标 device 上用 torch 向量操作/散射完成 sink/local/witness 与 learned 的去重合并），避免 .item() / .cpu().tolist() 的逐 step 同步与 Python 循环；计数器统计也尽量批量化或在关闭统计时跳过。至少应给出启用态的 decode 吞吐/延迟基准数据，证明其可用。
• policy 字符串分发未使用 Enum/Literal @ rtp_llm/models_py/modules/hybrid/topology_kv_policy.py:9
  • 建议：用 enum.Enum 或 typing.Literal["disabled","topology_sparse_merge","topology_compress_sparse","topology_only"] 定义策略集合，构造 TopologyKvPolicyConfig 时校验并对未知值 fail-fast（或明确 warn），环境变量解析处集中做一次映射，避免字符串在多文件重复。
• 计数器与 fingerprint 语义含糊、缺少说明，观测性易误导 @ rtp_llm/models_py/modules/hybrid/topology_kv_policy.py:34
  • 建议：为该模块补 module/函数级 docstring，解释 stable_scaffold/output_contract/fingerprint 的用途与来源；将计数器命名与实现对齐真实语义（如 unselected_tokens 而非 raw_kv_tokens_avoided），或删除当前无实际压缩含义的字段，避免观测指标误导。

P3

• 夹带与本 PR 无关的括号缩进改动且不符合 black @ rtp_llm/models_py/modules/hybrid/indexer.py:180
  • 建议：回退该行缩进改动，保持逻辑变更与格式变更分离；提交前跑 black/pre-commit 以确保格式合规。

Checklist Violations (2 fail / 56 total)

General Principles Checklist

• [6.1] Tests — 分布式/跨平台变更有对应覆盖 → issue 生产接线缺集成测试且 topk 坐标系假设未验证，启用后可能静默产生错误索引
_compute_topk 三条路径分别以不同的坐标参数调用策略：decode 路径 _apply_topology_kv_policy(topk_result, fmha_params.expanded_seq_lens) 不传 row_starts/offset；ragged 路径传 fmha_params.ks / fmha_params.topk_indices_offset；cp 路径传 cp_params.precomputed_ks / precomputed_topk_off。apply_topology_kv_policy 内部对 structural token 做 token + row_start + offset，并按 [row_start+offset, +length) 过滤 learned 值。但 _get_topk_paged/_get_topk_ragged 返回的 learned 索引究竟是绝对位置还是行内相对、是否已含 offset，未有测试验证。若坐标系不一致，越界值被过滤成 -1 或指向错误 K
• [6.1] Tests — 新逻辑有聚焦单测 + 相关集成/smoke 测试 → issue 生产接线缺集成测试且 topk 坐标系假设未验证，启用后可能静默产生错误索引
_compute_topk 三条路径分别以不同的坐标参数调用策略：decode 路径 _apply_topology_kv_policy(topk_result, fmha_params.expanded_seq_lens) 不传 row_starts/offset；ragged 路径传 fmha_params.ks / fmha_params.topk_indices_offset；cp 路径传 cp_params.precomputed_ks / precomputed_topk_off。apply_topology_kv_policy 内部对 structural token 做 token + row_start + offset，并按 [row_start+offset, +length) 过滤 learned 值。但 _get_topk_paged/_get_topk_ragged 返回的 learned 索引究竟是绝对位置还是行内相对、是否已含 offset，未有测试验证。若坐标系不一致，越界值被过滤成 -1 或指向错误 K

Strengths

• 特性默认 disabled，通过环境变量门控，对现网默认部署零影响，回滚路径清晰。
• topology_kv_candidate_schedule.py / topology_kv_policy.py 的纯函数单元有较全的单测覆盖（padding、去重、边界、2D/3D 输入、fp16 用 fp32 累加、RNG 状态不被污染等）。
• build_key_block_centroids 对 half precision 采用 fp32 累加，避免精度损失，并有对应测试。
• 输入校验较完整（block_size/seq_len 非负、候选索引形状/重复/越界检查）。

[Copilot]

Pull request overview

Note

Copilot couldn't run its full agentic review because no GitHub Actions runner was available. Make sure your repository has a runner available to run Copilot's review, or add a copilot-setup-steps.yml file specifying one with the runs-on attribute. See the docs for more details.

Adds a topology-aware KV candidate rewrite policy (with optional compression counters/fingerprinting) and wires it into the Hybrid Indexer behind an env-gated switch to preserve existing learned sparse top-k behavior by default.

Changes:

• Introduces topology_kv_policy.py implementing topology-based candidate selection/merge modes plus stable fingerprint + counters.
• Integrates policy application into Indexer._compute_topk behind RTP_LLM_TOPOLOGY_KV_POLICY=disabled default.
• Adds manual-only benchmark helpers and unit tests for topology scheduling and the policy helper.

Reviewed changes

Copilot reviewed 6 out of 6 changed files in this pull request and generated 5 comments.

Show a summary per file

File	Description
rtp_llm/models_py/modules/hybrid/topology_kv_policy.py	New helper implementing topology candidate merge/only modes plus compression counters/fingerprint.
rtp_llm/models_py/modules/hybrid/indexer.py	Env-gated integration hook to rewrite top-k indices and expose latest counters/fingerprint.
benchmark/topology_kv_candidate_schedule.py	Benchmark utility to build topology candidate schedules and compare dense vs sparse decode attention.
benchmark/test_topology_kv_policy.py	Tests for policy behavior, counters/fingerprint, and a CUDA sparse-attention E2E check.
benchmark/test_topology_kv_candidate_schedule.py	Tests for candidate schedule construction, validation, and benchmark determinism.
benchmark/BUILD	Adds manual Bazel py_test targets to avoid entering wildcard GPU CI.

---

💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.

[Copilot]

Copilot was unable to review this pull request because the user who requested the review has reached their quota limit.

[LLLLKKKK]

AI Code Review - PR #1162

Status: BLOCKING

Summary: P0/0 · P1/1 · P2/1 · P3/0

Blocking Issues

P1

• topology_only 默认只保留一半结构候选 @ rtp_llm/models_py/modules/hybrid/topology_kv_policy.py:422
  • 建议：对 topology_only 使用完整 budget，或调用 _merge_row 时强制 max_structural_fraction=1.0；补一条 topology_only 测试，断言可用结构 token 会填满 min(topk_width, length)。

Non-blocking Suggestions

P2

• policy 接受的 dtype 无法保证 padding 和绝对坐标语义 @ rtp_llm/models_py/modules/hybrid/topology_kv_policy.py:49
  • 建议：将 policy 输入限制为生产实际使用的 torch.int32/torch.int64，或在输出前统一提升到可表示 -1 和最大 offset 的有符号 dtype，并补充 unsigned/narrow dtype 的拒绝测试。

Checklist Violations (2 fail / 47 total)

General Principles Checklist

• [6.1] Tests — 新逻辑有聚焦单测 + 相关集成/smoke 测试 → issue ``topology_only 默认只保留一半结构候选
  _`topology_only` 把 `learned_values` 置为全 `-1`，但仍走 `merge_row` 的 `structural_budget=int(budget * max_structural_fraction)`。默认 0.5 时，topk=2048 只会输出最多 1024 个结构 token，剩余补 `-1`，即使结构候选充足。
• [6.1] Tests — 边界 case 覆盖（空、单元素、最大值） → issue policy 接受的 dtype 无法保证 padding 和绝对坐标语义
  模块约定负数是 padding，且输出会带 topk_indices_offset 的绝对 token 坐标；但 INTEGER_TOPK_DTYPES 允许 torch.uint8/int8/int16，随后用原 dtype 构造 merged。这些 dtype 不能可靠表达 -1 padding 或较大的 token offset。

Strengths

• 默认 RTP_LLM_TOPOLOGY_KV_POLICY=disabled，CUDA tensor 还需要额外显式允许 host-sync，默认线上路径风险被控制住。
• 新增单测覆盖了 ragged/CP topk_indices_offset 合约、coordinate mismatch fallback、size bypass 和 CUDA manual e2e 入口。

[Copilot]

Copilot was unable to review this pull request because the user who requested the review has reached their quota limit.

[LLLLKKKK]

AI Code Review - PR #1162

Status: BLOCKING

Summary: P0/0 · P1/1 · P2/0 · P3/0

Blocking Issues

P1

• topology_only 接受零结构来源并生成全 padding 候选 @ rtp_llm/models_py/modules/hybrid/topology_kv_policy.py:420
  • 建议：在 TopologyKvPolicyConfig.__post_init__ 中拒绝 topology_only 且三类结构块总数为 0 的配置，并在合并后断言非空序列至少存在一个有效候选。补充零结构来源和单 token 两个边界测试。

Checklist Violations (2 fail / 107 total)

General Principles Checklist

• [6.1] Architecture — 错误语义：fail-fast/retry/fallback/silent 行为显式 → issue ``topology_only 接受零结构来源并生成全 padding 候选
  _配置允许 `sink_blocks`、`local_blocks`、`witness_blocks` 同时为 0。此时 `topology_only` 先丢弃全部 learned 候选，`_structural_tokens` 又返回空列表，随后 `merge_row` 将整行补成 `-1`。即使 `row_length > 0`，下游也收不到任何有效 KV 候选，可能产生错误输出或触发稀疏注意力内核异常；现有测试仅覆盖 `sink_blocks=3`。
• [6.1] Tests — 边界 case 覆盖（空、单元素、最大值） → issue ``topology_only 接受零结构来源并生成全 padding 候选
  _配置允许 `sink_blocks`、`local_blocks`、`witness_blocks` 同时为 0。此时 `topology_only` 先丢弃全部 learned 候选，`_structural_tokens` 又返回空列表，随后 `merge_row` 将整行补成 `-1`。即使 `row_length > 0`，下游也收不到任何有效 KV 候选，可能产生错误输出或触发稀疏注意力内核异常；现有测试仅覆盖 `sink_blocks=3`。

Strengths

• 策略默认关闭，CUDA 路径还有独立的 host-sync 门控，默认推理路径和回滚边界清晰。
• topk_indices 已限制为 int32/int64，避免窄整数无法表达绝对坐标或 -1 padding；对应回归测试覆盖了被拒绝的 dtype。
• ragged/CP 坐标区间、重复候选、padding 布局和策略旁路均有聚焦测试。

[Copilot]

Copilot was unable to review this pull request because the user who requested the review has reached their quota limit.

[Copilot]

Copilot was unable to review this pull request because the user who requested the review has reached their quota limit.

[LLLLKKKK]

AI Code Review - PR #1162

Status: BLOCKING

Summary: P0/0 · P1/2 · P2/0 · P3/0

Blocking Issues

P1

• 默认限额使普通 prefill 策略恒为透传且没有可观测信号 @ rtp_llm/models_py/modules/hybrid/topology_kv_policy.py:384
  • 建议：按实际有效候选数或可处理行数重新设计限额，或者提供分块/GPU 实现。若透传是预期保护，必须在 Indexer 层暴露限频日志或指标，并补充 65、128 token 普通 prefill 及长 prefix 场景，明确断言策略生效或显式 bypass。
• CUDA “e2e” 测试没有经过本次修改的生产边界 @ benchmark/test_topology_kv_policy.py:845
  • 建议：增加真实 CUDA Bazel 集成测试，通过实际 Indexer 和 sparse MLA 入口开启策略及同步开关，覆盖普通 prefill、prefix prefill 和 CP，并使用 length > topk 的候选截断场景与原实现比对输出。性能测试应计入策略调度和 host sync 开销，而不只计 benchmark SDPA helper。

Checklist Violations (5 fail / 107 total)

General Principles Checklist

• [6.1] Architecture — 可观测性：日志/指标/超时可操作、非噪声 → issue 默认限额使普通 prefill 策略恒为透传且没有可观测信号
  生产 top-k 宽度固定为 2048；默认 max_topk_elements=****** 使 query row 超过 64 时直接透传。64 行以内且无 prefix 时，每行原 top-k 已包含全部因果 token，merge 只能重排；128 token 又会因 sum(lengths)=8256 超过另一默认限额。Indexer 只取 result.topk_indices，丢弃 policy_bypassed，因此常规 prefill 即使开启策略也不会改变候选，且没有指标或日志说明。
• [6.1] Architecture — 错误语义：fail-fast/retry/fallback/silent 行为显式 → issue 默认限额使普通 prefill 策略恒为透传且没有可观测信号
  生产 top-k 宽度固定为 2048；默认 max_topk_elements=****** 使 query row 超过 64 时直接透传。64 行以内且无 prefix 时，每行原 top-k 已包含全部因果 token，merge 只能重排；128 token 又会因 sum(lengths)=8256 超过另一默认限额。Indexer 只取 result.topk_indices，丢弃 policy_bypassed，因此常规 prefill 即使开启策略也不会改变候选，且没有指标或日志说明。
• [6.1] Tests — 分布式/跨平台变更有对应覆盖 → issue CUDA “e2e” 测试没有经过本次修改的生产边界
  CUDA 用例直接调用独立策略和 benchmark 专用 sparse_decode_attention，且选择全部 64 个 token，只验证恒等结果。生产 _compute_topk 在 decode 明确跳过策略，CUDA prefill 未开启额外同步开关也直接返回原结果；其余 Indexer 测试通过伪模块和 _FakeIndexerOp 隔离了真实 Indexer→FlashMLA/CP 边界，因此坐标转换、kernel 消费及性能回退均未被覆盖。
• [6.1] Tests — 新逻辑有聚焦单测 + 相关集成/smoke 测试 → issue CUDA “e2e” 测试没有经过本次修改的生产边界
  CUDA 用例直接调用独立策略和 benchmark 专用 sparse_decode_attention，且选择全部 64 个 token，只验证恒等结果。生产 _compute_topk 在 decode 明确跳过策略，CUDA prefill 未开启额外同步开关也直接返回原结果；其余 Indexer 测试通过伪模块和 _FakeIndexerOp 隔离了真实 Indexer→FlashMLA/CP 边界，因此坐标转换、kernel 消费及性能回退均未被覆盖。

Python Static-First Checklist

• [P.G] 测试规范 — mock/fake/stub 不得替代本次声称覆盖的生产边界 → issue CUDA “e2e” 测试没有经过本次修改的生产边界
  CUDA 用例直接调用独立策略和 benchmark 专用 sparse_decode_attention，且选择全部 64 个 token，只验证恒等结果。生产 _compute_topk 在 decode 明确跳过策略，CUDA prefill 未开启额外同步开关也直接返回原结果；其余 Indexer 测试通过伪模块和 _FakeIndexerOp 隔离了真实 Indexer→FlashMLA/CP 边界，因此坐标转换、kernel 消费及性能回退均未被覆盖。

Strengths

• 策略默认关闭，并对 CUDA host sync 增加了显式保护，避免无意引入在线热路径同步。
• 对坐标范围、dtype、padding、空候选及 CP/ragged 参数形状进行了较完整的防御性校验。
• 单元测试覆盖了多种策略模式、坐标异常和候选边界。

[Copilot]

Copilot was unable to review this pull request because the user who requested the review has reached their quota limit.

[LLLLKKKK]

AI Code Review - PR #1162

Status: BLOCKING

Summary: P0/0 · P1/2 · P2/0 · P3/0

Blocking Issues

P1

• 默认坐标回退会静默禁用策略 @ rtp_llm/models_py/modules/hybrid/indexer.py:272
  • 建议：消费并上报 coordinate_mismatch_fallbacks，至少按原因限频告警并增加低基数指标；同时保留 schedule_ms、候选淘汰量等关键结果，并添加生产调用路径的可观测性断言。
• 真实 H20 边界测试未进入常规 CI 门禁 @ rtp_llm/models_py/modules/hybrid/test/BUILD:105
  • 建议：将该 target 接入明确的 H20 CI job，并移除 open_skip，或在本次变更中提供 CI 显式选择它的配置与证据；保留现有 CPU 单测作为快速覆盖，但不要用 fake 边界替代生产集成测试。

Checklist Violations (4 fail / 97 total)

General Principles Checklist

• [6.1] Architecture — 可观测性：日志/指标/超时可操作、非噪声 → issue 默认坐标回退会静默禁用策略
Indexer 默认使用 fallback_disabled。坐标校验失败时，policy 返回原始 top-k 并仅设置 coordinate_mismatch_fallbacks=1；这里却只检查 policy_bypassed，随后丢弃其余 counters。结果是配置显示策略已启用，但每次请求都可能静默退回旧路径，日志和指标均无法发现。
• [6.1] Architecture — 错误语义：fail-fast/retry/fallback/silent 行为显式 → issue 默认坐标回退会静默禁用策略
Indexer 默认使用 fallback_disabled。坐标校验失败时，policy 返回原始 top-k 并仅设置 coordinate_mismatch_fallbacks=1；这里却只检查 policy_bypassed，随后丢弃其余 counters。结果是配置显示策略已启用，但每次请求都可能静默退回旧路径，日志和指标均无法发现。
• [6.1] Tests — 分布式/跨平台变更有对应覆盖 → issue 真实 H20 边界测试未进入常规 CI 门禁
  唯一跨越真实 Indexer、ragged/CP top-k kernel 和 SparseMlaOp 的测试被标记为 open_skip。benchmark 单测中的 IndexerOp 是 fake，只验证 Python 编排；本次变更也未增加显式选择该 H20 target 的 CI 配置，因此 CUDA 坐标或生产消费端回归不会形成合入门禁。
• [6.1] Tests — 新逻辑有聚焦单测 + 相关集成/smoke 测试 → issue 真实 H20 边界测试未进入常规 CI 门禁
  唯一跨越真实 Indexer、ragged/CP top-k kernel 和 SparseMlaOp 的测试被标记为 open_skip。benchmark 单测中的 IndexerOp 是 fake，只验证 Python 编排；本次变更也未增加显式选择该 H20 target 的 CI 配置，因此 CUDA 坐标或生产消费端回归不会形成合入门禁。

Strengths

• 策略默认关闭，并为 CUDA host sync 设置了独立显式开关和规模上限。
• 普通 prefill 与 CP prefill 均显式传递长度和绝对坐标 offset，并覆盖了 dtype、越界、单 token 和容量边界。
• benchmark runfiles 已完整声明；两组 CPU 单测可直接执行。

[Copilot]

Copilot was unable to review this pull request because the user who requested the review has reached their quota limit.

[LLLLKKKK]

AI Code Review - PR #1162

Status: BLOCKING

Summary: P0/0 · P1/2 · P2/1 · P3/0

Blocking Issues

P1

• H20 集成测试使用生产 fast-topk 不支持的宽度 @ rtp_llm/models_py/modules/hybrid/test/topology_kv_cuda_integration_test.py:103
  • 建议：按生产契约使用 topk=2048，并调整 query/prefix 长度以覆盖 length > topk 的实际截断场景；保留真实 Indexer、ragged/CP kernel 和 SparseMla consumer，不要通过 mock 绕过该断言。
• policy 测试缺少其直接读取文件的 Bazel runfiles @ benchmark/BUILD:16
  • 建议：通过专用 filegroup/exports_files 将所有直接读取的源文件、BUILD 和 .bzl 文件声明到 data，并为 metrics 使用正式依赖；更稳妥的是删除源码字符串自证，依靠真实 Bazel target 执行和 suite 依赖验证接入。

Non-blocking Suggestions

P2

• topology QPS 指标按 sparse layer 重复计数 @ rtp_llm/models_py/modules/hybrid/indexer.py:243
  • 建议：在 request/model 边界聚合后只上报一次 fallback/bypass QPS；若确实需要逐层采样，则将指标命名为 layer-forward event，并增加有界的 layer_idx tag，明确聚合语义。

Checklist Violations (4 fail / 114 total)

General Principles Checklist

• [6.1] Architecture — 可观测性：日志/指标/超时可操作、非噪声 → issue topology QPS 指标按 sparse layer 重复计数
  每个 sparse MlaAttention layer 都创建独立 Indexer，而 bypass/fallback AccMetric 在该 Indexer 的每次 forward 内上报。一个含 N 个 sparse layer 的请求会把同一次 cuda_sync_disabled、容量旁路或坐标 fallback 计为 N 次；tags 又没有 layer_idx，因此名为 QPS 的指标被层数放大，且无法区分具体层。
• [6.1] Tests — 新逻辑有聚焦单测 + 相关集成/smoke 测试 → issue policy 测试缺少其直接读取文件的 Bazel runfiles
topology_kv_policy_test 的 data 只包含 indexer.py 和 topology_kv_policy.py，但测试导入时直接加载 metrics reporter，随后还读取 CUDA integration 源文件、多个 BUILD 文件及 smoke suite .bzl。远程或沙箱 Bazel 只提供声明过的 runfiles，因此测试会在模块导入或 discovery 断言前因文件不存在而失败；直接从源码目录运行会掩盖此问题。

RTP-LLM Checklist

• [H] 测试与 CI — BUILD、py_test、cc_test、genrule 变更必须验证 srcs/data/runfiles/testdata 相对路径、import path 和 target 可执行性；genrule glob 不得捕获无关构建产物 → issue policy 测试缺少其直接读取文件的 Bazel runfiles
topology_kv_policy_test 的 data 只包含 indexer.py 和 topology_kv_policy.py，但测试导入时直接加载 metrics reporter，随后还读取 CUDA integration 源文件、多个 BUILD 文件及 smoke suite .bzl。远程或沙箱 Bazel 只提供声明过的 runfiles，因此测试会在模块导入或 discovery 断言前因文件不存在而失败；直接从源码目录运行会掩盖此问题。
• [H] 测试与 CI — 新增、迁移或删除测试必须证明目标行为仍在 CI 中执行；DISABLED_、#if 0、open_skip、导入即失败、未被 target 引用的用例不得计为覆盖 → issue policy 测试缺少其直接读取文件的 Bazel runfiles
topology_kv_policy_test 的 data 只包含 indexer.py 和 topology_kv_policy.py，但测试导入时直接加载 metrics reporter，随后还读取 CUDA integration 源文件、多个 BUILD 文件及 smoke suite .bzl。远程或沙箱 Bazel 只提供声明过的 runfiles，因此测试会在模块导入或 discovery 断言前因文件不存在而失败；直接从源码目录运行会掩盖此问题。

Strengths

• 新策略默认关闭，CUDA host-sync 路径需要显式开启，并为旁路和坐标不匹配提供了告警与指标。
• policy 单测覆盖了 topology-only、坐标区间、prefix/CP、容量限制、单 token 和 fallback 等主要边界。
• 候选输出保持原 tensor 的 dtype、device 和矩形 padding 契约。

[Copilot]

Copilot was unable to review this pull request because the user who requested the review has reached their quota limit.

[LLLLKKKK]

AI Code Review - PR #1162

Status: BLOCKING

Summary: P0/0 · P1/3 · P2/0 · P3/0

Blocking Issues

P1

• 候选裁剪没有推理质量回归门槛 @ rtp_llm/models_py/modules/hybrid/test/topology_kv_cuda_integration_test.py:301
  • 建议：为 topology_sparse_merge、topology_compress_sparse 和 topology_only 增加真实 Indexer 路径的 accuracy/golden 门槛，覆盖普通 prefill、prefix、batch>1 和 CP；使用确定性模型输入对比 disabled 基线，并让性能基准直接执行生产策略或复用同一调度实现。
• 策略配置延迟到首个 prefill 请求才完成校验 @ rtp_llm/models_py/modules/hybrid/indexer.py:78
  • 建议：在启动配置层声明并传播这些参数；Indexer 初始化时一次性构造、校验并保存冻结的 TopologyKvPolicyConfig。启用策略的非法配置应在服务接流量前 fail-fast，并补充启动期配置测试。
• H20 smoke gate 会把生产依赖故障当作跳过成功 @ rtp_llm/models_py/modules/hybrid/test/topology_kv_cuda_integration_test.py:98
  • 建议：在专用 H20 gate 中将缺少 CUDA 12.9、GPU 或 flash_mla 视为测试失败；若某些构建确实不支持该边界，应在 BUILD/CI 层条件注册目标，而不是运行时 skip。

Checklist Violations (3 fail / 107 total)

General Principles Checklist

• [6.1] Architecture — 兼容性：外部 HTTP/RPC API、持久数据、配置、环境迁移安全 → issue 策略配置延迟到首个 prefill 请求才完成校验
Indexer.__init__ 只解析环境值，范围和 coordinate_mismatch_action 校验要到 _apply_topology_kv_policy() 临时构造配置时才发生，CUDA sync guard 还会先行返回。启用策略后，负 block 数、越界 fraction 或错误 action 可通过启动与健康检查，随后在首个实际 prefill 请求抛错；这些配置也没有接入统一 server args/config 链路。
• [6.1] Architecture — 错误语义：fail-fast/retry/fallback/silent 行为显式 → issue 策略配置延迟到首个 prefill 请求才完成校验
Indexer.__init__ 只解析环境值，范围和 coordinate_mismatch_action 校验要到 _apply_topology_kv_policy() 临时构造配置时才发生，CUDA sync guard 还会先行返回。启用策略后，负 block 数、越界 fraction 或错误 action 可通过启动与健康检查，随后在首个实际 prefill 请求抛错；这些配置也没有接入统一 server args/config 链路。
• [6.1] Tests — 新逻辑有聚焦单测 + 相关集成/smoke 测试 → issue H20 smoke gate 会把生产依赖故障当作跳过成功
  该目标被加入 smoke_h20_mla 作为生产边界回归，但测试类使用 @skipIf(not CUDA_FLASHMLA_OK)；flash_mla 导入失败、CUDA 不可用或版本解析异常都会令目标以 skipped 成功结束。恰好需要该 gate 捕获的依赖打包或平台回归，因此可以在零生产断言执行的情况下保持 CI 绿色。

Strengths

• 策略默认关闭，CUDA host sync 还需要独立开关，具备明确回滚路径。
• 对 dtype、shape、候选坐标和容量设置了防护，坐标不匹配可返回原始 top-k。
• 指标 tag 使用有限集合，并为普通 prefill、prefix prefill 和 CP 路径增加了真实 CUDA 边界测试。