vLLM Router Chat 请求路由与 Worker 选择调用流程
vLLM Router Chat 请求路由与 Worker 选择调用流程
分析对象:vLLM Router
router/子树,仓库提交2d61d39,分析日期 2026-11-18。
分析方式:静态代码阅读,未进行运行时和性能验证。
文中源码路径均相对于router/。
1. 结论摘要
Chat 请求到达 Router 后,选择过程分两层:
- 先确定由哪个 Router 实例处理:单 Router 模式下由启动参数决定;IGW 模式下由
RouterManager按请求的model和 worker 类型决定。 - 再由该 Router 选择 worker:Regular Router 选一个 worker;PD Router 同时选一对 Prefill/Decode worker。
关键结论:
- 请求本身不带“Regular 或 PD”标记,判断依据是部署模式和 worker 注册类型。
- 单 Router 模式(
enable_igw=false)下,进程启动时AppState.router已经固定,请求不参与 Router 类型判断。 - IGW 模式(
enable_igw=true)下,RouterManager::get_router_for_model查该模型的 worker:存在Prefill/Decode类型则走http-pd,否则走http-regular。 - Regular 路径的候选池先按 model 过滤,再过滤健康状态和熔断状态,最后交给
--policy指定的策略选择。 - PD 路径在同一个准入锁内完成 P/D 成对选择和负载预留,不是两次独立请求。
- 选择发生在每次重试 attempt 内,失败重试会重新走选择流程。
2. 对象与术语
| 名称 | 含义 | 主要代码 |
|---|---|---|
RouterManager |
IGW 模式下的元路由,持有 http-regular 和 http-pd 两个 Router |
src/routers/router_manager.rs |
Router |
Regular Router,单 worker 选择与转发 | src/routers/http/router.rs |
VllmPDRouter |
PD Router,负责 P/D 成对选择和两阶段编排 | src/routers/http/vllm_pd_router.rs |
PdRouterBase |
PD 公共逻辑,包括候选过滤、准入和阶段选择 | src/routers/http/pd_router.rs |
Worker |
后端推理实例,带有 WorkerType、健康状态和熔断状态 |
src/core/worker.rs |
PolicyRegistry |
维护 model 到策略实例的映射,以及 PD 的 P/D 策略 | src/policies/registry.rs |
LoadBalancingPolicy |
负载均衡策略统一接口 | src/policies/mod.rs |
PdAttempt |
一次 P/D 准入的生命周期句柄,负责释放 P/D 负载 | src/routers/http/pd_types.rs |
WorkerType 有三种:
1 | |
它是 IGW 判断走 Regular 还是 PD 的直接依据。
3. 启动阶段:Router 实例的创建与保存
3.1 启动装配流程
flowchart TD
A["main.rs 解析 CLI"] --> B["server.rs::startup"]
B --> C["AppContext::new<br/>WorkerRegistry + PolicyRegistry"]
C --> D{"enable_igw"}
D -- "false" --> E["RouterFactory::create_router<br/>按 RoutingMode 创建单个 Router"]
D -- "true" --> F["RouterManager::new<br/>注册 http-regular / http-pd"]
E --> G["Arc 包装后的 Router 实例"]
F --> G
G --> H["AppState.router"]
H --> I["Arc 包装的 AppState"]
I --> J["build_app_with_wasm_middleware"]
J --> K[".with_state(app_state)"]
K --> L["serve(listener, app)"]
3.2 单 Router 模式
enable_igw=false 时,RouterFactory::create_router 只创建一个 Router:
| 启动条件 | RoutingMode | Router 实现 |
|---|---|---|
--vllm-pd-disaggregation,且配置了 --prefill/--decode、--vllm-discovery-address 或 K8s discovery |
VllmPrefillDecode |
VllmPDRouter |
--backend openai |
OpenAI |
OpenAIRouter |
其他,配合 --worker-urls |
Regular |
Router |
代码位置:
- CLI 转
RouterConfig:src/main.rs:484-570 - Router 创建:
src/routers/factory.rs:17-46 - 单 Router 分支:
src/server.rs:1210-1215
PD 模式缺少 P/D 地址或发现配置时,启动阶段直接报错,不会进入服务状态(src/main.rs:518)。
3.3 IGW 模式
enable_igw=true 时,启动阶段注册两个 Router:
http-regular→Routerhttp-pd→VllmPDRouter
代码位置:src/server.rs:1160-1199。
第一个注册成功的 Router 被设为默认 Router,正常情况下是 http-regular(src/routers/router_manager.rs:87-97)。两个 Router 共享 AppContext 里的 WorkerRegistry 和 PolicyRegistry,因此动态添加的 worker 对两者都可见。
3.4 Router 实例保存位置
Router 实例没有存放在全局静态变量中,所有权链如下:
1 | |
AppState 定义在 src/server.rs:111-117:
1 | |
请求处理函数通过 Axum 的 State 提取器拿到它:
1 | |
代码位置:src/server.rs:266-276。
IGW 模式下:
AppState.router指向RouterManager- 真正的
http-regular/http-pd保存在RouterManager.routers - 类型为
Arc<DashMap<RouterId, Arc<dyn RouterTrait>>>,定义在src/routers/router_manager.rs:55
4. 请求入口调用链
4.1 HTTP 入口
sequenceDiagram
autonumber
participant C as Client
participant AX as Axum 路由层
participant H as v1_chat_completions
participant AUTH as authorize_request
participant RM as RouterManager
participant WR as WorkerRegistry
participant R as 目标 Router
C->>AX: POST /v1/chat/completions
Note over AX: RequestId / CORS / BodyLimit / 并发限制等 layer
AX->>AX: 匹配 route,进入 post(v1_chat_completions)
AX->>AX: ChatCompletionRequest 反序列化
AX->>H: v1_chat_completions(State, HeaderMap, Json)
H->>AUTH: authorize_request(&state, &headers)
alt 配置了 api_key_validation_urls
AUTH->>AUTH: 查 api_key_cache
AUTH->>AUTH: 请求 validation URL 校验 Bearer token
end
AUTH-->>H: Ok / 401
alt enable_igw = true
H->>RM: state.router.route_chat(headers, body, None)
RM->>RM: select_router_for_request(headers, body.model)
RM->>WR: get_by_model(model)
WR-->>RM: worker 列表
RM->>RM: 检查 Prefill/Decode 类型
RM->>R: 选中实例 route_chat(...)
else enable_igw = false
H->>R: state.router.route_chat(headers, body, None)
end
R-->>AX: Response
AX-->>C: JSON 或 SSE
代码位置:
| 步骤 | 代码位置 |
|---|---|
| 路由注册 | src/server.rs:957-967 |
| 入口函数 | src/server.rs:266-276 |
| 鉴权 | src/server.rs:493 |
| RouterManager 入口 | src/routers/router_manager.rs:627-649 |
| Router 选择 | src/routers/router_manager.rs:398-476 |
| 按 model 取 Router | src/routers/router_manager.rs:111-143 |
从入口到 worker 的模块调用总览:
| 阶段 | 模块 | 关键函数 |
|---|---|---|
| HTTP 接入 | src/server.rs |
v1_chat_completions |
| 鉴权 | src/server.rs |
authorize_request |
| 元路由(IGW) | src/routers/router_manager.rs |
route_chat、select_router_for_request、get_router_for_model |
| Regular 请求处理 | src/routers/http/router.rs |
route_chat、route_typed_request、route_prepared_request |
| 重试循环 | src/core/retry.rs |
RetryExecutor::execute_response_with_retry |
| 策略查找 | src/policies/registry.rs |
get_policy_or_default |
| 候选 worker | src/core/worker_registry.rs |
get_by_model_fast、get_all |
| 选择算法 | src/policies/* |
select_worker_with_qualified_inputs、select_worker_with_inputs、select_worker_with_headers |
| Regular 下发 | src/routers/http/router.rs |
send_typed_request |
| PD 请求处理 | src/routers/http/vllm_pd_router.rs |
route_chat、route_transparent、admit_pair、process_vllm_two_stage_request |
| PD 准入与选择 | src/routers/http/pd_router.rs |
select_and_admit、select_pd_pair、select_stage |
| 传输 | src/backend/frontend.rs / src/otel_http.rs |
dispatch_with_first_output(gRPC)、send_client_request(HTTP) |
补充:配置了 epd 时,/v1/chat/completions 会注册成 epd_chat_completions,走 route_transparent(src/server.rs:961-965),而不是 v1_chat_completions。
4.2 Router 选择判定
flowchart TD
A["route_chat 请求"] --> B{"IGW 模式?"}
B -- "否" --> C["使用启动时创建的 AppState.router"]
B -- "是" --> D{"请求带 model?"}
D -- "是" --> E["worker_registry.get_by_model(model)"]
E --> F{"存在 Prefill/Decode worker?"}
F -- "是" --> G["http-pd"]
F -- "否" --> H["http-regular"]
E --> I{"该 model 没有 worker?"}
I -- "是" --> J["默认 Router<br/>通常为 http-regular"]
D -- "否" --> K["遍历所有 Router 打分"]
K --> L{"x-prefer-pd 命中?"}
L -- "是" --> G
L -- "否" --> H
具体规则:
请求带
modelworker_registry.get_by_model(model)取该模型的 worker。- 任意 worker 是
WorkerType::Prefill { .. }或WorkerType::Decode→ 选http-pd。 - 全部是
WorkerType::Regular→ 选http-regular。 - 模型没有 worker,或对应 Router 创建失败 → 退回默认 Router。
请求不带
model- 遍历所有已注册 Router 打分。
- 代码期望无
x-prefer-pd时偏向 Regular,有x-prefer-pd时偏向 PD。 - 当前实现存在类型字符串不一致,见 9.2 节;上图描述的是代码意图。
4.3 Worker 类型如何产生
IGW 模式下通过 POST /workers 动态添加:
1 | |
RouterManager::add_worker 根据 worker_type 创建不同类型的 worker(src/routers/router_manager.rs:187-204):
worker_type |
创建的 Worker |
|---|---|
"prefill" |
WorkerFactory::create_prefill_with_labels |
"decode" |
WorkerFactory::create_decode_with_labels |
| 其他或省略 | WorkerFactory::create_regular_with_labels |
未指定 model_id 时,会访问 worker 的 /v1/models 或 gRPC GetModelInfo 自动发现模型(src/routers/router_manager.rs:162-177)。
静态 PD 模式下,--prefill / --decode 在启动时直接注册为 Prefill / Decode(src/routers/http/pd_router.rs:1064-1083)。
5. Regular Router 调用链
5.1 调用时序
sequenceDiagram
autonumber
participant C as Client
participant S as Axum 路由层
participant R as Router
participant RR as RetryExecutor
participant PR as PolicyRegistry
participant WR as WorkerRegistry
participant P as LoadBalancingPolicy
participant IP as 输入准备
participant W as Worker
participant M as RouterMetrics
C->>S: POST /v1/chat/completions
Note over S: 入口与鉴权见 4.1 节
S->>R: route_chat
R->>R: route_typed_request
R->>R: route_prepared_request
R->>R: typed_req.get_model()
R->>WR: has_model(model)
R->>R: classify_worker_urls
alt gRPC 池
R->>R: EngineFrontend::prepare(chat)
else HTTP 池
R->>R: 保留 raw body
end
R->>R: extract_text_for_routing
R->>R: resolve_affinity_identity
R->>RR: RetryExecutor::execute_response_with_retry(...)
loop 每个 attempt
RR->>R: 执行 attempt 闭包
opt 启用 Program scheduling
R->>R: acquire_program_completion
end
Note over R: forced_worker_url 存在时跳过策略选择
R->>PR: get_policy_or_default(model)
PR-->>R: Arc 包装的 Policy
R->>WR: get_by_model_fast(model) / get_all
WR-->>R: worker 列表
R->>R: filter is_available
opt kv_aware / cache_aware 需要 token
R->>IP: prepare_http_kv_inputs
IP->>W: POST /tokenize
W-->>IP: token ids
IP-->>R: WorkerTokenInputs
end
R->>R: select_worker_for_model
alt kv_aware
R->>P: select_worker_with_qualified_inputs
else cache_aware
R->>P: select_worker_with_inputs
else 其他策略
R->>P: select_worker_with_headers
end
P-->>R: worker index / receipt
R->>R: RequestLoadGuard::from_selection
R->>R: send_typed_request
alt gRPC worker
R->>W: EngineFrontend::dispatch_with_first_output
W-->>R: gRPC stream
else HTTP worker
R->>W: POST worker_url + route
W-->>R: Response / SSE
end
R->>W: record_outcome
R->>R: failed_workers.push (kv/plugin)
R-->>RR: Response
RR->>RR: should_retry / backoff
end
RR-->>R: final Response
R->>M: record_request / record_generate_duration
R-->>S: Response
S-->>C: JSON 或 SSE
函数调用栈(Regular):
1 | |
5.2 分步说明
进入 Regular Router
route_chat:src/routers/http/router.rs:2976-2984route_typed_request:src/routers/http/router.rs:1496-1505route_prepared_request:src/routers/http/router.rs:1508
解析 model
- 代码:
src/routers/http/router.rs:1519-1521
1
2
3let model_id = model_id
.or_else(|| typed_req.get_model())
.filter(|model| self.worker_registry.has_model(model));如果请求里的
model没有注册,会被当成None,后续从全部 worker 中选择。- 代码:
判断 backend 池类型
- 代码:
src/routers/http/router.rs:1525-1530 - 所有 worker URL 必须是同一种协议,全部 HTTP 或全部 gRPC。混合池在启动或添加 worker 时会被拒绝。
- 代码:
准备 token 输入
- gRPC 池在进入策略前由
EngineFrontend统一 tokenize(src/routers/http/router.rs:1557-1595)。 - HTTP 池中,
kv_aware或cache_aware需要 token 时,会向候选 worker 的/tokenize取 token(src/backend/preprocess.rs的prepare_http_kv_inputs)。 - 取不到 token 时,两种策略都会退化为按负载选择。
- gRPC 池在进入策略前由
Program scheduling 覆盖
- 如果启用
--enable-program-scheduling且请求被识别为 Program turn,acquire_program_completion会先向调度器申请目标 worker(src/routers/http/router.rs:1685-1694)。 - 拿到
forced_worker_url后直接使用该 worker,不再走负载均衡策略(src/routers/http/router.rs:1767-1798)。 - 策略只用于生成 KV receipt。
- 如果启用
构造候选池
available_workers:src/routers/http/router.rs:1427-1436- 有 model:
worker_registry.get_by_model_fast(model) - 无 model:
worker_registry.get_all() - 过滤
worker.is_available()
is_available()=is_healthy() && circuit_breaker.can_execute()(src/core/worker.rs:80)。选择策略
policy_for_model:src/routers/http/router.rs:1420-1425select_worker_for_model:src/routers/http/router.rs:1440-1494
策略分三条分支:
策略 调用 kv_awareselect_worker_with_qualified_inputs(src/policies/kv_aware.rs:1205)cache_awareselect_worker_with_inputs(src/policies/cache_aware.rs:253)其他 select_worker_with_headers(src/policies/mod.rs:79)预留负载
RequestLoadGuard::from_selection:src/routers/http/router.rs:1836-1840- 策略声明
tracks_request_load()(cache_aware、kv_aware、power_of_two)或命中 Program 调度时,Router 通过RequestLoadGuard维护该 worker 的在途负载。 random、round_robin、哈希类策略默认不跟踪在途负载,因为它们本来就不看 load。
下发请求
send_typed_request:src/routers/http/router.rs:2070- gRPC 分支:
src/routers/http/router.rs:2087-2122 - HTTP 分支:
src/routers/http/router.rs:2125起 - DP 模式会从 worker URL 中解析
@rank,并通过X-data-parallel-rank头下发。
记录结果与重试
worker.record_outcome:src/routers/http/router.rs:1901-1904- 重试判定:
src/routers/http/router.rs:1915-1918 - 整个 attempt 由
RetryExecutor包住:src/routers/http/router.rs:1678-1927
5.3 策略分支图
flowchart TD
A["可用 worker 列表"] --> B{"policy 类型"}
B -- "kv_aware" --> C["查 KV 索引命中<br/>计算前缀复用和负载 cost"]
B -- "cache_aware" --> D{"负载失衡?"}
D -- "是" --> E["选最低 load"]
D -- "否" --> F{"最高前缀匹配率大于 cache_threshold?"}
F -- "是" --> G["在最高匹配率中选最低 load"]
F -- "否" --> E
B -- "其他" --> H["按策略自身规则选择"]
6. PD Router 调用链
6.1 调用时序
sequenceDiagram
autonumber
participant C as Client
participant S as Axum 路由层
participant V as VllmPDRouter
participant B as PdRouterBase
participant PR as PolicyRegistry
participant WR as WorkerRegistry
participant IP as 输入准备
participant PL as PdLoadManager
participant PP as Prefill Policy
participant DP as Decode Policy
participant PW as Prefill Worker
participant DW as Decode Worker
participant MET as RouterMetrics
C->>S: POST /v1/chat/completions
Note over S: 入口与鉴权见 4.1 节
S->>V: route_chat
Note over V: 命中 Program turn 时可能直接由 process_program_request 返回
Note over V: gRPC P/D 走 process_grpc_two_stage_chat;此处画 HTTP 路径
V->>V: serde_json::to_value(body)
V->>V: route_transparent
alt use_discovery = true
V->>V: process_vllm_request
V->>V: admit_discovered_pair
V->>V: discovery_candidates(service_registry)
else 静态 URL
V->>WR: get_prefill_workers / get_decode_workers
WR-->>V: P/D worker 列表
V->>V: filter is_available
end
V->>V: admit_pair
V->>V: admit_pair_with_tokens
V->>PR: get_prefill_policy / get_decode_policy
PR-->>V: P/D policies
V->>IP: tokio::join!(prepare_prefill_inputs, prepare_decode_inputs)
IP->>PW: POST /tokenize
PW-->>IP: tokens
IP->>DW: POST /tokenize
DW-->>IP: tokens
IP-->>V: WorkerTokenInputs
V->>V: cache_aware prepare_selection (可选)
V->>V: extract_affinity_key
V->>B: select_and_admit(context)
B->>PL: pd_load.admit(closure)
PL->>B: 锁内执行 select_pd_pair
B->>B: select_pd_pair(loads, P/D pools, policies)
B->>B: eligible 过滤:is_available / model / 粒度
B->>B: select_stage(Prefill)
B->>PP: pick_prefill / select_prepared / select_worker_with_headers
PP-->>B: StageDecision(P)
B->>B: select_stage(Decode)
B->>DP: select_decode / select_prepared / select_worker_with_headers
DP-->>B: StageDecision(D)
B->>B: PdAttempt::attach_workers(P, D)
B-->>V: (PdSelection, PdAttempt)
V->>V: process_vllm_two_stage_request
Note over V: NIXL 推送模式可能改走 process_concurrent_two_stage
V->>PW: send_client_request(POST prefill_url, kv_transfer_params)
PW-->>V: prefill response
V->>V: finish_prefill_response + parse kv_transfer_params
V->>DW: send_client_request(POST decode_url, kv_transfer_params)
DW-->>V: decode response / SSE
V->>V: handle_decode_response -> finalize_decode_stream / finalize_decode_body
V->>MET: record_pd_request / prefill / decode 指标
V-->>S: attempt.track_response
S-->>C: JSON 或 SSE
函数调用栈(PD):
1 | |
6.2 分步说明
进入 PD Router
route_chat:src/routers/http/vllm_pd_router.rs:2796-2830route_transparent:src/routers/http/vllm_pd_router.rs:2975-3089
构造候选池
模式 来源 代码 静态 URL worker_registry.get_prefill_workers()/get_decode_workers(),过滤is_available()src/routers/http/vllm_pd_router.rs:3004-3015服务发现 service registry 的实例快照,转成临时 worker src/routers/http/vllm_pd_router.rs:1363-1394任一池为空直接返回 503。
准备 P/D 输入
admit_pair:src/routers/http/vllm_pd_router.rs:946-965admit_pair_with_tokens:src/routers/http/vllm_pd_router.rs:970-1057- P 和 D 的 token 输入准备并发执行(
src/routers/http/vllm_pd_router.rs:990-1005)。 - 同时提取 session affinity key 和 cache salt。
成对选择与准入
select_and_admit:src/routers/http/pd_router.rs:563-627select_pd_pair:src/routers/http/pd_router.rs:35-110- 选择和预留在同一个准入锁内完成,避免并发请求同时基于旧负载选中同一实例。
候选过滤
- 代码:
src/routers/http/pd_router.rs:56-67 - 条件:
worker.is_available()- 同一 endpoint 的聚合/按 rank 计数粒度不能中途切换
- model 匹配;worker 未标注模型时视为匹配
- 代码:
Prefill 阶段选择
- 代码:
src/routers/http/pd_router.rs:112-334 - 分支:
kv_aware且待处理 token 数已知:计算active_prefill_tokens + new_prefill_tokens,调pick_prefill(src/policies/kv_aware.rs:1795)kv_aware但存在未知 backlog:按投影后的占用选最低的 P,不使用 session affinitycache_aware:用预先准备好的前缀匹配结果select_prepared- 其他策略:
select_worker_with_headers
- 代码:
Decode 阶段选择
kv_aware:select_decode(src/policies/kv_aware.rs:1829),选占用最低的 D;开启 session affinity 时优先粘住原 D。cache_aware:select_prepared。- 其他策略:
select_worker_with_headers。
两阶段下发
process_vllm_two_stage_request:src/routers/http/vllm_pd_router.rs:1613- 先发 Prefill,读取并校验 P 的响应,提取
kv_transfer_params。 - 再发 Decode。
- 成功响应通过
attempt.track_response绑定生命周期(src/routers/http/vllm_pd_router.rs:3073)。
生命周期与负载释放
PdAttempt定义:src/routers/http/pd_types.rs- P/D 负载在
select_and_admit提交预留,PdAttempt在 stream 结束、失败或客户端断开时释放。 Drop实现负责兜底释放,避免取消或异常路径泄漏占用。
6.3 PD 策略来源
| 配置 | 效果 |
|---|---|
--policy cache_aware |
P 和 D 都使用 cache_aware |
--policy kv_aware |
P 和 D 都使用 kv_aware |
--prefill-policy kv_aware |
P 使用 kv_aware,D 继承主策略 |
--decode-policy power_of_two |
D 使用 power_of_two,P 继承主策略 |
策略实例由 RouterFactory::create_vllm_pd_router 创建,并写入 PolicyRegistry(src/routers/factory.rs:72-84)。
7. 各策略如何选择 Worker
| 策略 | 选择依据 | 关键实现 |
|---|---|---|
random |
健康 worker 中均匀随机 | src/policies/random.rs:22-41 |
round_robin |
原子计数器取模 | src/policies/round_robin.rs:26-46 |
power_of_two |
随机抽两个,选 load 更小的 | src/policies/power_of_two.rs:42-97 |
cache_aware |
前缀匹配率超过阈值且负载均衡时,在最高匹配率 worker 中选负载最低的;否则选最低 load | src/policies/cache_aware.rs:253-393 |
kv_aware |
KV 层级命中 + 传输代价 + 实时负载 | src/policies/kv_aware.rs:1205-1346 |
consistent_hash |
session key 映射到 160 个虚拟节点的哈希环 | src/policies/consistent_hash.rs:328 |
rendezvous_hash |
对每个 worker 算 hash(key + url),取最大值 | src/policies/rendezvous_hash.rs:43 |
sticky_least_loaded |
已有 session 粘住原 worker,新 session 选活跃 session 最少的 worker | src/policies/sticky_least_loaded.rs:205 |
7.1 cache_aware 的判定
代码:src/policies/cache_aware.rs:338-393
1 | |
负载失衡判定(src/policies/cache_aware.rs:443-446):
1 | |
默认配置(src/policies/mod.rs:215-225):
| 参数 | 默认值 |
|---|---|
cache_threshold |
0.5 |
balance_abs_threshold |
32 |
balance_rel_threshold |
1.1 |
eviction_interval_secs |
30 |
max_tree_size |
1 << 25 |
7.2 kv_aware 的 cost
代码:src/policies/kv_aware.rs:777-820
1 | |
new_prefill_tokens 会扣除 KV 命中带来的可复用 token;device、host、external、disk 各层使用不同的传输信用系数。多个 scorer 可以对 cost 累加。
选择器:
- 所有 cost 为 0 或 temperature <= 0 且存在 0 cost 时,按
ptoken、batchsize做确定性选择。 - 否则由
TemperaturePicker选择;router_temperature <= 0时退化为最小 cost,temperature 大于 0 时按 cost 加权随机。
kv_aware 还支持 session affinity:同一 session 的请求优先回到之前的 worker,绑定记录有上限和空闲 TTL(src/policies/kv_aware.rs:481-694)。
8. 会影响选择结果的请求输入
| 输入 | 作用 |
|---|---|
body.model |
Regular 模式限定 worker 池;IGW 模式决定走 http-regular 还是 http-pd |
x-prefer-pd |
仅 IGW 且请求未指定 model 时,期望偏好 PD Router |
x-session-id 等 session 头 |
哈希类、sticky 类策略的 key |
x-claude-code-session-id、session-id、thread-id 等 |
KV-aware session affinity 的身份来源 |
lora_name、cache_salt |
隔离 cache 身份和 KV 前缀匹配作用域 |
X-data-parallel-rank |
选择 DP rank;Router 选中后自行写入,客户端传入值会被覆盖 |
| 可重试状态码 | 触发下一次 attempt 重新选择 |
| Program scheduling 头/body | 命中时直接绑定 worker,绕过策略 |
session key 提取顺序(src/policies/hash_key.rs:13-33):
1 | |
9. 失败处理与边界
9.1 重试
Regular 路径由 RetryExecutor 包住(src/routers/http/router.rs:1678-1927):
- 每次 attempt 重新执行 Program 调度、候选池构造、策略选择和负载预留。
failed_workers记录本请求已经失败的 worker。- 只有
kv_aware或 plugin 自带 token 的场景会填充排除列表(src/routers/http/router.rs:1906-1908)。 - 其他策略重试时没有排除列表,可能再次选到同一个 worker。
- 失败状态会通过
worker.record_outcome计入熔断器。
PD 路径:
- P 或 D 任一池为空,返回 503。
select_pd_pair返回None时返回No eligible P/D pair。- Prefill 失败不会继续发 Decode;
PdAttempt负责释放已预留的 P 负载。
9.2 已知边界
请求 model 未注册时按无 model 处理
route_prepared_request用has_model过滤,未注册的 model 会变成None。- 结果是可能从全部 worker 中选择,而不是返回 404。
is_pd_mode与router_type字符串不一致RouterManager用is_pd_mode()判断 Router 是否是 PD。- 默认实现是
router_type() == "pd"(src/routers/mod.rs:190-192)。 VllmPDRouter::router_type()返回"vllm_pd"(src/routers/http/vllm_pd_router.rs:2965-2967)。- 因此
http-pd的is_pd_mode()恒为false,无 model 请求时x-prefer-pd的加分分支不会命中。 - 建议 chat 请求始终携带
model,走确定性的get_router_for_model判断。
IGW 下 model 发现失败
add_worker自动发现模型失败时,model_id会被写成"unknown"(src/routers/router_manager.rs:164-174)。- 此时
get_by_model(实际模型名)找不到该 worker,RouterManager会退回默认 Router。 - 动态添加 PD worker 时应显式传
model_id,或确保 worker 的/v1/models可用。
同一模型同时存在 Regular 和 P/D worker
get_router_for_model只要发现任意 P/D worker 就选http-pd。- Regular Router 不会收到该模型的请求。
静态 PD 模式的 worker model 标签
- 静态
--prefill/--decode创建的 worker 默认 model 为"unknown"。 - PD 准入的 model 过滤允许
"unknown"匹配任意请求(src/routers/http/pd_router.rs:62-67)。 - 多模型部署需要额外的模型标注能力。
- 静态
负载跟踪范围
RequestLoadGuard在策略声明tracks_request_load()、命中 Program 调度或存在 KV receipt 时维护 in-flight load。round_robin、random、哈希类策略不维护该计数;power_of_two优先使用/get_load缓存,缺失时使用本地 in-flight 计数。
10. 观测与定位
| 手段 | Regular 路径 | PD 路径 |
|---|---|---|
| 启动日志 | Single router mode (enable_igw=false) |
Multi-router mode enabled (enable_igw=true);Created HTTP vLLM PD Router |
| 请求日志 | http proxy stages |
Transparent proxy: prefill=..., decode=...;P/D admission |
| 指标 | vllm_router_requests_total |
vllm_router_pd_requests_total、vllm_router_pd_prefill_requests_total、vllm_router_pd_decode_requests_total |
| 响应特征 | 可能带 x-router-stages |
两阶段路径不加该头 |
| 典型错误 | No available workers (all circuits open or unhealthy) |
No eligible P/D pair |
代码位置:
- Regular 指标:
src/routers/http/router.rs:1934-1940 - PD 指标:
src/routers/http/vllm_pd_router.rs:1467-1473 - PD 选择 debug 日志:
src/routers/http/pd_router.rs:611-624 - Regular stage 日志:
src/routers/http/router.rs:87-98
11. 代码索引
| 功能 | 代码位置 |
|---|---|
| HTTP 路由注册 | src/server.rs:957-967 |
| chat 入口 | src/server.rs:266-276 |
AppState |
src/server.rs:111-117 |
| Router 创建 | src/server.rs:1148-1216 |
AppState 构造 |
src/server.rs:1244-1249 |
| Axum 状态挂载 | src/server.rs:1339-1347、1053 |
| IGW Router 选择 | src/routers/router_manager.rs:398-476 |
| 按 model 取 Router | src/routers/router_manager.rs:111-143 |
| IGW route_chat | src/routers/router_manager.rs:627-649 |
| Regular route_chat | src/routers/http/router.rs:2976-2984 |
| Regular 主流程 | src/routers/http/router.rs:1508-1943 |
| Regular 选 worker | src/routers/http/router.rs:1440-1494 |
| Regular 候选池 | src/routers/http/router.rs:1427-1436 |
| Regular 下发 | src/routers/http/router.rs:2070 |
| PD route_chat | src/routers/http/vllm_pd_router.rs:2796-2830 |
| PD 透明转发 | src/routers/http/vllm_pd_router.rs:2975-3089 |
| PD 准入 | src/routers/http/vllm_pd_router.rs:946-1058 |
| PD 成对选择 | src/routers/http/pd_router.rs:35-110 |
| PD 阶段选择 | src/routers/http/pd_router.rs:112-334 |
| PD 准入与预留 | src/routers/http/pd_router.rs:563-627 |
| PD 两阶段请求 | src/routers/http/vllm_pd_router.rs:1613 |
| 策略统一接口 | src/policies/mod.rs:61-202 |
| KV-aware 选择 | src/policies/kv_aware.rs:1205-1346 |
| Cache-aware 选择 | src/policies/cache_aware.rs:253-393 |
| session key 提取 | src/policies/hash_key.rs:13-33 |
| 粘性 session | src/policies/sticky_least_loaded.rs:205 |
12. 小结
- Chat 请求的 Router 类型不由请求直接决定:单 Router 模式在启动时固定,IGW 模式按
model对应的 worker 类型决定。 - Regular 路径的核心是“model 过滤候选池 → 健康/熔断过滤 → 策略选择 → 负载预留 → 下发”,每次重试都会重新走一遍。
- PD 路径的核心是“P/D 候选池 → 准入锁内成对选择 → 同时预留 P/D 负载 → 先 P 后 D 两阶段下发”。
- 默认策略是
cache_aware,但部署常用round_robin建立基线;具体选择依据取决于--policy、--prefill-policy和--decode-policy。 - 需要模型级确定性的请求应始终携带
model,避免落到无 model 的打分分支。