用云端大模型跑 Agent，最怕三件事：账单失控、数据出域、限流卡脖子。vLLM 是当下最主流的高吞吐开源推理引擎，最香的一点是——它暴露的 API 和 OpenAI 几乎一模一样。你的 Agent 代码一行不用改，只要把 base_url 从 api.openai.com 指到 localhost:8000/v1，后端就从「租别人的模型」变成「自己的显卡」。
🚀 本教程适合：想私有化 Agent 后端、降本、或做高并发推理的开发者 / 运维。你需要一台带 NVIDIA GPU 的 Linux 机器（显存越大能跑的模型越大），以及 Python 3.9+。
先搞懂：vLLM 给你什么？
vLLM 的核心卖点是 PagedAttention + 连续批处理（continuous batching），吞吐通常是原生 HuggingFace 推理的 2–10 倍。对我们做 Agent 最关键的是它实现了 /v1/chat/completions 等 OpenAI 兼容端点，因此：
| 直接调 HF 模型 | vLLM OpenAI 兼容服务 |
|---|---|
| 要自己写推理循环 | 直接复用 OpenAI SDK |
| 并发一高就 OOM | 连续批处理，高并发稳 |
| 无流式 / 无工具调用 | 支持 stream + tool_calls |
它不能「让小显卡跑大模型」。显存不够该量化量化、该换小模型换小模型。vLLM 解决的是「吞吐与易用」，不是「显存魔法」。
Step 1：环境准备与安装
1 装 vLLM（自带 CUDA 依赖）
# 建议用虚拟环境
python -m venv venv && source venv/bin/activate
pip install vllm
# 验证
python -c "import vllm; print(vllm.__version__)"💡 用 pip 装的 vLLM 会带匹配的 CUDA 版本，省去配驱动之苦。若你机器是较新的 Blackwell（如 B 系列）显卡，请装最新版 vLLM 以获得支持。
Step 2：一行命令起服务
2 启动 OpenAI 兼容 API 服务
python -m vllm.entrypoints.openai.api_server \
--model Qwen/Qwen3-8B \
--host 0.0.0.0 --port 8000 \
--tensor-parallel-size 1启动后访问 http://localhost:8000/v1/models 应返回模型信息。这一步你的「私有 GPT」就已经在线了。
生产环境千万别直接 --host 0.0.0.0 裸奔到公网。至少加反向代理 + 鉴权（见 Step 7）。本地联调无所谓。
Step 3：用 OpenAI 客户端连本地
3 改一行 base_url 即可
from openai import OpenAI
client = OpenAI(
base_url="http://localhost:8000/v1",
api_key="EMPTY", # 本地服务无 key，占位即可
)
resp = client.chat.completions.create(
model="Qwen/Qwen3-8B",
messages=[{"role":"user","content":"用一句话解释什么是 Agent"}],
stream=True,
)
for chunk in resp:
print(chunk.choices[0].delta.content or "", end="")💡 你的 Agent 框架（LangGraph / OpenAI Agents SDK / 自建循环）只要把
base_url 指过来，工具调用、流式输出全部照常工作——这就是 OpenAI 兼容的红利。Step 4：量化与显存优化
4 显存不够就上量化
python -m vllm.entrypoints.openai.api_server \
--model Qwen/Qwen3-8B \
--quantization awq \ # 或 gptq / fp8
--gpu-memory-utilization 0.90 \
--max-model-len 8192量化有精度代价。Agent 的「推理 / 工具选择」对精度较敏感，先在小流量上对比 AWQ 与 fp8 的效果再定型，别一上来就压到最狠。
Step 5：并发与吞吐调优
5 让多 Agent 同时打也不崩
python -m vllm.entrypoints.openai.api_server \
--model Qwen/Qwen3-8B \
--max-num-seqs 256 \ # 并发序列数
--enable-prefix-caching \ # 系统提示词前缀缓存，省 token
--disable-log-requests🚀
--enable-prefix-caching 对 Agent 特别有用：每轮对话都带同一段 system prompt，命中缓存后首 token 延迟大幅下降。Step 6 & 7：多卡、多模型与生产化
6 多卡切分与多模型
# 两张卡跑一个大模型
--tensor-parallel-size 2
# 同时挂多个模型（各占一份显存）
--served-model-name my-agent-qwen # 给客户端看的别名第 7 步把它变成「服务」而非「terminal 进程」：用 Docker 或 systemd 托管，并加鉴权与限流：
# 前置 Nginx / Caddy 反代 + API Key 校验
# systemd 示例核心行
ExecStart=/opt/venv/bin/python -m vllm.entrypoints.openai.api_server --model Qwen/Qwen3-8B --port 8000🎉 到这一步，你拥有了一个私有、高吞吐、OpenAI 兼容的 Agent 后端。把全公司 Agent 的 base_url 统一指过来，成本与数据主权都拿回来了。
常见问题速查
| 现象 | 大概率原因 & 解决 |
|---|---|
| 启动报 CUDA / 驱动不匹配 | vLLM 版本与显卡驱动不匹配，升级驱动或换对应 vLLM 版本 |
| 显存爆了（OOM） | 降 max-model-len、上量化、或换更小模型 |
| 客户端连不上 | 确认端口放行；云服务器注意安全组；别裸 0.0.0.0 暴露公网 |
| tool_calls 不返回 | 模型本身需支持函数调用；确认 served-model-name 与请求 model 一致 |