# 项目概览

这个项目验证一个问题：

**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 预测。