vLLM Router Chat 请求路由与 Worker 选择调用流程

vLLM Router Chat 请求路由与 Worker 选择调用流程

分析对象:vLLM Router router/ 子树,仓库提交 2d61d39,分析日期 2026-11-18。
分析方式:静态代码阅读,未进行运行时和性能验证。
文中源码路径均相对于 router/。

1. 结论摘要

Chat 请求到达 Router 后,选择过程分两层:

  1. 先确定由哪个 Router 实例处理:单 Router 模式下由启动参数决定;IGW 模式下由 RouterManager 按请求的 model 和 worker 类型决定。
  2. 再由该 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
2
3
4
5
enum WorkerType {
Regular,
Prefill { bootstrap_port: Option<u16> },
Decode,
}

它是 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:

  1. http-regular → Router
  2. http-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
2
3
4
5
6
7
8
9
10
RouterFactory::create_router()
→ Box<dyn RouterTrait>
→ Arc::from(...)
→ 局部变量 router src/server.rs:1148
→ AppState.router src/server.rs:1245
→ Arc<AppState> src/server.rs:1244
→ build_app_with_wasm_middleware() src/server.rs:1339
→ .with_state(app_state) src/server.rs:1053
→ Axum Router 内部状态
→ serve(listener, app) src/server.rs:1352

AppState 定义在 src/server.rs:111-117:

1
2
3
4
5
6
7
#[derive(Clone)]
pub struct AppState {
pub router: Arc<dyn RouterTrait>,
pub context: Arc<AppContext>,
pub concurrency_queue_tx: Option<tokio::sync::mpsc::Sender<QueuedRequest>>,
pub router_manager: Option<Arc<RouterManager>>,
}

请求处理函数通过 Axum 的 State 提取器拿到它:

1
2
3
4
5
6
7
8
async fn v1_chat_completions(
State(state): State<Arc<AppState>>,
headers: http::HeaderMap,
Json(body): Json<ChatCompletionRequest>,
) -> Response {
...
state.router.route_chat(Some(&headers), &body, None).await
}

代码位置: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

具体规则:

  1. 请求带 model

    • worker_registry.get_by_model(model) 取该模型的 worker。
    • 任意 worker 是 WorkerType::Prefill { .. } 或 WorkerType::Decode → 选 http-pd。
    • 全部是 WorkerType::Regular → 选 http-regular。
    • 模型没有 worker,或对应 Router 创建失败 → 退回默认 Router。
  2. 请求不带 model

    • 遍历所有已注册 Router 打分。
    • 代码期望无 x-prefer-pd 时偏向 Regular,有 x-prefer-pd 时偏向 PD。
    • 当前实现存在类型字符串不一致,见 9.2 节;上图描述的是代码意图。

4.3 Worker 类型如何产生

IGW 模式下通过 POST /workers 动态添加:

1
2
3
4
5
{
"url": "http://127.0.0.1:8000",
"model_id": "deepseek-v4",
"worker_type": "prefill"
}

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
2
3
4
5
6
7
8
9
10
11
12
13
14
15
server.rs::v1_chat_completions
→ server.rs::authorize_request
→ routers/router_manager.rs::route_chat // 仅 IGW
→ select_router_for_request
→ get_router_for_model
→ routers/http/router.rs::route_chat
→ route_typed_request
→ route_prepared_request
→ core/retry.rs::RetryExecutor::execute_response_with_retry
→ policies/registry.rs::get_policy_or_default
→ core/worker_registry.rs::get_by_model_fast / get_all
→ policies/*::select_worker_with_*
→ routers/http/router.rs::send_typed_request
→ backend/frontend.rs::dispatch_with_first_output // gRPC
→ otel_http.rs::send_client_request // HTTP

5.2 分步说明

  1. 进入 Regular Router

    • route_chat:src/routers/http/router.rs:2976-2984
    • route_typed_request:src/routers/http/router.rs:1496-1505
    • route_prepared_request:src/routers/http/router.rs:1508
  2. 解析 model

    • 代码:src/routers/http/router.rs:1519-1521
    1
    2
    3
    let model_id = model_id
    .or_else(|| typed_req.get_model())
    .filter(|model| self.worker_registry.has_model(model));

    如果请求里的 model 没有注册,会被当成 None,后续从全部 worker 中选择。

  3. 判断 backend 池类型

    • 代码:src/routers/http/router.rs:1525-1530
    • 所有 worker URL 必须是同一种协议,全部 HTTP 或全部 gRPC。混合池在启动或添加 worker 时会被拒绝。
  4. 准备 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 时,两种策略都会退化为按负载选择。
  5. 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。
  6. 构造候选池

    • 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)。

  7. 选择策略

    • policy_for_model:src/routers/http/router.rs:1420-1425
    • select_worker_for_model:src/routers/http/router.rs:1440-1494

    策略分三条分支:

    策略 调用
    kv_aware select_worker_with_qualified_inputs(src/policies/kv_aware.rs:1205)
    cache_aware select_worker_with_inputs(src/policies/cache_aware.rs:253)
    其他 select_worker_with_headers(src/policies/mod.rs:79)
  8. 预留负载

    • 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。
  9. 下发请求

    • 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 头下发。
  10. 记录结果与重试

    • 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
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
server.rs::v1_chat_completions
→ server.rs::authorize_request
→ routers/router_manager.rs::route_chat // 仅 IGW
→ select_router_for_request
→ get_router_for_model
→ routers/http/vllm_pd_router.rs::route_chat
→ route_grpc_chat // gRPC P/D 池
→ route_transparent // HTTP 路径
→ process_vllm_request // 服务发现
→ admit_discovered_pair
→ admit_pair // 静态 URL;发现路径内部也会调用
→ admit_pair_with_tokens
→ pd_router.rs::prepare_prefill_inputs
→ pd_router.rs::prepare_decode_inputs
→ pd_router.rs::select_and_admit
→ pd_load.admit
→ select_pd_pair
→ select_stage(Prefill)
→ select_stage(Decode)
→ process_vllm_two_stage_request
→ otel_http.rs::send_client_request(Prefill)
→ otel_http.rs::send_client_request(Decode)

6.2 分步说明

  1. 进入 PD Router

    • route_chat:src/routers/http/vllm_pd_router.rs:2796-2830
    • route_transparent:src/routers/http/vllm_pd_router.rs:2975-3089
  2. 构造候选池

    模式 来源 代码
    静态 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。

  3. 准备 P/D 输入

    • admit_pair:src/routers/http/vllm_pd_router.rs:946-965
    • admit_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。
  4. 成对选择与准入

    • select_and_admit:src/routers/http/pd_router.rs:563-627
    • select_pd_pair:src/routers/http/pd_router.rs:35-110
    • 选择和预留在同一个准入锁内完成,避免并发请求同时基于旧负载选中同一实例。
  5. 候选过滤

    • 代码:src/routers/http/pd_router.rs:56-67
    • 条件:
      • worker.is_available()
      • 同一 endpoint 的聚合/按 rank 计数粒度不能中途切换
      • model 匹配;worker 未标注模型时视为匹配
  6. 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 affinity
      • cache_aware:用预先准备好的前缀匹配结果 select_prepared
      • 其他策略:select_worker_with_headers
  7. Decode 阶段选择

    • kv_aware:select_decode(src/policies/kv_aware.rs:1829),选占用最低的 D;开启 session affinity 时优先粘住原 D。
    • cache_aware:select_prepared。
    • 其他策略:select_worker_with_headers。
  8. 两阶段下发

    • 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)。
  9. 生命周期与负载释放

    • 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
2
3
4
5
6
if 负载失衡:
选最低 load
else if 最高前缀匹配率 > cache_threshold:
在匹配率最高的 worker 中选负载最低的
else:
选最低 load

负载失衡判定(src/policies/cache_aware.rs:443-446):

1
2
3
max_load - min_load > balance_abs_threshold
且
max_load > min_load * balance_rel_threshold

默认配置(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
2
3
ptoken = new_prefill_tokens + active_prefill_tokens
projected_batchsize = active_requests + 1
cost = ptoken * projected_batchsize

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
2
3
4
5
6
7
8
9
10
11
x-session-id
> x-user-id
> x-tenant-id
> x-correlation-id
> x-request-id
> x-trace-id
> body.session_params.session_id
> body.user
> body.session_id
> body.user_id
> 请求体哈希

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 已知边界

  1. 请求 model 未注册时按无 model 处理

    • route_prepared_request 用 has_model 过滤,未注册的 model 会变成 None。
    • 结果是可能从全部 worker 中选择,而不是返回 404。
  2. 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 判断。
  3. 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 可用。
  4. 同一模型同时存在 Regular 和 P/D worker

    • get_router_for_model 只要发现任意 P/D worker 就选 http-pd。
    • Regular Router 不会收到该模型的请求。
  5. 静态 PD 模式的 worker model 标签

    • 静态 --prefill / --decode 创建的 worker 默认 model 为 "unknown"。
    • PD 准入的 model 过滤允许 "unknown" 匹配任意请求(src/routers/http/pd_router.rs:62-67)。
    • 多模型部署需要额外的模型标注能力。
  6. 负载跟踪范围

    • 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 的打分分支。

vLLM Router Chat 请求路由与 Worker 选择调用流程
https://orion-wyc.github.io/2026/11/17/2026-11-18-vLLM-Router聊天请求路由与Worker选择调用流程/
作者
Yuchen
发布于
2026年11月18日
许可协议