大模型推理框架 vllm 源码解析 一

很多人上手 vLLM 是被部署报错逼的：服务起不来、显存爆了、并发上不去，改参数只能在黑盒外试探。想真正搞明白，就得读源码，可一打开仓库几百个文件又不知道从哪下手。这篇不逐行讲代码，只给一张架构地图：先分清入口层、引擎层、调度与显存管理这几块各自负责什么，再给一条从哪读起、读到什么程度算过关的顺序。看完你至少能定位「这个问题大概出在哪一层」，为后面深读具体模块省下瞎翻的时间。

很多人上手 vLLM 是被部署报错逼的：服务起不来、显存爆了、并发上不去，改参数只能在黑盒外反复试探。想真正搞明白，就得读源码，可一打开仓库几百个文件又不知道从哪下手，翻两小时还在入口函数里绕。这篇不逐行讲代码，只给一张架构地图：先分清入口层、引擎层、调度与显存管理这几块各自负责什么。

然后给一条从哪读起、读到什么程度算过关的顺序。看完你至少能定位「这个问题大概出在哪一层」，为后面深读具体模块省下瞎翻的时间。注意这是第一篇，只搭骨架，不会带你逐行抠某个类的实现细节。

先想清楚读源码要解决什么问题

读源码之前先问自己一句：我到底在解什么题。不同动因对应的切入模块完全不同，盲目从 main 顺着读效率最低，读三天可能还没碰到你真正关心的那段逻辑。下面这张对照表可以帮你先给自己归个类。

• 读之前先跑通一次最小可用服务，留下可观测的日志和显存曲线当参照，否则你没法判断自己读对没有
• 把「我想让服务多扛几个并发」「我想知道显存被谁吃了」这类问题写成一句话贴在旁边，读到无关代码时能提醒自己跳开
• 准备一个能改一行就重启验证的环境，读代码不动手，理解通常是假的

整体分层：请求从进门到出 token 要过哪几关

把一次请求想象成走一条流水线：从进程外部进来，到最终吐出 token，中间要穿过几层职责不同的代码。你不需要记住每个文件名，但要知道每一层大致管什么，这样出问题时能先圈定范围，再去翻对应目录。

入口层

协议解析、参数校验、请求排队。请求被拒、参数报错、格式不合法，多半是这一层拦下的

引擎层

串起调度、批处理与执行，决定吞吐和延迟的基本形态，是整条链路的中枢

模型执行层

权重加载、前向计算、自定义算子落地，关心模型能不能跑对就看这里

显存与缓存层

KV 缓存分配、显存池管理，决定能同时扛多少请求，也是显存占用的主要来源

1. 打一个真实请求用最小的参数发一次请求，打开日志级别，让链路信息尽量完整地打出来。别一上来就压测，先看清楚单条请求长什么样
2. 把日志往分层上对把日志里的每一行归到上面四层中的某一层，哪一层缺日志，说明你还没看清它，或者它根本没被执行到
3. 画一张自己的图不要求好看，能标出请求在哪一层被接收、在哪一层被拆批、在哪一层碰到显存就够了。这张图后面每读一个模块都可以往上补

做完这一步你会有个具体感受：有些层你压根没打开过它的代码，却已经知道它存在。这正是架构地图的价值——先知道有这回事，再去读实现，心里不慌。

调度与 KV 缓存：vLLM 最值得先读的两块

如果只能先读两块，那就选调度和 KV 缓存。原因很直接：你日常感知到的「并发上不去」「显存吃紧」「延迟忽高忽低」，最终都会在这两块里找到解释。其他模块更多是锦上添花。

调度决定每个批次装哪些请求、什么时候抢占或换出。它是并发表现的真正来源，也是很多「为什么我的请求等了这么久才被处理」的答案所在。读的时候重点看状态流转和容量上限判断，不要陷进单个函数的实现细节里拔不出来。

• 关注请求的状态在几个阶段之间怎么迁移，什么条件触发抢占、什么条件触发放回队列
• 关注容量上限怎么算出来的、达到上限后是等待还是拒绝，这决定了服务的稳定边界
• 关注批次是怎么拼起来的，为什么有的请求会被塞进同一批、有的被拆出去
• 如果驱动你的是显存吃紧或吞吐掉底，先读这两块再去看别的，顺序反了会白费力气

KV 缓存这块的价值在于：它是显存占用的主要来源之一，理解它的分配与回收方式，你才能判断「调大某个参数到底是在换什么」。具体占用数字随模型和配置变化，别记死数，到站内的性能与参数页面对照当时的实测更靠谱。

一条可执行的阅读顺序与验收标准

顺序比速度重要。按下面三步走，每一步都有明确的过关标志，过不了就别急着往下走，否则后面读得越多越糊涂。

1. 走通主链路从请求进来到结果返回，把调度、执行这几个关键节点串一遍。过关标志：不看代码也能口述一遍请求经过了哪些环节
2. 挑一个模块下钻按你实际遇到的问题选模块，而不是按目录顺序。过关标志：能说清这个模块对外暴露了哪些行为、依赖谁、被谁调用
3. 做小改动验证加一行日志看调度决策，或者改个分支看行为变化，能对上你的预期就说明读对了。过关标志：预测和实际输出一致

验收不靠读完多少文件，靠「给一个现象能说出大概哪一层出问题」。这是个可以随时自测的硬标准，比数行数有用得多。

读源码的目标不是读完，而是拿到一张能定位问题的地图。