草稿

使用 vLLM 部署本地推理服务

本地大模型推理不再遥不可及，vLLM 让你的 Mac 也能拥有“专属 GPT”，高效、安全、完全自主。

注意
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 的架构。

图 1: vLLM 架构图
图 1: vLLM 架构图

vLLM 的分层架构说明：

  1. 用户请求层
    • 应用通过 OpenAI API 格式（/v1/completions 或 /v1/chat/completions）发送请求。
    • vLLM 内置一个 API Server，兼容 OpenAI 协议，方便集成。
  2. 调度与批处理层
    • 请求调度器（Scheduler）：收集多个用户请求，决定哪些请求可以一起处理。
    • 连续批处理（Continuous Batching）：即使请求长度不同，也能动态合并，避免 padding 浪费。
  3. PagedAttention 引擎 & 执行层
    • 管理 KV Cache，采用分页存储（Page Pool）。
    • 类似“虚拟内存”，显存利用率高，支持高并发。
    • 基于 PyTorch / CUDA 内核运行 Transformer 模型。
    • 支持 vLLM 的优化算子，如高效 KV 管理、并行解码。
  4. 输出层
    • 生成结果返回给 API Server。
    • 响应格式与 OpenAI 保持一致，开发者无缝切换。

Attention vs PagedAttention

在大模型推理中，Attention 机制 是核心计算模块，而 KV Cache（Key-Value 缓存）用于存储中间计算结果以加速生成过程。传统的 Attention KV Cache 需要为每个请求分配一块连续的显存，这在高并发场景下容易导致显存碎片化，影响性能。

下图展示了 传统 Attention KV Cache 和 vLLM 的 PagedAttention 对比。

图 2: Attention vs PagedAttention
图 2: Attention vs PagedAttention
  • 左边（PagedAttention）：把 KV Cache 拆成小的 page，集中放到“Page 池”里统一调度。不同请求只需要维护一个“页表映射”，就能复用显存，极大提高并发吞吐。
  • 右边（传统方式）：每个请求都要一整块连续显存来存 KV Cache，随着请求数量和长度增加，很快会出现碎片，导致显存浪费。

安装与运行步骤（适配 macOS）

环境准备：确保 macOS 已经安装最新的开发者工具（Xcode Command Line Tools）以及 Python 3.9+。首先安装 PyTorch（CPU 或 MPS 版本）和必要依赖：

💻 安装必要依赖
1
2
3
4

# 安装最新pip和必要依赖
pip install --upgrade pip setuptools packaging ninja numpy
# 安装支持Apple Metal加速的PyTorch（也可选CPU版）
pip install torch torchvision

接下来获取 vLLM 源码并编译安装 CPU 后端：

💻 编译安装 vLLM
1
2
3
4
5
6
7
8

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 兼容服务。

💻 启动 vLLM 服务
 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11

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 调用 Chat Completions
1
2
3
4
5
6
7

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就是模型生成的回复。

将看到类似下面的响应：

📋 vLLM Chat Completions 响应示例
 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36

{
  "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 一样调用本地模型。例如：

📄 使用 OpenAI Python SDK 调用 vLLM
 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13

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 是一个理想选择。它结合了开源模型和高性能引擎，既避免了敏感数据外发，又提供了接近云服务的使用体验。
发布于: 2025/09/22 • 最后更新: 2025/11/04 • 字数: 3343 • 阅读时间: 7 mins

文章导航

章节内容

这是章节的内容页面。

章节概览