企业官网建设流程全解析

当一批用户同时请求对话、摘要、代码生成时，GPU 显存很快被 KV Cache 占满，推理吞吐骤降，这是很多做过 LLM 服务化部署的人都经历过的场景。单靠 PyTorch 手写推理循环，往往无法满足高并发下的性能要求，这时就需要一个专门为大模型推理设计的高吞吐服务框架。vLLM 是目前社区最流行的选择之一，它通过 PagedAttention、Continuous Batching 等机制，把显存利用率和请求吞吐提升了一个量级。

进入 2025 年，vLLM 已经成为 AI Infra 层无法绕开的核心组件。本文将围绕 vLLM 的系统设计与实践落地，先拆解它的核心架构，再逐步演示环境准备、模型服务启动、客户端调用，最后整理高频问题与生产环境建议。无论你是在做 RAG 应用、Agent 编排，还是在给团队搭建模型推理服务，都可以从本文找到可直接落地的内容。

1. 为什么大模型推理需要专门引擎

1.1 大模型推理与普通推理的本质区别

传统深度学习推理模式非常简单：输入一张图片或一段文本，前向计算一次，输出分类结果或向量，整个过程毫秒级完成，内存占用也基本固定。

大语言模型（LLM）则完全不同。它以自回归方式生成文本，也就是一个 token 一个 token 地产生结果。每生成一个新 token，都要把之前的 token 重新读入计算。为了加速这个过程，推理框架会缓存历史 token 的注意力中间结果，也就是 KV Cache，它随着生成的推进不断增长。

这个特性让“简单用 PyTorch 跑一次 forward”的思路失效了。一个完整的 LLM 推理服务，需要考虑：显存如何分配、KV Cache 如何管理、多个请求如何组织成 batch、不同长度的生成序列如何调度、服务接口如何暴露。

1.2 高吞吐推理的三个核心瓶颈

结合工程实际，LLM 推理服务通常受三方面制约：

第一是显存墙。模型权重本身占据大量显存，而 KV Cache 在并发请求下增长极快。如果 KV Cache 管理粗糙，可能几百个并发就把 A100 80G 的显存打满，实际计算单元却大量空闲。

第二是访存墙。自回归生成是典型的访存密集型任务，每一个 token 的生成都需要把完整的权重从显存搬运到计算单元。此时 GPU 的计算单元可能只用了 10%，而显存带宽已经跑满。这是高吞吐推理设计中最难优化的部分。

第三是调度墙。不同请求的 prompt 长度不同，期望输出长度也不同。一个 batch 里既有马上结束的短请求，也有持续生成的超长请求。如何动态调度，决定了 GPU 资源能不能被榨干。

1.3 vLLM 的定位：推理服务框架，不是深度学习框架

很多同学会把 vLLM 和 PyTorch 混淆，或者拿 vLLM 与 LangChain 比较，这里先澄清一个概念。

PyTorch 是深度学习训练与推理的基础框架，负责自动微分、算子执行、张量计算。LangChain 是应用层编排框架，负责把大模型包装成链式调用、接入 RAG 和 Agent。vLLM 则位于两者之间，它是专门为 LLM 推理而生的服务框架，基于 PyTorch 构建，但解决的问题是“如何更高效地把模型跑成服务”。

vLLM 与当前比较火的 SGLang 也常被放在一起对比。SGLang 主打 RadixAttention 和更高效的前后端协同调度，在部分长 prompt 场景下性能表现亮眼；vLLM 则胜在生态成熟、接口兼容性好、社区案例多。两者都在快速迭代，选型时建议用真实业务流量做 benchmark，而不是只看宣传数据。

2. vLLM 核心架构拆解

2.1 PagedAttention：把虚拟内存思想搬进显存

PagedAttention 是 vLLM 论文中最重要的设计，也是它早期脱颖而出的关键。要理解 PagedAttention，先要看传统 LLM 推理框架是怎么管理 KV Cache 的。

传统方案在请求开始时，根据预估值申请一整块连续显存存放该请求的 KV Cache。这个预估值通常取最大序列长度，比如 2048 或 4096。问题在于，大部分请求实际生成的 token 数远少于预设值，那块显存申请了但用不满，造成内部碎片；同时，不同请求的 KV 块大小不一致，显存中出现大量无法合并的小空洞，造成外部碎片。

PagedAttention 的思路非常像操作系统中的分页机制。它把 KV Cache 切分成固定大小的 block（块），每个 block 可以存储若干 token 的 KV 值。请求的 KV Cache 不要求物理连续，而是通过 block table 映射到任意可用的物理块。新增 token 时动态申请新块，用完的块立刻释放。这样就避免了大量预分配浪费，显存利用率显著提升。

用一句话概括：PagedAttention 用“显存分页”的方式，把 KV Cache 的碎片与浪费降到了极低水平。这个机制直接提升了批处理容量，也就是同一时刻能并发处理的请求数量，从而带来更高的吞吐。

2.2 Continuous Batching：请求级动态调度

传统批处理通常采用静态 batching：一批请求同时进入计算，必须等最慢的一个生成完成，整批结果才能一起返回。如果某个请求生成特别长，其他请求只能干等，GPU 的算力白费。

vLLM 实现了 Continuous Batching，也叫迭代级调度或请求级调度。它的核心逻辑是：在每个 decoder step 之前，调度器都会重新决定“这一轮计算哪些 sequence”，而不是一开始就把批次锁死。

当一个请求提前生成结束，系统立刻把它从当前批次中移除，并释放它占用的显存 block；同时，等待队列里的新请求可以立即插入下一轮计算。这个动态调度机制让 GPU 始终在处理有意义的 token 生成，而不是浪费在等待和空转上。

与 Continuous Batching 配套的还有 Preemption（抢占）机制。当显存不足时，调度器会暂停某些序列的生成，先保证高优先级请求继续，等显存释放后再恢复被抢占序列。这种设计牺牲了少量单请求延迟，换取整体吞吐稳定，非常贴合在线服务场景。

2.3 vLLM 的整体服务流水线

从代码层面拆解，vLLM 的核心组件大致包括：

• API Server：对外暴露 OpenAI 兼容的 HTTP 接口；
• LLM Engine：管理模型加载、推理循环、采样参数；
• Scheduler：负责 continuous batching、抢占、block 管理；
• Distributed Executor：处理张量并行/数据并行下的模型执行；
• Model Worker：真正执行 Transformer 前向计算的进程。

一个完整请求的流程可以简化为以下步骤：

1. 客户端通过/v1/chat/completions发送请求。
2. API Server 解析请求参数，放入待调度队列。
3. Scheduler 在下一轮 step 把符合条件的序列加入 batch。
4. 模型执行器对 batch 做前向计算，产出新的 token。
5. KV Cache 按需写入新的 block，同时更新 block table。
6. 如果序列到达结束条件，调度器将其移出并返回结果；否则继续下一轮。

这套设计把请求管理、显存管理、模型执行解耦，每个组件可以独立演进，也让多卡部署、量化支持、LoRA 微调插入等功能变得更容易扩展。

3. 环境准备与安装部署

3.1 操作系统与硬件要求

vLLM 目前在 Linux 环境下的支持最稳定，这也是绝大多数生产环境的选择。NVIDIA GPU 配合 CUDA 的路径资料最多，问题也最容易排查。

如果你想在 Windows 10 或 Windows 11 上使用 vLLM，需要明确一点：官方对原生 Windows 的支持并不优先，很多底层算子依赖 Linux 生态。社区中常见的做法是使用 WSL2，或者直接在 Docker Desktop 中跑 Linux 容器。如果只是本地调试单个模型，WSL2 的体验已经比较接近 Linux 原生环境。

在安装前，建议确认下面几个信息：

• GPU 型号与显存大小；
• 驱动版本是否支持目标 CUDA 版本；
• Python 版本，建议 3.10 以上；
• 是否已配置 NVIDIA Container Toolkit（Docker 部署时需要）。

如果使用非 NVIDIA 硬件，比如昇腾、寒武纪等国产芯片，需要额外适配插件。例如昇腾平台有对应版本的 vLLM-ASCEND 适配项目，但支持矩阵通常滞后于 NVIDIA 主线。特别是 Embedding 模型和 Reranker 模型，因为任务类型与生成模型差异较大，在昇腾 910B 系列上经常出现启动失败或算子不支持的问题，这一点后续在常见问题部分会展开说明。

3.2 pip 与 Docker 安装方式

最直接的方式是通过 pip 安装：

pip install vllm

安装后会拉取大量依赖，包括 torch、transformers、flashinfer 等。需要注意版本匹配问题，不建议手动升级或降级 torch 版本，否则可能导致算子编译失败。

生产环境更推荐使用 Docker。vLLM 官方镜像会提前编译好符合特定 CUDA 版本的依赖，避免本地编译时间和环境冲突。

docker pull vllm/vllm-openai:latest

启动容器时，需要把模型目录挂载进去，并映射端口：

docker run --runtime nvidia --gpus all \ -v ~/models:/models \ -p 8000:8000 \ --ipc=host \ vllm/vllm-openai:latest \ --model /models/qwen/Qwen2.5-7B-Instruct \ --served-model-name qwen2.5-7b

这里的--ipc=host很重要，vLLM 在并行解码时依赖共享内存，如果容器 IPC 限制过小，可能触发无法预料的启动失败。

4. 核心启动参数深度解析

4.1 dtype 精度选择：fp16、fp32 与 bf16

大模型的精度参数直接决定显存占用和推理质量。vLLM 默认按模型保存的权重精度加载，但很多情况下我们需要手动指定。

fp16 的优点是计算快、显存占用减半，缺点是动态范围较窄，容易出现数值溢出，尤其在注意力分数较大的场景。bf16 是近年来大模型训练和推理的主流选择，它有和 fp32 相同的大范围指数位，数值稳定性好，几乎不会溢出，也不需要额外的缩放逻辑。代价是低精度尾数可能带来轻微的精度损失，但在绝大多数 NLP 任务中感知不到。

fp32 适合需要精确数值验证的场景，比如排查推理结果异常、对照参考实现，或者模型本身过于敏感。但显存占用直接翻倍，生产环境极少全 fp32 推理。

在实际操作中，启动服务时常用：

--dtype bfloat16

如果你的 GPU 是 Turing 架构及更老的卡，不支持 bf16，可以改用 fp16：

--dtype float16

选择精度还需要关注量化方案。AWQ、GPTQ 等量化权重可以显著降低显存需求，但启动服务时不能直接指定--dtype int4，而是直接把量化后的模型目录传给--model，vLLM 会自动读取量化配置。建议先了解自己 GPU 的架构和算子支持情况，再决定精度策略。

4.2 --enforce-eager 到底有什么影响

很多人在部署时看到网上教程用--enforce-eager，却不知道这个参数真正做了什么。

vLLM 默认会使用 CUDA Graph 来提高推理性能。CUDA Graph 会把一系列 GPU kernel 启动捕获并重放，大幅降低 kernel launch 带来的 CPU 开销，在短请求、高并发场景下收益非常明显。代价是 CUDA Graph 需要额外的显存空间，且在每次请求形状变化时可能需要重新捕获。

--enforce-eager的作用是禁用 CUDA Graph，强制使用 eager 模式执行。启用后，显存占用会明显降低，模型加载速度也更快，但吞吐量通常会下降，尤其在短 prompt、高并发场景下。

适合使用--enforce-eager的场景包括：

• 显存非常紧张，无法容纳 CUDA Graph 预留空间；
• 在机器学习开发阶段，只想快速验证服务能否启动；
• 调试算子问题时，需要绕过 CUDA Graph 的重放逻辑。

生产环境追求吞吐时，不建议随意开启这个参数。如果你看到“显存不足”报错，优先排查的是并发参数和模型量化，而不是直接关掉 CUDA Graph。

4.3 max-num-seqs 与并发控制

--max-num-seqs是控制并发序列数的关键参数，默认值通常是 256。它表示 Scheduler 在每一轮迭代中最多同时处理的序列数量。

这个参数与显存的关系很直接。并发序列越多，KV Cache 占用越大，所以当显存不足时，降低max-num-seqs往往最有效。反过来，如果 GPU 利用率偏低，但显存还有不少余量，适当提高这个值可以让更多请求进入 batch，提升吞吐。

需要强调的是，max-num-seqs并不等于客户端的最大并发请求数。当请求数量超过该值时，超出部分会在队列中等待，而不会报错。因此，它更像是推理引擎内部的批处理能力上限，而不是服务入口的并发限制。

另外一个相关参数是--max-model-len，它决定了模型能接受的最长序列长度。如果设置过长，会预分配更多显存；如果过短，长文本请求会被截断或报错。部署时建议根据业务实际输入场景来配置，而不是无脑设置成模型的最大长度。

4.4 多卡部署与张量并行

当单卡显存放不下模型时，vLLM 支持通过张量并行（Tensor Parallelism）将模型切分到多张卡上。

--tensor-parallel-size 2

这个参数表示把模型切分到 2 张 GPU 上运行。常用场景是 70B 级别模型或 32B 模型在双卡 A100/L20 上的部署。

多卡部署最容易踩的坑有两个。

第一个坑是显存不均。张量并行要求每张卡预留的空间保持一致，如果某张卡已经被其他进程占用了部分显存，vLLM 可能启动失败。排查时可用nvidia-smi先检查剩余显存。

第二个坑是算力共享与通信瓶颈。张量并行涉及每层 transformer 的 allreduce 通信，PCIe 或 NVLink 带宽会成为瓶颈。在 L20 这类双卡不过 NVLink 直连的服务器上，大模型吞吐可能远低于预期。此时先确认nvidia-smi topo -m的拓扑结构，再决定是否使用多卡。如果通信拓扑不理想，优先考虑单卡小模型或者数据并行（每个副本独立服务一个请求）。

4.5 如何启动 Embedding 与 Reranker 模型

vLLM 的核心定位是生成式大模型的高吞吐推理，但社区也一直在扩展 Embedding 模型和 Reranker 模型的支持。

如果你使用主流的 bge、gte 系列 embedding 模型，可以尝试：

vllm serve /models/bge-m3 \ --task embedding \ --served-model-name bge-m3

Reranker 模型则通过--task reranker指定。启动后同样可以通过/v1/embeddings或/v1/rerank接口调用。

但这里必须说明：vLLM 对 Embedding/Reranker 的支持远不如生成模型成熟。部分模型结构可能缺少适配算子，不同版本的兼容性差异也很大。在昇腾 910B 这类非 NVIDIA 平台上，由于适配项目优先对齐生成式模型，Embedding 和 Reranker 模型启动失败的情况非常常见。

如果你的业务是纯 RAG 场景，并且把向量检索和段落重排当作核心链路，建议优先考虑专门面向 Embedding 的推理服务，比如 Hugging Face 的 TEI（Text Embeddings Inference），或者使用支持更多任务类型的框架。把 vLLM 用在生成任务上，把专业工具用在检索任务上，整体稳定性会高很多。

5. 完整实战：部署一个开源大模型服务

5.1 准备模型与项目目录

本文以 Qwen2.5-7B-Instruct 为例进行演示。先创建模型目录，下载模型权重。如果你已经有离线模型文件，直接复用即可。

mkdir -p ~/models cd ~/models # 通过 modelscope 或 huggingface 下载，按实际网络情况选择 pip install modelscope modelscope download --model Qwen/Qwen2.5-7B-Instruct --local_dir ./Qwen2.5-7B-Instruct

这里建议使用 modelscope 在国内网络环境中加速下载。下载完成后，检查目录中是否包含config.json、model.safetensors等关键文件。

5.2 启动 vLLM 服务

在服务器终端执行下面的命令，启动一个 OpenAI 兼容的推理服务：

vllm serve ~/models/Qwen2.5-7B-Instruct \ --served-model-name qwen2.5-7b \ --dtype bfloat16 \ --max-model-len 8192 \ --max-num-seqs 64 \ --port 8000

参数说明：

• --served-model-name：对外暴露的模型名，可自定义，方便后续切换。
• --dtype bfloat16：按 bf16 精度加载权重。
• --max-model-len 8192：限制最大序列长度，预分配显存。
• --max-num-seqs 64：限制并发序列数量，避免显存被打爆。
• --port 8000：服务监听端口。

启动成功后，日志中会显示模型加载耗时、GPU 显存分布和当前通过 OpenAI 兼容 API 对外提供服务。此时可以打开另一个终端，验证服务健康状态：

curl http://localhost:8000/v1/models

如果返回了模型列表，说明服务已经正常运行。

5.3 使用 OpenAI SDK 调用

由于 vLLM 提供了 OpenAI 兼容接口，你可以直接使用openai客户端库调用，无需任何改造。

from openai import OpenAI client = OpenAI( base_url="http://localhost:8000/v1", api_key="EMPTY" ) resp = client.chat.completions.create( model="qwen2.5-7b", messages=[ {"role": "system", "content": "你是一个乐于助人的中文助手。"}, {"role": "user", "content": "请用一句话解释什么是 KV Cache。"} ], temperature=0.7, max_tokens=512 ) print(resp.choices[0].message.content)

运行这个脚本前需要安装依赖：

pip install openai

正常输出会是一段关于 KV Cache 的解释。这个示例说明，你的业务代码完全可以在本地开发环境使用 OpenAI 接口，在生产环境切换到 vLLM 服务，只需改变base_url，代码层面无需改动。

5.4 流式输出与多轮对话

在对话类应用中，流式输出几乎是标配，因为用户不希望等整个结果生成完才看到内容。vLLM 同样支持 OpenAI 的流式协议，只需要把参数stream设为True。

from openai import OpenAI client = OpenAI( base_url="http://localhost:8000/v1", api_key="EMPTY" ) stream = client.chat.completions.create( model="qwen2.5-7b", messages=[ {"role": "user", "content": "写一个 Python 快速排序函数。"} ], stream=True ) for chunk in stream: delta = chunk.choices[0].delta if delta and delta.content: print(delta.content, end="", flush=True)

流式输出的内部机制是 vLLM 在生成每个 token 后立即通过 SSE（Server-Sent Events）推送给客户端，而不是等完整序列结束。这在长文生成场景中极大改善了用户体验。

多轮对话的实现也不复杂，只需要把历史消息都放入messages数组，vLLM 会自动对整段上下文做 prefill，并结合 KV Cache 复用历史计算结果。

5.5 观察服务日志与性能指标

部署上线后，观察服务日志是每日运维的基础工作。vLLM 的默认日志会输出每次请求的排队时间、prefill token 数、decode token 数、总耗时、吞吐等指标。

典型的日志片段如下：

INFO 06-01 12:00:00 engine.py:123] Avg prompt throughput: 150.2 tokens/s INFO 06-01 12:00:00 engine.py:123] Avg generation throughput: 850.6 tokens/s INFO 06-01 12:00:00 engine.py:123] Running: 24 reqs, queued: 8 reqs

如果看到 queued 数量持续增长，说明服务吞吐已经达到瓶颈，需要考虑调大max-num-seqs、加卡或者横向扩容。如果 Running 数量明显低于配置上限，但 GPU 利用率已经很高，则说明序列生成本身已经接近硬件上限，继续加并发未必有效。

6. 高频问题与排查思路

6.1 加载 Qwen 9B 等中型模型爆显存

很多用户在部署 Qwen 7B/9B 级别模型时遇到显存不足，报错信息通常类似：

CUDA out of memory. Tried to allocate 512.00 MiB

这个问题的原因不只是模型权重，KV Cache 和 CUDA Graph 预留空间同样占据显存。排查流程如下：

先用nvidia-smi确认显卡总显存和当前占用，再计算权重所需显存。7B 模型在 bf16 下约需 14GB，9B 约需 18GB，基础权重已经占去一半以上显存。剩下的显存需要同时容纳 KV Cache 和 CUDA Graph。

解决方向包括：

• 将--max-num-seqs调低，比如 16 或 32；
• 将--max-model-len调低，比如 4096；
• 使用--enforce-eager关闭 CUDA Graph 的额外显存占用；
• 对权重做量化，比如 AWQ 4bit。

建议按“先减并发、再减长度、最后加量化”的顺序调试，避免一次性修改多个参数导致无法定位原因。

6.2 L20 等双卡服务器无法多卡运行模型

L20 显卡在 AI 推理服务器中非常常见，但很多用户反馈双卡跑大模型失败或吞吐异常低。

首先检查驱动和 CUDA 是否识别到两张卡：

nvidia-smi

如果只显示一张卡，先检查物理插槽、PCIe 通道或 BIOS 设置。如果两张卡都正常，再用张量并行启动，并把--tensor-parallel-size设置为 2。启动失败时重点看日志中是否出现 NCCL 相关错误，这往往意味着多卡通信初始化失败。

还有一个容易忽略的问题：L20 双卡之间如果没有 NVLink，而是通过 PCIe 通信，张量并行的吞吐提升会非常有限。此时建议改用数据并行，也就是用两个独立的 vLLM 进程分别加载模型副本，前面由负载均衡组件分发请求，效果可能更好。

6.3 昇腾等非 NVIDIA 平台无法启动 Embedding/Reranker

在昇腾 910B 服务器上使用 vLLM 启动 Embedding 和 Reranker 模型失败，通常是算子适配问题。昇腾的适配项目 vLLM-ASCEND 主要面向生成式 LLM，Embedding 池化和 Reranker 交叉编码相关的算子往往滞后甚至缺失。

如果必须在这类硬件上提供向量检索能力，建议两条路线：

• 改用原生的 MindIE 或昇腾相关推理方案；
• 使用专门的 Embedding 服务框架，并通过标准化 API 对外提供服务。

如果你只是生成式模型推理需要昇腾适配，则建议严格对照适配项目的支持矩阵选择模型和版本，不要盲目升级 vLLM 主线版本，否则可能破坏兼容性。

6.4 启动失败速查清单

7. 生产环境最佳实践

7.1 模型预热与平滑上线

vLLM 服务刚启动时，模型权重已经加载到显存，但第一次请求仍然会触发 CUDA kernel 的初始化和显存分配，响应延迟明显偏高。生产环境上线前，建议主动发送一批预热请求，覆盖典型的输入输出长度，让 CUDA Graph 缓存和显存分配提前稳定下来。

预热可以用简单的 Python 脚本完成，循环调用接口几十次。预热后再把服务切到生产流量，可以避免“上线即超时”的尴尬。

7.2 并发评估与容量规划

容量规划不能用“最大并发用户数”直接换算。更准确的做法是基于 token 吞吐量来评估。

假设单实例的 generation throughput 是 800 tokens/s，业务平均每个请求输出 300 token，那么这个实例每秒大约可以完成 2.7 个完整请求，换算成每分钟约 160 个请求。这样的估算方式比单纯看并发数更接近真实情况。

在压测时，建议使用真实业务 prompt 的分布，而不是统一的短文本。不同长度 prompt 的 prefill 时间和显存占用差异很大，会直接影响吞吐结果。

7.3 版本管理与灰度发布

vLLM 迭代速度极快，新版本可能带来性能提升，也可能引入 regression。生产环境不建议直接跟随 latest 版本。推荐做法是固定版本，并在测试环境用同一批压测脚本验证后再升级。

对于模型更新，同样需要灰度。可以利用--served-model-name把新旧模型同时部署在两个独立服务上，通过网关按比例分发流量。确认新模型质量稳定后，再逐步切换。

7.4 vLLM 与 SGLang 的选型建议

如果你正在搭建新的推理服务，可以在 vLLM 和 SGLang 之间做一次对比测试。vLLM 的优势是社区影响力大、OpenAI 兼容接口稳定、Embedding/多模态扩展方向清晰。SGLang 的优势是 RadixAttention 在长 prompt 和高并发复用场景下表现出色，多模态和结构化输出也做得很好。

我的建议比较务实：如果团队刚起步，优先选 vLLM，因为它遇到问题时更容易搜到答案。如果业务主要是复杂提示词、多轮对话、代码生成等重度前缀复用场景，并且团队有算法工程能力做针对性调优，再考虑 SGLang。

7.5 监控、告警与安全边界

生产环境的推理服务必须纳入监控。至少要采集以下指标：

• GPU 利用率、显存使用率、显存温度；
• 平均 prefill tokens/s 和 generation tokens/s；
• 请求排队数、P99 延迟；
• 错误率与超时数。

安全方面，vLLM 默认提供的 API 接口没有鉴权机制。如果服务暴露在非可信网络，必须在网关层增加 API Key 校验、IP 白名单和请求频率限制，避免被刷爆显存。

权限管理遵循最小权限原则：推理服务账号不应具备模型文件所在目录的写权限，模型更新应该通过独立流程执行，运维人员与开发人员的权限需分开管理。涉及模型替换或配置变更时，先在测试环境验证，再走生产变更流程，必要时提前备份原始权重。