[Bug]: persistent_topk silently drops top-k candidates when many values share a coarse histogram bin

快速结论：这个报错出现在调用 vLLM 的 torch.ops._C.persistent_topk 时：当同一行里大量元素落进同一个粗粒度直方图 bin（例如 logits 值域很窄，或 fp32 logits 超过 fp16 上限被统一映射为 +inf），该算子会静默丢弃真实的 top-k 候选并返回更小的值。优先排查 logits 的数值分布以及 k 与序列长度的组合。

适用环境：Issue 中已确认的环境为 vLLM 0.20.1.dev408+ga019ba60d（源码分析基于 main 的 a311916a291c1fed3dbfb72e60f74cd778c8419d）、CUDA 13.0.88、PyTorch 2.11.0+cu130、NVIDIA B300 SXM6（sm103）。另有独立复现报告：Tesla V100（SM70）、CUDA 12.8、PyTorch 2.10.0，基于包含 #41444 修复的 vLLM 派生分支。

最快修复方案：暂无确认的一步修复方案（Issue 中未出现已验证的补丁或开关）。可优先尝试：在小 row 数场景下改用 torch.topk 替代该调用，报告者用此方式恢复了逐步选择的逐位一致性和跨进程 16/16 token 匹配（V100 上 decode 单步开销约 15%–25%）。这一做法属于缓解而非修复。

注意事项：换用 torch.topk 会带来性能开销，且只在报告者的 V100 小 row 数场景下验证过，其他硬件与大 batch 场景未验证。该故障的输出不含 -1 槽位，也没有重复索引，因此除与参考实现（如 torch.topk）逐值比对外，其他检查都发现不了问题。

问题场景

在 vLLM 稀疏注意力索引器（sparse_attn_indexer / DSA 类模型，如报告中的 Qwen3.8 Flash Next、QSA indexer、TP4）中，调用了 torch.ops._C.persistent_topk 从 logits 中选出 top-k 候选。当一行的 logits 值域较窄（训练后的 indexer head 的常见状态），或许多值共享同一个粗直方图 bin 时，返回结果会静默出错：丢失真实 top-k 候选，并用更小的值替代。报告者在全模型 decode 中观察到：相同 prompt、temperature=0 时，在 ≥4K 上下文下每次运行产生不同的贪心输出，首次出现分歧的 tensor 可追溯到该算子。

报错原文

[Bug]: persistent_topk silently drops top-k candidates when many values share a coarse histogram bin

原因分析

可能原因：该算子内部的多个实现路径都有固定的内部缓冲区容量，当同一个粗 bin 中的候选数超过容量时，结果被静默截断，而不会报错。评论中给出了各处容量线索：

FilteredTopK 路径在 bin 人口为 16384 时结果干净，16385 时开始丢候选。
medium 路径（lens ≤ RADIX_THRESHOLD）常量 MAX_BUFFERED_ITEMS = 4096；评论者测得 bin 人口恰为 4096 时仍每轮丢 32–128 个候选。
histogram_2048_topk 路径（seq_len ≤ HIST2048_THRESHOLD = 8192）的双缓冲容量 DBUF = (SBASE - BOFF) / 2 = 3708，小于 4096，且同样使用带保护条件的静默追加模式。评论者认为这一容量能解释测得的 32–128 非确定性丢弃。
另一条触发路径：算子接收 fp32 logits，但 ToCoarseKey 会把值转换为 fp16；任何超过 65504 的 fp32 值都会被映射为 +inf，从而全部落入同一个粗 bin，按构造直接进入最坏情形。

丢弃数量多为 warp 粒度（32/64/96/128），并且同一输入多次调用结果不一致，说明存在非确定性成分。返回值严格小于正确值，属于值错误，而不仅仅是 tie-break 顺序差异。

环境排查

确认 vLLM 版本是否受该内核实现影响（报告中为 0.20.1.dev408+ga019ba60d，源码基于 main a311916a291c1fed3dbfb72e60f74cd778c8419d，并提到 #41444 修复已包含在派生分支中）。
确认 CUDA 与 PyTorch 版本（报告环境：CUDA 13.0.88 / PyTorch 2.11.0+cu130；V100 复现环境：CUDA 12.8 / PyTorch 2.10.0）。
确认 GPU 架构（B300 sm103 / V100 SM70 均已复现）。
检查调用方 logits 的值域：是否存在大量值集中在狭窄范围，或 fp32 值超过 65504 被转为 fp16 后变成 +inf。
确认 k（512/1024/2048 均受影响）与序列长度的组合，以及走的是哪条内核路径（受 RADIX_THRESHOLD、HIST2048_THRESHOLD=8192 等阈值影响）。

解决步骤

先用与 Issue 中类似的复现脚本（窄值域 logits、k 取 512/1024/2048、较长行）确认你的环境能否复现：比较 persistent_topk 选出的值多重集与 torch.topk 参考值，只比较值、不比较索引顺序。
如果确认复现，在调用方对受影响的场景改用 torch.topk 作为临时替代（可优先尝试；报告者在 V100 小 row 数下验证有效，代价是 decode 单步约 15%–25% 开销）。
检查你的输入构造：若某些分数可能超过 65504（例如由列索引派生的 rank key），评估能否缩放到 fp16 范围内，以减少落入单一粗 bin 的概率。
关注上游修复：Issue 已关闭（2026-10-26），但评论证据表明截断容量问题涉及多条路径，升级前建议用上述复现脚本回归验证。

验证方法

对同一输入，将 persistent_topk 返回的索引 gather 回原 logits，排序后与 torch.topk(logits, k) 的值排序结果逐值比对（无需容差），应无差异；同时对同一输入重复调用多次，应得到一致的选择集合。端到端可在 temperature=0 下多次运行同一 prompt，确认贪心输出逐 token 一致（报告中修复替换后跨进程实现 16/16 token 匹配）。