注意
vLLM 可作为生产级部署，本文只是对其的基本演示，未进行调优。在本书中的其余部分推荐使用 LM Studio 运行本地大模型。
本节我们将在 Mac Mini M4 上使用 vLLM 构建本地推理服务。
背景原理与核心概念
vLLM（virtual LLM）是一个高性能的本地大模型推理引擎，旨在加速大语言模型的推理速度和吞吐量。它的核心创新包括 PagedAttention 等机制，通过高效管理 Attention 计算和缓存，实现对多请求的连续批处理调度，极大提升了硬件利用率。简单来说，与直接使用 Hugging Face Transformers 推理相比，vLLM 可以更充分地利用内存和算力，在同样硬件上获得数倍的吞吐性能提升。
值得一提的是，vLLM 提供了OpenAI API兼容的 HTTP 服务接口。也就是说，我们可以用与调用 OpenAI 的 GPT-3/4 接口相同的方式，调用本地部署的模型。这对于将现有应用从云端 API 切换到本地非常便利，因为客户端代码几乎无需改动。vLLM 当前支持 OpenAI 的 /v1/completions 和 /v1/chat/completions 等端点，兼容大部分请求参数。开发者也可以使用 OpenAI 官方的 Python SDK，只需将 api_base 指向本地服务器并提供本地 API Key 即可。
平台兼容性：vLLM 最初为 GPU 设计，但也支持 CPU 后端。对于 Mac Mini 这类没有 NVIDIA GPU 的设备，vLLM 已支持 ARM 架构 CPU（Apple Silicon）的推理和服务，不过需要从源码编译安装。官方将对 macOS/Apple Silicon 的支持标注为实验性，意味着性能相对 GPU 会较低，但可满足小模型 CPU 推理的需求。由于缺少预编译的安装包，我们需要手动构建 CPU 版本。
vLLM 架构
vLLM 的架构有以下特点：
- 架构分层清晰：从用户 API 到调度器，再到核心执行引擎，最后统一返回。
- 关键创新点：
- Continuous Batching：动态合并请求，提升吞吐。
- PagedAttention：分页存储 KV Cache，提高显存利用率和并发能力。
- 易用性：兼容 OpenAI API，不需要开发者修改代码即可切换到本地推理。
下图展示了 vLLM 的架构。
【iframe defaul_iframe_type】https://assets.jimmysong.io/images/book/ai-handbook/vllm/local-inference/9a6c3715a3a9d7beeb123392e8bbe8ac.svg
图 1: vLLM 架构图
vLLM 的分层架构说明：
- 用户请求层
- 应用通过 OpenAI API 格式（/v1/completions 或 /v1/chat/completions）发送请求。
- vLLM 内置一个 API Server，兼容 OpenAI 协议，方便集成。
- 调度与批处理层
- 请求调度器（Scheduler）：收集多个用户请求，决定哪些请求可以一起处理。
- 连续批处理（Continuous Batching）：即使请求长度不同，也能动态合并，避免 padding 浪费。
- PagedAttention 引擎 & 执行层
- 管理 KV Cache，采用分页存储（Page Pool）。
- 类似“虚拟内存”，显存利用率高，支持高并发。
- 基于 PyTorch / CUDA 内核运行 Transformer 模型。
- 支持 vLLM 的优化算子，如高效 KV 管理、并行解码。
- 输出层
- 生成结果返回给 API Server。
- 响应格式与 OpenAI 保持一致，开发者无缝切换。
Attention vs PagedAttention
在大模型推理中，Attention 机制 是核心计算模块，而 KV Cache（Key-Value 缓存）用于存储中间计算结果以加速生成过程。传统的 Attention KV Cache 需要为每个请求分配一块连续的显存，这在高并发场景下容易导致显存碎片化，影响性能。
下图展示了 传统 Attention KV Cache 和 vLLM 的 PagedAttention 对比。
【iframe defaul_iframe_type】https://assets.jimmysong.io/images/book/ai-handbook/vllm/local-inference/7e14a3edbf344876e8663d70e431e826.svg
图 2: Attention vs PagedAttention
- 左边（PagedAttention）：把 KV Cache 拆成小的 page，集中放到“Page 池”里统一调度。不同请求只需要维护一个“页表映射”，就能复用显存，极大提高并发吞吐。
- 右边（传统方式）：每个请求都要一整块连续显存来存 KV Cache，随着请求数量和长度增加，很快会出现碎片，导致显存浪费。
安装与运行步骤（适配 macOS）
环境准备：确保 macOS 已经安装最新的开发者工具（Xcode Command Line Tools）以及 Python 3.9+。首先安装 PyTorch（CPU 或 MPS 版本）和必要依赖：
# 安装最新pip和必要依赖
pip install --upgrade pip setuptools packaging ninja numpy
# 安装支持Apple Metal加速的PyTorch（也可选CPU版）
pip install torch torchvision接下来获取 vLLM 源码并编译安装 CPU 后端：
git clone https://github.com/vllm-project/vllm.git
cd vllm
# 尝试直接安装（可能会尝试CUDA编译而失败）
pip install -e .
# 如果遇到 "Cannot find CUDA_HOME" 错误，则禁用CUDA：
export VLLM_TARGET_DEVICE=cpu
export VLLM_BUILD_WITH_CUDA=0
pip install -e .提示
上述环境变量会让安装过程跳过 CUDA 组件，仅编译 CPU 后端。如无意外，vLLM 会在几分钟内编译完成。
上述命令会在本地启动 HTTP 服务（默认需提供一个
--api-key参数设置访问令牌，可用--api-key token-abc123设置一个自定义令牌）。这里我们指定--dtype float16以减少 CPU 内存占用，并使用小模型 OPT-125M 以适配 Mac Mini 性能。启动成功后，vLLM 会下载并加载模型权重，然后开始监听端口。
使用小模型快速验证 vLLM 安装
如果你想快速验证 vLLM 是否可用，可以使用更小的模型 facebook/opt-125m 来启动服务：
# 设置不使用 CUDA，仅用 CPU 运行export VLLM_USE_CUDA=0
python3 -m vllm.entrypoints.openai.api_server
--model facebook/opt-125m
--host 0.0.0.0 --port 8000
--dtype float16然后使用 cURL 测试：
curl -s http://127.0.0.1:8000/v1/completions
-H "Content-Type: application/json"
-H "Authorization: Bearer token-abc123"
-d '{ "model": "facebook/opt-125m",
"prompt": "how are you doing today?",
"max_tokens": 100,
"temperature": 0.7
}如果可以正确返回结果，表示 vLLM 安装成功。
运行服务：安装成功后，即可启动本地 OpenAI 兼容服务。
export VLLM_USE_CUDA=0
export HF_ENDPOINT=https://hf-mirror.com # 这个模型是公开的，不需要单独的 token 就能下载。但如果你在中国大陆网络环境下，访问 Hugging Face 可能会被限速或阻断，可以加上镜像
export VLLM_CPU_KVCACHE_SPACE=4 # GiB；按内存可调，先保守点
python3 -m vllm.entrypoints.openai.api_server
--model Qwen/Qwen2.5-1.5B-Instruct
--host 0.0.0.0 --port 8000
--dtype float32
--enforce-eager
--max-model-len 4096
--max-num-batched-tokens 4096这里选择 Qwen 是因为它比起 Facebook 的模型对中文支持更好，具体来说你可以选择：
- 最省内存/最快：
Qwen/Qwen2.5-0.5B-Instruct
- 适合先把链路打通；中文可用，但生成质量一般。
- 平衡质量/速度：
Qwen/Qwen2.5-1.5B-Instruct
- 中文明显更好，CPU 还能跑得动；建议首选
粗略内存（仅权重 fp32）：0.5B≈2 GB、1.5B≈6 GB。再加 KV Cache（由 max-model-len 决定），所以我们把上下文降到 4K 更省内存。
示例调用
服务就绪后，可以用 curl 或 OpenAI 官方 SDK 来调用本地模型。以下是使用 curl 调用 Chat Completions 接口的示例：
curl -s http://127.0.0.1:8000/v1/chat/completions
-H "Content-Type: application/json"
-d '{
"model": "Qwen/Qwen2.5-1.5B-Instruct",
"messages": [{"role":"user","content":"你好！请用一句话介绍大语言模型。"}],
"max_tokens": 100
}'|jq .上述请求会 POST 到本地 vLLM 服务，并指定模型、对话消息列表等参数。如果调用成功，vLLM 将返回一个与 OpenAI API 格式一致的 JSON 响应，其中choices[0].message.content就是模型生成的回复。
将看到类似下面的响应：
{
"id": "chatcmpl-826c4180ff3a4a0daa03dc5263f820aa",
"object": "chat.completion",
"created": 1758536008,
"model": "Qwen/Qwen2.5-1.5B-Instruct",
"choices": [
{
"index": 0,
"message": {
"role": "assistant",
"content": "好的，以下是一个简单的大语言模型的介绍：</br></br>我是一个基于深度学习和自然语言处理技术开发的语言模型，能够理解和生成人类语言，并能回答问题、创作故事、提供解释等。我的目标是尽可能地准确、流畅地与用户交流。",
"refusal": null,
"annotations": null,
"audio": null,
"function_call": null,
"tool_calls": [],
"reasoning_content": null
},
"logprobs": null,
"finish_reason": "stop",
"stop_reason": null,
"token_ids": null
}
],
"service_tier": null,
"system_fingerprint": null,
"usage": {
"prompt_tokens": 39,
"total_tokens": 95,
"completion_tokens": 56,
"prompt_tokens_details": null
},
"prompt_logprobs": null,
"prompt_token_ids": null,
"kv_transfer_params": null
}也可以使用 OpenAI 的 Python 库，只需将
openai.api_base设置为本地 URL 并提供匹配的api_key，即可像平时调用 OpenAI 一样调用本地模型。例如：
from openai import OpenAI
# For openai>=1.0.0
client = OpenAI(
base_url="http://localhost:8000/v1",
api_key="dummy"
)
response = client.chat.completions.create(
model="Qwen/Qwen2.5-1.5B-Instruct",
messages=[{"role": "user", "content": "敢问路在何方？"}]
)
print(response.choices[0].message.content)总结
- vLLM 特点：开源的高性能推理引擎，利用高效的内存管理和调度技术（如 PagedAttention）提升多并发生成任务的吞吐量。在有限算力下也能充分挖掘模型性能，已成为业界常用的本地部署方案之一。
- OpenAI 接口兼容：vLLM 内置兼容 OpenAI REST API 的服务器，实现了
/v1/completions和/v1/chat/completions等端点。这使得我们可以很容易将现有应用从 OpenAI 切换到本地服务，只需改变 API 地址和密钥，降低了集成成本。
- 在 CPU 上运行：vLLM 支持纯 CPU 运行，包括 ARM 架构的 Mac 设备。虽然性能不及 GPU，但通过使用小模型（如几十亿参数以下）或量化模型（int4/int8 等）可以在 Mac Mini 上实现可用的响应速度。vLLM 也支持 FP16/BF16 等低精度，在 CPU 上默认使用 BF16 以兼顾性能。
- 资源占用与优化：对比传统 Transformers 推理，vLLM 能动态批量处理请求，提高 GPU/CPU 利用率；此外还支持高效的 KV 缓存管理，使得长上下文或多轮对话的生成开销更低。这些优化手段使 vLLM 在学术和工业测试中比常规实现最高快了 20 倍以上。
- 应用场景：当客户希望在本地或私有环境部署 ChatGPT 类服务时，vLLM 是一个理想选择。它结合了开源模型和高性能引擎，既避免了敏感数据外发，又提供了接近云服务的使用体验。
