手写 vLLM 分页 KV Cache(一):先从 Continuous Batching 调度器看全局

手写 vLLM 分页 KV Cache(一):先从 Continuous Batching 调度器看全局

系列导读 :本系列采用 Top-Down(自顶向下) 的顺序拆解 vLLM 核心机制------本篇先从最上层的调度器切入 ,搞清楚请求如何流转、显存不足时如何抢占重算、以及多线程下如何保证并发安全;后续两篇再向下深潜到底层的物理块切分(BlockAllocator)与共享写时复制(CoW / Prefix Cache)。

全文代码来自我的学习仓库 learn-vllm-paged-kvcache:纯 C++17、零第三方依赖、无 GPU,cmake --build 之后 ctest 就能把本文每个结论跑一遍(61 个单测 + 2 个压力测试,覆盖 Linux/GCC、Windows/MSVC、ThreadSanitizer 三套 CI)。 注:本项目为个人学习复现,与 vLLM 官方项目无关,不含其任何源代码。


0. 先说清楚要解决什么问题

假设显存池里只有 16 个物理块,4 个请求同时在跑。

静态批处理(Static Batching)的做法是:攒一个 batch,一起 prefill,一起 decode,直到最慢的那个生成结束才统一收工。这会带来三个直接浪费:

  • 显存空转:提前结束的请求占着物理块不放,整批结束前谁也用不了;
  • 排队高延迟:新来的请求只能干等下一批,哪怕此刻显存里明明有块空着;
  • 算力空转:为了凑成规整的张量形状,短序列必须做大量 padding。

连续批处理(Continuous Batching)把"批"从一个静态容器 变成一个每步重算的动态视图 :每个 step() 重新决定这一轮谁跑,请求一旦完成立刻释放显存、立刻让出槽位,新请求随时可以插进来。

调度器在每个 step() 里做的其实就是三件朴素的事:

动作 触发时机 本项目里的位置
准入(Admit) 新请求到达 / 显存有空间腾出 step() 阶段一、阶段三
抢占(Preempt) 运行中的请求本步写不下新 token step() 阶段二 → preempt()
退场(Retire) 生成长度达到上限 step() 阶段四

难的不是这三个词,难在三个工程问题:怎么保证抢占重算之后输出一字不差?怎么保证多线程下不丢唤醒、不发生数据竞争?怎么向自己证明没写错? 本文按这个顺序展开。


1. 调度器手里有什么(5 分钟建立心智模型)

在看 step() 之前,先对齐每个请求(Request)身上的核心元数据:

字段 用途
block_table 逻辑块号 → 物理块号(block_id)的映射表
slot_mapping 本步要写入的物理槽位号(每步重建,非历史累积)
all_tokens prompt + 已生成 token,抢占重算和前缀哈希都靠它
sequence_length 当前序列总长度
num_cached_blocks block_table 开头已命中/已注册前缀缓存的块数
max_new_tokens / num_generated_tokens 生成预算与当前进度

极简例子(理解后续判据只需这 4 行) : 设每个物理块固定存 BLOCK_SIZE = 16 个 token。某请求当前 sequence_length = 17,block_table = [3, 7]:

  • 前 16 个 token 填满了物理块 3,第 17 个 token 落在物理块 7 的 offset = 17 % 16 = 1 号槽位,因此 slot_mapping 就是 [7 * 16 + 1] = [113];
  • 当 sequence_length 涨到 32(offset == 0)时,物理块 7 彻底写满,下一步写入前必须申请一块新的物理块;
  • 若 sequence_length = 17 且物理块 7 的引用计数 ref_count > 1(说明正被其他请求通过 Prefix Cache 共享),写入前必须触发写时复制(CoW)------同样需要消耗 1 个新物理块。

整个系统的三层结构保持严格单向依赖:

flowchart LR S[&#34;Scheduler<br/>准入 / 抢占 / 组装 batch / 生命周期&#34;] M[&#34;BlockManager<br/>前缀哈希匹配与注册 / release&#34;] A[&#34;BlockAllocator<br/>free_list_ / ref_count&#34;] P[&#34;原语层<br/>prefill / append_slot / append_token&#34;] S --> M S --> P P --> M M --> A P --> A

Scheduler 只持有 BlockManager&,BlockManager 只持有 BlockAllocator*,没有反向回调,也没有 shared_ptr 循环引用纠缠。组件所有权全在调用方(测试或 demo 的栈作用域),析构函数只负责把后台线程安全收干净。

全文阅读地图 (scheduler.cpp 约 400 行,拆成三块):

  • 第 2--3 节(调度策略) :step() 四阶段状态机、抢占与重算语义;
  • 第 4--5 节(并发工程) :后台调度线程、promise 通知时序、无队列"翻牌"Worker 池;
  • 第 6 节(正确性验证):不变量检查与多组差分对拍。

2. step() 的四阶段推进

主循环骨架如下:

cpp 复制代码
void Scheduler::step()
{
    std::lock_guard<std::mutex> step_lock(step_mutex_); // 同一时刻只允许一个推进者
    BlockAllocator* allocator = manager_.get_allocator();
    const int num_blocks = allocator->num_blocks();

    std::vector<PendingCompletion> finished; // 本步完成的请求,锁外统一兑现
    // ① 过滤超限请求  ② 为运行中请求分配写入槽(不够则抢占)
    // ③ 准入等待请求  ④ 并行采样 + 状态落盘 + 锁外唤醒
}

step_mutex_ 保证"后台调度线程跑 run()"和"单元测试手动单步调 step()"不会同时推进状态------这是第 6 节单线程确定性测试的前提。

阶段一:先把"数学上永远装不下"的请求判死

cpp 复制代码
{
    std::unique_lock<std::mutex> l1(sched_mutex_);     // inbox_
    std::unique_lock<std::mutex> l2(pending_mutex_);   // pending_
    std::unique_lock<std::mutex> l3(waiting_mutex_);   // waiting_queue_
    while(!inbox_.empty())
    {
        auto it = inbox_.begin();
        int need = ((*it)->all_tokens.size() + (*it)->max_new_tokens + BLOCK_SIZE - 1) / BLOCK_SIZE;
        if(need > num_blocks - WATER_MARK)
        {
            (*it)->s = ReqState::ABORTED;               // 装不下,直接判死
            auto node = pending_.extract((*it)->arrival_id);
            if(!node.empty()) finished.push_back(std::move(node.mapped()));
            inbox_.erase(it);
            unfinished--;
            continue;
        }
        waiting_queue_.push_back(*it);
        inbox_.erase(it);
    }
}

这里的准入上限按最坏情况 估算:prompt + max_new_tokens 全部装下才放行,且额外保留 WATER_MARK = 4 个物理块作为安全水位线。

两个设计决策值得单独解释:

  1. 为什么一次判死,而不是"先放进去试试看"? 一个总长度超过整个显存池容量的请求,留在 waiting_queue_ 里只会永久卡死队首,把后面所有正常请求全部挡住(见阶段三的 FIFO 语义)。早判死早释放调用方,调用方拿到的 std::future 会在本步结束时立刻就绪,不会白等。
  2. 为什么标 ABORTED 而不是抛异常? add_request() 的接口契约只有一条:返回的 future 一定会就绪 。异常如果直接在后台调度线程里抛出,调用方根本接不到,只会触发 std::terminate。

代价也很坦白:这是偏保守的策略。如果某个请求把 max_new_tokens 设得极大,即便它实际生成 2 个 token 就会遇到 EOS 结束,也会在入口处被拒。生产级引擎通常会按当前空闲显存动态放宽或延迟重试,本项目为了消除一切复杂边界,选择了最不容易出错的硬上限。

阶段二:为每个运行中的请求"要一个写入槽"

can_append() 是这一步的唯一判据:当前步的新 token 有没有物理槽位可写。

cpp 复制代码
bool Scheduler::can_append(std::shared_ptr<Request> req)
{
    int offset = req->sequence_length % BLOCK_SIZE;
    bool needs_new;
    if(offset == 0 || req->block_table.empty())
        needs_new = true;                                     // 块已写满,要开新块
    else
        needs_new = manager_.get_allocator()
                        ->get_block(req->block_table.back()).ref_count > 1;  // 共享块,要 CoW
    return !needs_new || manager_.get_allocator()->num_free_blocks() >= 1;
}

它与 append_slot() 的三个执行分支严格一一对应:

sequence_length % 16 尾块 ref_count 本步写入动作 can_append 显存要求
0 --- 申请新物理块 free_blocks >= 1
!= 0 1 原地直接写 0(不消耗新块)
!= 0 > 1 CoW:申请新块并拷贝旧内容 free_blocks >= 1

于是阶段二的逻辑非常直接------"要不到槽位就抢占":

cpp 复制代码
bool preempted = false;
std::vector<std::shared_ptr<Request>> batch; // 本步真正要送去 decode 的请求

// 注:为突出主干逻辑,此处省略了与外部只读观测接口共享的队列锁,完整实现见仓库
for(size_t i = 0; i < running_queue_.size(); ++i)
{
    while(!can_append(running_queue_[i]))
    {
        preempt();
        preempted = true;
        if(i >= running_queue_.size()) break; // 受害者可能正是自己
    }
    if(i < running_queue_.size())
    {
        append_slot(manager_, *running_queue_[i]); // 就地分配或 CoW,生成唯一写入槽
        batch.push_back(running_queue_[i]);
    }
}

这里有一个极易写错的越界边界 :preempt() 抢占的是 running_queue_ 的队尾。如果当前正在检查的下标 i 恰好就是队尾(例如队列里只剩最后一个请求,且它自己需要新块但空闲块为 0),它会把自己移出 running_queue_,此时 running_queue_[i] 已经越界。因此 preempt() 之后必须立刻检查 i >= running_queue_.size(),否则就是未定义行为(UB)------这种边界单测很难想到,但随机压力测试几乎必中。

此外,batch 中收集的请求顺序与 running_queue_ 保持一致,方便阶段四采样完成后按下标一一回填。

阶段三:为什么是 break 而不是 continue

cpp 复制代码
if(!preempted) // 本步没发生抢占才准入新请求
{
    std::lock_guard<std::mutex> lock_w(waiting_mutex_);
    while(!waiting_queue_.empty())
    {
        auto req = waiting_queue_.front();
        int need = blocks_needed_for_prefill(req);
        if(need + WATER_MARK > allocator->num_free_blocks()) break; // ← 关键:break 而非 continue

        bool ok = prefill(req->all_tokens, *req, manager_);
        assert(ok);
        req->s = ReqState::RUNNING;
        waiting_queue_.pop_front();
        running_queue_.push_back(req);
        // 故意不放进 batch:prefill 刚把 prompt 灌完,下一步再进 decode
    }
}

为什么必须用 break? 假设等待队列里排着 [需要 8 块的大请求 A, 需要 2 块的小请求 B],当前显存只剩 3 块:

  • 如果用 continue,调度器会跳过 A、直接放 B 进来。等 B 跑完释放 2 块,池子里依然只有 3 块;而在这期间源源不断的新小请求还会继续填空隙。A 就会被彻底饿死------它需要一个 8 块的空闲窗口,但系统永远只给它留 3 块。
  • 用 break 则强制等待队列严格按 FIFO 顺序准入:队首的大请求过不去,后面的小请求就得老实排队。

这就是严格队首阻塞的全部意义:牺牲一点局部吞吐,换取绝不饿死任何请求的确定性公平。

为什么"本步发生过抢占就不收新请求"? 本步刚刚因为显存见底踢走了一个正在跑的请求,如果此刻又把新请求放进来,下一步极大概率再次触发抢占,把刚恢复的请求又踢出去,造成剧烈的"抢占抖动(Thrashing)"。等老请求真正跑完释放显存后再准入,系统稳得多。

再看一个算错一行就会引发断言崩溃的细节------blocks_needed_for_prefill():

cpp 复制代码
int Scheduler::blocks_needed_for_prefill(std::shared_ptr<Request> req)
{
    int total = (req->all_tokens.size() + BLOCK_SIZE - 1) / BLOCK_SIZE;
    auto match = manager_.match_prefix(req->all_tokens);

    int hit_live = 0; // 只有 ref_count > 0 的命中缓存块才算"免费"
    for(int id : match.cached_blocks)
        if(manager_.get_allocator()->get_block(id).ref_count > 0) hit_live++;

    return total - hit_live;
}

为什么命中的缓存块里还要区分 ref_count > 0 和 ref_count == 0?

  • ref_count > 0 :这块正被其他活跃序列持有,inc_ref 共享它不会消耗任何空闲块 → 算免费;
  • ref_count == 0 :这块虽然保留着历史哈希(已释放但尚未被覆盖复用),但它正躺在 free_list_ 里计入 num_free_blocks()。inc_ref 把它"复活"时必须把它从空闲链表摘除------它实打实地消耗 1 个空闲块 → 必须计入 need。

如果漏掉 ref_count > 0 这个过滤条件,在显存临界水位就会出现"准入检查通过、实际 prefill 分配失败"的 Bug。阶段三的 assert(ok) 正是用来兜底抓这种算账偏差的。

阶段四:先算,再改,最后锁外唤醒

cpp 复制代码
std::vector<int> new_tokens;
sample_batch_parallel(batch, new_tokens); // 1. 纯计算:不持任何锁

{
    std::unique_lock<std::mutex> l1(pending_mutex_);
    std::unique_lock<std::mutex> l2(running_mutex_);
    for(size_t i = 0; i < batch.size(); ++i)
    {
        append_token(manager_, *batch[i], new_tokens[i]); // 2. 写状态:写满整块则注册前缀哈希
        batch[i]->num_generated_tokens++;

        if(batch[i]->num_generated_tokens >= batch[i]->max_new_tokens)
        {
            batch[i]->s = ReqState::FINISHED;
            manager_.release(*batch[i]);                  // 物理块全部 dec_ref
            auto it = std::find(running_queue_.begin(), running_queue_.end(), batch[i]);
            if(it != running_queue_.end()) running_queue_.erase(it);
            unfinished--;
            auto node = pending_.extract(batch[i]->arrival_id);
            if(!node.empty()) finished.push_back(std::move(node.mapped()));
        }
    }
}

++num_steps_;
if(step_hook_) step_hook_(*this);                     // 3. 不变量检查:此时无任何并发修改

for(auto& pc : finished) pc.done.set_value();         // 4. 锁外兑现 promise
if(!finished.empty() && unfinished.load() == 0) sched_cv_.notify_all();

这四步的先后顺序每一条都有并发原因,第 4 节会逐条拆解。先记住核心口诀:计算不持锁、改状态持锁、hook 在兑现前、唤醒在最后且不持锁。


3. 抢占机制:抢谁、抢完怎么办

cpp 复制代码
void Scheduler::preempt()
{
    auto victim = running_queue_.back();
    // 硬前提:被抢的请求必须能完整重算,否则就是逻辑 bug
    assert(static_cast<int>(victim->all_tokens.size()) == victim->sequence_length);

    manager_.release(*victim);         // 块全部 dec_ref,归还进 free_list_
    victim->s = ReqState::WAITING;
    running_queue_.pop_back();
    waiting_queue_.push_front(victim); // 插到等待队列最前面,下次优先恢复
    ++num_preemptions_;
}

为什么抢队尾,而不是"挑块最多的抢"?

running_queue_ 按准入时间从早到晚排列,队尾永远是最晚进来的请求。抢队尾有两个好处:

  1. 它跑过的 decode 步数最少,丢弃的计算进度代价最小;
  2. 早进来的老请求能稳定推进直到退场,不会因为新请求不断涌入而全部卡死。

抢占后使用 push_front 放回 waiting_queue_ 队首,保证被抢占的请求在下一轮显存富余时排在所有新请求前面优先恢复 ,避免同一个人被反复抢占导致饿死。这也是 vLLM v0 _preempt 中 RECOMPUTE 策略的同款取舍(细微差异在于 vLLM 会按原始到达时间戳重排等待队列,本项目简化为队首优先,完整对照见仓库 docs/VLLM_MAPPING.md)。

为什么选"释放 + 重算(Recompute)",而不是 Swap 回 CPU?

release() 执行后,受害者的 block_table 被清空、sequence_length 归零------但 all_tokens 完整保留 。等下次重新准入时,直接对 all_tokens 再跑一遍 prefill(),即可恢复全部 KV 状态。

抢占方案 显存占用 时间开销 工程复杂度
重算(本项目) 抢占后彻底归零 恢复时 O(len)O(\text{len}) O(len) 前向计算 低
Swap 到 CPU 需等量 CPU 内存缓冲 换出 + 换入两次 PCIe 拷贝 高(双池管理 + 异步状态机)

选择重算的核心原因有两个:

  1. 本项目没有真实 GPU,KV 内容是确定性生成的整数模拟,做内存拷贝没有意义;
  2. 只有走重算路径,才能强力验证**"抢占释放 → 重新分配 → 重建前缀哈希"整条链路没有任何状态残留**------只要 all_tokens.size() == sequence_length 这个不变量成立,重算就一定能还原出与不抢占时一模一样的 token 序列。

同时,这个逻辑直接钉死了第 4 条系统不变量:处于 WAITING(被抢占)状态的请求,其 block_table 必须为空 。如果非空,说明 release() 漏还了块,就是显存泄漏。


4. 从"单步 step()"到"后台调度线程"

如果只写到第 3 节,它只是一个需要外部手动 while 驱动的状态机。要变成真正异步的推理引擎,需要独立的后台线程:

cpp 复制代码
void Scheduler::run()
{
    while(true)
    {
        {
            std::unique_lock<std::mutex> lk(sched_mutex_);
            sched_cv_.wait(lk, [&]{ return stop_flag_.load() || unfinished.load() > 0; });
            if(stop_flag_.load()) break;
        }   // 故意在此释放锁:step() 阶段一需要重新获取 sched_mutex_
        step();
    }
    abort_all_pending(); // 排空未完成请求并释放其占用的物理块
}

为什么不能靠"看队列空不空"判断有没有活干?

这是我在开发第 6 天踩过的坑。直觉上很容易写出 while (!waiting_queue_.empty() || !running_queue_.empty()),但中间存在多个危险的时间窗口:

  • 请求刚被 pop 出 inbox_,还没 push 进 waiting_queue_;
  • 阶段三刚把请求从 waiting_queue_ 弹出,还没塞进 running_queue_。

在这些微秒级窗口里,所有队列都可能是空的,但系统明明还有活要干。队列短暂为空 ≠\neq = 任务全部完成。

因此必须引入一个独立的原子计数器 std::atomic<int> unfinished:add_request() 入队时 ++,请求进入 FINISHED 或 ABORTED 终态时 --。它是判断系统是否空闲的唯一真相。

完成通知机制:promise + pending_ 映射表

cpp 复制代码
std::future<void> Scheduler::add_request(std::shared_ptr<Request> req)
{
    if(stop_flag_.load() || req->all_tokens.empty() || req->max_new_tokens <= 0)
    { /* 标为 ABORTED,返回一个立刻就绪的 future */ }

    std::unique_lock<std::mutex> lock1(sched_mutex_);
    std::unique_lock<std::mutex> lock2(pending_mutex_);

    int id = next_arrival_id_++;
    req->arrival_id = id;
    auto [it, ok] = pending_.try_emplace(id);   // arrival_id → promise
    inbox_.push_back(req);
    unfinished++;
    sched_cv_.notify_all();
    return it->second.done.get_future();
}

pending_ 维护 arrival_id → promise 的映射,请求结束时通过 pending_.extract() 原子摘除,保证每个请求的完成事件只会被兑现一次。

两条用 CI 血泪换来的同步铁律

铁律一:promise::set_value() 必须在所有互斥锁之外执行

业务线程在 future.wait() 返回后的下一微秒,极有可能立刻调用 add_request() 提交下一条请求。如果你在持有 pending_mutex_ 或 running_mutex_ 时调用 set_value(),被唤醒的线程会立刻撞上同一把锁------自己把自己堵死在临界区外 。把已完成条目先移入局部 finished 数组,等锁全部析构后再统一 set_value(),彻底消除锁竞争。

铁律二:promise::set_value() 必须在 step_hook_ 之后执行

这条是 CI 里的 ThreadSanitizer(TSan) 抓出来的真实数据竞争(对应提交 fix:修复数据竞争导致的CI不通过):

  • step_hook_ 会在每个 step() 结尾扫描所有请求做不变量校验;
  • 如果先 set_value() 再跑 step_hook_,外部测试线程在 future.get() 返回后立刻读取 req->num_generated_tokens 或 req->s,而后台调度线程同时 正在 step_hook_ 里读取同一个 req 的字段------TSan 直接报 Data Race;
  • 把 step_hook_ 放在 set_value() 之前,就建立了一条严格的 happens-before 关系:本步的所有状态修改与统计校验,一定发生在调用方 wait() 返回之前。

停机流程:两种语义,一条销毁顺序

cpp 复制代码
void Scheduler::stop(bool drain)
{
    {
        std::unique_lock<std::mutex> lk(sched_mutex_);
        if(!stop_flag_.load())
        {
            if(drain && sched_thread_.joinable())
                sched_cv_.wait(lk, [&]{ return unfinished.load() == 0; }); // 优雅排空
            stop_flag_ = true;
        }
    }
    sched_cv_.notify_all();

    // 销毁顺序不能反:调度线程可能正阻塞在 done_cv_ 上等待 Worker 收工
    if(sched_thread_.joinable()) sched_thread_.join();
    stop_pool();
    abort_all_pending(); // 释放运行中/等待中请求的物理块,并兑现所有剩余 promise
}

Scheduler::~Scheduler() { stop(true); }
  • stop(true):等所有已提交请求跑完再停机(优雅退出);
  • stop(false):立刻中止,强制回收所有未完成请求占用的物理块、标记 ABORTED 并兑现所有 future,确保没有任何调用方永久阻塞。

线程销毁顺序不可颠倒 :必须先 join 调度线程,再销毁 Worker 池。如果先停 Worker 池,正在执行 step() 阶段四的调度线程可能会永久卡死在 done_cv_ 上等不到收工信号,导致 sched_thread_.join() 死锁。

锁层级纪律(严格单向加锁,严禁反向)

互斥量 保护范围
sched_mutex_ inbox_、next_arrival_id_、stop_flag_、sched_cv_
pending_mutex_ pending_(arrival_id → promise 映射表)
waiting_mutex_ / running_mutex_ waiting_queue_ / running_queue_ 的外部只读观察
step_mutex_ 整个 step() 单步推进过程
pool_mutex_ Worker 池状态:round_、remaining_、cur_*、worker_error_
alloc_mutex_ free_list_、ref_count(粒度最细,仅在分配器内部获取)

全局加锁顺序固定为:sched_mutex_ → pending_mutex_ → waiting_mutex_ / running_mutex_,任何路径绝不反向嵌套,从根源杜绝 AB-BA 死锁。


5. Worker 池:用"轮次翻牌"代替任务队列

走到阶段四时,batch 里的 N 个请求各自独立采样下一个 token,完全没有共享写操作,天然适合并行。

常规线程池的做法是"任务队列 + 哨兵退出":主线程每步 push N 个任务,停机时 push N 个哨兵。本项目没有引入任务队列,而是采用**轮次翻牌(Epoch/Round Flip)**协议:

cpp 复制代码
// 主线程(sample_batch_parallel 内)
worker_error_ = nullptr;
remaining_ = num_workers_;   // 必须在 notify 之前设好活跃 Worker 数
++round_;                    // 翻牌:round_ 递增,所有 Worker 立刻知道新一轮开始
task_cv_.notify_all();
done_cv_.wait(lock, [&]{ return remaining_ == 0; });   // 等本轮全部收工

// Worker 线程(worker_loop 内,持有 pool_mutex_)
task_cv_.wait(lock, [&]{ return workers_stop_.load() || round_ != seen; });
if(round_ == seen) return;   // 醒来且轮次未变,只可能是停机信号
seen = round_;
batch = cur_batch_;          // 以下切片边界必须在锁内一次性快照完
out   = cur_out_;
begin = cur_begin_[id];
end   = cur_end_[id];        // 出锁后主线程可能已进入下一轮

// 无锁并行计算(持锁计算会退化成串行)
for(size_t i = begin; batch && out && i < end; ++i)
    (*out)[i] = run_sample(*(*batch)[i]);

{
    std::lock_guard<std::mutex> lk(pool_mutex_);
    if(--remaining_ == 0) done_cv_.notify_one();
}

为什么翻牌协议比任务队列更适合推理步进?

  1. 每个 step() 的切片是静态已知的,直接分发 [begin, end) 下标即可,省去每步 N 次堆内存分配与队列入队/出队开销;
  2. seen != round_ 语义极其干净,不会出现"哨兵被某个线程多吃掉一个导致其他线程退不出"的经典 Bug;
  3. 停机协议零额外状态:置位 workers_stop_ 并广播,Worker 醒来发现 round_ == seen 直接退出。

实现翻牌协议必踩的三个坑

  1. 空批次严禁翻牌 :某一步可能只有请求入队或全部完成,batch.empty() == true。如果此时照样 ++round_,remaining_ 却没有重置或无人递减,主线程就会永久死等在 done_cv_ 上。因此入口必须早退:

    cpp 复制代码
    out.assign(batch.size(), 0);
    if(batch.empty()) return; // 空批次直接返回,绝不翻牌
  2. 分配到空区间的 Worker 也必须递减 remaining_ : 当请求数少于线程数时(例如 3 个请求、8 个 Worker),后 5 个 Worker 分到的是 [0, 0) 空区间。它们虽然不执行循环体,但必须走完 --remaining_ ,否则主线程永远等不到 0(对应单测 test_pool_more_workers_than_requests)。

  3. 跨线程异常捕获与重抛 :Worker 内部如果抛出异常不捕获,会直接导致整个进程 std::terminate。必须用 std::exception_ptr 接住第一个异常,等本轮全部收工后在主线程栈上 std::rethrow_exception(worker_error_),把异常语义原封不动还给调用方。

已知短板:静态分片的长尾效应

目前按 n / num_workers 静态均分下标,如果某个请求模拟计算耗时较长,其他 Worker 干完只能空等。更优解是改用共享原子游标(std::atomic<size_t> next_idx) ,每个 Worker 循环 fetch_add(1) 动态领任务。这一项已列入仓库 Roadmap------在教学复现阶段,先把同步协议写得清晰可验证,远比过早优化负载均衡重要。


6. 怎么向自己证明没写错

多线程 + 引用计数 + 抢占重算,靠"肉眼走读代码"几乎不可能保证没有隐藏泄漏或竞态。本项目搭建了三层自动化验证,全部集成在 ctest 中。

第一层:每个 step() 结尾强制校验四条全局不变量

通过 set_step_hook() 把 check_invariants() 挂载到每个 step() 的末尾:

cpp 复制代码
inline void check_invariants(const Scheduler& sched, const BlockAllocator& allocator)
{
    // 活跃请求 = RUNNING ∪ WAITING
    // 遍历所有活跃请求的 block_table,统计每个物理块实际被引用的次数 expected_ref[]
    // ① 物理块记录的 ref_count == expected_ref[block_id]
    // ② ref_count == 0 的物理块总数 == allocator.free_list_.size()
    // ③ 所有 RUNNING 请求:block_table.size() == ceil(sequence_length / 16)
    // ④ 所有 WAITING 请求:block_table.empty() 必须为 true
}
不变量 专抓哪类致命 Bug
① ref_count 严格守恒 重复释放(计数变负)或共享时漏调 inc_ref
② 零引用块数 == 空闲链表长度 显存泄漏(块没还进 free_list_)或双重认领(块既在自由链表又被请求持有)
③ 运行中请求表长匹配 append_slot 与 append_token 步调错位
④ 被抢占请求块表为空 preempt() 释放路径遗漏物理块

第二层:两组"差分对拍(Differential Testing)"

  1. 单线程 vs 多线程对拍 :固定同一批请求和采样器种子,分别以 num_workers = 1 / 2 / 4 运行,断言每个请求的 all_tokens 逐个元素完全一致 (test_pool_output_identical),证明并行化没有引入任何非确定性副作用。

  2. 大池(零抢占)vs 小池(高频抢占)对拍 :同一份随机负载,分别丢进 4096 块大池(永不抢占) 和 11~20 块小池(频繁触发抢占与重算) :

    cpp 复制代码
    CHECK(large.num_preemptions == 0);                          // 大池确认零抢占
    CHECK(small_mt.generated_tokens == small.generated_tokens); // 多线程结果一致
    for(const auto& kv : small.generated_tokens)                  // 抢占重算后结果一字不差
        CHECK(kv.second == large.generated_tokens.at(kv.first));

    这是整套调度器最核心的正确性证明:无论中间被抢占踢出多少次、重新 prefill 多少次,最终生成的 token 序列与显存无限大时完全一致。

第三层:暴力和异常路径的"零泄漏停机"测试

cpp 复制代码
// test_thread_stop_without_drain_notifies_all
for(int i = 0; i < 50; ++i) futures.push_back(sched.add_request(make_req(...)));
sched.stop(false); // 不等排空,强行立刻停机
// 断言:50 个 future 全部在 5 秒内就绪,状态均为 FINISHED 或 ABORTED
EXPECT_EQ(alloc.num_free_blocks(), 16); // 所有物理块必须 100% 归还

测试用例总览

测试套件 核心覆盖点 用例数
scheduler_test 准入控制、抢占队尾、优先恢复、抢占前后输出一致、超限请求中止 9
scheduler_thread_test 后台线程生命周期、多生产者并发提交、future 兑现时机、Worker 池异常与停机 10
random_pressure_test 随机负载下"大池/小池 × 串行/并行"四象限全量对拍 随机压测
thread_stress_test 多生产者 + 调度线程 + Worker 池高并发混合压测,每步校验四条不变量 随机压测
kvcache_phase1_3_test 底层分配器、写时复制(CoW)、前缀缓存命中(后续两篇展开) 42

7. 值得单独带走的三个工程经验

  1. break 而不是 continue :为了眼前的局部吞吐放过队首大请求,本质上是在制造饥饿。调度系统的公平性,往往要靠在关键位置主动变慢来换取。
  2. promise 必须在锁外、且在 step_hook_ 之后兑现:锁内唤醒会造成调用方自我阻塞;早于 hook 兑现会破坏 happens-before 语义引发数据竞争。同步原语的先后顺序本身就是协议的一部分。
  3. 空批次严禁翻牌 :设计任何"通知 / 等待"配对协议时,第一反应永远应该是问自己------"如果这一轮任务数为 0,等待方会怎么醒来?"

8. 坦诚的已知限制

完整清单见仓库 README,这里列出本教学实现刻意保留的边界:

  • 无 Chunked Prefill :prefill() 要求一次性装下整个 prompt;真实生产系统需要将超长 prompt 切块分步推进,否则单个万字输入就会阻塞整批 decode。
  • 无 Swap 路径 :ReqState::SWAPPED 仅为预留枚举,抢占策略目前只有 RECOMPUTE。
  • 保守准入 :按 prompt + max_new_tokens 最坏上界判死,会误拒实际提前遇到 EOS 的短输出请求。
  • blocks_needed_for_prefill() 存在重复哈希计算 :阶段三探路时调一次 match_prefix(),准入后 prefill() 内部又会重算一遍。如果队首大请求长期卡住,每个 step() 都会重复计算其前缀哈希;后续可通过传递匹配结果缓存优化,但会增加原语层接口耦合。
  • Worker 静态分片:长尾请求会导致部分 Worker 空等,Roadmap 中计划替换为原子游标动态抢占。
  • FIFO 空闲链表 :未引入 LRU 淘汰策略,块释放后依赖 has_hash / hash 双字段懒惰校验失效。
  • Release 模式下 assert 失效 :prefill 与 preempt 内部的不变量检查依赖 assert,工程化部署需替换为显式错误码或日志告警。

9. 仓库与系列导航

  • GitHub 仓库 :laoyeye831/learn-vllm-paged-kvcache(C++17 / 零依赖 / 61 单测 + 2 压测 / Linux GCC + Windows MSVC + TSan CI)
  • 2 秒快速体验 :编译后运行 ./build/kvcache_demo(支持 --paced 分步慢放),直观演示前缀缓存复用、CoW 写时复制、跨波次缓存复活以及抢占重算。
  • 源码对照与踩坑实录 :仓库内 docs/VLLM_MAPPING.md 逐符号对照了本项目与 vLLM 的实现差异;docs/DEVLOG.md 完整记录了 7 天开发中的错误判断与重构过程。

本系列后续规划(Top-Down 拆解)

  • 第一篇(本篇):全局调度器 ------ Continuous Batching、抢占重算、并发控制与差分验证
  • 第二篇(待更) :显存切分与物理块分配 ------ BlockAllocator、Block Table、Slot Mapping,以及为什么 vLLM v1 抛弃 std::list 改用 O(1)O(1) O(1) 双向指针链表
  • 第三篇(待更):显存共享与写时复制 ------ 引用计数生命周期、CoW 触发边界、以及块释放后的"惰性缓存复活"机制
相关推荐
徐小夕2 小时前
开源!我们用知识图谱重构了电子档案,AI 驱动全文智能关联
前端·vue.js·github
一条Go3 小时前
开源新生代雷达 · 第 13 期
github
一条Go3 小时前
Kubernetes 多集群接入:kubeconfig 只进不出
后端·架构·github
怕浪猫13 小时前
全球 3D 网络地球的实时通信节点,来看看这四种交互地球,满足你对物理互联网的所有好奇
面试·架构·github
wflynn15 小时前
GitHub 今日推荐|kiri:clone3 系统调用直达容器,2.5 毫秒启动无 runc 中间层
docker·rust·kubernetes·开源·github·containers
可乐ea16 小时前
MCP 和 CLI 差 42 倍:一次 GitHub 任务的上下文成本实测
人工智能·github·工具调用·ai智能体·openrouter·mcp协议·上下文优化
逛逛GitHub17 小时前
Claude 最新模型发布 1 周了,瞧瞧外网惊艳到震撼的玩法。
github
逛逛GitHub17 小时前
最近逛 GitHub 挑了 8 个刚开源、Star 涨得挺快的项目。
github
dong_junshuai18 小时前
每天一个开源项目#158 AG-UI:让Agent事件流接上前端状态
github