vLLM：知识地图与设计图

flowchart TD
    A["Python / C++ / Linux / 并发与内存"] --> B["PyTorch 与 GPU 执行"]
    T["Transformer / Attention / 自回归生成"] --> C["Prefill / Decode / KV Cache"]
    B --> R["计算量 / 访存量 / Roofline"]
    C --> R
    C --> K["分页 KV / Prefix Cache / 内存生命周期"]
    C --> S["Continuous Batching / Chunked Prefill"]
    K --> E["vLLM V1 Engine / Scheduler / Worker"]
    S --> E
    B --> E
    R --> O["FlashAttention / CUDA Graph / 编译 / 量化"]
    E --> O
    E --> P["TP / PP / DP / EP 与通信"]
    K --> X["KV Connector / LMCache / Mooncake"]
    P --> D["PD 分离 / 多副本路由 / 分布式缓存"]
    X --> D
    E --> M["指标 / Benchmark / Profiling"]
    O --> M
    D --> M
    M --> F["SLO / Goodput / 成本 / 容错"]

flowchart TB
    U["客户端 / 压测器"] --> API
    subgraph AP["API 进程或进程组"]
        API["HTTP API / 校验 / 输入处理"]
        TOK["Tokenizer / 多模态预处理"]
        EC["Engine Client / 输出处理"]
        API --> TOK --> EC
    end
    subgraph CP["EngineCore 进程：通常每 DP rank 一个"]
        CORE["EngineCore 循环"]
        SCH["Scheduler"]
        KV["KV Cache Manager / Block Pool"]
        CS["Connector 调度侧：可选"]
        EX["Executor"]
        CORE --> SCH
        SCH <--> KV
        SCH <--> CS
        CORE --> EX
    end
    subgraph WP["GPU Worker：按 TP / PP 等拓扑组织"]
        W["Worker / 分布式执行"]
        MR["ModelRunner / 输入准备"]
        MODEL["模型层 / Attention / 采样"]
        MEM["GPU 权重 / KV / Workspace"]
        CW["Connector 执行侧：可选"]
        W --> MR --> MODEL
        MODEL <--> MEM
        MR <--> CW
        CW <--> MEM
    end
    EC <-->|"IPC；在线架构常用 ZMQ"| CORE
    EX <--> W
    CS -.->|"本轮传输元数据"| CW
    CW <-->|"KV 数据"| STORE["外部缓存 / 远端 Worker"]
    EC -->|"流式结果"| U

flowchart TD
    A["解析配置与模型元信息"] --> B["建立引擎与 Worker 通信"]
    B --> C["初始化设备与并行组"]
    C --> D["加载模型权重与执行后端"]
    D --> E["估计非 KV 开销与可用显存"]
    E --> F["规划并分配 KV blocks"]
    F --> G["初始化缓存管理与可选 Connector"]
    G --> H["必要的编译 / warmup / graph capture"]
    H --> I["健康检查通过，服务可接收请求"]

sequenceDiagram
    autonumber
    participant U as 客户端
    participant A as API与Engine Client
    participant E as EngineCore
    participant S as Scheduler
    participant K as KV Manager
    participant W as Worker与ModelRunner
    participant G as GPU
    U->>A: prompt与生成参数
    A->>A: 校验、模板与tokenization
    A->>E: 提交请求
    E->>S: 加入等待队列
    loop 直到结束或取消
        E->>S: 生成本轮调度决策
        S->>K: 查找前缀、分配所需blocks
        K-->>S: blocks与可复用token信息
        S-->>E: 请求、token数量、block映射
        E->>W: 执行本轮任务
        W->>G: 输入准备、forward、适用时采样
        G-->>W: 结果与完成状态
        W-->>E: 执行结果
        E->>S: 更新计算进度、停止条件
        E-->>A: 新输出及状态
        A-->>U: 有输出时流式返回
    end
    S->>K: 释放请求引用
    Note over S,K: 外部异步传输可能延迟物理block回收

stateDiagram-v2
    [*] --> Waiting
    Waiting --> WaitingKV: 需要外部KV
    WaitingKV --> Waiting: 传输完成或回退重算
    Waiting --> Running: 满足调度与内存约束
    Running --> Running: 执行下一轮
    Running --> Preempted: 资源压力
    Preempted --> Waiting: 重新排队或恢复
    Running --> Finished: EOS或长度等停止条件
    Waiting --> Cancelled: 客户端取消或超时
    WaitingKV --> Cancelled: 取消或失败
    Running --> Cancelled: 取消或失败
    Finished --> Reclaiming
    Cancelled --> Reclaiming
    Reclaiming --> [*]: 引用与在途操作清理完成

flowchart LR
    subgraph A["请求 A 的逻辑块"]
        A0["A0：共同前缀"]
        A1["A1：共同前缀"]
        A2["A2：后缀 A"]
    end
    subgraph B["请求 B 的逻辑块"]
        B0["B0：共同前缀"]
        B1["B1：共同前缀"]
        B2["B2：后缀 B"]
    end
    subgraph P["GPU 物理 blocks"]
        P7["物理 7：ref=2"]
        P2["物理 2：ref=2"]
        P9["物理 9：ref=1"]
        P4["物理 4：ref=1"]
    end
    A0 --> P7
    B0 --> P7
    A1 --> P2
    B1 --> P2
    A2 --> P9
    B2 --> P4

sequenceDiagram
    autonumber
    participant S as Scheduler
    participant C as Connector调度侧
    participant K as KV Manager
    participant W as Connector执行侧
    participant X as LMCache或其他后端
    participant G as GPU执行
    S->>C: 查找本地未覆盖的可复用token
    C->>X: 查询兼容的缓存对象
    X-->>C: 命中范围或未命中
    C-->>S: 候选复用长度与加载状态
    S->>K: 预留目标blocks
    S->>W: 下发加载元数据
    W->>X: 取回KV
    X-->>W: 数据传输与完成通知
    W-->>S: 加载完成或失败
    alt 加载成功
        S->>G: 允许执行依赖该KV的计算
    else miss或加载失败
        S->>S: 撤销无效复用状态
        S->>G: 按支持的路径重算或终止请求
    end
    Note over W,G: layerwise实现可按层等待；并非全部传输都阻塞整个引擎

flowchart TB
    U["请求"] --> R["路由 / 排队 / admission"]
    R --> E0["EngineCore：副本 0"]
    R --> E1["EngineCore：副本 1"]
    subgraph DP0["副本 0，TP=2"]
        G0["GPU 0：每层部分权重与KV"]
        G1["GPU 1：每层部分权重与KV"]
        G0 <-->|"collective"| G1
    end
    subgraph DP1["副本 1，TP=2"]
        G2["GPU 2：每层部分权重与KV"]
        G3["GPU 3：每层部分权重与KV"]
        G2 <-->|"collective"| G3
    end
    E0 --> G0
    E0 --> G1
    E1 --> G2
    E1 --> G3
    E0 -.-> CACHE["可选：共享KV存储 / 缓存位置索引"]
    E1 -.-> CACHE

flowchart TD
    A["TTFT / ITL / Goodput 未达标"] --> B["确认计时口径、负载与冷暖状态"]
    B --> C{"主要延迟在哪里"}
    C -->|"排队"| Q["检查到达率、admission、KV压力、路由"]
    C -->|"CPU或IPC"| H["tokenizer、调度、序列化、同步、日志"]
    C -->|"GPU执行"| G["检查kernel trace与计算/带宽"]
    C -->|"跨卡通信"| N["collective、拓扑、小消息、负载不均"]
    C -->|"缓存取回"| K["lookup、网络、H2D、布局转换、锁与队列"]
    Q --> V["提出一个可证伪的假设"]
    H --> V
    G --> V
    N --> V
    K --> V
    V --> E["保持其他条件固定，做对照实验"]
    E --> R["检查正确性、分位延迟、Goodput与成本"]