执行摘要

• 一句话：限制预填充 inflight 轮询警告频率
• 推荐动作：值得合并，变更安全且目标明确。建议阅读 review 讨论中关于 KVPoll.Bootstrapping 状态异常的跟踪 issue (#25063)，以排查底层根本原因。

功能与动机

在分离式预填充中，process_disagg_prefill_inflight_queue 在每次调度循环中轮询 inflight KV 发送器。如果请求处于短暂的中间状态，同一个警告会频繁重复输出，导致日志噪音过大。PR body 中展示了当前代码的输出截图，一行警告反复打印。

实现拆解

1. 在 python/sglang/srt/disaggregation/prefill.py 的 process_disagg_prefill_inflight_queue 方法中，将 PP 共识路径下的 logger.warning 替换为 logger.warning_once，该警告在 PP rank 上遇到非终端 poll 状态时触发。
2. 将该方法中通用 inflight 意外状态路径下的 logger.warning 也替换为 logger.warning_once，该路径在所有非 PP 场景下也会触发。
3. 两处调用均添加了尾随逗号以保持与 warning_once 签名兼容。
4. 未涉及测试、配置或部署变更。

关键文件：

• python/sglang/srt/disaggregation/prefill.py（模块 解耦预填充；类别 source；类型 core-logic）: 唯一变更文件，修改了 process_disagg_prefill_inflight_queue 中的两处日志调用，将 logger.warning 替换为 logger.warning_once，以抑制重复警告。

关键符号：process_disagg_prefill_inflight_queue

关键源码片段

python/sglang/srt/disaggregation/prefill.py

唯一变更文件，修改了 process_disagg_prefill_inflight_queue 中的两处日志调用，将 logger.warning 替换为 logger.warning_once，以抑制重复警告。

# python/sglang/srt/disaggregation/prefill.py (partial)
​
def process_disagg_prefill_inflight_queue(self, rids_to_check=None):
    """
    Poll the requests in the middle of transfer. If done, return the request.
    rids_to_check: For PP, on rank > 0, check the rids from the previous rank has consensus with the current rank.
    """
    # ... 轮询逻辑 ...
    for req, poll in zip(self.disagg_prefill_inflight_queue, polls):
        if rids_to_check is not None:
            # ... PP 共识检查 ...
            if poll not in (KVPoll.Success, KVPoll.Failed):
                # 使用 warning_once 避免每个调度循环重复输出相同 rid 的警告
                logger.warning_once(
                    f"PP rank {self.pp_rank}: unexpected poll state {poll} for rid {req.rid} "
                    f"from consensus; treating as undone",
                )
                undone_reqs.append(req)
                continue
        # ... 处理成功 / 失败 / 传输中状态 ...
        else:
            # 非 PP 路径下的意外 poll 状态，同样使用 warning_once 抑制重复
            logger.warning_once(
                f"Unexpected polling state {poll} for rid {req.rid} in inflight queue; "
                f"treating as undone",
            )
            undone_reqs.append(req)
    # ... 后续完成请求处理 ...

评论区精华

1. 最初的实现使用了自定义 _log_prefill_inflight_poll_warning 辅助函数来按 rid 追踪警告状态。审核者 ShangmingCai 建议直接使用 logger.warning_once，认为这样更简洁。
2. 作者 tangcy98 担心 warning_once 会丢失请求的实时状态信息，但审核者指出 KVPoll.Bootstrapping 状态不应出现在 process_disagg_prefill_inflight_queue 中，因此使用 warning_once 足以捕获首次出现的情况，同时避免噪音。
3. 审核者进一步指出需要调查为什么请求会以 KVPoll.Bootstrapping 状态出现在该函数中，并建议创建 issue 跟踪。作者已创建 issue #25063。

• 使用 logger.warning_once 还是自定义辅助函数 (design): 采用 logger.warning_once，放弃自定义辅助函数。
• KVPoll.Bootstrapping 状态异常 (question): 创建 issue #25063 跟踪根本原因。

风险与影响

• 风险：极低风险。变更仅限于日志输出方式，不涉及推理路径逻辑。logger.warning_once 是 Python logging 的内置方法，仅在日志系统层面过滤重复消息，不会影响运行时的正确性或性能。
• 影响：影响范围很小，仅改动一个文件中的两行日志调用。受益用户是使用分离式预填充并遇到大量重复警告日志的开发者或运维人员，日志噪音将显著降低。
• 风险标记：日志变更, 无测试覆盖

关联脉络

• PR #24932 [PD] Refactor hybrid state transfer: 同属分离式预填充模块的重构，修改了同一目录下的多个文件。