agentic-pd-hybrid/docs/PROJECT_OVERVIEW.md

项目概览

这个项目验证一个问题：

agentic coding workload 里，如果 router 更懂 session 和 KV cache，P/D serving 的端到端延迟能不能更低。

当前基于：

• SGLang v0.5.10
• Qwen3-Coder-30B-A3B-Instruct
• 单机 8 GPU
• Mooncake loopback 模拟 P -> D 传输

设计

代码按两层分开：

• 机制：启动 SGLang、发送请求、管理 session、收集 metrics。
• 策略：决定请求去哪个 P node、哪个 D node。

这样后续可以单独改 routing policy，不把它和 SGLang/xPyD 机制混在一起。

已实现

• 单机 P/D stack 启动和关闭。
• 本地 Python PD router。
• Ali trace 加载、session 级采样、synthetic prompt 生成。
• 按 trace 原始到达时间 replay，不用固定 concurrency 强行压流量。
• request-level metrics 和 summary。
• 路由策略：
  • default
  • sticky
  • kv-aware
• serving 机制：
  • pd-disaggregation
  • kvcache-centric
  • pd-colo
• micro-benchmark trace 生成。
• worker-managed / router-managed KV admission 对比。
• worker-managed 下的 D session soft-cap，避免所有 session 都挤进 D KV。
• SGLang patch：
  • decode worker 支持 PD mode 下 local append-prefill；
  • 暴露 streaming session cache 状态；
  • 支持按 session 粒度 evict idle streaming session；
  • 支持 direct append admission 查询。

当前结论

micro-benchmark 上，kvcache-centric 可以比 pd-disaggregation 好。

原因很简单：session 少，D KV 放得下，turn2+ 可以直接走 D session，省掉一部分 P/D 路径开销。

但在 300+ request、58 session 的测试上，情况不同：

• D KV 放不下全部 session working set。
• naive worker-managed 会频繁 evict/reseed 整个 session。
• reseed 和 transfer 压力会抵消 KV reuse 收益。
• aggressive P-backup 会增加尾延迟风险。

当前 soft-cap 优化后：

• worker-managed 比旧版本更稳；
• TTFT 明显下降；
• 没有再出现 600s transfer hang 被当成成功响应的问题；
• 但 sampled Ali trace 上，pd-disaggregation 仍然略好。

当前判断：

KV-cache-centric 只应该保留真正 hot 的 session。不是所有 session 都值得占 D KV。

下一步最有价值的是：

• inter-turn-gap-aware admission；
• session aging；
• 更精确地预测哪些 session 会很快复用 KV。

SGLang 维护方式

third_party/sglang 已纳入主仓库。

历史结构：

• chore: vendor sglang v0.5.10 snapshot：干净上游基线。
• feat(sglang): ... / fix(sglang): ...：我们的 SGLang patch。

后续改 SGLang 时：

• 只改 third_party/sglang 下相关文件；
• 单独提交；
• commit message 带 (sglang)；
• 不把 benchmark 输出、pyc、日志混进提交。

已知限制

• 这是实验原型，不是生产 router。
• 当前主要验证单机 8 GPU。
• Ali trace 没有原始 prompt，只能用 hash_ids 合成 prompt。
• 当前 routing 还缺少真正的 hot-session 预测。