Components

Router

以 Markdown 格式查看

Dynamo KV Router 通过评估不同 worker 上的计算成本来智能地路由请求。它同时考虑解码成本（来自活动 block）和预填充成本（来自新计算的 block），并利用 KV cache 重叠来尽量减少重复计算。优化 KV Router 对于在分布式推理部署中实现最大吞吐量和最低延迟至关重要。

快速开始

我们可以通过 Dynamo frontend 使用 KV Router：

$python -m dynamo.frontend --router-mode kv --http-port 8000

对于 Kubernetes，请在 Frontend service 上设置 DYN_ROUTER_MODE=kv。对于事件驱动的 KV 状态，请使用 Router Operations 中描述的后端专用 flag，配置 backend worker 发布 KV cache 事件。仅当你希望使用近似的 cache 状态预测时，才使用 --no-router-kv-events。

参数默认值描述
--router-mode kvround-robin启用感知 KV cache 的路由
--load-awaredisabled使用 KV 活动负载路由，不使用 cache 复用信号；在 frontend 上隐含启用 --router-mode kv
--router-kv-overlap-score-credit1.0设备本地 prefix 重叠的 credit 乘数，范围从 0.0 到 1.0
--router-prefill-load-scale1.0在加入 decode block 之前，对调整后的 prompt 侧 prefill 负载进行缩放
--router-kv-events / --no-router-kv-events--router-kv-events消费 worker KV 事件，或在没有事件时回退到近似路由
--router-queue-thresholddisabled背压队列阈值；设置数值后启用队列，nvext.agent_hints.priority 会对等待中的请求重新排序
--router-queue-policyfcfs队列调度策略：fcfs（尾部 TTFT）、wspt（平均 TTFT）或 lcfs（仅用于比较的反向排序）
--no-router-track-prefill-tokensdisabled在 router 负载统计中忽略 prompt 侧 prefill token；适用于仅 decode 的路由路径

独立 Router

你也可以将 KV router 作为独立服务运行（不使用 Dynamo frontend）。更多详细信息请参阅 Standalone Router component。

有关部署模式和快速开始步骤，请参阅 Router Guide。有关 CLI 参数和调优指南，请参阅 Configuration and Tuning。有关 A/B 基准测试，请参阅 KV Router A/B Benchmarking Guide。

前提条件和限制

要求：

  • 仅支持动态 endpoint：KV router 要求使用 model_input=ModelInput.Tokens 调用 register_model()。你的 backend handler 会接收带有 token_ids 的预分词请求，而不是原始文本。
  • Backend worker 必须使用 model_input=ModelInput.Tokens 调用 register_model()（请参阅 Backend Guide）
  • 使用 KV routing 时请使用动态发现，以便 router 跟踪 worker 实例及其 KV cache 状态

多模态支持：

  • 通过多模态 hash 进行图像路由：在已文档化的 TRT-LLM 和 vLLM router 路径中受支持。
  • 其他 backend 或模态组合：在依赖多模态 hash routing 之前，请检查相应 backend 的多模态文档。

限制：

  • KV routing 不支持静态 endpoint；请使用动态发现，以便 router 跟踪 worker 实例及其 KV cache 状态

对于不使用 KV routing 的基础模型注册，请在静态和动态 endpoint 中使用 --router-mode round-robin、--router-mode random、--router-mode least-loaded 或 --router-mode device-aware-weighted。

后续步骤