model.generate()
已经能回答问题,为什么上线还要换推理框架?看一个常见场景:A
正在生成答案,B 带着长文档进来,C 刚断开连接。服务必须继续给
A 出 token、分段处理 B、及时回收 C 的
KV,还不能让三者的状态串在一起。这些工作不属于一次模型
forward(),却直接决定首 token
延迟、并发和显存占用。
本文把推理框架(inference framework / serving engine)拆成调度、KV 管理、并行执行、采样和模型运行五个职责,再用分页、批处理与部署示例串起来。已有机制详解见 11 推理基础、12 分页与连续批处理;集群服务化与网关见 21、22。这里关注单个引擎如何工作,不做吞吐排行榜。
部署命令按官方文档核对到 2026-10-31;本文没有执行模型服务,也不提供自测性能结论。读者需要准备匹配的运行环境与权重。
先看边界:网关治理请求,引擎安排计算,内核执行算子。
〇、30 秒版
- 一次生成调用与请求服务是两层工作:后者要接纳、取消、排队、回收资源,还要守住服务等级目标(SLO)。框架提供手段,不保证超载时仍满足目标。
- 引擎的五个职责:调度决定本步算谁,KV 管理决定数据放哪,并行运行时协调多卡,采样决定输出,模型运行器组织实际执行。租户配额与统一鉴权通常在网关。
- 先按约束筛候选:通用 GPU 服务考察 vLLM/SGLang/LMDeploy,NVIDIA 专用优化考察 TensorRT-LLM,昇腾核对 MindIE 等厂商栈,本地考察 llama.cpp/Ollama。DeepInfer 当前公开版是特定模型的离线推理入口;TGI 已维护并归档。
- 性能看成本,不看名字:Prefill/Decode 的权重与 KV 流量不同,分页不能消除读 KV 的成本,前缀缓存也只有在前缀真的重复且可安全共享时才有收益。
- 先做单机冒烟,再谈生产:串行启动一个引擎,检查模型名和聊天接口;之后补 21 服务化、22 网关、23 观测。
一、为啥需要推理框架
1.1 能生成答案,还缺哪些服务能力
实验室脚本关心的是:这份权重能不能在一张卡上出答案。生产线关心的是另一组指标:
| 指标或能力 | 含义 | 单纯包一层 HTTP 常遇到的问题 |
|---|---|---|
| TTFT | 请求开始到首个输出 token 的时间 | 排队、分词和长 prefill 都可能拖慢首 token |
| TPOT / ITL | TPOT 是首 token 后的平均每 token 时间;ITL 是相邻 token 间隔 | 平均值尚可,但某一步很慢;需另看 ITL 分位数 |
| 活跃请求数 | 同时驻留、等待或执行的请求数 | 并发能力须结合上下文长度和 KV 预算,不能只报会话数 |
| 吞吐(tok/s) | 单位时间处理或输出的 token 数 | 必须区分输入与输出;批次空位无法及时补入工作 |
| 多租户治理 | 配额、隔离、适配器权限 | 需要网关与引擎协作,基本 API key 校验不等于完整隔离 |
普通 transformers 的 generate()
面向一次生成调用,成员通常是固定 batch。常见默认
DynamicCache
按层动态增长;滑窗等层可能有增长上限。StaticCache
按配置上限预分配,便于固定形状与编译,但会为尚未使用的位置占空间。二者都不能仅凭名称推断出服务引擎的跨请求分页布局。
这不是 Transformers
全库的能力边界。它已有约束采样接口,PEFT
也能处理适配器;当前主线文档还提供
generate_batch()、ContinuousBatchingManager
和 transformers serve,包括分页、前缀共享与
OpenAI 兼容端点。比较时应把「普通
generate()」「专门的批处理/服务路径」分开,再核对所用发布版本。真正要选的是一条适配模型、硬件和运维需求的完整路径。
1.2 瓶颈地图
把问题摊开,会看到四类彼此耦合的瓶颈——框架存在的理由,就是同时对付它们:
- 计算:较长 prefill 通常有足够多的 token 行摊薄权重读取,GEMM 更容易受算力限制;短 prompt 或通信占主导时不一定如此。
- 带宽:小 batch decode 常受读权重、读历史 KV 的流量限制;增加 batch 可提高复用,但会改变单步时间与排队延迟。
- 容量:权重、工作区和 KV 共同占显存。分页减少按最大长度预留的浪费,前缀共享减少重复数据,但都不能让显存预算消失。
- 系统:到达、取消、超时和 LoRA 切换需要一致的请求状态;过载时还要限流或拒绝,不能全靠堆 batch。
框架把这些约束放到同一轮决策里:在有限显存和计算资源下,分配每步工作量,权衡吞吐与延迟。
二、框架在栈里的位置
总览图是职责图,不是每个请求必经的串行调用栈:
| 组件 | 负责什么 | 不应混为一谈 |
|---|---|---|
| Serving API | 校验请求、套聊天模板、分词、协议转换和流式返回 | OpenAI 兼容不代表支持所有参数;完整鉴权、配额、路由通常属于网关 |
| Scheduler | 决定本步请求与 token 数,维护等待/运行状态,处理抢占 | 不执行 attention 数值计算;并非所有引擎都支持同一种优先级策略 |
| KV Manager | 分配、引用、回收块,查询可复用前缀 | 不决定答案内容;swap、重算、分层卸载是不同策略 |
| Parallel Runtime | 组织权重分片、worker 与集合通信 | TP/PP/DP/EP 不是每个后端都任意可组合 |
| Sampling / Structured Output | 修改 logits、施加允许 token 集、采样与终止判断 | tool-call 格式解析不是执行工具;JSON 合法不保证业务语义正确 |
| Model Runner | 构造输入与 attention 元数据,运行模型和采样路径 | 底层内核和通信库执行算子;量化加载还需匹配模型与硬件 |
调度器和 KV Manager 相互协商,模型运行器通过并行运行时安排执行,再把结果交回请求状态机。它们可能在不同进程,具体划分随框架而变。引擎之上的多副本负载均衡、PD 池编排和租户治理仍是集群工作,见 21。
三、框架实际做什么
下面按「一次请求穿过引擎」来看职责,而不是按仓库目录罗列文件名。
3.1 请求调度与连续批处理
静态 batch 的成员在生成过程中不变。C 提前结束后,可以先把答案交给客户端,但它留下的位置往往继续做 padding 或被屏蔽,D 仍进不了这批;问题是不能及时补入新工作,并非 GPU 在等待 EOS 而停止计算。
Yu 等人的 Orca(OSDI 2022)把调度粒度从整个请求改为一次模型迭代,提出迭代级调度与选择性批处理。现代引擎沿着这条路做连续批处理(continuous batching):每步重新决定活跃请求,完成者退出,新请求在资源允许时加入。
不过,能插入新请求还不够。一个长 prompt 若占满本次执行,其他请求的下一 token 仍会延后。分块预填充(chunked prefill)把它拆成多步,与 decode 交织。Agrawal 等人的 Sarathi-Serve(OSDI 2024)进一步讨论如何控制块大小、构造不暂停已有 decode 的批次。块太大仍会拉长单步,太小又增加调度和启动开销;它缓解阻塞,不保证任意负载下都满足延迟目标。
3.2 Paged KV 与前缀缓存
按请求最大长度整段预留 KV,会把尚未生成的位置也算进预算;每条请求单独保留相同前缀,又会重复计算和存储。PagedAttention 把 KV 分成固定大小块,用 block table 记录逻辑位置到物理块的映射,让请求按需增长。块池可先预分配,节省的是请求级预留与碎片,并非完全没有预留。
分页与前缀缓存是两个层次。vLLM 的 automatic prefix caching 用块哈希查找可复用 KV;SGLang 的 RadixAttention 用 radix tree 管理共享前缀。两者都能支持多轮、分叉和重复提示,不能仅凭数据结构宣称谁更适合 Agent。缓存通常省去重复前缀的 prefill,不会省掉后续每个新 token 的全部 decode 工作。
引擎要保持块映射与引用计数一致:共享块不能被提前回收,可写尾块不能污染其他请求。具体写时复制与完整块复用规则见 5.2。
3.3 并行策略
| 策略 | 切什么 | 典型触发 |
|---|---|---|
| TP | 层内矩阵与相关张量 | 分摊权重/计算;每层通信可能抵消单步收益 |
| PP | 不同层放到不同设备 | 跨卡容纳模型;流水气泡与阶段不均会浪费资源 |
| DP | 模型副本,按请求分流 | 扩大总服务能力;在线推理通常不做训练式梯度同步 |
| EP | MoE 专家及 token 路由 | 分摊专家权重;all-to-all 与专家热点可能主导延迟 |
引擎负责 worker 拓扑、权重分片、collective 插入点和分布式输入;副本之间的请求路由可由引擎或外置负载均衡承担。TP 不保证降延迟,PP 不必只用于极深模型,EP 也常与其他并行维度组合。先核对后端支持的组合,再看卡间链路、显存分布与专家负载。
3.4 量化加载、多 LoRA、结构化输出、投机接口
- 量化加载:AWQ/GPTQ/FP8/FP4 是不同格式和计算路径,支持权重加载不等于支持任意硬件上的对应算子;KV 量化还需另核对 dtype、scale 与精度,见 14。
- 多 LoRA:同一底座处理不同适配器,请求要携带正确的 adapter 身份,缓存不能跨不相容适配器误共享。动态装载还涉及权限与显存预算。
- 结构化输出:grammar 或 JSON Schema 后端根据当前状态屏蔽不允许的 token,再交给采样。工具调用还需要聊天模板与格式解析器;引擎产出调用内容,应用执行工具。
- 投机解码:draft 模型或 MTP 头产出候选,target 验证;运行器、采样与 KV 管理共同完成接受、回滚和计数更新,见 15。
3.5 OpenAI 兼容 API 与观测钩子
OpenAI 兼容 API 减少了接入改动,但模板、tool call、usage、流式错误与参数支持仍要逐项核对。观测至少覆盖队列等待、TTFT、ITL、KV 占用、前缀命中、每步 token 数和抢占;指标名与支持情况随引擎而变。
客户端测量与引擎内部指标也不能混用:HTTP chunk 可能包含多个 token,网络和网关会改变 TTFT/ITL。先说明测量起止点、输入/输出 token 口径与是否流式,再与 23 的端到端指标对齐。
四、常用引擎地图(2026)
4.1 机制与使用边界
下面列可核对的机制和部署约束,不给「吞吐强、延迟弱」评分。所有候选都应先核对目标模型、权重格式、硬件与具体发布版本;性能再按同一负载测。
- vLLM:提供请求调度、分页 KV、块级前缀缓存与 OpenAI 兼容服务;V1 的调度/执行结构见第五节。硬件和模型支持不是所有后端一致。
- SGLang:RadixAttention 管理前缀 KV,服务后端可直接接 OpenAI 客户端。DSL 是可选的程序前端,不是使用缓存的前提,也不意味着其他引擎无法共享分叉前缀。
- TensorRT-LLM:NVIDIA
专用推理运行时与算子路径。当前官方迁移文档已将
PyTorch 列为唯一执行后端,
trtllm-serve可直接加载 Hugging Face checkpoint,不要求先构建 TensorRT engine。旧版 engine 构建流程属于旧后端,Triton Inference Server 是可选集成;部署须核对安装版本,不能只凭产品名推断执行路径。 - TGI:2025-12-11 进入 maintenance mode,2026-03-21 仓库归档。维护公告建议后续考虑 vLLM/SGLang 等;新项目不宜再把它作为持续演进的默认引擎,存量服务则先安排迁移验证。
- LMDeploy:提供 TurboMind 和 PyTorch 等后端及 API server;支持矩阵、量化与 KV dtype 随后端变化,不能概括成「只擅长吞吐」。
- MindIE:华为昇腾推理套件。按卡型、CANN、MindIE 版本与模型适配矩阵核对,不把 CUDA 环境的安装命令直接搬过去。
- DeepInfer:当前 README 列出 DeepSeek-V4.1-Flash、NVIDIA SM100 与 Ascend 950,公开版提供离线推理。README 还明确,完整服务所需的 KV cache system、VE/Prefill/Decode 分离和 DP 副本负载均衡不在本次 release 中;这不代表离线 forward 完全没有 KV,而是不能把公开包当成完整在线服务。详解见 28。
- llama.cpp / Ollama:本地 CPU/GPU 的常用入口,前者以 GGUF 权重和本机 server 为核心,后者提供模型管理与服务封装。llama.cpp 也有连续批处理,边界在容量、实现与部署条件,不是「本地引擎没有调度」。
4.2 选型多路径
按下面顺序缩小范围,比先选品牌更稳:
- 模型能否加载?先确认架构、量化格式、聊天模板、LoRA 与结构化输出要求。
- 硬件能否执行?NVIDIA 可对照 vLLM/SGLang/LMDeploy/TensorRT-LLM;昇腾核对 MindIE 或相应适配;本地 CPU/Metal 则从 llama.cpp/Ollama 看起。
- 流量长什么样?重复系统提示值得测缓存命中;长文档值得测分块 prefill;MoE 要观察路由与通信。任何一个特征都不直接决定某引擎必胜。
- 团队能否维护?记录框架版本、后端、驱动与模型 revision,比较升级回归、监控和故障定位成本。DeepInfer 的特化离线入口与通用在线 API 服务不是同一个交付目标。
五、一次调度里的计算、KV 与执行
从计算流量、token 写入位置到一步调度,下面用具体状态说明五个职责如何配合。例子都是机制示意,不是框架日志或 benchmark。
5.1 Prefill 与 Decode:先算搬多少,再看算多少
Roofline 模型把计算性能的上限写成:
\[ I = \frac{F}{Q}, \qquad P \leq \min(P_{\mathrm{peak}}, B_{\mathrm{mem}} I). \]
\(F\) 是计算量(FLOP),\(Q\) 是经过所选存储层级的流量(byte);这里选 GPU HBM。\(P\) 的单位是 FLOP/s,\(B_{\mathrm{mem}}\) 是 byte/s,\(I\) 是 FLOP/byte。拐点在 \(I_* = P_{\mathrm{peak}}/B_{\mathrm{mem}}\):左侧上限由带宽决定,右侧由算力决定。图用线性坐标画上限,不是测量曲线,也不是 tok/s 排名;实际性能还会受访存效率、启动开销和通信限制。
以一个稠密线性层为例:本步有 \(M\) 个 token 行,权重形状为 \(d_{\mathrm{in}}\times d_{\mathrm{out}}\),每个权重占 \(s\) byte。只计一次权重读取、忽略输入输出流量时:
\[ \begin{aligned} F &\approx 2M d_{\mathrm{in}}d_{\mathrm{out}}, \\ Q_W &\approx s d_{\mathrm{in}}d_{\mathrm{out}}, \\ I_W &\approx \frac{2M}{s}. \end{aligned} \]
Prefill 的 \(M\) 包含一批 prompt token,可以摊薄读权重的成本;普通 decode 中每条活跃序列通常只有一个 token 行,小 batch 难以摊薄这笔成本。Decode attention 还要读历史 KV,长上下文会增加这部分流量。分页改变的是寻址与分配,不会自动免去对历史 KV 的读取;稀疏或滑窗 attention 则是另一个计算假设。
因此,长 prefill 的 GEMM 常偏算力受限,小 batch decode
常偏带宽受限,但这不是阶段的固定属性。短 prompt、大 decode
batch、GQA/MLA、量化、MoE 和通信都可能移动图上的位置。调
max_num_seqs 只限制序列数,调 token budget
才控制每步 token 工作量;两者还须一起受 KV
容量与延迟约束。
5.2 PagedAttention:一个 token 写到哪里
Kwon 等人的 PagedAttention(SOSP 2023)让逻辑连续的 KV 序列落在不连续的物理块中。设块大小为 \(b\),token 的位置 \(t\) 从零开始,则:
\[ \ell = \left\lfloor\frac{t}{b}\right\rfloor, \qquad o = t \bmod b. \]
先用逻辑块号 \(\ell\) 查
block_table,得到物理块,再用块内偏移 \(o\) 写入。KV Manager
要在执行前准备好所需映射;新位置跨过块边界时才需要新块,遇到共享可写块则还需处理写时复制。
下面假设不做投机解码、不共享前缀,block_size = 16。物理块号只为示意,不是运行输出。
- 入队:A 的 prompt 长 20 token,B 长 10 token。两者都在 waiting,尚未分配 KV。
- A prefill 完成:A 进入 running,B
仍等待。A 用 \(\lceil20/16\rceil=2\)
块,
block_table[A]=[7,3];块 3 已写 4 个位置,prompt 最后的 logits 可采样首个输出 token。 - B prefill 完成:A、B 都在
running,waiting 为空。
block_table[B]=[9],块 9 已写 10 个位置。 - A 下一次 decode:将刚采样出的 token 送入模型,其位置 \(t=20\);写入物理块 3 的偏移 4,再采样下一个 token,无需新块。
- A 结束:从 running 移除 A,释放它的块引用。本例无缓存留存,块 7、3 可回到空闲池,B 继续运行。
输出了一个 token,不等于已经存下它的 KV:普通自回归路径里,它在下一次 forward 才成为输入并产生 KV。调度时的「已生成」与「已计算」计数不能混用。
共享也有条件。vLLM 的块级前缀缓存通常复用已计算的完整块;本例 B 的整个 prompt 只有 10 token,连一个完整的 16-token 块都没有,不能仅因系统提示相同就宣称可命中。即使 token 相同,模型、LoRA、位置与缓存命名空间等影响计算的上下文也必须相容。共享块的引用归零后可能仍作为可驱逐缓存保留,释放请求不等于立刻抹掉全部 KV。
5.3 一步调度:token 预算与 KV 预算要同时够
一次调度至少回答三件事:每条请求本步计算几个
token、这些位置映射到哪些 KV
块、哪些请求暂时不执行。请求已在 running
中,也可能还没完成 prefill;不能把 running
简化成「每条只算一个 decode token」。
假设每步最多算 8 个 token,A 需要一次普通 decode,B 还剩 10 个 prompt token。本例给 A 优先级,且 KV 块充足:
- 第一步:A 算 1 个 decode 输入,B 算 7 个 prefill 输入,共 \(1+7=8\)。A 可以采样;B 的 prompt 尚未算完,不输出答案。
- 第二步:A 再算 1 个 decode 输入,B 算剩余 3 个 prefill 输入,共 \(1+3=4\)。A 继续采样;B 这时可从 prompt 最后位置的 logits 采样首 token。
这里的 8 是演示预算,不是推荐配置。真实调度还受
max_num_seqs、KV
空闲块、优先级、前缀命中和投机候选影响。若 A
的下一个输入跨块边界,也必须分配块;若 B
全部命中缓存,即使没有新的空闲块,也未必不能接纳。不能只在接纳
waiting 请求时检查 KV,也不能扣了 token
预算却忘记扣块预算。
vLLM V1 的 vllm/v1/core/sched/scheduler.py
中,Scheduler 仍用 Python 实现;每步按未计算
token 数、预算和可分配 KV 形成
SchedulerOutput,交给 worker 构造输入并执行。V1
并不靠一个固定的「先 prefill、后 decode」阶段开关工作。GPU
侧的 attention、GEMM、采样等才进入 CUDA/Triton
等算子路径。
KV 紧张时的抢占策略依实现而异。vLLM V1 的常规路径释放被抢占请求的块、以后重算;不能把旧版 CPU swap 字段套在所有 V1 部署上。SGLang 也会结合前缀命中与资源情况安排请求,radix tree 是缓存组织方式,不是通用优先级规则。
取消请求则要停止后续调度,在已发出的执行安全完成后释放引用、回收资源;网关还需把超时或断连传到引擎。否则客户端离开了,后端仍可能持续生成。
5.4 Attention backend:策略、布局与算子不是一层
沿着一次执行读代码,可以分三步:
- 后端选择:根据模型 attention 变体、dtype、KV 格式与硬件能力,选兼容的实现;不一定每步重新选一次。
- 元数据构造:模型运行器准备 token 位置、序列长度、block table、slot mapping 等,让内核找到正确的 KV。
- 算子执行:FlashAttention、FlashInfer、Triton 或厂商实现完成 attention,GEMM/MoE 等另有自己的后端。
vLLM V1 的几个阅读入口:
- 调度决策:
vllm/v1/core/sched/scheduler.py,对应队列长度与抢占次数。 - KV
分配:
vllm/v1/core/kv_cache_manager.py,对应空闲块、分配失败与缓存命中。 - 输入与执行:
vllm/v1/worker/gpu_model_runner.py,对应每步 token 数、shape 与耗时。 - 具体后端:从启动日志对到 attention backend 实现,核对实际 dtype、模型和硬件支持。
FlashAttention 的核心是减少 attention 的 HBM 读写,不等于「只跑 prefill」;FlashInfer 也不只跑 paged decode。两者的阶段与布局支持要看版本。RoPE 是位置编码,ALiBi 是位置相关偏置,它们影响 attention 计算语义,不是 KV 分页布局;GQA/MLA 则改变 KV 表示或访问方式。只看某个 kernel 名字,不足以判断整条推理路径是否兼容。
5.5 从机制到生产,剩下的取舍
- 拆池还是交织? Sarathi-Serve 说明分块可缓解同池的 prefill/decode 干扰;PD 分离则能独立配置两类资源,但要传输 KV、安排跨池请求。若传输量为 \(Q_{\mathrm{KV}}\)、有效链路带宽为 \(B_{\mathrm{link}}\),传输时间至少受 \(Q_{\mathrm{KV}}/B_{\mathrm{link}}\) 约束,还不含排队与协议开销。是否值得拆,要对照 21 的端到端延迟,而非只看计算阶段变快。
- 缓存命中还是公平? PagedAttention 与 SGLang 分别提供分页共享、树形前缀管理的入口。两种组织方式都能复用前缀;收益受重复率、块粒度和驱逐策略限制。多租户还要决定共享的安全域,避免用命中行为暴露其他租户是否问过同一问题。提高总命中率不等于每个租户的等待时间更短。
- 投机是否真省时间? target 一次验证多个候选,需要提交已接受位置的 KV、丢弃拒绝部分并更新调度计数。低接受率、draft 开销或小 batch 下的验证成本,都可能抵消收益;机制见 15。框架提供接口,不保证接上 draft 就提速。
这些问题的共同点是:单个算子正确且快,还不够。请求排队、缓存生命周期与数据传递必须放进同一笔账。
六、部署 Demo:先把一个聊天请求接通
环境:A/B 使用 Linux、Python
3.12、已安装的 uv 与受支持的 NVIDIA
GPU;按各版本安装文档匹配驱动和 CUDA,SGLang
当前默认安装路径要求 CUDA 13。能访问 Hugging Face,或把模型
ID 换成本地权重目录。显存要容纳权重、KV
和工作区;小模型也可能因上下文配置、CUDA graph 或其他进程而
OOM。
下面固定 vLLM 0.32.0、SGLang
0.5.22、LMDeploy
0.18.0,这些版本在核对时均已发布。安装、服务和权重下载没有在本文环境实跑。每段在新的工作目录创建独立环境,A/B
串行运行:先在原终端用 Ctrl-C
停掉上一个服务,确认它退出,再启动下一个。它们复用端口
8000 和模型别名 demo。
6.1 Demo A:vLLM
依据 vLLM Quickstart 和 serve 参数:
uv venv --python 3.12 --seed .venv-vllm
source .venv-vllm/bin/activate
uv pip install "vllm==0.32.0" --torch-backend=auto
export MODEL=Qwen/Qwen2.5-0.5B-Instruct
vllm serve "$MODEL" --host 127.0.0.1 --port 8000 \
--served-model-name demo --max-model-len 2048--max-model-len 限制的是 prompt
与输出的总上下文长度,不是单独的输出上限;这里的 2048
只是短请求冒烟设置,不能据此承诺某张卡不 OOM。
Docker 是替代启动方式,不要与上面的进程同时运行。宿主机需要 NVIDIA Container Toolkit;镜像内部监听所有接口,但只把宿主端口发布到回环地址:
docker run --rm --gpus all --ipc=host -p 127.0.0.1:8000:8000 \
vllm/vllm-openai:v0.32.0 \
--model Qwen/Qwen2.5-0.5B-Instruct \
--host 0.0.0.0 --port 8000 \
--served-model-name demo --max-model-len 2048此版本镜像入口接受
--model,也支持位置参数;这与宿主的
vllm serve "$MODEL"
并不冲突。--ipc=host 共享宿主 IPC
命名空间,属于单机演示选择,生产应按隔离要求配置共享内存。
6.2 Demo B:SGLang 或 LMDeploy
任选一个,使用与 A 同一模型和别名。这样客户端可以不改,差异来自引擎而不是模型名。
uv venv --python 3.12 .venv-sglang
source .venv-sglang/bin/activate
uv pip install "sglang==0.5.22"
export MODEL=Qwen/Qwen2.5-0.5B-Instruct
sglang serve "$MODEL" --host 127.0.0.1 --port 8000 \
--served-model-name demo文本服务不必安装包含其他工作负载依赖的
[all]。此版本也保留
python -m sglang.launch_server --model-path "$MODEL"
路径;不要把两种入口的模型参数混写。
LMDeploy 依据 v0.18.0 支持矩阵 与 API server CLI:
uv venv --python 3.12 .venv-lmdeploy
source .venv-lmdeploy/bin/activate
uv pip install "lmdeploy==0.18.0"
export MODEL=Qwen/Qwen2.5-0.5B-Instruct
lmdeploy serve api_server "$MODEL" --backend pytorch \
--server-name 127.0.0.1 --server-port 8000 --model-name demo这里显式选 PyTorch 后端。要对照 TurboMind,可在核对其模型、权重与 KV dtype 支持后替换后端;这次启动不是两个后端的性能比较。
6.3 A/B 共用客户端:先查模型,再聊天
服务器启动会阻塞当前终端。另开终端,等日志显示加载完成,再运行:
curl -fsS http://127.0.0.1:8000/v1/models &&
curl -fsS http://127.0.0.1:8000/v1/chat/completions \
-H 'Content-Type: application/json' \
-d '{
"model": "demo",
"messages": [{"role":"user","content":"用一句话解释 KV cache"}],
"max_tokens": 128
}'检查 /v1/models 返回的 ID 是否为
demo,聊天响应是否有有效的
choices;仅看到 HTTP 200
还不能代替内容检查。未就绪时 curl -f
会报告错误,不把失败响应当成功输出。本例是非流式功能冒烟;要验证流式,再加
"stream": true 并用 curl -N 接收
SSE。不要从单次 curl 推断 TTFT、ITL 或并发吞吐。
6.4 Demo C:llama.cpp CPU server 与 Ollama
llama.cpp 需要 Git、CMake、C/C++
工具链和已有的 Qwen2.5-0.5B-Instruct
GGUF。以下假设文件已放在
$HOME/models/qwen2.5-0.5b-instruct-q4_k_m.gguf,名称与路径按实际文件调整。依据
构建文档
与 server
文档:
git clone --depth 1 https://github.com/ggml-org/llama.cpp llama-demo
cmake -S llama-demo -B llama-demo/build \
-DCMAKE_BUILD_TYPE=Release -DGGML_CUDA=OFF
cmake --build llama-demo/build --target llama-server --config Release -j2
git -C llama-demo rev-parse HEAD
export GGUF="$HOME/models/qwen2.5-0.5b-instruct-q4_k_m.gguf"
test -f "$GGUF" &&
./llama-demo/build/bin/llama-server -m "$GGUF" -ngl 0 \
--host 127.0.0.1 --port 8080 --alias demo-ngl 0 不把模型层卸载到 GPU;记录输出的
commit 与 GGUF 来源,避免源码主线更新后无法对照。GGUF
应包含正确聊天模板;此处的 Qwen Instruct 文件若缺模板,可按
server 文档显式用
--chat-template chatml,不要给任意模型强套该模板。
另开终端验证:
curl -fsS http://127.0.0.1:8080/health &&
curl -fsS http://127.0.0.1:8080/v1/chat/completions \
-H 'Content-Type: application/json' \
-d '{"model":"demo","messages":[{"role":"user","content":"解释 KV cache"}],"max_tokens":128}'/health 加载中可返回 503,就绪后返回
200;客户端仍要检查聊天内容。llama.cpp
可以调度并发请求,但本例只验证单机接口,不能外推集群容量。
Ollama 是更简短的本地入口。按 Linux 安装文档 安装后,若已有后台服务,不重复启动;否则在一个终端运行:
OLLAMA_HOST=127.0.0.1:11434 ollama serve在另一终端运行:
curl -fsS http://127.0.0.1:11434/ &&
OLLAMA_HOST=127.0.0.1:11434 ollama run qwen2.5:0.5b "解释 continuous batching"模型不存在时 run
会下载,因而首轮等待包含下载与加载;不能拿它与已预热的 GPU
服务直接比延迟。
6.5 常见失败与安全边界
| 现象 | 先检查什么 | 处理方向 |
|---|---|---|
| CUDA/算子不兼容 | GPU 架构、驱动、包版本与安装文档 | 重建匹配版本的独立环境,不混装各引擎的 Torch/CUDA 依赖 |
| CUDA OOM | 启动日志、其他进程、上下文和 KV 配置 | 停掉上个引擎,缩短上下文/降低并发;区分权重 OOM 与缓存预算不足 |
| 连接拒绝或加载中 | 服务是否退出、实际端口、加载日志 | 先等就绪;8000、8080、11434 对应不同 Demo |
| 模型名错误 | /v1/models、启动参数中的别名 |
A/B/llama.cpp 的 chat 都用 demo,Ollama
用自身模型 tag |
| 下载失败或聊天模板错误 | 权重来源、许可证、tokenizer/GGUF 元数据 | 使用可信的本地权重,核对 Instruct 模型与模板 |
单机 Demo
默认回环监听,不是公网服务模板。对外提供接口时,再配置 22
鉴权网关、TLS、租户配额与取消传播;模型许可证、HF_TOKEN
和数据驻留按 24
处理。生产还要验证排队、长
prompt、断连、过载和升级回归,而非只检查 curl
能否出答案。
七、落地选型与多路径
按目标选择下一步:
- 学习机制:11 → 12 → 本篇。能解释谁调度、谁管 KV、谁执行,再读 13 引擎比较。
- 单机上手:选一个 Demo,通过就绪与聊天检查;换引擎时保持模型、请求和别名相同。性能对照另建统一负载,不能用功能冒烟代替。
- 准备上线:补 21 服务化、22 网关、23 观测,测试长 prompt、取消和过载,确认端到端 SLO。
- 特化部署:根据硬件和模型适配进入 TensorRT-LLM、MindIE 或 DeepInfer;多维护一套栈就多一套镜像、回归和排障路径,收益要覆盖这些成本。
一个本地聊天服务与一个在线多租户集群,优化目标不同。先明确要交付什么,再决定引擎和外层基础设施。
八、与系列交叉引用 + 延伸阅读
| 你想解决的问题 | 去哪篇 |
|---|---|
| Prefill/Decode/KV 心智 | 11 推理引擎基础 |
| PagedAttention / Continuous Batching 机制 | 12 |
| 引擎产品横评与决策树 | 13 |
| 量化与 KV 量化 | 14 |
| 投机解码 / MTP | 15 |
| 服务化 / PD 分离 | 21 |
| 网关 | 22 |
| 可观测 | 23 |
| 成本与安全合规 | 24 |
| DeepSeek 生产引擎切片 | 28 DeepInfer |
| 国产芯片主路径 | 26 |
官方文档与源码
以下状态按 2026-10-31
核对;main/latest
文档会更新,部署命令的固定包版本见第六节。
- NERSC:Roofline Performance Model;算术强度的存储层级与性能上限定义。
- Transformers:KV
cache、连续批处理与服务入口;区分普通
generate()与专门服务路径。 - vLLM:V1 Scheduler、KV Manager、前缀缓存设计、V1 调优与抢占。
- SGLang:官方介绍、Quickstart;区分 DSL 前端与推理后端。
- TensorRT-LLM:TensorRT 后端移除迁移指南、项目仓库。当前文档不要求 engine 构建;旧版须按自己的发布文档部署。
- TGI:2025-12-11 维护公告提交、已归档仓库;维护与归档是两件事。
- LMDeploy:项目仓库;具体 Demo 的版本化支持矩阵与 CLI 见 6.2。
- MindIE:华为昇腾官方产品页;以实际卡型、CANN、套件版本组合为准。
- DeepInfer:当前 README;模型/硬件范围与公开版未包含的服务组件均以该文件为依据。
- llama.cpp:当前官方仓库;构建与 server 文档见 6.4。Ollama:Linux 文档。
核心论文
- Williams、Waterman、Patterson,Roofline: An Insightful Visual Performance Model for Multicore Architectures,Communications of the ACM,2009。本文使用其计算/带宽上限模型,不据此估计实际 tok/s。
- Yu 等,Orca: A Distributed Serving System for Transformer-Based Generative Models,OSDI 2022。迭代级调度与选择性批处理的来源。
- Kwon 等,Efficient Memory Management for Large Language Model Serving with PagedAttention,SOSP 2023。分页映射与 KV 共享的来源。
- Agrawal 等,Taming Throughput-Latency Tradeoff in LLM Inference with Sarathi-Serve,OSDI 2024。分块 prefill 与 stall-free 调度;实验结论有其负载和硬件条件,本文不搬用其吞吐倍数。
- Zheng 等,SGLang: Efficient Execution of Structured Language Model Programs,2024,引用 arXiv 版本。前端/运行时分层与 RadixAttention 的来源;论文中的机制不等于当前各后端的完整功能矩阵。
推理框架的价值在于把请求状态、KV 生命周期和 GPU 执行接在一起。判断一条路径是否适合上线,先问它能否正确管理这些状态,再用目标流量测延迟、吞吐与容量。
源码下载
本文相关源码已整理,共 1 个文件。
文章导航
读完这篇,下一步读什么
优先读同系列或同问题的下一篇,把单篇消费变成主题集群。
【大模型基础设施工程】11:推理引擎基础
从 Prefill/Decode 两阶段、KV Cache、Continuous Batching 到 PD 分离,系统讲清楚大模型推理的工程基础。
【大模型基础设施工程】12:PagedAttention 与 Continuous Batching
PagedAttention 与 Continuous Batching 如何抬高推理吞吐:KV Cache 分页、批调度与工程取舍。
【大模型基础设施工程】13:vLLM / SGLang / TensorRT-LLM / TGI 对比
主流推理引擎的架构、性能、生态深度对比,给出工程选型与落地决策依据。
【大模型基础设施工程】21:推理服务化
从单机引擎到生产级集群:Triton、Ray Serve、KServe、vLLM OpenAI Server、PD 分离、LoRA 多租户、KEDA 自动扩缩、Serverless GPU 的全景工程实战。