执行摘要
本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.” 无具体争议，变更被顺利接受。这反映设计合理，团队共识较高。
风险与影响
风险点：
- 调度器单线程假设：PR body强调“each scheduler is single-threaded”，需确保无并发问题，否则可能引发竞态条件。
- 事件循环延迟：
_check_pending_flush依赖process_input_requests循环，若循环间隔长，超时响应可能不精准。
- 测试覆盖：单元测试验证了核心逻辑，但未模拟高负载或极端超时，可能遗漏边界情况。
影响分析：
- 用户：API更友好，减少客户端错误处理负担，提升使用体验。
- 系统：轻微性能开销来自队列管理，但无显著性能退化。
- 团队：新增代码需维护，文档更新促进知识共享，单元测试增强代码可靠性。
关联脉络
与近期PR #21490（“Simplify flush_cache: reject concurrent requests, remove client-side retry”）紧密相关，两者协同优化flush_cache功能：本PR添加服务器端超时等待，而#21490简化逻辑并拒绝并发请求。这显示团队正逐步改进缓存刷新机制，以减少客户端依赖并提升系统稳定性。结合issue #21359，整体演进方向是增强API的健壮性和易用性，应对异步操作带来的状态管理挑战。
参与讨论