1. 背景与目标
在前两个阶段，我们已经完成了 Agent 的搭建与基础功能联调，核心链路依赖 OpenAI API 提供的 GPT 系列模型。虽然效果不错，但随之而来的问题是：调用成本随使用频率线性增长，且数据需出域、延迟受公网波动影响。
本阶段的目标很明确：
在本地（或自有 GPU 服务器）部署一套vLLM + 量化模型的推理服务，通过 OpenAI 兼容接口无缝替换云端 API，让 Agent 在几乎不修改业务代码的前提下跑在自托管模型上，同步展示部署与降本能力。
完成后，整体架构从：
Agent → OpenAI API（公网、按 token 计费）切换为：
Agent → 自建推理网关（vLLM，OpenAI 兼容协议）→ 本地量化模型2. 为什么选择 vLLM + 量化
2.1 vLLM 的优势
vLLM 是目前社区活跃度最高的高性能 LLM 推理框架之一，核心优势在于：
- PagedAttention 机制：显存利用率大幅提升，支持更高并发。
- Continuous Batching：动态合并请求，吞吐量显著高于原生 transformers。
- OpenAI 兼容接口：原生提供
/v1/chat/completions、/v1/completions，Agent 侧几乎零改动。 - 量化模型友好：支持 AWQ、GPTQ、FP8 等多种量化格式。
2.2 量化的意义
量化是在可接受精度损失范围内，显著降低显存占用与推理延迟的有效手段。以 7B 模型为例：
| 精度 | 显存占用（约） | 说明 |
|---|---|---|
| FP16 | 14 GB | 基线 |
| AWQ 4-bit | 5～6 GB | 体积减半以上，速度提升明显 |
| FP8 | 8 GB | 需要 H100/H20 及以上硬件支持 |
对于单卡 24 GB（如 4090、A10、L4）的环境，量化几乎是部署 7B～14B 模型的必经之路。
3. 环境准备
3.1 硬件建议
| 场景 | 推荐配置 |
|---|---|
| 个人实验 | 单卡 24 GB（RTX 4090 / A10） |
| 团队共用 | 单卡 48 GB（A40 / L40S）或双卡推理 |
| 生产级并发 | 多卡 + Tensor Parallel |
本阶段以单卡 24 GB、部署 7B 量化模型为例进行说明。
3.2 软件环境
# 建议使用 Python 3.10python--version# 创建独立环境python-mvenv vllm_envsourcevllm_env/bin/activate# 升级 pippipinstall--upgradepip4. 安装 vLLM
vLLM 现在提供了非常方便的安装方式，直接通过 pip 即可完成：
pipinstallvllm如果你的 CUDA 版本与默认构建不匹配，可以去 vLLM 官方文档查看对应的安装指令。以 CUDA 12.1 环境为例：
pipinstallvllm --index-url https://download.pytorch.org/whl/cu121安装完成后验证：
python-c"import vllm; print(vllm.__version__)"5. 选择并下载量化模型
本阶段推荐使用Qwen2.5-7B-Instruct-AWQ，理由如下：
- 中文能力强，适合 Agent 的中文指令场景。
- 官方提供 AWQ 4-bit 版本，开箱即用。
- 显存占用约 6 GB，单卡 24 GB 环境可留出充足余量跑长上下文。
下载模型：
fromhuggingface_hubimportsnapshot_download model_path=snapshot_download(repo_id="Qwen/Qwen2.5-7B-Instruct-AWQ",local_dir="./models/Qwen2.5-7B-Instruct-AWQ")print(model_path)也可以使用 ModelScope 加速国内下载：
pipinstallmodelscopefrommodelscopeimportsnapshot_download model_path=snapshot_download("Qwen/Qwen2.5-7B-Instruct-AWQ",local_dir="./models/Qwen2.5-7B-Instruct-AWQ")6. 启动 vLLM 推理服务
6.1 基础启动命令
vllm serve ./models/Qwen2.5-7B-Instruct-AWQ\--host0.0.0.0\--port8000\--max-model-len8192\--gpu-memory-utilization0.85\--dtypeauto参数说明：
| 参数 | 作用 |
|---|---|
--host 0.0.0.0 | 允许局域网访问 |
--port 8000 | 服务端口 |
--max-model-len 8192 | 最大上下文长度 |
--gpu-memory-utilization 0.85 | 显存占用上限，留出 KV Cache 余量 |
--dtype auto | 自动识别量化格式 |
6.2 验证服务
服务启动后，用 curl 快速探测：
curlhttp://localhost:8000/v1/models预期返回模型列表，确认/v1端点已就绪。再测一遍对话：
curlhttp://localhost:8000/v1/chat/completions\-H"Content-Type: application/json"\-d'{ "model": "Qwen2.5-7B-Instruct-AWQ", "messages": [ {"role": "user", "content": "用一句话介绍 vLLM"} ], "temperature": 0.7 }'7. 将 Agent 切换到本地 vLLM
这是本阶段最关键的一步：让上一步的 Agent 用本地模型替换 OpenAI API，同时尽量少改代码。
由于 vLLM 提供了 OpenAI 兼容协议，绝大多数 OpenAI SDK 场景只需要修改三个配置项：
7.1 使用 OpenAI SDK 直接切换
原来连接 OpenAI 的代码可能类似：
fromopenaiimportOpenAI client=OpenAI(api_key="sk-xxxx",# 原来填 OpenAI 密钥base_url="https://api.openai.com/v1")现在只需更换base_url与api_key：
fromopenaiimportOpenAI client=OpenAI(api_key="EMPTY",# vLLM 默认不校验，占位即可base_url="http://127.0.0.1:8000/v1")后续调用逻辑完全不用变：
response=client.chat.completions.create(model="Qwen2.5-7B-Instruct-AWQ",messages=[{"role":"system","content":"你是一个严谨的代码助手。"},{"role":"user","content":"帮我设计一个日志采集模块。"}],temperature=0.7)print(response.choices[0].message.content)7.2 使用 LangChain 场景切换
如果 Agent 基于 LangChain 构建，同样只需要改两行：
fromlangchain_openaiimportChatOpenAI llm=ChatOpenAI(model="Qwen2.5-7B-Instruct-AWQ",openai_api_key="EMPTY",openai_api_base="http://127.0.0.1:8000/v1",temperature=0.7)7.3 Agent 工具调用注意事项
如果上一阶段的 Agent 依赖Function Calling，需要注意：
- Qwen2.5-Instruct 系列本身支持工具调用，vLLM 下需要加上
--enable-auto-tool-choice --tool-call-parser hermes参数以正确解析函数调用格式。 - 建议把提示词中的模型相关描述改成对本地模型的描述，避免模型"自报家门"出现偏差。
对应启动命令升级为：
vllm serve ./models/Qwen2.5-7B-Instruct-AWQ\--host0.0.0.0\--port8000\--max-model-len8192\--gpu-memory-utilization0.85\--dtypeauto\--enable-auto-tool-choice\--tool-call-parser hermes8. 部署效果与降本分析
8.1 单请求延迟对比
在同一台服务器上，对比云端 API 与本地 vLLM 的端到端延迟（单请求、512 token 输出）：
| 链路 | 平均延迟 | 备注 |
|---|---|---|
| OpenAI API（公网） | 8～15 s | 受网络与排队影响 |
| 本地 vLLM + AWQ | 3～6 s | 无公网往返，稳定 |
本地部署在网络敏感场景下优势明显，延迟抖动显著降低。
8.2 成本模拟对比
假设团队每天调用 10 万 token（包含输入与输出），一个月约 300 万 token：
| 方案 | 月估算成本 | 说明 |
|---|---|---|
| 云端 GPT-4 级 API | 数千元级 | 按 token 计费，随用量上升 |
| 本地 vLLM + 7B AWQ | 电费 + 折旧约数百元 | 一次性硬件投入外，边际成本极低 |
实际成本会因 token 单价、硬件折旧方式不同而变化，此处只做数量级对比。核心结论是：使用量越大，本地部署的相对成本优势越明显。
8.3 并发吞吐测试
可使用 vLLM 自带的 benchmark 脚本进行简单压测：
python-mvllm.entrypoints.openai.benchmark\--base-url http://127.0.0.1:8000/v1\--modelQwen2.5-7B-Instruct-AWQ\--num-prompts50\--request-rate2重点关注Throughput与TTFT（首 token 时间）两个指标，便于后续调优对比。
9. 常见问题与优化建议
9.1 显存不足
若启动时 OOM，降低--max-model-len或--gpu-memory-utilization：
--max-model-len4096--gpu-memory-utilization0.79.2 输出被截断
检查max_tokens设置，并确认--max-model-len足够容纳完整上下文。
9.3 高并发下延迟上升
可开启 Prefix Caching 复用公共前缀（如固定的 system prompt）：
--enable-prefix-caching对于固定 system prompt 的 Agent 场景，该优化通常能显著降低 TTFT。
9.4 生产化建议
- 使用
systemd或 Docker 守护 vLLM 进程，避免异常退出。 - 通过 Nginx 反向代理统一入口，便于后续多模型路由与鉴权。
- 定期保存并回放线上日志样本，用于量化模型的效果回归。
10. 小结
本阶段完成了从「云端 API 依赖」到「本地自托管推理」的关键切换：
- 使用 vLLM 部署了 Qwen2.5-7B-Instruct-AWQ 量化模型。
- 通过 OpenAI 兼容接口，仅修改
base_url和api_key即完成 Agent 接入。 - 对比了延迟、成本与并发表现，验证了本地部署在降本与稳定性上的价值。
- 针对 Function Calling、高并发、显存受限等场景给出了可落地的优化方案。
这一步不只是"能跑通"，更重要的是证明了：在控制成本的前提下，团队完全有能力将核心模型能力掌握在自己手中，为后续私有化交付、行业定制微调打下基础。
