IP 层（网络层）是 Linux 协议栈的核心，负责报文的寻址、路由、转发与分片重组。本文基于 Linux 6.4-rc1 源码，从 ip_rcv 入口函数出发，逐层拆解接收路径、FIB 路由查找、发送路径、分片重组和 netfilter 钩子的完整实现，并给出实用的内核诊断技巧。文中所有代码均来自 net/ipv4/ip_input.c、net/ipv4/ip_output.c、net/ipv4/fib_trie.c、net/ipv4/ip_fragment.c、net/ipv4/ip_forward.c 和 net/netfilter/core.c 等实际文件。

本文是 Linux 网络内核协议栈系列的第二篇，聚焦于网卡驱动框架与 NAPI（New API）收发包机制。我们将深入 Linux 6.4-rc1 源码，逐层拆解从网卡硬件中断到 sk_buff 进入协议栈的完整链路，并对称地分析发送路径。所有代码片段均直接取自内核源文件，确保与实际内核行为一致。

本系列基于 Linux 6.4-rc1 源码（commit ac9a78681b92），所有代码片段均从真实源文件读取，路径为 include/linux/skbuff.h 与 net/core/skbuff.c。

一、为什么要读懂 Linux 网络协议栈

网络性能调优、eBPF 程序开发、内核模块编写，乃至排查一个”神秘的丢包”——这些工作的底层都有一个共同的核心：sk_buff（socket buffer）。它是 Linux 内核网络子系统中最关键的数据结构，每一个在内核中流动的网络报文都以 sk_buff 的形式存在。

本系列文章将从零到深，系统拆解 Linux 网络协议栈。第一篇先建立全局视图，再深入 sk_buff 的内存模型与操作原语。

二、网络协议栈完整架构

2.1 接收路径（RX Path）

从网卡收到一帧，到用户态 read() 返回数据，内核经历的完整调用链如下：

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17

硬件中断
    └─ napi_schedule()              // 将 NAPI poll 加入软中断队列
         └─ net_rx_action()         // softirq: NET_RX_SOFTIRQ
              └─ napi->poll()       // 驱动的 poll 函数，如 igb_poll()
                   └─ napi_gro_receive()
                        └─ netif_receive_skb()
                             └─ __netif_receive_skb_core()
                                  ├─ deliver_skb() → packet socket tap
                                  └─ ip_rcv()                  // IPv4 入口
                                       └─ ip_rcv_finish()
                                            └─ ip_local_deliver()
                                                 └─ ip_local_deliver_finish()
                                                      └─ tcp_v4_rcv()         // TCP 入口
                                                           └─ tcp_rcv_established()
                                                                └─ tcp_queue_rcv()
                                                                     └─ sk->sk_data_ready()
                                                                          └─ 唤醒用户态 read()

关键节点说明：

NAPI（New API） 是现代驱动的标准轮询机制。硬中断只负责触发 napi_schedule()，将 poll 工作推给软中断 NET_RX_SOFTIRQ，从而避免高速网卡的中断风暴。驱动在 poll 函数中用 napi_build_skb() 或 __napi_alloc_skb() 创建 skb，并调用 napi_gro_receive() 进入 GRO（Generic Receive Offload）聚合层。

netif_receive_skb() 是协议层的分发入口。它通过 ptype_base 哈希表查找与 skb->protocol 对应的协议处理函数（如 ip_rcv、ipv6_rcv）。

ip_rcv() 完成 IP 首部校验、路由查找（ip_route_input_noref()），然后决定报文去向：本地投递还是转发。本地投递进入 ip_local_deliver()，这里完成 IP 分片重组，再调用上层协议（TCP/UDP/ICMP）的接收函数。

tcp_v4_rcv() 根据四元组找到 socket，将报文挂入 sk->sk_receive_queue，并通过 sk->sk_data_ready 回调唤醒阻塞在 read() 的用户进程。

2.2 发送路径（TX Path）

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15

用户态 write() / sendmsg()
    └─ sock_sendmsg()
         └─ tcp_sendmsg()
              └─ tcp_push_one() / __tcp_push_pending_frames()
                   └─ tcp_write_xmit()
                        └─ tcp_transmit_skb()        // 封装 TCP 首部
                             └─ ip_queue_xmit()      // 封装 IP 首部 + 路由
                                  └─ ip_output()
                                       └─ ip_finish_output()
                                            └─ ip_finish_output2()
                                                 └─ neigh_output()        // ARP/邻居子系统
                                                      └─ dev_queue_xmit() // 入队
                                                           └─ qdisc_run() // 流量控制
                                                                └─ dev_hard_start_xmit()
                                                                     └─ ndo_start_xmit() // 驱动发送

发送路径的核心在于 TCP 在 sk_write_queue 中维护待发送的 skb。TCP 实现了可靠传输，skb 只有在收到 ACK 后才会通过 tcp_clean_rtx_queue() 释放。发送时，TCP 先调用 skb_clone() 产生一个 fclone（fast-clone），将克隆体交给 IP 层，自己保留原始 skb 用于重传。

三、sk_buff 结构体深度分析

3.1 什么是 sk_buff

sk_buff 是 Linux 内核网络子系统中报文的载体。它本身不直接存储报文数据，而是一个元数据描述符，通过指针指向实际的数据缓冲区。其设计目标是：在协议栈各层之间传递报文时，尽量避免数据拷贝，只修改指针和元数据。

3.2 核心内存布局：四个指针

skbuff.h 中的官方注释给出了最清晰的内存模型（源码第 706-728 行）：

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19

/**
 * DOC: Basic sk_buff geometry
 *
 *                                  ---------------
 *                                 | sk_buff       |
 *                                  ---------------
 *     ,---------------------------  + head
 *    /          ,-----------------  + data
 *   /          /      ,-----------  + tail
 *  |          |      |            , + end
 *  |          |      |           |
 *  v          v      v           v
 *   -----------------------------------------------
 *  | headroom | data |  tailroom | skb_shared_info |
 *   -----------------------------------------------
 *                                 + [page frag]
 *                                 + [page frag]
 *                                 + frag_list    --> | sk_buff |
 */

四个核心指针在结构体末尾（源码第 1053-1057 行）：

1
2
3
4
5
6
7

/* These elements must be at the end, see alloc_skb() for details.  */
sk_buff_data_t		tail;
sk_buff_data_t		end;
unsigned char		*head,
                    *data;
unsigned int		truesize;
refcount_t		    users;

各指针含义：

在 64 位系统（NET_SKBUFF_DATA_USES_OFFSET 宏定义时），tail 和 end 存储的是相对于 head 的偏移量，而非指针，节省内存并方便原子操作。

Headroom（头部预留空间） 是 data - head 的字节数，发送时用于各层协议依次 skb_push() 写入自己的首部，无需移动数据。Tailroom 是 end - tail 的字节数（不含 skb_shared_info），接收时用于 skb_put() 追加数据。

3.3 len、data_len 与 truesize 的区别

这三个字段是初学者最容易混淆的：

1
2

unsigned int		len,         // 源码第 896 行
                    data_len;

• skb->len：报文的逻辑总长度，等于线性区域长度加上所有分片的长度。skb_headlen(skb) + skb->data_len。
• skb->data_len：仅计算非线性部分（page frags + frag_list）的字节数。线性 skb 的 data_len 为 0。
• **truesize**：内核为这个 skb 实际占用的内存大小，包含 sk_buff 结构体本身、数据缓冲区以及 skb_shared_info。用于 socket 发送/接收缓冲区的内存计费（sk_wmem_alloc / sk_rmem_alloc）。

1
2
3
4

/* return minimum truesize of one skb containing X bytes of data */
#define SKB_TRUESIZE(X) ((X) +                          \
         SKB_DATA_ALIGN(sizeof(struct sk_buff)) +       \
         SKB_DATA_ALIGN(sizeof(struct skb_shared_info)))

truesize 的精确计算在 __finalize_skb_around() 中（net/core/skbuff.c 第 352-375 行）：

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16

static inline void __finalize_skb_around(struct sk_buff *skb, void *data,
                                         unsigned int size)
{
    struct skb_shared_info *shinfo;

    size -= SKB_DATA_ALIGN(sizeof(struct skb_shared_info));

    /* Assumes caller memset cleared SKB */
    skb->truesize = SKB_TRUESIZE(size);
    refcount_set(&skb->users, 1);
    skb->head = data;
    skb->data = data;
    skb_reset_tail_pointer(skb);
    skb_set_end_offset(skb, size);
    // ...
}

3.4 cb[48]：各层私有控制块

1

char    cb[48] __aligned(8);   // 源码第 880 行

这 48 字节是各协议层的私有暂存区，对上下层完全透明。内核使用宏来访问它：

IP 层（include/net/ip.h）：

1
2
3
4
5
6
7
8

struct inet_skb_parm {
    int           iif;
    struct ip_options opt;   /* Compiled IP options */
    u16           flags;
    // IPSKB_FORWARDED, IPSKB_XFRM_TUNNEL_SIZE, ...
};

#define IPCB(skb) ((struct inet_skb_parm*)((skb)->cb))

TCP 层（include/net/tcp.h）：

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25

struct tcp_skb_cb {
    __u32   seq;        /* Starting sequence number */
    __u32   end_seq;    /* SEQ + FIN + SYN + datalen */
    union {
        __u32   tcp_tw_isn;
        struct {
            u16 tcp_gso_segs;
            u16 tcp_gso_size;
        };
    };
    // tx 路径：发送时间戳、delivered 计数等
    // rx 路径：ip header 信息（h4/h6）
    union {
        struct {
            u32 is_app_limited:1;
            // ...
        } tx;
        union {
            struct inet_skb_parm  h4;
            struct inet6_skb_parm h6;
        } header;
    };
};

#define TCP_SKB_CB(__skb) ((struct tcp_skb_cb *)&((__skb)->cb[0]))

TCP 在发包时用 TCP_SKB_CB(skb)->seq 记录序列号，在收包时用 TCP_SKB_CB(skb)->header.h4 读取 IP 层留下的信息。由于 sizeof(struct tcp_skb_cb) <= 48，两者都合法地复用同一块内存。

3.5 sk 与 dev 字段

1
2
3
4

union {
    struct sock     *sk;            // 所属 socket
    int              ip_defrag_offset;  // IP 分片重组时复用
};

skb->sk 指向拥有这个报文的 socket。在发送路径中，skb 一直持有对 socket 的引用（用于内存计费）；在接收路径进入 TCP/UDP 处理后也会被赋值。ip_defrag_offset 是 IP 分片重组阶段对 sk 字段的临时复用，无需额外内存。

1
2
3
4
5
6
7
8
9
10
11

union {
    struct {
        struct sk_buff  *next;
        struct sk_buff  *prev;
        union {
            struct net_device   *dev;
            unsigned long        dev_scratch;
        };
    };
    // ...
};

skb->dev 指向 skb 当前关联的网络设备（struct net_device）。在接收路径，它指向收包的网卡；在发送路径，它指向出口网卡。某些协议（如 UDP 接收路径）会将 dev 置 NULL 并用 dev_scratch 存储其他临时信息。

3.6 _skb_refdst：路由缓存

1
2
3
4
5
6
7

union {
    struct {
        unsigned long   _skb_refdst;
        void          (*destructor)(struct sk_buff *skb);
    };
    // ...
};

_skb_refdst 存储指向 struct dst_entry 的指针（路由缓存条目）。最低位被用作标志位 SKB_DST_NOREF，表示是否持有引用计数：

1
2
3
4
5
6
7
8
9

#define SKB_DST_NOREF   1UL
#define SKB_DST_PTRMASK ~(SKB_DST_NOREF)

static inline struct dst_entry *skb_dst(const struct sk_buff *skb)
{
    WARN_ON((skb->_skb_refdst & SKB_DST_NOREF) &&
            !rcu_read_lock_held() && !rcu_read_lock_bh_held());
    return (struct dst_entry *)(skb->_skb_refdst & SKB_DST_PTRMASK);
}

在快速转发路径（如 ip_forward()）中，内核使用 skb_dst_set_noref() 以 RCU 方式持有路由缓存，避免昂贵的引用计数操作。

3.7 GSO/GRO 相关字段

GSO（Generic Segmentation Offload）和 GRO（Generic Receive Offload）是 Linux 将分段/聚合工作推迟到驱动层或硬件的机制，核心信息存储在 skb_shared_info（见下节）中：

1
2
3
4
5
6
7

struct skb_shared_info {
    // ...
    unsigned short  gso_size;   // 单个 MSS 大小
    unsigned short  gso_segs;   // 待分段数量
    unsigned int    gso_type;   // SKB_GSO_TCPV4, SKB_GSO_TCPV6, ...
    // ...
};

发送路径中，TCP 构造一个大 skb（可包含多个 MSS 的数据），设置 gso_size = tp->mss_cache、gso_segs = 数量，并设置 ip_summed = CHECKSUM_PARTIAL，由驱动或网卡完成实际切割和 checksum。

接收路径中，GRO 将多个小包聚合成一个大 skb，减少协议栈处理次数。skb->slow_gro 标志指示该 skb 在 GRO 合并时携带了额外状态（连接跟踪、路由等），需要在释放时特殊处理。

3.8 Checksum Offload 字段

1
2
3
4
5
6
7
8

__u8    ip_summed:2;    // CHECKSUM_NONE/UNNECESSARY/COMPLETE/PARTIAL
union {
    __wsum  csum;
    struct {
        __u16 csum_start;
        __u16 csum_offset;
    };
};

四种状态的含义（源码 include/linux/skbuff.h 第 99-250 行有完整文档）：

TX 路径中，csum_start 是从 skb->head 开始计算 checksum 的起始偏移，csum_offset 是相对于 csum_start 的 checksum 写入位置。

3.9 skb_shinfo() 与 skb_shared_info

skb_shared_info 紧跟在数据缓冲区的末尾（end 指针处）：

1

#define skb_shinfo(SKB) ((struct skb_shared_info *)(skb_end_pointer(SKB)))

完整结构（源码第 574-599 行）：

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20

struct skb_shared_info {
    __u8            flags;          // SKBFL_ZEROCOPY_ENABLE 等零拷贝标志
    __u8            meta_len;
    __u8            nr_frags;       // page frags 数量（最多 MAX_SKB_FRAGS=17）
    __u8            tx_flags;       // SKBTX_HW_TSTAMP 等时间戳标志
    unsigned short  gso_size;
    unsigned short  gso_segs;
    struct sk_buff  *frag_list;     // 指向下一个 skb（用于 IP 分片链、超大帧）
    struct skb_shared_hwtstamps hwtstamps;
    unsigned int    gso_type;
    u32             tskey;
    /*
     * Warning : all fields before dataref are cleared in __alloc_skb()
     */
    atomic_t        dataref;        // 数据区引用计数（clone 计数）
    unsigned int    xdp_frags_size;
    void           *destructor_arg;
    /* must be last field, see pskb_expand_head() */
    skb_frag_t      frags[MAX_SKB_FRAGS];
};

frags[] 是 Scatter-Gather IO 的核心。每个 skb_frag_t（实为 struct bio_vec）描述一个页片段：

1
2
3
4
5
6
7
8

typedef struct bio_vec skb_frag_t;

// bio_vec 定义：
struct bio_vec {
    struct page  *bv_page;
    unsigned int  bv_len;
    unsigned int  bv_offset;
};

网卡驱动通过 DMA 将数据直接写入这些页，frags[] 只存储（页, 偏移, 长度）三元组，完全避免数据拷贝。

frag_list 是一个 skb 链表，用于两种场景：

1. IP 分片重组：各个分片 skb 通过 frag_list 链接在一起，skb->len 是全部分片的总长度。
2. GSO fraglist：SKB_GSO_FRAGLIST 模式下，将多个小 skb 链成链表交给驱动。

dataref 是 skb_shared_info 中最重要的计数器，分为两个 16 位字段：低 16 位是总引用数，高 16 位是 payload-only 引用数（nohdr clone）。skb_clone() 共享数据区时递增此计数，skb_release_data() 递减，归零后才真正释放数据缓冲区。

四、sk_buff 操作函数详解

4.1 alloc_skb / __alloc_skb：slab 缓存分配

内核为 sk_buff 头部维护了专用的 slab 缓存（net/core/skbuff.c 第 89-90 行）：

1
2

struct kmem_cache *skbuff_cache __ro_after_init;
static struct kmem_cache *skbuff_fclone_cache __ro_after_init;

核心分配函数 __alloc_skb()（源码第 625-687 行）：

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43

struct sk_buff *__alloc_skb(unsigned int size, gfp_t gfp_mask,
                            int flags, int node)
{
    struct kmem_cache *cache;
    struct sk_buff *skb;
    bool pfmemalloc;
    u8 *data;

    cache = (flags & SKB_ALLOC_FCLONE)
        ? skbuff_fclone_cache : skbuff_cache;

    if (sk_memalloc_socks() && (flags & SKB_ALLOC_RX))
        gfp_mask |= __GFP_MEMALLOC;

    /* Get the HEAD */
    if ((flags & (SKB_ALLOC_FCLONE | SKB_ALLOC_NAPI)) == SKB_ALLOC_NAPI &&
        likely(node == NUMA_NO_NODE || node == numa_mem_id()))
        skb = napi_skb_cache_get();   // NAPI 路径：per-CPU 缓存
    else
        skb = kmem_cache_alloc_node(cache, gfp_mask & ~GFP_DMA, node);
    if (unlikely(!skb))
        return NULL;
    prefetchw(skb);

    data = kmalloc_reserve(&size, gfp_mask, node, &pfmemalloc);
    if (unlikely(!data))
        goto nodata;

    memset(skb, 0, offsetof(struct sk_buff, tail));
    __build_skb_around(skb, data, size);
    skb->pfmemalloc = pfmemalloc;

    if (flags & SKB_ALLOC_FCLONE) {
        struct sk_buff_fclones *fclones;
        fclones = container_of(skb, struct sk_buff_fclones, skb1);
        skb->fclone = SKB_FCLONE_ORIG;
        refcount_set(&fclones->fclone_ref, 1);
    }
    return skb;
nodata:
    kmem_cache_free(cache, skb);
    return NULL;
}

分配分两步：

1. 从 slab 缓存分配 sk_buff 结构体（仅元数据，约 232 字节）
2. 调用 kmalloc_reserve() 分配数据缓冲区

kmalloc_reserve() 内部会优先尝试 skb_small_head_cache（专为 TCP 头部优化的小块缓存，大小为 SKB_HEAD_ALIGN(MAX_TCP_HEADER)），对于不超过 1024 字节的小报文走快速路径。

NAPI 路径还有额外优化：napi_skb_cache_get() 维护一个 per-CPU 的 64 个 skb 的批量缓存，使用 kmem_cache_alloc_bulk() 批量分配，大幅减少 slab 调用开销。

4.2 skb_reserve：为各层头部预留空间

1
2
3
4
5

static inline void skb_reserve(struct sk_buff *skb, int len)
{
    skb->data += len;
    skb->tail += len;
}

在 skb 刚分配、尚未写入数据时调用，同时移动 data 和 tail，使 head 到 data 之间形成 headroom。后续各层通过 skb_push() 向前扩展，写入自己的首部，无需移动已有数据。

驱动分配接收 skb 时通常调用：

1
2

skb_reserve(skb, NET_SKB_PAD);          // 驱动预留（NET_SKB_PAD = 32 字节）
skb_reserve(skb, NET_SKB_PAD + NET_IP_ALIGN);  // NAPI 路径额外对齐

发送路径中，sock_alloc_send_skb() 预留的空间要包含所有协议层首部的总长度：

1

NET_SKB_PAD + MAX_HEADER(ETH + IP + TCP 首部之和)

4.3 skb_push / skb_pull / skb_put：指针操作

这三个函数是协议栈各层操作数据的核心原语（源码第 2383-2428 行）：

skb_put() — 向 tail 方向扩展，用于接收路径追加数据：

1
2
3
4
5
6
7
8
9
10

void *skb_put(struct sk_buff *skb, unsigned int len)
{
    void *tmp = skb_tail_pointer(skb);
    SKB_LINEAR_ASSERT(skb);
    skb->tail += len;
    skb->len  += len;
    if (unlikely(skb->tail > skb->end))
        skb_over_panic(skb, len, __builtin_return_address(0));
    return tmp;  // 返回新区域的起始地址
}

skb_push() — 向 head 方向扩展，用于发送路径在 headroom 中写入首部：

1
2
3
4
5
6
7
8

void *skb_push(struct sk_buff *skb, unsigned int len)
{
    skb->data -= len;
    skb->len  += len;
    if (unlikely(skb->data < skb->head))
        skb_under_panic(skb, len, __builtin_return_address(0));
    return skb->data;
}

skb_pull() — 从 data 头部移除数据，用于接收路径跳过已处理的首部：

1
2
3
4
5
6
7
8
9
10

void *skb_pull(struct sk_buff *skb, unsigned int len)
{
    return skb_pull_inline(skb, len);
}

static inline void *__skb_pull(struct sk_buff *skb, unsigned int len)
{
    skb->len -= len;
    return skb->data += len;
}

三者关系图示（发送路径，从上层到下层）：

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19

初始状态（alloc + reserve 后）：
  [headroom...................|  tailroom  | skb_shared_info]
   ^                         ^            ^
   head                      data=tail    end

tcp_push() → skb_push(TCP_hdr_len)：
  [headroom......|TCP hdr|data|  tailroom  | skb_shared_info]
                 ^                ^
                 data             tail

ip_output() → skb_push(IP_hdr_len)：
  [headroom..|IP hdr|TCP hdr|data|  tailroom  | skb_shared_info]
             ^                    ^
             data                 tail

dev_hard_start_xmit() → 发出后 ip_finish_output2() → skb_push(ETH_hdr_len)：
  [ETH hdr|IP hdr|TCP hdr|data|  tailroom  | skb_shared_info]
  ^                            ^
  data (= head)                tail

4.4 skb_clone vs skb_copy：引用计数 vs 深拷贝

**skb_clone()**（源码第 1853-1881 行）：

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18

struct sk_buff *skb_clone(struct sk_buff *skb, gfp_t gfp_mask)
{
    struct sk_buff_fclones *fclones = container_of(skb,
                                       struct sk_buff_fclones, skb1);
    struct sk_buff *n;

    if (skb->fclone == SKB_FCLONE_ORIG &&
        refcount_read(&fclones->fclone_ref) == 1) {
        n = &fclones->skb2;           // 快路径：使用预分配的 fclone
        refcount_set(&fclones->fclone_ref, 2);
        n->fclone = SKB_FCLONE_CLONE;
    } else {
        n = kmem_cache_alloc(skbuff_cache, gfp_mask);
        if (!n) return NULL;
        n->fclone = SKB_FCLONE_UNAVAILABLE;
    }
    return __skb_clone(n, skb);
}

skb_clone() 只复制 sk_buff 元数据结构，共享数据缓冲区（递增 shinfo->dataref）。克隆体不能修改数据内容，但可以修改自己的首部指针（data 等）。适用于：

• TCP 发送时保留原始 skb 用于重传
• Netfilter 分支处理

fclone 优化：TCP 通过 SKB_ALLOC_FCLONE 标志分配 sk_buff_fclones（两个 skb 紧挨着分配），第一次 clone 时直接使用伴生的 skb2，无需额外 slab 分配。

**skb_copy()**（源码第 1933-1953 行）：

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17

struct sk_buff *skb_copy(const struct sk_buff *skb, gfp_t gfp_mask)
{
    int headerlen = skb_headroom(skb);
    unsigned int size = skb_end_offset(skb) + skb->data_len;
    struct sk_buff *n = __alloc_skb(size, gfp_mask,
                                    skb_alloc_rx_flag(skb), NUMA_NO_NODE);
    if (!n) return NULL;

    /* Set the data pointer */
    skb_reserve(n, headerlen);
    /* Set the tail pointer and length */
    skb_put(n, skb->len);

    BUG_ON(skb_copy_bits(skb, -headerlen, n->head, headerlen + skb->len));
    skb_copy_header(n, skb);
    return n;
}

skb_copy() 完全复制数据，包括 headroom、线性数据以及所有 page frags，返回一个完全独立的 skb。代价是需要实际的数据拷贝。适用于需要修改数据内容的场景。

4.5 skb_linearize：处理分散/聚集 IO

1
2
3
4
5
6
7
8
9

static inline int skb_linearize(struct sk_buff *skb)
{
    return skb_is_nonlinear(skb) ? __skb_linearize(skb) : 0;
}

static inline int __skb_linearize(struct sk_buff *skb)
{
    return __pskb_pull_tail(skb, skb->data_len) ? 0 : -ENOMEM;
}

当代码需要顺序访问报文所有字节，但 skb 是非线性的（data_len > 0，存在 page frags 或 frag_list）时，调用 skb_linearize() 将所有 page frags 的数据拷贝到线性区域，整合为线性 skb。

这是一个较重的操作，会触发内存分配和拷贝。协议栈中有大量 pskb_may_pull() 调用——它只确保 skb 的首部位于线性区域（仅 pull 必要的字节），比完整的 skb_linearize() 代价小得多。

4.6 kfree_skb vs consume_skb：释放路径的语义区别

两者都会递减 skb->users 引用计数，归零后调用 __kfree_skb() 释放内存，但语义不同，这对 tracing 工具（如 drop_monitor、skb:kfree_skb tracepoint）至关重要：

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15

// kfree_skb：报文被丢弃（drop），通常意味着异常
void kfree_skb_reason(struct sk_buff *skb, enum skb_drop_reason reason)
{
    if (__kfree_skb_reason(skb, reason))
        __kfree_skb(skb);
}

// consume_skb：报文被正常消费，不是 drop
void consume_skb(struct sk_buff *skb)
{
    if (!skb_unref(skb))
        return;
    trace_consume_skb(skb, __builtin_return_address(0));  // 触发 consume tracepoint
    __kfree_skb(skb);
}

释放链路（__kfree_skb() 路径）：

1
2
3
4
5
6
7
8
9
10
11
12
13

__kfree_skb(skb)
  └─ skb_release_all(skb, reason, false)
       ├─ skb_release_head_state(skb)
       │    ├─ skb_dst_drop(skb)         // 释放路由缓存引用
       │    ├─ skb->destructor(skb)      // 如 sock_wfree() 归还 socket 内存配额
       │    ├─ nf_conntrack_put()        // 释放连接跟踪引用
       │    └─ skb_ext_put(skb)          // 释放扩展数据
       └─ skb_release_data(skb, reason, false)
            ├─ 递减 shinfo->dataref
            ├─ napi_frag_unref()         // 释放 page frags（可能触发 page_pool 回收）
            ├─ kfree_skb_list(frag_list)
            └─ skb_free_head()           // 释放数据缓冲区
  └─ kfree_skbmem(skb)                  // 归还 sk_buff 到 slab 缓存

五、零拷贝相关机制

5.1 skb_frag_t 页片段机制

skb_frag_t 等价于 struct bio_vec，每个 frag 持有一个 struct page * 引用：

1
2
3
4
5
6
7

typedef struct bio_vec skb_frag_t;

// 访问 frag 的工具函数：
static inline unsigned int skb_frag_size(const skb_frag_t *frag)
{
    return frag->bv_len;
}

驱动在接收时通常这样操作：

1. 预先分配 page（通常通过 page_pool 管理），通过 DMA 映射给网卡
2. 网卡将数据写入 page，触发中断/NAPI
3. 驱动调用 skb_add_rx_frag() 将 page 引用填入 frags[]

1
2
3
4
5
6
7
8

void skb_add_rx_frag(struct sk_buff *skb, int i, struct page *page,
                     int off, int size, unsigned int truesize)
{
    skb_fill_page_desc(skb, i, page, off, size);
    skb->len      += size;
    skb->data_len += size;
    skb->truesize += truesize;
}

page_pool 是 6.x 内核引入的高性能页缓存机制，通过 skb->pp_recycle 标志和 skb_pp_recycle() 函数，在 skb 释放时直接将 page 归还给 page_pool 而非系统内存池，避免了 page allocator 的开销，实现”原地回收”。

5.2 sendfile/splice 的 skb 复用

sendfile() 和 splice() 系统调用走的是 SKBFL_SHARED_FRAG 路径：文件页缓存中的 page 直接被加入 skb 的 frags[]，内核标记该 frag 为可能被外部修改：

1
2
3
4
5
6

/* This indicates at least one fragment might be overwritten
 * (as in vmsplice(), sendfile() ...)
 * If we need to compute a TX checksum, we'll need to copy
 * all frags to avoid possible bad checksum
 */
SKBFL_SHARED_FRAG = BIT(1),

此时 skb 的数据直接来自 page cache，全程无需拷贝到内核网络缓冲区。但如果需要计算 TX checksum（ip_summed == CHECKSUM_PARTIAL 但硬件不支持），内核必须通过 skb_copy_ubufs() 先复制 frags 内容，再计算 checksum，这是 zero-copy sendfile 的一个隐含成本。

用户态零拷贝（MSG_ZEROCOPY，SKBFL_ZEROCOPY_ENABLE）则通过 ubuf_info 回调机制，在 DMA 传输完成后通知用户态释放缓冲区，实现用户态缓冲区到网卡的真正零拷贝。

六、关键结构体尺寸速查（x86-64，Linux 6.4）

七、系列文章导航

本系列共计划 10 篇，系统覆盖 Linux 网络内核的核心子系统：

参考资料

• Linux 6.4-rc1 源码：include/linux/skbuff.h、net/core/skbuff.c
• Linux 内核文档：Documentation/networking/skbuff.rst（内核源码树内）
• Jonathan Corbet 等：Linux Device Drivers, 3rd Edition，Chapter 17
• Jesper Dangaard Brouer：Network stack receive path
• Thomas Graf：Kernel Networking Walkthrough（netdev 历届会议资料）

vLLM 官方 recipes 仓库 提供了超过 57 个生产级部署配方，覆盖 28+ 主流模型家族。本文深入剖析这些配方背后的部署模式、硬件选择、并行策略与调优技巧，帮助你快速从零到一地在生产环境中部署大型语言模型。

第三部分：Scheduler——vLLM 的大脑

简介

Scheduler 是 vLLM 的核心调度器。在每个微秒级的时间窗口内，它都要做出关键决策：处理哪些 request、计算多少个 token、何时 preempt request，以及如何最大化 GPU 利用率。本文将深入探讨 Scheduler 的算法与实现。

调度挑战

问题空间

在任意时刻，Scheduler 必须处理：

• 等待中的 request：等待处理的新 prompt
• 运行中的 request：正处于 decode 阶段的持续生成任务
• 资源限制：有限的 GPU 内存和计算预算
• 目标冲突：最小化延迟 vs. 最大化吞吐量
• 动态负载：request 异步到达和完成

没有简单的解决方案

与传统批处理不同，LLM 推理服务面临独特挑战：

1. 请求长度不固定：无法预测完成时间
2. 内存随序列长度增长：不仅仅受计算限制
3. prefill 与 decode 的不对称性：prefill 每个 token 耗时约为 decode 的 100 倍
4. 共享 KV cache：内存决策影响所有 request

Continuous Batching

vLLM 的核心创新：continuous batching（又称迭代级批处理）。

传统静态批处理

1
2
3
4
5
6
7
8
9
10
11
12
13

# Static batching - wait for batch to fill
batch = []
while len(batch) < batch_size:
    batch.append(wait_for_request())

# Process entire batch
outputs = model.forward(batch)

# Wait for ALL requests to finish
while any_request_incomplete(batch):
    outputs = model.forward(batch)

# All done - start next batch

问题：

• 队头阻塞：快速 request 需等待慢速 request
• 低 GPU 利用率：随着 request 完成，batch 规模不断缩小
• 高延迟：必须等待 batch 填满

Continuous Batching

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15

# Continuous batching - add/remove every iteration
running = []

while True:
    # Remove finished requests
    running = [r for r in running if not r.finished]

    # Add new requests if there's capacity
    while can_fit_new_request() and waiting_requests:
        running.append(waiting_requests.pop())

    # Process current batch
    outputs = model.forward(running)

    # Immediately continue - no waiting!

优点：

• 无队头阻塞：request 完成后立即离队
• 持续高 GPU 利用率：始终维持最大 batch 大小
• 更低延迟：新 request 可立即开始处理

Scheduler 架构

文件位置：vllm/v1/core/sched/scheduler.py

核心数据结构

Scheduler 维护 requests、waiting、running 和 skipped_waiting，并持有 KVCacheManager / EncoderCacheManager 等资源管理器。其中 max_num_scheduled_tokens 的来源是：

1
2
3
4
5

self.max_num_scheduled_tokens = (
    self.scheduler_config.max_num_scheduled_tokens
    if self.scheduler_config.max_num_scheduled_tokens
    else self.scheduler_config.max_num_batched_tokens
)

也就是说，max_num_batched_tokens 现在是 fallback，而不是唯一来源。

Request 状态

当前 V1 的 request 状态比“WAITING → RUNNING → FINISHED”更细：

• WAITING
• WAITING_FOR_STRUCTURED_OUTPUT_GRAMMAR
• WAITING_FOR_REMOTE_KVS
• WAITING_FOR_STREAMING_REQ
• RUNNING
• PREEMPTED
• 多个 finished 子状态：FINISHED_STOPPED、FINISHED_LENGTH_CAPPED、FINISHED_ABORTED、FINISHED_IGNORED、FINISHED_ERROR、FINISHED_REPETITION

因此，更准确的流转应理解为：

• 新请求通常从 WAITING 进入 RUNNING
• 被抢占的请求会变成 PREEMPTED 并重新入队
• 恢复执行时是 PREEMPTED → RUNNING
• 结束时会进入某个具体的 finished 子状态，而不是单一的 FINISHED

Request 队列

当前 RequestQueue 的核心 API 是：

1
2
3
4

queue.add_request(request)
request = queue.pop_request()
request = queue.peek_request()
queue.prepend_request(request)

如果启用 priority 策略，优先级大小规律也与很多直觉相反：数值越小，优先级越高。PriorityRequestQueue 直接依赖 Request.__lt__，比较顺序是：

1. priority（更小者优先）
2. arrival_time（更早者优先）
3. request_id

调度算法

整体流程

schedule() 的核心思路仍然是“先处理 running，再在条件允许时接纳 waiting”。SchedulerOutput 会分别携带：

• scheduled_new_reqs
• scheduled_cached_reqs
• num_scheduled_tokens: dict[str, int]
• total_num_scheduled_tokens
• scheduled_spec_decode_tokens
• scheduled_encoder_inputs
• finished_req_ids
• preempted_req_ids
• 以及 prefix / encoder / connector 相关的附加信息

可以把主循环简化理解为：

1
2
3
4
5
6
7
8

def schedule(self) -> SchedulerOutput:
    token_budget = self.max_num_scheduled_tokens

    # 1. 先调度 running request
    # 2. 必要时执行 preemption
    # 3. 仅在本轮没有 preempt 时尝试接纳 waiting request
    # 4. 构造包含 per-request token 预算、spec decode、
    #    encoder inputs 和 finished/preempted IDs 的 SchedulerOutput

第一步：Token Budget

token budget 的概念没有变化：它仍然是当前迭代最重要的“算力 / latency / activation memory”上限之一。当前实现用 self.max_num_scheduled_tokens 作为每轮 budget，并在 chunked prefill、running request 续跑、spec decode 等路径上共享这份预算。

第二步：调度运行中的 Request

当前 scheduler 不再显式维护“prefill phase / decode phase”两套完全独立的 API。更准确的做法是根据：

• request.num_computed_tokens
• request.num_tokens_with_spec
• request.num_output_placeholders

之间的差值来决定本轮还需要为该 request 安排多少 token。

对 running request 来说，scheduler 主要会：

1. 计算本轮 num_new_tokens
2. 结合 long_prefill_token_threshold 等配置裁剪超长 prefill
3. 为已命中的 prefix cache / 外部 KV transfer / speculative lookahead 计算额外上下文
4. 调用 allocate_slots() 尝试拿到新 slot
5. 若拿不到 slot，则按当前策略 preempt 其他 request 或 preempt 当前 request

因此，比起“给 request 写回 request.num_scheduled_tokens = ...”，当前实现更准确的说法是：每轮调度数量被记录在 SchedulerOutput.num_scheduled_tokens[request_id] 中。

第三步：调度等待中的 Request

一个新 request 要进入本轮 batch，通常会经历这些检查：

1. 从 waiting 或 skipped_waiting 中选择可调度的队列
2. 处理 structured output grammar、remote KV、streaming 等阻塞状态
3. 先调用 get_computed_blocks() 查找 prefix cache 命中
4. 再用 can_fit_full_sequence() 判断完整序列是否可以被系统接纳
5. 通过 allocate_slots() 为本轮真正需要的 token 分配 slot

这里有两个关键点：

• scheduler 维护的是 waiting + skipped_waiting 两条队列，而不是单一 waiting queue
• 只有当本轮没有发生 preemption 时，scheduler 才会继续接纳 waiting request

第四步：处理 Preemption

preemption 通过 _preempt_request() 完成，流程更接近：

1
2
3
4
5
6

def _preempt_request(self, request, timestamp):
    self.kv_cache_manager.free(request)
    self.encoder_cache_manager.free(request)
    request.status = RequestStatus.PREEMPTED
    request.num_preemptions += 1
    self.waiting.prepend_request(request)

需要注意：

• request 会以 PREEMPTED 状态重新入队，而不是简单地回到 WAITING
• preemption 后确实需要重新调度，但如果 prefix cache 还能命中完整 block，后续恢复执行时不一定要“从零开始重算”
• victim 选择也不是固定的“进度最少者优先”：在 priority 模式下，会先牺牲较差优先级的 running request；FCFS 模式下则更接近按当前运行队列尾部顺序处理

高级调度策略

Chunked Prefill

chunked prefill 仍然存在，但当前实现不是 self.chunk_size 这种字段驱动。更贴近源码的配置包括：

• enable_chunked_prefill
• long_prefill_token_threshold
• max_num_partial_prefills
• max_long_partial_prefills

因此，当前行为更像是：

• 对超长 prefill request 截断本轮 num_new_tokens
• 在 token budget 内把长 prompt 分摊到多轮
• 让长 prompt 不至于一次耗尽整个 batch 配额

优先级调度

当前 vLLM 只支持两种调度策略：

• fcfs
• priority

priority 模式下数字越小越先执行。可以这样理解：

1
2
3

# Lower numeric value = higher scheduling priority
priority = 0   # interactive / urgent
priority = 10  # background

支持 Speculative Decoding

当前 scheduler 对 speculative decoding 的感知体现在：

• request 上的 spec_token_ids
• SchedulerOutput.scheduled_spec_decode_tokens
• num_lookahead_tokens
• 输出更新阶段对 draft token 的接受 / 拒绝处理

因此，比起 main_model.verify(draft_tokens) 这种直观伪代码，更准确的描述是：scheduler 会为 lookahead / draft token 预留 slot，并通过 scheduled_spec_decode_tokens 把本轮 spec decode 信息传给后续执行与输出更新路径。

Request 重排序

当前本地源码里并没有一个按“预估 prefix cache 命中率”对 waiting requests 进行重排序的 reorder_for_cache_hits() 实现。waiting 请求的顺序主要由 FCFS / priority queue 决定，再叠加 skipped_waiting 的恢复逻辑。

资源管理

KV Cache 分配

更贴近源码的准入流程是：

1
2
3
4
5
6
7
8
9
10
11
12
13

computed_blocks, num_cached_tokens = kv_cache_manager.get_computed_blocks(request)

if kv_cache_manager.can_fit_full_sequence(
    request,
    num_new_computed_tokens=num_cached_tokens,
    new_computed_blocks=computed_blocks,
):
    new_blocks = kv_cache_manager.allocate_slots(
        request,
        num_new_tokens,
        num_new_computed_tokens=num_cached_tokens,
        new_computed_blocks=computed_blocks,
    )

当存在 sliding window、external KV transfer、spec decode 或 encoder-decoder cross-attention 时，allocate_slots() 还会综合这些上下文一起计算需要分配的 block 数量。

内存压力处理

当前 scheduler 的内存压力处理更接近“尝试为 running request 分配 slot，失败时根据当前策略 preempt”。prefix cache 的显式淘汰接口是 kv_cache_manager.evict_blocks(block_ids)，它按 block id 清理缓存索引。

Encoder Cache 管理

多模态 / encoder-decoder 场景下，当前 request 并不是暴露 encoder_input_ids 这个简化字段。scheduler 会通过 request.mm_features、_try_schedule_encoder_inputs()，以及 EncoderCacheManager.can_allocate() / allocate() / check_and_update_cache() 来判断 encoder side 是否有容量。

性能指标

Scheduler 统计信息

SchedulerStats 的重点字段包括：

• num_running_reqs
• num_waiting_reqs
• kv_cache_usage
• encoder_cache_usage
• prefix_cache_stats
• connector_prefix_cache_stats
• kv_cache_eviction_events
• spec_decoding_stats
• perf_stats

而“本轮 preempt 了多少 request”这类信息，当前是放在 IterationStats.num_preempted_reqs 里，而不是 SchedulerStats.num_preempted。

优化目标

因此，当前 scheduler 更像是在平衡这些目标：

1. 最大化吞吐量：尽可能在 token budget 内安排更多有效计算
2. 最小化延迟：优先保持 running request 的连续推进
3. 控制长 prompt 影响：通过 chunked prefill / long prefill threshold 避免大 prompt 独占
4. 减少无谓 preemption：让 KV cache 与 encoder cache 的压力保持可控
5. 尽可能利用 prefix cache / external KV：减少重复 prefill 计算

示例：调度时间线

下面给出一个更接近当前实现语义的简化时间线。注意这里使用的是 scheduler_output.num_scheduled_tokens[req_id] 这个“每轮输出”，而不是给 request 对象写回一个持久字段。

初始状态

1
2
3

waiting = [A(prompt=100), B(prompt=50)]
running = []
token_budget = 200

迭代 1

• A 和 B 都还是新请求
• scheduler 分别检查 prefix cache 命中、完整序列准入与 KV slot 分配
• 若两者都能被接纳，则输出里会类似地记录：

1
2
3
4

scheduler_output.num_scheduled_tokens = {
  "A": 100,
  "B": 50,
}

迭代 2

• A、B 进入 running 集合
• 若此时到来一个超长请求 C，scheduler 会先为 running request 预留预算，再根据 long_prefill_token_threshold 与剩余 budget 决定 C 这一轮最多能推进多少 token
• 如果本轮发生了 preemption，则 waiting request 的接纳会被延后到下一轮

后续迭代

• request 的自然完成不是在 schedule() 里直接调用某个 finish_request() helper，而是要等 model output 返回后，由 scheduler.update_from_output(...) 更新状态并判断 stop / length cap / error 等 finished 原因
• 若 B 被 preempt，scheduler 会把它以 PREEMPTED 状态重新入队；等资源恢复后，它会再次进入 RUNNING

调度策略

当前 vLLM 暴露的调度策略只有两种：

FCFS（先到先服务）

• 队列类型：FCFSRequestQueue
• 主要接口：add_request() / pop_request() / peek_request()
• 优点：简单、可预测
• 缺点：长 request 更容易拖慢后续 waiting request 的进入时机

基于优先级

• 队列类型：PriorityRequestQueue
• 排序规则：priority 数值越小越先执行；若相同则按 arrival_time，再按 request_id
• 优点：可以显式优先保障交互式 / 重要流量
• 缺点：如果优先级设计不当，低优先级 request 可能长期等待

排查 Scheduler 问题

高 Preemption 率

更贴近当前指标的观察方式是关注：

• IterationStats.num_preempted_reqs
• SchedulerStats.kv_cache_usage
• SchedulerStats.encoder_cache_usage

如果 preemption 频繁发生，通常优先检查：

1. KV cache 是否过小
2. max_num_seqs 是否过高
3. 是否启用了 chunked prefill，以及 long_prefill_token_threshold 是否合理

等待队列持续增长

如果 SchedulerStats.num_waiting_reqs 长时间偏高，通常意味着：

1. token budget 太保守
2. 长 prompt 占用了过多 budget
3. priority / FCFS 策略与业务流量类型不匹配

高延迟

如果 TTFT 偏高，通常优先检查：

1. 是否启用 chunked prefill
2. max_num_scheduled_tokens 是否过大
3. prefix cache / external KV 是否发挥作用
4. 高优先级交互流量是否需要单独的 priority 策略

关键要点

1. Continuous batching 通过每次迭代动态增减 request，消除了队头阻塞

2. Token budget 控制 batch 大小，平衡延迟与吞吐量的权衡

3. 运行中的 request 拥有优先权，以最小化 decode 延迟

4. Preemption 是内存紧张时的最后手段：它会中断当前运行进度，但后续恢复时仍可能重新命中 prefix cache

5. Chunked prefill 在处理长 prompt 与交互式 request 之间取得平衡

6. 当前的 SchedulerOutput 是结构化输出，会同时携带 per-request token 分配、spec decode、encoder 输入与 finished/preempted request 信息

下一步

在第四部分中，我们将探索 Request Processing——request 如何从 tokenization 到流式输出在系统中流转，以及跨迭代的状态管理机制。

参考资料

• Scheduler Implementation
• Continuous Batching Paper (Orca)
• Request Queue

Scheduler 是 vLLM 的大脑，每秒钟要做出成千上万个瞬间决策，在满足延迟 SLA 的同时最大化 GPU 利用率。接下来，我们将看到 request 如何在系统中端到端地流转。

第二部分：PagedAttention——核心创新

简介

PagedAttention 是 vLLM 的突破性创新，彻底改变了大语言模型的服务方式。在 PagedAttention 出现之前，高效服务 LLM 长期受到内存碎片化和浪费问题的困扰。本文将深入探讨 PagedAttention 的工作原理、重要意义，以及它在 vLLM 中的实现方式。

LLM 服务中的内存问题

理解 KV Cache

在 transformer 模型中，attention 层为每个 token 计算键（K）和值（V）向量。在生成过程中：

1. Prefill 阶段：为所有提示词 token 计算 K、V
2. Decode 阶段：对每个新 token，计算其 K、V，并对所有之前的 K、V 进行 attention 计算

挑战：我们必须存储所有之前的 K、V 张量（即”KV cache”），以避免重复计算。

内存大小：以 Llama-3-8B 为例：

• 32 个 attention 层
• 4096 隐藏维度
• FP16 精度（2 字节）
• 每个 token：32 层 × 4096 维度 × 2（K、V）× 2 字节 = 512 KB

对于 2048 个 token 的序列：仅 KV cache 就需要 1 GB！

碎片化问题

传统服务系统为每个请求的最大长度预先分配连续内存：

1
2
3
4
5
6
7
8

Request 1 (max 2048 tokens, actual 512):
[████░░░░░░░░░░░░] 75% wasted

Request 2 (max 2048 tokens, actual 1800):
[████████████████] 12% wasted

Request 3 (max 2048 tokens, actual 200):
[██░░░░░░░░░░░░░░] 90% wasted

问题：

1. 过度分配：必须按最坏情况的长度进行分配
2. 碎片化：无法将一个请求的未使用空间分配给另一个请求
3. 低吞吐量：内存成为瓶颈，而非计算

实际影响：没有 PagedAttention，你可能只能服务 10 个并发请求；而有了 PagedAttention，同样的内存可以服务 50 个以上的请求！

PagedAttention 的解决方案

PagedAttention 将虚拟内存的理念应用于 attention 计算：

核心思想：不再将 KV cache 连续存储，而是将其拆分为固定大小的 block。每个请求获得一个 block table，将逻辑位置映射到 physical block。

虚拟内存类比

基于 block 的存储

取代连续分配的方式：

1
2
3
4
5
6
7
8
9
10
11

Request 1 (512 tokens, 32 blocks):
Blocks: [11, 3, 7, 12, ..., 89]
       Scattered in GPU memory

Request 2 (1800 tokens, 113 blocks):
Blocks: [1, 2, 4, 5, ..., 105]
       Can reuse freed blocks from other requests

Request 3 (200 tokens, 13 blocks):
Blocks: [6, 8, 9, ..., 18]
       Minimal waste (only last block partially filled)

优势：

1. 无过度分配：按需分配 block
2. 无碎片化：任何空闲 block 都可分配给任意请求
3. 近零浪费：每个请求只有最后一个 block 可能是部分填充的
4. 共享：共同前缀可共享 physical block

实现深度解析

block 结构

文件位置：vllm/v1/core/kv_cache_utils.py

当前源码中的 KVCacheBlock 是一个 @dataclass(slots=True)，核心字段包括：

1
2
3
4
5
6
7
8

@dataclass(slots=True)
class KVCacheBlock:
    block_id: int
    ref_cnt: int = 0
    _block_hash: BlockHashWithGroupId | None = None
    prev_free_block: KVCacheBlock | None = None
    next_free_block: KVCacheBlock | None = None
    is_null: bool = False

其中 block_hash 通过 property 暴露，实际携带的是“block hash + KV cache group id”的组合键，而不是一个简单的 int。

物理存储：

v1 不再假设单一固定的 torch.empty(..., float16) layout。实际实现会先根据 KVCacheConfig 分配原始缓存，再由不同 attention backend（如 FlashInfer、Triton、FlashAttention）重塑为各自需要的 KV layout。常见 shape 仍然围绕 num_blocks / 2(K,V) / block_size / num_kv_heads / head_size 展开，但具体维度顺序与 dtype 取决于 backend。

Block Pool

文件位置：vllm/v1/core/block_pool.py

BlockPool 维护所有 KV cache block、空闲队列与 prefix cache 索引。构造函数的核心形态如下：

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16

class BlockPool:
    def __init__(
        self,
        num_gpu_blocks: int,
        enable_caching: bool,
        hash_block_size: int,
        enable_kv_cache_events: bool = False,
        metrics_collector: KVCacheMetricsCollector | None = None,
    ):
        self.blocks = [KVCacheBlock(idx) for idx in range(num_gpu_blocks)]
        self.free_block_queue = FreeKVCacheBlockQueue(self.blocks)
        self.cached_block_hash_to_block = BlockHashToBlockMap()

        # block 0 被预留为特殊 null_block
        self.null_block = self.free_block_queue.popleft()
        self.null_block.is_null = True

这有两个容易忽略的细节：

1. block_id=0 不是普通数据块，而是 null_block 占位块。
2. cached_block_hash_to_block 不是简单的 dict[int, block]，而是支持 hash 冲突的 BlockHashToBlockMap。

分配与释放：

BlockPool 的核心接口是 get_new_blocks()、touch() 与 free_blocks()：

1
2
3

new_blocks = block_pool.get_new_blocks(num_blocks)
block_pool.touch(cached_blocks)            # prefix cache 命中时增加引用
block_pool.free_blocks(reversed(blocks))   # 释放时通常按逆序归还

• get_new_blocks() 会从 free queue 批量取出 block，并在需要时调用 _maybe_evict_cached_block() 清理旧的缓存元数据。
• touch() 用于 prefix cache 命中路径：若命中的 block 仍在 free queue 中，会先移出再增加 ref_cnt。
• free_blocks() 按列表批量释放 block；调用方通常按逆序释放，以便让尾部 block 更容易被优先回收。

block table 与 KVCacheBlocks

当前 v1 更接近“按 KV cache group 组织 block 列表”的实现，而不是 [[7], [23], ...] 这种每个逻辑 block 再包一层列表的结构。

• 请求侧使用 KVCacheBlocks.blocks: tuple[Sequence[KVCacheBlock], ...]
• 调用 get_block_ids() 后，会得到按 KV cache group 分组的 block id 列表
• kernel 侧最终消费的是按 group 构造的 block_table tensor

对单一 attention group 来说，可以把它理解为一个平坦的 physical block id 序列；有多个 group（如 attention + Mamba）时，外层再按 group 分组。

KVCacheManager

文件位置：vllm/v1/core/kv_cache_manager.py

KVCacheManager 的职责不只是“给 request 分配新 block”，而是把 prefix cache 命中、完整序列准入、sliding window 裁剪、speculative lookahead，以及 encoder-decoder 的 cross-attention 都纳入同一套 slot 管理逻辑。

当前更重要的接口是：

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18

computed_blocks, num_computed_tokens = kv_cache_manager.get_computed_blocks(request)

can_admit = kv_cache_manager.can_fit_full_sequence(
    request,
    num_new_computed_tokens=num_computed_tokens,
    new_computed_blocks=computed_blocks,
)

new_blocks = kv_cache_manager.allocate_slots(
    request,
    num_new_tokens,
    num_new_computed_tokens=num_computed_tokens,
    new_computed_blocks=computed_blocks,
    num_lookahead_tokens=num_lookahead_tokens,
    num_external_computed_tokens=num_external_computed_tokens,
    delay_cache_blocks=delay_cache_blocks,
    num_encoder_tokens=num_encoder_tokens,
)

这套接口有几个关键点：

• get_computed_blocks() 与 allocate_slots() 是分开的两个阶段，scheduler 会先查 prefix cache，再决定是否准入。
• allocate_slots() 返回 KVCacheBlocks | None，而不是 (blocks, num_cached_tokens)。
• allocate_slots() 还会在真正分配前调用 remove_skipped_blocks()，把 sliding window 或 sparse attention 下已经不需要的 block 替换成 null_block。

Prefix Caching：跨请求共享

Prefix caching 仍然是 PagedAttention 最有价值的能力之一，但当前实现比“对 token tuple 做一次 Python hash”要复杂得多。

block 哈希

源码里的 block hash 是链式计算的：当前 block 的 hash 会把父 block 的 hash、当前 block token、以及 multimodal / LoRA / cache salt / prompt embed 等额外键一起纳入计算。返回值类型是 BlockHash（bytes 包装），不是简单的 int。

可以把它理解为：

1

block_hash = H(parent_block_hash, current_block_tokens, extra_keys)

这让 vLLM 可以：

• 只对完整 block建立 prefix cache 索引
• 区分同一 token 序列在不同 KV cache group 中的缓存项
• 在多模态、LoRA 或 prompt embedding 参与时避免误共享

cache 查找

当前 KVCacheManager.get_computed_blocks() 会调用 coordinator / manager 路径来寻找“最长可命中的前缀”，而不是直接遍历 request.block_hashes 并手动递增 ref_cnt。

1
2
3
4
5
6

computed_blocks, num_new_computed_tokens = (
    self.coordinator.find_longest_cache_hit(
        request.block_hashes,
        max_cache_hit_length,
    )
)

几个细节很重要：

• prefix cache 只会命中完整 block
• 即使“整个 prompt 都命中”，也通常要重新计算最后一个 token 以得到 logits，因此 max_cache_hit_length 会被限制为 request.num_tokens - 1
• 命中后的引用计数增加发生在 block_pool.touch(...) 路径，而不是在查找函数里直接修改

reference counting

reference counting 的基本含义没有变化：多个 request 可以共享同一个 prefix block，只有 ref_cnt == 0 时它才会回到 free queue，成为可复用或可淘汰对象。

cache 淘汰

当前实现不是“扫描 free queue 找第一个 ref_cnt == 0 的 cached block 并返回”的 evict_cached_block() 接口。更接近真实源码的过程是：

1. get_new_blocks() 先从 free queue 取出候选 block
2. 若该 block 仍带有 block_hash，则调用 _maybe_evict_cached_block(block) 把它从 cached_block_hash_to_block 中摘除
3. 若需要显式按 block id 淘汰 prefix cache，则使用 evict_blocks(block_ids)

也就是说，淘汰是围绕“取出的 block 是否还挂着 cache 元数据”展开的。

使用 block 进行 attention 计算

Prefill 阶段

当前 v1 并没有统一公开的 paged_attention_prefill(...) Python API。prefill 由具体 attention backend 负责执行，例如 FlashInfer 路径会使用 BatchPrefillWithPagedKVCacheWrapper / BatchPrefillWithRaggedKVCacheWrapper，其他 backend 则会构造自己的 metadata 和 kernel 调用。

对外可以把它理解为两步：

1. scheduler / attn metadata 根据 seq_lens 和 block tables 构建 batch 视图
2. backend kernel 直接按 paged KV cache layout 完成 prefill attention

Decode 阶段

decode 阶段通常由具体 attention backend 负责。以 FlashInfer 路径为例，decode 侧会通过 BatchDecodeWithPagedKVCacheWrapper（或 TRT-LLM decode path）直接消费 paged KV cache。

因此，当前实现更准确的描述是：

• prefill / decode 都是 backend-specific
• block table 会在 metadata 构建阶段转成 tensor 形式
• kernel 直接根据 paged KV layout 取 K/V，而不是先在 Python 层把 block 拼接成连续张量

多组 KV cache

vLLM 支持不同层使用不同 cache 规格，相关配置类型是 KVCacheGroupSpec / KVCacheConfig。

概念上可以理解为：

• KVCacheConfig 持有 num_blocks、kv_cache_tensors 和 kv_cache_groups
• 每个 KVCacheGroupSpec 绑定一组 layer 名称与对应的 kv_cache_spec
• kv_cache_spec 可以是 FullAttentionSpec、SlidingWindowSpec、MambaSpec 等不同类型

因此，一个 request 的 block 记录也会天然按 group 分层，例如：

1
2
3
4

blocks = (
    [attn_block_0, attn_block_1, attn_block_2],
    [mamba_block_0, mamba_block_1, mamba_block_2],
)

这也是为什么 BlockHash 需要和 group id 绑定：同一段 token 在不同 KV cache group 中对应的是不同的物理缓存项。

性能影响

内存效率

使用 PagedAttention 之前（连续分配）：

1
2
3

10 requests × 2048 max length × 512 KB/token = 10.5 GB
Actual usage: 10 requests × 500 avg length = 2.5 GB
Efficiency: 24%

使用 PagedAttention 之后（block 分配）：

1
2
3

500 blocks allocated across all requests
Waste: ~10 blocks (partial last blocks)
Efficiency: 98%

结果：并发请求数提升 4 倍！

吞吐量提升

真实基准测试（Llama-3-8B，运行于 H100）：

Prefix Caching 收益

使用共同系统提示词（500 个 token）时：

缓存命中率：对于带有系统提示词的聊天机器人，通常在 60-80% 之间。

进阶主题

滑动窗口 attention

对 Mistral 这类 sliding-window 模型，当前实现不会简单地“切片旧 block 然后逐个 free”。更接近真实源码的流程是：

• 先根据 total_computed_tokens 计算哪些 block 已经落到窗口之外
• 调用 remove_skipped_blocks() 把这些位置替换为 null_block
• 再把不再需要的真实 block 批量归还给 block pool

这样既保留了逻辑 block table 的形状，又避免了窗口外 token 继续占用可复用的缓存块。

speculative decoding

在当前 v1 中，speculative decoding 主要通过 num_lookahead_tokens、slot allocation 和 scheduler 的 scheduled_spec_decode_tokens 协同完成。

更准确地说：

• scheduler 会为 lookahead token 预留 slot
• allocate_slots() 只会把最终确认的 token 提交到 prefix cache
• 被拒绝的 draft token 会在 slot mapping / 输出更新路径中被屏蔽，而不是靠手工 ref_cnt += 1 / 回滚 block 列表来管理

实现中的注意事项

hash 碰撞

当前实现通过 BlockHashToBlockMap 处理哈希碰撞。对于同一个 hash，值可能是单个 KVCacheBlock，也可能退化成 {block_id: KVCacheBlock} 这样的结构，而不是简单的 hash -> list[block]。

不完整的 block

最后一个 block 仍然可能是不完整的，但当前实现不会在 KVCacheBlock 元数据里单独维护 num_tokens_in_last_block 这样的字段。vLLM 只对完整 block建立 prefix cache，并通过 seq_lens 等 batch metadata 在 attention 计算时屏蔽无效位置。

线程安全

线程安全方面，block_pool.py 并没有对外暴露 allocate/_allocate_unsafe 这类接口；调度路径更接近单一 owner 管理 block pool 状态，而不是通过显式锁 API 暴露给外部使用。

核心要点

1. PagedAttention 将 KV cache 拆分为固定大小的 block，消除了碎片化和过度分配问题

2. block table 将逻辑 block 映射到 physical block，类似于虚拟内存的页表

3. prefix caching 跨请求共享 block，大幅减少了冗余计算

4. reference counting 确保安全共享，防止过早释放内存

5. 近零内存浪费在实践中实现了 4-5 倍的吞吐量提升

6. attention 内核经过优化，可直接使用 block 索引存储进行计算

下一步

在第三部分，我们将探索 Scheduler——vLLM 的核心调度器，它负责决定处理哪些请求、何时进行抢占，以及如何通过 continuous batching 最大化 GPU 利用率。

参考资料

• PagedAttention Paper
• Block Pool Implementation
• KVCacheManager
• Flash Attention with Paging

PagedAttention 是 vLLM 卓越性能的基础。在下一篇文章中，我们将看到 Scheduler 如何在此之上协调请求的执行。

第一部分：vLLM 架构概览

简介

在深入研究具体组件之前，我们需要先了解 vLLM 的整体架构。本文梳理了各主要组件及其交互方式，为后续各部分的深入探讨奠定基础。

全局视角

vLLM 的设计围绕以下几个核心原则：

1. 关注点分离：不同职责（调度、执行、服务）由各自独立的组件负责处理
2. 进程隔离：V1 架构采用多进程设计，以提升健壮性和 CPU 利用率
3. 异步处理：请求在流水线中流转，不会产生阻塞
4. 默认分布式：从底层设计上即支持多 GPU 执行

高层数据流

当你向 vLLM 发送一个请求时，整个流程如下：

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17

User Request (HTTP/gRPC)
    ↓
API Server Process
    ↓ (ZMQ Socket)
Engine Core Process
    ↓
Scheduler
    ↓
GPU Worker Processes
    ↓ (NCCL/Collective Ops)
Model Execution
    ↓
Output Processing
    ↓ (ZMQ Socket)
API Server Process
    ↓
Streaming Response to User

V1 多进程架构

V1 架构（于 2024 年底引入）采用多进程设计，以实现更好的 CPU 利用率和进程隔离。下面逐一介绍各进程类型：

1. API Server 进程

职责：处理前端请求、I/O，以及与 engine core 的通信

主要任务：

• 接收并校验 OpenAI-compatible HTTP 请求
• 对输入文本进行 tokenize
• 加载多模态数据（图像、音频）
• 将输出以流式方式返回给客户端
• 处理 API 鉴权及其他前端请求逻辑

核心实现：OpenAI-compatible HTTP 服务位于 vllm/entrypoints/openai/api_server.py；gRPC 服务位于 vllm/entrypoints/grpc_server.py。

API server 对于模型执行而言是无状态的。它不了解 GPU 内存、KV cache 或模型权重，只负责：

1. 将用户请求转换为 EngineCoreRequest 对象
2. 通过 ZMQ 将其发送给 engine core
3. 接收返回的 EngineCoreOutput 对象
4. 将其转换为 API 响应

进程数量：默认单 API server；在在线 data parallel 部署中，api_server_count 的默认值会随 internal / hybrid / external load-balancing 模式变化，并可由 --api-server-count 覆盖。

CPU 线程：使用 VLLM_MEDIA_LOADING_THREAD_COUNT 个线程（默认 8）并行加载媒体文件。

2. Engine Core 进程

职责：调度请求并协调模型执行

主要任务：

• 维护请求队列
• 运行 scheduler 以决定计算内容
• 管理 KV cache 分配
• 协调 GPU worker
• 处理请求抢占与换出

核心实现：vllm/v1/engine/core.py

engine core 运行一个紧凑的循环（run_busy_loop，core.py:1138）：

1
2
3
4
5
6
7
8
9
10
11
12
13

def run_busy_loop(self):
    while self._handle_shutdown():
        # 1. 从 input_queue 拉取新请求（add_request / abort_requests）
        self._process_input_queue()
        # 2. 调度 + 执行一次模型 step，将输出推入 output_queue
        self._process_engine_step()

def _process_engine_step(self):
    # step() 内部：scheduler.schedule() -> model_executor.execute_model()
    outputs, model_executed = self.step_fn()
    for output in outputs.items() if outputs else ():
        self.output_queue.put_nowait(output)
    self.post_step(model_executed)

进程数量：每个 data parallel rank 对应一个。设置 --data-parallel-size 4 时，将启动 4 个 engine core。

CPU 用量：运行忙循环以实现低延迟的调度决策。

3. GPU Worker 进程

职责：在 GPU 上执行模型前向传播

主要任务：

• 将模型权重加载到 GPU
• 执行前向传播
• 管理 GPU 内存
• 运行 CUDA kernel（attention、FFN 等）
• 参与集合通信操作（用于 tensor parallelism / pipeline parallelism）

核心实现：vllm/v1/worker/gpu_worker.py

在 MultiprocExecutor 下，通常会看到“每个 GPU 一个 worker 进程”；但在单机单卡默认的 UniProcExecutor 路径中，worker 会运行在 EngineCore 进程内，而不是独立的 OS 进程。worker 负责：

1. 加载其对应分片的模型权重
2. 从对应的 engine core 接收执行请求
3. 运行模型前向传播
4. 将执行结果交回 executor / engine core 的后续处理路径

进程数量：取决于 executor 后端。对于 8 个 GPU、设置 --tensor-parallel-size 4 --data-parallel-size 2 这类多 GPU 部署，通常会看到 8 个 worker，由 2 个 engine core 分别协调 2 组 tensor parallel worker。

4. DP Coordinator 进程（按需启动）

职责：在 data parallel 部署中汇总引擎状态，并为前端负载均衡与 wave coordination 提供协调信息

主要任务：

• 汇总各 DP engine 的 waiting / running 队列统计
• 将这些统计发布给 front-end client，供其做负载均衡决策
• 维护 request wave / running state，并在需要时广播 START_DP_WAVE

核心实现：vllm/v1/engine/coordinator.py

进程数量：当 --data-parallel-size > 1 时启动 1 个，否则不启动。

进程数量示例

下面来看几个具体示例。需要注意的是，实际 OS 进程数量会随 executor 后端与 load-balancing 模式变化；以下示例以当前 CLI 默认路径为参考：

示例 1：单 GPU

1

vllm serve meta-llama/Llama-3-8B

进程：

• 1 个 API Server（当前进程）
• 1 个 Engine Core
• GPU worker 以内嵌方式运行在 EngineCore 进程内（UniProcExecutor）
• 共计：通常约 2 个 OS 进程

示例 2：Tensor Parallelism（4 个 GPU）

1

vllm serve meta-llama/Llama-3-70B --tensor-parallel-size 4

进程：

• 1 个 API Server
• 1 个 Engine Core
• 4 个 GPU Worker（每个 GPU 各一个）
• 共计：6 个进程

示例 3：Data Parallelism（4 个 GPU）

1

vllm serve meta-llama/Llama-3-8B --data-parallel-size 4

进程：

• 1 个 launcher / manager
• 4 个 API Server
• 4 个 Engine Core（每个 DP rank 各一个）
• 4 个 GPU Worker（每个 GPU 各一个）
• 1 个 DP Coordinator
• 共计：单机 internal-LB 部署下通常约 14 个进程

示例 4：混合并行（8 个 GPU）

1

vllm serve meta-llama/Llama-3-70B --tensor-parallel-size 2 --data-parallel-size 4

进程：

• 1 个 launcher / manager
• 4 个 API Server
• 4 个 Engine Core（每个 DP rank 各一个）
• 8 个 GPU Worker（每个 DP rank 2 个，每个 GPU 各一个）
• 1 个 DP Coordinator
• 共计：单机 internal-LB 部署下通常约 18 个进程

核心组件详解

LLMEngine

LLMEngine 类是离线推理（直接使用 Python API）的主要入口点。

位置：vllm/v1/engine/llm_engine.py

主要职责：

• 创建并管理 engine core
• 通过 InputProcessor 处理输入
• 通过 OutputProcessor 转换输出
• 管理请求生命周期

使用示例：

1
2
3
4
5
6
7
8
9
10

from vllm import LLM, SamplingParams

# Initialize engine
llm = LLM(model="meta-llama/Llama-3-8B")

# Generate
outputs = llm.generate(
    ["Hello, my name is"],
    SamplingParams(temperature=0.8, top_p=0.95)
)

在底层，LLM 创建 LLMEngine，LLMEngine 再创建 EngineCore，由其协调各 worker。

Scheduler

Scheduler 是 vLLM 的核心大脑，负责决策：

• 每次迭代处理哪些请求
• 每个请求计算多少 token
• 何时以及对哪些请求进行抢占
• 如何分配 KV cache 块

位置：vllm/v1/core/sched/scheduler.py

Scheduler 维护三个队列：

1. 等待队列（Waiting）：等待开始处理的新请求
2. 运行队列（Running）：正在被处理的请求
3. 暂跳队列（Skipped Waiting）：因依赖关系而被临时跳过的请求

调度算法（简化版）：

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20

def schedule(self) -> SchedulerOutput:
    scheduled_requests = []
    token_budget = max_num_scheduled_tokens

    # First, schedule running requests (priority)
    for req in running:
        if token_budget > 0:
            num_tokens = min(req.remaining_tokens, token_budget)
            scheduled_requests.append((req, num_tokens))
            token_budget -= num_tokens

    # Then, schedule waiting requests
    for req in waiting:
        if token_budget >= req.num_prompt_tokens:
            scheduled_requests.append((req, req.num_prompt_tokens))
            token_budget -= req.num_prompt_tokens
        else:
            break  # Not enough budget

    return SchedulerOutput(scheduled_requests)

我们将在第三部分深入探讨 scheduler。

KV Cache Manager

使用 PagedAttention 管理 attention key-value cache 的内存。

位置：vllm/v1/core/kv_cache_manager.py

核心概念：

• Block（块）：固定大小的 KV cache 单元（例如 16 个 token）
• Block Pool（块池）：预分配的块集合
• Block Table（块表）：逻辑位置到物理块的映射
• Prefix Cache（前缀缓存）：用于共享公共 prompt 前缀的块

示例：若块大小为 16，共有 1000 个块，则可以服务于：

• 1 个拥有 16,000 个 token 的请求，或
• 16 个各有 1,000 个 token 的请求，或
• 任何能放入 1000 个块的组合

我们将在第二部分深入剖析 PagedAttention。

Worker 与后端 Runner

worker 进程负责加载模型并执行前向传播。

Worker（vllm/v1/worker/gpu_worker.py）：

• 管理 GPU 设备
• 初始化模型权重
• 与其他 worker 协调（用于 tensor parallelism / pipeline parallelism）

具体后端的 model runner（例如 GPUModelRunner / CPUModelRunner / XPUModelRunner，以及较新的 GPU runner 路径）：

• 准备输入 tensor
• 执行模型前向传播
• 应用 CUDA graph 优化
• 产出供 executor / engine core 后续处理的执行结果

请求生命周期

让我们跟踪一个完整请求在系统中的流转过程：

1. 请求到达

1
2
3
4
5
6

POST /v1/completions
{
  "model": "meta-llama/Llama-3-8B",
  "prompt": "The capital of France is",
  "max_tokens": 50
}

2. API Server 处理

• 校验请求
• 对 prompt 进行 tokenize：[791, 3139, 315, 9822, 374]
• 创建 EngineCoreRequest 对象
• 通过 ZMQ 发送至 engine core

3. Engine Core 接收

• 将请求加入 scheduler 的等待队列
• 请求 ID 通常已在前端 InputProcessor 阶段分配/随机化，并随 EngineCoreRequest 一起传入
• 初始化请求状态

4. 首次调度迭代

• Scheduler 发现等待队列中的新请求
• 检查 prefix cache / KV cache 状态
• 为本轮需要计算的 token 分配 KV cache 块（块大小为 16 token 时，这个例子中通常只需要 1 个块）
• 生成本轮 SchedulerOutput

5. Worker 执行

• executor / worker 接收调度结果
• 准备输入 tensor
• 运行模型前向传播
• 若需要采样，则通过 model_executor.sample_tokens(...) 生成本轮 token 输出

6. 输出处理

• engine core 使用 scheduler.update_from_output(...) 更新请求状态
• 将 EngineCoreOutput 通过 ZMQ 发送给 API server

7. API Server 流式输出

• 从 engine core 接收 token
• Detokenize：”Paris”
• 流式返回给客户端：data: {"text": "Paris", "finish_reason": null}

8. 后续迭代

• 请求移入运行队列
• Scheduler 持续分配 token
• 每次迭代：计算 1 个新 token（decode 阶段）
• 将每个 token 流式发送给客户端

9. 请求完成

• 达到 max_tokens 上限或生成 EOS
• 释放 KV cache 块（或保留在 prefix cache 中）
• 向客户端发送最终完成结果
• 从 scheduler 中移除请求

配置与初始化

vLLM 的配置统一集中在 VllmConfig 中：

1
2
3
4
5
6
7
8
9

from vllm.config import VllmConfig

vllm_config = VllmConfig(
    model_config=ModelConfig(...),
    cache_config=CacheConfig(...),
    scheduler_config=SchedulerConfig(...),
    parallel_config=ParallelConfig(...),
    # ... more configs
)

许多核心组件会共享或持有同一个 VllmConfig，以确保配置一致性。

主要配置项：

• ModelConfig：模型名称、dtype、tokenizer
• CacheConfig：KV cache 大小、块大小、prefix caching
• SchedulerConfig：最大批量大小、调度策略
• ParallelConfig：TP/PP/DP 规模、分布式后端

类层次结构

类层次结构遵循一致的模式：

1
2
3
4
5
6
7
8
9
10
11
12

LLMEngine
  ├── InputProcessor (tokenization, preprocessing)
  ├── EngineCore
  │   ├── StructuredOutputManager
  │   ├── Scheduler
  │   │   ├── KVCacheManager
  │   │   └── EncoderCacheManager
  │   └── Executor
  │       └── Workers / backend runners
  │           └── GPUModelRunner / CPUModelRunner / XPUModelRunner
  │               └── Model (nn.Module)
  └── OutputProcessor (detokenization, streaming)

许多核心类会接收或持有 VllmConfig，但并非所有类都直接以它作为构造参数；例如 OutputProcessor 并不直接接收 VllmConfig。

进程间通信

ZMQ Sockets

API server 与 engine core 通过 ZMQ 进行通信，消息编码采用基于 MsgpackEncoder / MsgpackDecoder 的 multipart frame：

• front-end / API server 一侧会把 EngineCoreRequest 编码成 multipart 消息并通过 send_multipart(...) 发送
• engine core 一侧通过 recv_multipart(...) 接收，再按消息类型用 MsgpackDecoder 解码
• 在需要传输 tensor 的路径上，还会配合 tensor IPC，而不是把所有内容都塞进单个 pickle payload

为什么选择 ZMQ？

• 高性能（微秒级延迟）
• 灵活的通信模式（req-rep、pub-sub、push-pull）
• 内置队列管理
• 语言无关

NCCL 用于 GPU 通信

GPU worker 使用 NCCL 进行集合通信操作：

1
2
3
4
5
6

# Tensor parallelism: all-reduce across GPUs
torch.distributed.all_reduce(
    tensor,
    op=torch.distributed.ReduceOp.SUM,
    group=tensor_parallel_group
)

通信模式：

• Tensor Parallel：在 attention/FFN 之后执行 All-reduce
• Pipeline Parallel：各阶段之间执行发送/接收操作
• Data Parallel：前向传播期间无需通信

内存布局

理解内存布局对于 vLLM 至关重要：

GPU 内存分布

1
2
3
4
5

Total GPU Memory: 80GB (H100)
├── Model Weights: 16GB (Llama-3-8B in FP16)
├── KV Cache: 60GB (dynamically allocated blocks)
├── Activation Memory: 2GB (for batch processing)
└── Framework Overhead: 2GB (PyTorch, CUDA)

KV Cache 内存

对于块大小为 16 token 的 8B 模型：

• 每个块存储 32 个 attention 层的 K 和 V
• 每块大小：16 token × 32 层 × 2（K,V）× 4096 维 × 2 字节 = 8.4 MB
• 若 KV cache 分配 60GB：约 7,100 个块
• 总容量：跨所有请求约 113,600 个 token

性能特征

H100 GPU 上的典型性能表现：

下一步

现在我们已经了解了整体架构，接下来可以深入探讨各具体组件：

• 第二部分：PagedAttention 与 KV cache 管理
• 第三部分：Scheduler 的决策过程
• 第四部分：请求处理与状态管理
• 第五部分：分布式执行与并行策略

关键要点

1. V1 采用多进程架构，以提升 CPU 利用率和故障隔离能力
2. Scheduler 是核心协调者，负责决策每次迭代的计算内容
3. KV cache 管理（PagedAttention）是内存效率的关键所在
4. 进程数量随并行度扩展：但会受到 executor 后端、load-balancing 模式以及是否存在 launcher / manager 进程的影响
5. ZMQ 实现了高效的进程间通信
6. 许多核心组件共享或持有统一的 VllmConfig，以保持配置一致性

参考资料

• vLLM 架构文档
• Engine Core 实现
• Scheduler 实现
• PagedAttention 论文

在下一篇文章中，我们将详细探讨 PagedAttention，了解 vLLM 如何通过精巧的内存管理实现近乎零浪费的内存利用。

vLLM 深度解析系列：理解现代大语言模型服务

系列概述

本系列对 vLLM 进行全面深入的技术剖析。vLLM 是大语言模型推理与服务领域最重要的开源项目之一，最初由 UC Berkeley 的 Sky Computing Lab 开发，现已成为生产环境中高性能 LLM 服务的事实标准。

引言

prow-images 仓库是基于 Kubernetes Prow 构建的复杂 CI/CD 基础设施的核心组件。它作为专用容器镜像的集中式集合，为持续集成和交付流水线的各个方面提供动力。本文将深入探讨 prow-images 生态系统的架构、组件和工作流程，特别关注它与 prow-configs 仓库和 manual-trigger 服务之间的关系。

什么是 prow-images？

prow-images 仓库是一个包含超过 35 个不同专用容器镜像的单体仓库（monorepo），每个镜像都设计用于处理 Prow 作业中的特定任务。这些镜像从基本实用工具（如 Git 操作）到复杂工具（如 E2E 测试框架、Kubernetes 集群配置和自动安全 PR 生成）应有尽有。

仓库结构

仓库中的每个组件都遵循一致的结构：

• 用于构建容器镜像的 Dockerfile
• 跟踪当前版本的 VERSION 文件（例如 v0.0.1）
• 包含基于 Go 的主应用程序的 entrypoint 目录
• 组件特定的 README 文档

根目录的 Makefile 负责协调所有镜像的构建和推送到中央镜像仓库 hub.tess.io/prowimages/。

核心组件

让我们深入了解组成这个生态系统的一些关键组件：

1. CI Generator - 配置自动化引擎

CI Generator 是生态系统中最关键的组件之一。它从简化的清单文件自动生成 Prow 作业规范。

主要特性：

• 从 prow-configs 仓库读取 .manifest 文件
• 支持多种作业生成类型：Build 和 UnitTest
• 自动生成 presubmit 和 postsubmit 作业配置
• 处理与 Kaniko 集成的复杂构建场景

工作原理：

1. 开发者在 prow-configs 中的仓库作业目录中创建 ci.manifest 文件
2. CI Generator 读取这些清单文件并生成完整的 Prow 作业 YAML 规范
3. 生成的文件会自动标记头部信息：”此文件由 ci generator 自动生成，请勿手动编辑”
4. 作业可以配置不同的触发器：PR 时 (onPr)、标签时 (onTag)，支持正则表达式模式

清单示例片段：

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16

tess/maintenance:
  - jobGenType: Build
    name: build-maintenance-controller
    branch: master
    dockerFile: Dockerfile
    versionFile: VERSION
    buildTime: kaniko
    targets:
      - onPr:
          imageTags:
            - hub.tess.io/maintenance/maintenance-controller:pr-${PULL_NUMBER}
      - onTag:
          tagRegex:
            - ^v(\d)+\.(\d)+\.(\d)+
          imageTags:
            - hub.tess.io/maintenance/maintenance-controller:${PULL_BASE_REF}

2. Kaniko - 安全的容器构建

Kaniko 镜像包装器提供了一种在 Kubernetes Pod 中安全构建容器镜像的方式，无需访问 Docker 守护进程。

功能：

• 支持可配置深度的 Git 仓库克隆
• 支持 git-crypt 加密仓库
• 多个目标镜像仓库
• 构建参数和标签
• 镜像仓库镜像支持
• TLS 验证选项
• 自动向 GitHub PR 发送构建结果评论
• 构建后命令执行

在 Prow 作业中的使用模式：

1
2
3
4
5
6
7
8

spec:
  containers:
  - image: hub.tess.io/prowimages/kaniko:latest
    args:
    - --dockerfile=Dockerfile
    - --context=/workspace/repo
    - --destination=hub.tess.io/myapp:${PULL_NUMBER}
    - --build-arg=VERSION=${VERSION}

3. Kind - Docker 中的 Kubernetes 测试环境

Kind 镜像能够在 CI 流水线中创建临时 Kubernetes 集群用于 E2E 测试。

特性：

• 创建隔离的 Kubernetes 集群
• 支持多个 Kubernetes 版本（1.20、1.32、1.34）
• 与上游 Kubernetes 补丁集成
• 可脚本化的集群配置
• 自动清理

4. Auto Security PR - 自动化 RBAC 管理

这个专用工具自动化创建跨多个集群的安全相关 RBAC 资源的拉取请求。

工作流程：

1. 在 YAML 中定义 RBAC 资源（ClusterRoles、ServiceAccounts、ClusterRoleBindings）
2. 指定作用域：fcp、cluster、tessAppsAZ、tessNetAZ 或 tessMasterAZ
3. 针对特定集群或使用 all: true 针对作用域中的所有集群
4. 该工具生成并提交 PR 到 sig-security 仓库

使用示例：

1
2
3
4
5
6
7
8
9
10

clusterRoles:
- metadata:
    name: cluster-role-1
  rules:
  - apiGroups: [""]
    resources: ["pods"]
    verbs: ["get", "list"]
  scope:
    cluster:
      all: true

5. Auto Approval/Validation - PR 自动化

这些组件处理拉取请求的自动批准和验证：

• Auto Approval：当特定文件包含某些键值对时自动批准 PR
• Auto Validation：验证 PR 更改的不可变性和 Kubernetes 对象的正确性

6. E2E 测试套件

多个 E2E 测试镜像提供全面的测试能力：

• e2e：通用 E2E 测试的基础镜像
• fd-e2e：专门用于功能开发 E2E 测试
• tessci：用于 E2E 测试的集群获取和管理工具

7. 构建工具集合

各种专业的构建工具：

• Bazel：多个版本（3.4.1、4.2.2、7.3.1、7.7.1）用于 Bazel 构建
• Go：标准化的 Golang 构建环境
• Ko：Go 容器镜像构建器
• Buildctl：BuildKit CLI 包装器
• Python：Python 运行时环境（3.8.15、3.14.0）

8. Git 操作

Git 相关实用工具：

• git：核心 Git 操作包装器
• git-sync-k8s-patches：同步 Kubernetes 补丁与上游
• make-commit：自动化提交创建

9. 开发工具

• helm-bot：自动化 Helm chart 管理和 PR 创建
• autotag：自动化版本标记
• clone-and-do：克隆仓库并执行命令（Bash、Make）
• gotestcover：Go 测试覆盖率分析和报告

10. 专用工具

• canirun：镜像漏洞扫描
• prow-config-validator：验证 Prow 配置文件
• prow-image-builder：构建此仓库中定义的镜像
• create-release：自动化发布创建
• release-notes：生成发布说明

三仓库生态系统

仓库 1：prow-images

用途：容器镜像定义和构建逻辑

位置：/Users/tashen/prow-images

内容：

• 35+ 个专用容器镜像定义
• Dockerfile 和 VERSION 文件
• 基于 Go 的入口应用程序
• 通过 Makefile 进行构建编排
• 公共 Go 库（git 实用工具、清单处理）

构建过程：

1
2
3
4
5
6
7
8

# 构建所有镜像
make image

# 推送所有镜像到镜像仓库
make push

# 构建特定镜像
make image-kaniko

镜像仓库：所有镜像都推送到 hub.tess.io/prowimages/

仓库 2：prow-configs

用途：Prow 作业配置和 CI/CD 流水线定义

位置：/Users/tashen/prow-configs

结构：

1
2
3
4
5
6
7
8
9

prow-configs/
├── jobs/
│   ├── ebaytess/       # 组织特定的作业
│   ├── ebayistio/
│   ├── ESTOOLS/
│   └── ...
├── prow-configs/       # Prow 配置文件
├── hack/               # 辅助脚本
└── Makefile

关键文件：

• ci.manifest：CI Generator 处理的简化作业定义
• *.yaml：自动生成的 Prow 作业规范
• presubmit、postsubmit 和 periodic 作业的配置

工作流程：

1. 开发者创建/修改 ci.manifest 文件
2. 运行 make jobgen 生成作业规范
3. CI 验证生成的配置
4. 合并后，Prow 加载新配置

仓库 3：test-infra/prow/cmd/manual-trigger

用途：手动作业触发服务

位置：/Users/tashen/test-infra/prow/cmd/manual-trigger

功能：HTTP 服务，允许在没有 GitHub 事件的情况下触发 Prow 作业

完整工作流程

场景 1：添加新的构建作业

1. 开发者操作（prow-configs）：

   1 2 3 4 5 6 7 8 9 10 11 12

   # 在 prow-configs/jobs/myorg/myrepo/ci.manifest myorg/myrepo: - jobGenType: Build name: build-myapp branch: main dockerFile: Dockerfile versionFile: VERSION buildTime: kaniko targets: - onPr: imageTags: - hub.tess.io/myorg/myapp:pr-${PULL_NUMBER}

2. CI 生成：

   • CI Generator（来自 prow-images）读取清单
   • 生成完整的 Prow 作业 YAML 规范
   • 创建在 PR 上运行的 presubmit 作业
   • 配置来自 prow-images 的 Kaniko 镜像作为作业容器

3. 作业执行：

   • 当创建 PR 时，Prow 触发 presubmit 作业
   • Kaniko 镜像克隆仓库
   • 使用指定的 Dockerfile 构建容器
   • 推送到镜像仓库，标签为 pr-${PULL_NUMBER}
   • 将构建状态发布回 GitHub PR

场景 2：手动运行 E2E 测试

1. 开发者需要测试特定提交：

   1 2 3 4 5 6 7 8 9 10

   curl -X POST "http://manual-trigger.tessprow/manual-trigger" \ -H "Content-Type: application/json" \ -d '{ "org": "tess", "repo": "tessops", "base_ref": "feature-branch", "prowtype": "postsubmit", "prowjob": "sddz-e2e-k8s-1.32", "user": "developer-name" }'

2. Manual Trigger 服务：

   • 验证请求参数
   • 在来自 prow-configs 的 Prow 配置中查找作业
   • 在 Kubernetes 中创建 ProwJob 自定义资源
   • 设置 AUTHOR=developer-name 环境变量

3. 作业执行：

   • Prow 调度器拾取 ProwJob
   • 使用来自 prow-images 的 e2e 镜像
   • 配置 Kind 集群（使用来自 prow-images 的 kind 镜像）
   • 运行 E2E 测试
   • 报告结果（但不会发布到 GitHub，因为是手动触发）

场景 3：自动生成的安全 PR

1. 安全团队操作：

   • 在 YAML 文件中定义 RBAC 资源
   • 指定目标集群（集群 11、22 或所有集群）

2. 自动化工作流程：

   • Prow periodic 作业触发 auto-security-pr 镜像
   • 镜像扫描集群配置
   • 为每个集群生成适当的 RBAC 清单
   • 创建 PR 到 sig-security 仓库
   • Auto-validation 作业验证 PR
   • 如果满足条件，Auto-approval 作业批准

场景 4：构建和更新 prow-images 本身

1. 开发者更新 Kaniko 镜像：

   • 修改 /Users/tashen/prow-images/kaniko/entrypoint/main.go
   • 在 /Users/tashen/prow-images/kaniko/VERSION 中将版本提升到 v0.0.2

2. 本地构建：

   1 2 3

   cd /Users/tashen/prow-images make image-kaniko make push-kaniko

3. CI 集成：

   • prow-images 的 PR 触发 presubmit 作业
   • prow-image-builder 作业构建所有修改的镜像
   • 测试验证新镜像
   • 合并后，postsubmit 作业构建并推送到镜像仓库

4. Prow-configs 更新：

   • prow-configs 中引用 Kaniko 镜像的作业现在可以使用新版本
   • 在清单文件中更新镜像标签或使用 latest 标签自动更新

关键集成点

1. 镜像仓库作为中心枢纽

所有组件通过 hub.tess.io 的中央镜像仓库进行通信：

• prow-images 构建并推送到 hub.tess.io/prowimages/
• prow-configs 从此镜像仓库引用镜像
• 应用程序镜像构建并推送到组织特定的命名空间

2. 清单驱动的配置

CI Generator 在简单清单和复杂 Prow 配置之间建立桥梁：

• 开发者编写简单的 .manifest 文件
• CI Generator（来自 prow-images）将它们转换为完整的作业规范
• Prow（由 prow-configs 配置）执行这些作业
• 作业使用来自 prow-images 的镜像

3. Git 作为真相来源

所有三个仓库都使用 Git 进行版本控制和触发：

• prow-images 的更改触发镜像重建
• prow-configs 的更改触发配置验证
• 应用程序仓库的更改触发在 prow-configs 中定义的作业
• Manual-trigger 在需要时提供带外触发

4. Kubernetes 原生架构

一切都在 Kubernetes 上运行：

• Prow 组件作为 Kubernetes 服务运行
• ProwJob 是 Kubernetes 自定义资源
• 所有作业执行都在 Kubernetes Pod 中进行
• 来自 prow-images 的镜像提供 Pod 容器

高级功能

版本管理

prow-images 中的每个镜像都维护一个 VERSION 文件：

1

v0.0.1

这使得：

• 工具的语义版本控制
• 可重现的构建
• 回滚能力
• CI 作业中的镜像标签生成

多触发器支持

作业可以配置在不同的触发器上运行：

• onPr：在拉取请求时运行
• onTag：当推送特定标签模式时运行
• Manual：通过 manual-trigger 服务触发
• Periodic：定期执行

安全和认证

• Git 操作使用基于令牌的认证
• 镜像支持用于加密仓库的 git-crypt
• 通过 Kubernetes Secret 进行镜像仓库认证
• Prow 作业执行权限的 RBAC

可观测性

• 在端口 9090 上暴露 Prometheus 指标
• 所有镜像中的详细日志
• PR 作业的 GitHub 状态报告
• 在 Prow UI（deck）中可见 ProwJob 状态

最佳实践

prow-images 开发

1. 版本提升：进行更改时始终更新 VERSION 文件
2. 测试：推送前在本地测试镜像
3. 文档：对重大更改更新组件 README
4. 向后兼容性：更改接口时考虑现有用户

prow-configs 管理

1. 使用清单：优先使用 .manifest 文件而不是手写作业 YAML
2. 本地验证：提交 PR 前运行 make jobgen
3. 测试作业：合并前使用 manual-trigger 测试新作业
4. 避免手动编辑：永远不要直接编辑自动生成的文件

手动触发

1. 使用正确的类型：选择 presubmit 用于 PR 测试，postsubmit 用于分支测试
2. 设置用户：始终提供 user 参数以进行审计跟踪
3. 监控作业：在 Prow UI 或通过 kubectl 检查作业状态
4. 清理：应该调查并清理失败的作业

常见工作流程总结

向 prow-images 添加新工具

1
2
3
4
5
6
7
8

1. 创建目录：prow-images/mytool/
2. 添加 Dockerfile
3. 添加 VERSION 文件
4. 实现 entrypoint/main.go
5. 更新 Makefile 添加构建目标
6. 构建：make image-mytool
7. 推送：make push-mytool
8. 在 prow-configs 作业定义中使用

向 prow-configs 添加新作业

1
2
3
4
5
6
7

1. 创建/编辑 ci.manifest 文件
2. 使用 jobGenType、name、triggers 定义作业
3. 运行：make jobgen
4. 验证生成的 YAML
5. 创建 PR 到 prow-configs
6. CI 验证配置
7. 合并 → Prow 加载新作业

手动触发作业

1
2
3
4
5
6

1. 从 prow-configs 查找作业名称
2. 识别 org、repo、branch
3. POST 到 manual-trigger 服务
4. 在响应中接收 job_name
5. 监控：kubectl get prowjobs -n tessprow | grep <job_name>
6. 在 Prow UI 中查看日志

架构图（概念）

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50

┌─────────────────────────────────────────────────────────┐
│                     GitHub 事件                          │
│              (创建 PR、推送提交)                         │
└────────────────────┬────────────────────────────────────┘
                     │
                     ▼
┌─────────────────────────────────────────────────────────┐
│                   Prow 控制器                            │
│        (从 prow-configs 仓库读取配置)                    │
└─────────┬──────────────────────────────────────┬────────┘
          │                                       │
          │ 触发 ProwJob                          │
          │                                       │
          ▼                                       ▼
┌──────────────────────┐              ┌──────────────────────┐
│  Manual Trigger      │              │   定期作业           │
│  (HTTP 服务)         │              │   (Periodic)         │
└─────────┬────────────┘              └──────────┬───────────┘
          │                                       │
          │ 创建 ProwJob                          │
          │                                       │
          ▼                                       ▼
┌─────────────────────────────────────────────────────────┐
│              Kubernetes ProwJob 资源                     │
└─────────┬───────────────────────────────────────────────┘
          │
          │ 生成 Pod
          │
          ▼
┌─────────────────────────────────────────────────────────┐
│                容器执行                                  │
│    (使用来自 prow-images 仓库的镜像)                     │
│                                                          │
│  ┌─────────────┐  ┌─────────────┐  ┌─────────────┐    │
│  │   Kaniko    │  │    Kind     │  │     E2E     │    │
│  │   镜像      │  │   镜像      │  │    镜像     │    │
│  └─────────────┘  └─────────────┘  └─────────────┘    │
│                                                          │
│  ┌─────────────┐  ┌─────────────┐  ┌─────────────┐    │
│  │     Git     │  │  CI-Gen     │  │  Auto-Sec   │    │
│  │   镜像      │  │   镜像      │  │    镜像     │    │
│  └─────────────┘  └─────────────┘  └─────────────┘    │
└─────────┬───────────────────────────────────────────────┘
          │
          │ 结果
          │
          ▼
┌─────────────────────────────────────────────────────────┐
│               GitHub 状态 / Prow UI                      │
└─────────────────────────────────────────────────────────┘

故障排除指南

镜像构建失败

问题：make image-kaniko 失败

• 检查 Dockerfile 语法
• 验证基础镜像可用性
• 确保依赖项已被 vendor
• 检查 Docker 守护进程是否运行

作业不运行

问题：Prow 作业在 PR 上不触发

• 验证 prow-configs 中是否启用了 trigger 插件
• 检查作业名称在配置中是否匹配
• 确保 prow-configs release 对象状态为 Succeeded
• 验证清单文件是否已正确处理

Manual Trigger 错误

问题：”配置中未找到作业 X”

• 验证确切的作业名称（区分大小写）
• 检查 org/repo 组合是否正确
• 确保已部署最新的 prow-configs
• 验证作业类型匹配（presubmit/postsubmit）

镜像版本不匹配

问题：作业使用旧镜像版本

• 检查作业规范中的镜像标签
• 验证新镜像是否已推送到镜像仓库
• 通过删除 :latest 标签强制拉取
• 检查 imagePullPolicy 是否设置正确

结论

prow-images 生态系统代表了基于 Kubernetes 和 Prow 构建的全面的生产级 CI/CD 基础设施。三仓库架构提供了清晰的关注点分离：

• prow-images：工具和实用程序（”如何做”）
• prow-configs：作业定义和流水线（”做什么”）
• manual-trigger：带外控制平面（”何时做”）

这些组件共同实现了：

• 自动化构建和测试
• 安全的容器镜像创建
• 临时测试环境
• 自动化安全管理
• 灵活的作业触发
• 企业级规模的可扩展 CI/CD

通过 CI Generator 的清单驱动方法显著降低了 Prow 配置的复杂性，使开发者能够轻松使用，同时保持 Kubernetes 原生 CI/CD 的全部功能。

无论您是构建新工具、添加测试作业还是手动触发部署，理解这三个仓库如何交互是有效使用这个强大 CI/CD 平台的关键。

延伸阅读

• Prow 官方文档
• Kubernetes 测试基础设施
• Kaniko 项目
• Kind - Docker 中的 Kubernetes

最后更新：2026 年 4 月 8 日

存储 IO 性能问题是生产环境中最常见也最棘手的问题之一。数据库响应变慢、应用延迟飙升、批处理任务超时，背后往往隐藏着复杂的 IO 瓶颈。本文从内核源码层面出发，系统梳理 Linux 存储性能的监控、分析与调优方法，覆盖从 iostat 到 eBPF、从 blktrace 到 ftrace 的完整工具链。