共计 3353 个字符，预计需要花费 9 分钟才能阅读完成。
如果你平时只是自己终端里敲两句对话，ollama run qwen2.5:14b 确实够方便。但当我上个月把本地模型接入 Cursor 代码补全、Dify 知识库检索以及自建的 Multi-Agent 工作流时，Ollama 很快就扛不住了：多客户端突发请求直接排队十几秒、上下文稍微一长显存就剧烈抖动，并发吞吐量几乎掉到个位数。
单张消费级 24G 显存卡（RTX 3090 或 4090）完全有能力承担小团队内部的高性能 API 网关。要达成这一目标，核心是换掉默认的通用后端，切换到底层支持 PagedAttention 和 动态前缀缓存（Automatic Prefix Caching） 的专用推理引擎。本文记录我使用 vLLM + LiteLLM 搭建生产级私有大模型网关的完整流程与压测避坑经验。
一、核心架构：为什么是 vLLM + LiteLLM？
直接给下游客户端暴露原始推理端口非常脆弱。在实际业务中，我们通常需要：统一的 OpenAI 协议分发、多 Key 权限隔离、速率控制，以及流式请求故障熔断。因此，极客最推荐的轻量拓扑是：
- 推理引擎（vLLM）： 负责纯粹的 GPU 显存调度、张量并行与高速批处理生成（Continuous Batching）。
- API 网关（LiteLLM Proxy）： 负责多模型聚合、请求鉴权、RPM/TPM 限流，以及将请求无感路由到备用云端 API（做 Fallback）。
- 下游消费端：Cursor、Cline（VS Code 插件）、Obsidian 本地插件及内部自动化脚本。
二、显存规划与 vLLM 核心参数避坑
在 24G 显卡上部署一个 14B Q4 量化（如 AWQ）或 7B/8B FP16 模型，显存分配必须精打细算。很多开发者在启动脚本中无脑照抄参数，导致运行时频繁抛出 CUDA OOM 错误。
1. 算清两笔显存账：权重显存 vs KV Cache 显存
以 Qwen2.5-14B-Instruct-AWQ 为例，模型量化后静态权重约占 9.5 GB。24GB 显存扣除后，理论上还有约 14.5 GB 可以分配给上下文的 KV Cache。
# 错误的启动参数示例（极易炸显存）vllm serve Qwen/Qwen2.5-14B-Instruct-AWQ \
--gpu-memory-utilization 0.99 \
--max-model-len 32768 避坑点 1：--gpu-memory-utilization 绝不能设 0.99。
PyTorch 初始化、CUDA Context 以及临时激活值计算必须预留空间。在消费级卡上，建议设为 0.88 ~ 0.92。设得过高，一旦并发上来出现动态张量分配，显卡会瞬间抛出 RuntimeError: CUDA out of memory。
避坑点 2：开启前缀缓存（Automatic Prefix Caching）。
Agent 和代码补全有一个鲜明特征： 系统 Prompt（System Prompt）和大量前缀代码是高度重复的 。开启 --enable-prefix-caching 后，vLLM 会对已经计算过 KV 的前缀块进行哈希缓存，后续请求命中缓存时，首字延迟（TTFT）能从原来的 1.2 秒骤降到 80 毫秒以内。
三、Docker Compose 一键生产级编排
使用容器化编排可以彻底解决 CUDA 驱动污染宿主机的问题。以下是我验证过的稳定配置：
version: '3.8'
services:
vllm-engine:
image: vllm/vllm-openai:v0.6.3.post1
container_name: vllm-qwen14b
runtime: nvidia
deploy:
resources:
reservations:
devices:
- driver: nvidia
count: 1
capabilities: [gpu]
shm_size: '16gb'
environment:
- HF_HUB_ENABLE_HF_TRANSFER=1
volumes:
- /data/models/huggingface:/root/.cache/huggingface
command: >
--model Qwen/Qwen2.5-14B-Instruct-AWQ
--quantization awq
--gpu-memory-utilization 0.90
--max-model-len 16384
--enable-prefix-caching
--enforce-eager
--served-model-name qwen-14b
ports:
- "8000:8000"
restart: unless-stopped
litellm-proxy:
image: ghcr.io/berriai/litellm:main-v1.52.0
container_name: litellm-gateway
volumes:
- ./litellm-config.yaml:/app/config.yaml
command: ["--config", "/app/config.yaml", "--port", "4000"]
ports:
- "4000:4000"
depends_on:
- vllm-engine
restart: unless-stopped关键参数解释：
shm_size: '16gb'： 必填！ PyTorch 底层通过共享内存进行张量通信。默认 Docker 的 shm 只有 64MB，高并发下直接报错Bus error (core dumped)。--enforce-eager：对于 24G 显存单卡，跳过 Torch 编译阶段（Eager 模式）不仅能大幅缩短启动时间，还能防止 PyTorch 2.x 的 Inductor 预热占用近 2GB 的额外固定显存。
四、LiteLLM 路由与鉴权配置
新建 litellm-config.yaml，用于统一分发 API 并设置流控：
model_list:
- model_name: codellm
litellm_params:
model: openai/qwen-14b
api_base: http://vllm-engine:8000/v1
api_key: "none"
litellm_settings:
drop_params: true
request_timeout: 60
general_settings:
master_key: sk-nassky-master-key-2026
database_url: "sqlite:////app/litellm.db" 启动后，LiteLLM 提供了完全兼容 OpenAI 的标准接口 http://<IP>:4000/v1/chat/completions。在 Cursor 或 Cline 中直接填入该端点，并设置自定义 API Key 即可稳定使用。
五、压测对比：吞吐与延迟提升实测
我使用自写的并发测试脚本，模拟 8 个并发客户端连续向本地服务发送包含 2000 tokens 上下文（其中 1500 tokens 为通用 System Prompt）的代码补全请求：
- 方案 A（Ollama 原生配置，默认 4 并发）： 平均首字时间（TTFT）约 4.8 秒，总吞吐量维持在 18.2 tokens/s 左右，峰值时出现请求重试。
- 方案 B（vLLM + Prefix Caching 开启）： 平均首字时间直接缩短至 0.31 秒 ，总聚合吞吐量飙升至 87.6 tokens/s，显存占用稳定在 21.8 GB，未发生一次抖动。
六、极客排障手记
1. 为什么下载 HuggingFace 模型慢如蜗牛？
在 Compose 中注入环境变量 HF_HUB_ENABLE_HF_TRANSFER=1 并提前安装 Rust 编写的 hf_transfer，可以跑满千兆带宽。如果网络受限，直接指定国内镜像端点 HF_ENDPOINT=https://hf-mirror.com。
2. 量化后端 Marlin 报算力不兼容？
AWQ 模型加载时默认可能会尝试调用 Marlin 内核提速。如果遇到 AssertionError: ... Compute capability must be >= 8.0 错误，请确保你的 CUDA 驱动版本不低于 12.1，并在驱动配置中核验是否为 Ampere (RTX 30 系) 或更高架构。
单卡折腾大模型推理的核心原则永远是： 不要盲目追求大参数，把 14B/8B 模型的 KV Cache 调度和命中率榨干，实际体验远比卡顿卡死的 32B 舒服得多。
