执行摘要

本PR为SGLang的/flush_cache API添加超时参数，解决了在HiCache异步操作进行时缓存刷新立即失败的问题。通过引入待处理队列和事件循环检查，允许系统在指定时间内等待空闲后执行刷新，提升了API的鲁棒性，减少客户端不必要的轮询。变更涵盖API端点、核心调度逻辑、单元测试和文档，是一个有意义的功能增强。

功能与动机

动机源自issue #21359，当HiCache进行异步操作（如GPU kv cache写入Host）时，flush_cache因系统非完全空闲而返回400 Bad Request错误。PR body明确指出：“flush_cache can only be safely applied when is_fully_idle() is true”，客户端需要不断轮询直到成功。引入超时参数后，服务器可等待系统空闲，减少重试开销。测试代码显示，添加timeout参数后，flush_cache请求成功执行，不再返回错误。

实现拆解

实现按模块拆解如下：

• API层：在python/sglang/srt/entrypoints/http_server.py中，修改flush_cache函数，添加timeout查询参数（默认0.0），并传递至tokenizer_manager。
• 数据层：更新python/sglang/srt/managers/io_struct.py中的FlushCacheReqInput类，新增timeout_s字段。
• 核心调度层：在python/sglang/srt/managers/scheduler.py中，关键改动包括：
  • 新增_pending_flush队列存储待处理请求和截止时间。
  • flush_cache_wrapped方法：根据timeout_s值决定立即刷新（超时≤0或系统空闲）或加入队列。
  • _check_pending_flush方法：在process_input_requests中每轮循环检查，若系统空闲则刷新所有待处理请求并回复成功，否则超时过期回复失败。
  • _expire_timed_out_pending_flushes方法：处理超时请求。
• 通信层：调整python/sglang/srt/managers/tokenizer_communicator_mixin.py的flush_cache方法以支持timeout_s参数。
• 测试与文档：新增test/registered/unit/managers/test_scheduler_flush_cache.py单元测试覆盖多种场景；更新docs/basic_usage/native_api.ipynb文档，添加参数说明和示例。

评论区精华

Review讨论较少，仅gemini-code-assist[bot]给出总结性评论：“This pull request introduces a new /flush_cache endpoint with a timeout parameter, allowing for deferred cache flushing.” 无具体争议，变更被顺利接受。这反映设计合理，团队共识较高。

风险与影响

风险点：

1. 调度器单线程假设：PR body强调“each scheduler is single-threaded”，需确保无并发问题，否则可能引发竞态条件。
2. 事件循环延迟：_check_pending_flush依赖process_input_requests循环，若循环间隔长，超时响应可能不精准。
3. 测试覆盖：单元测试验证了核心逻辑，但未模拟高负载或极端超时，可能遗漏边界情况。

影响分析：

• 用户：API更友好，减少客户端错误处理负担，提升使用体验。
• 系统：轻微性能开销来自队列管理，但无显著性能退化。
• 团队：新增代码需维护，文档更新促进知识共享，单元测试增强代码可靠性。

关联脉络

与近期PR #21490（“Simplify flush_cache: reject concurrent requests, remove client-side retry”）紧密相关，两者协同优化flush_cache功能：本PR添加服务器端超时等待，而#21490简化逻辑并拒绝并发请求。这显示团队正逐步改进缓存刷新机制，以减少客户端依赖并提升系统稳定性。结合issue #21359，整体演进方向是增强API的健壮性和易用性，应对异步操作带来的状态管理挑战。