Dynamo Router 调用链与关键信息

请求 tokens
   │
   ▼
KvPushRouter (端到端，含分发 / 生命周期)
   │  调用
   ▼
KvRouter::find_best_match_details          ← 顶层协调
   ├─► Indexer.find_matches_by_tier()       ← 缓存命中（device / host / disk 分层）
   ├─► (可选) SharedKvCache.check_blocks()   ← 外部共享缓存（HiCache）
   └─► KvScheduler.schedule()
          └─► LocalScheduler → SchedulerQueue → WorkerSelector(cost function)
                                    │
                                    └─► ActiveSequencesMultiWorker(active block 跟踪)

缓存块由 KvIndexer 的全局 radix tree 维护；活跃块由 router 本地 slot manager 跟踪。

router 为每个 worker 跟踪这两类负载，共同喂给成本函数。

• Potential Prefill Blocks（预填充成本）
  新请求需从头计算的 token =（总输入 − 重叠块 × block_size）/ block_size。
  来源：KvIndexer 的全局前缀树（基于 worker 上报的 KV 事件）。重叠越多 → 改善 TTFT。
• Potential Decode Blocks（解码负载）
  worker 当前活跃序列占用的 block，反映其繁忙程度。
  来源：router 本地 slot manager（ActiveSequencesMultiWorker）。加入 +1、prefill 完成更新、释放 −1。影响 ITL。

frontend → preprocessor → migration → backend → [prefill_op] → [service_backend]

KV 模式下 service_backend = decode 侧 KvPushRouter。
来源：lib/llm/src/entrypoint/input/common.rs:369–379

缩进表示嵌套调用；标 ★ 的为进入 router 核心的步骤。

1. PrefillRouter::generate
prefill_op 的 forward 入口。未激活 prefill → 直接走 next（聚合模式）； 否则 set_phase(Prefill)，克隆 prefill_req（max_tokens=1）。
   lib/llm/src/kv_router/prefill_router/mod.rs:82
   2. resolve_prefill_worker(prefill_req, preselected)
      为 Bootstrap 优化提前选 worker、拿 bootstrap（host/port/room）。无预选 worker 时调 query_prefill_worker。
      lib/llm/src/kv_router/prefill_router/execution.rs:24
      3. ★ KvRouter::find_best_match(update_states=false)
         peek 行为：只窥探最佳 worker，不预订调度槽。非 KV 模式则走 SimpleRouter 轮询/随机。
         execution.rs:281 → kv_router.rs:632
   3. execute_prefill / spawn_prefill_task
      真正执行 prefill。Bootstrap 路径后台 spawn，原始路径同步等待完成。
      lib/llm/src/kv_router/prefill_router/execution.rs:128
      5. ★ InnerPrefillRouter::generate_to_worker → KvPushRouter::generate
         prefill 侧端到端路由：请求已带 prefill_worker_id，走精确 pin 路径 （update_states=true 预订槽）+ inner.direct() 分发。
         inner.rs:33 → push_router.rs:490
   6. ★ next.generate(decode_req) → KvPushRouter::generate
      prefill 完成后 set_phase(Decode)，注入 decode override （overlap_score_credit=0、assume_kv_reuse=false、track_prefill_tokens=false）， 路由到 decode worker。
      mod.rs:249 → service_backend (decode KvPushRouter)

上面 3 处核心入口最终都收敛到 KvRouter::find_best_match_details （kv_router.rs:464），内部三步：

• a. compute_block_hash_for_seq(tokens) — 按 block_size 切块并对每块 token 内容做 hash；有 LoRA 时把 adapter 名混入 hash。 kv_router.rs:490
• b. Indexer::find_matches_by_tier(block_hashes) — 在 radix tree 上做分层前缀匹配（device / host_pinned / disk），返回 per-worker 命中块数； 可并行查询外部 SharedKvCache（HiCache）。 kv_router/indexer/mod.rs:337
• c. KvScheduler::schedule → SchedulerQueue → DefaultWorkerSelector — 队列准入（容量阈值背压）→ 成本函数为每个 worker 打分 → 选最低 cost（或 softmax 采样）→ ActiveSequences 记账。 scheduler.rs / scheduling/queue.rs / scheduling/selector.rs

adjusted_prefill = max(
    raw_prefill_blocks
    - overlap_score_credit   * device_overlap_blocks
    - host_cache_hit_weight  * host_overlap_blocks
    - disk_cache_hit_weight  * disk_overlap_blocks
    - shared_cache_multiplier* shared_beyond_blocks,
    0)

cost = prefill_load_scale * adjusted_prefill + decode_blocks   // 越低越好

来源：lib/kv-router/src/scheduling/selector.rs:160–168
temperature=0 取最低 cost（并列随机）； temperature>0 对 cost 做 softmax 采样以分散负载。

• NATS Core / Event Plane + Local Indexer（默认）
  worker 各自维护 local radix tree，通过事件面（NATS Core 或 ZMQ）发布；事件带单调递增 id。 router 检测序号 gap 主动向 worker 补查；worker 上线 dump 全量、下线移除其块。延迟低、部署简单。
• JetStream（--durable-kv-events，opt-in）
  KV 事件进持久化 JetStream，各 router replica 作为 durable consumer 消费， 状态经 object store 快照跨重启持久化。适合需要多副本一致性的生产环境； 前端与 worker 都需开启。已标记 deprecated。

来源：lib/kv-router/src/scheduling/config.rs · 多数参数还可通过 RouterConfigOverride 逐请求覆盖。