共计 4419 个字符，预计需要花费 12 分钟才能阅读完成。
很多朋友在搭建本地大模型服务或对接内部 Agent 时，第一反应往往是起一个 Ollama 容器，或者直接用 Hugging Face 官方的 generate() 接口包一层 FastAPI。在自己玩单轮对话时，一切看似丝滑；但只要把并发打到 10 以上，或者 Agent 丢过来几段长达 4k tokens 的 RAG 检索上下文，服务瞬间就会出现明显的排队卡死、显存 OOM，首字延迟（TTFT）直接飙到几十秒。
上个月在重构我们团队内部代码助手和文档问答网关时，我彻底弃用了早期的简易封装方案，基于 vLLM + Ray + SSE（Server-Sent Events） 重新搭了一套单节点多卡高吞吐推理底座。在单张 RTX 4090（24G）上跑 Qwen2.5-7B-Instruct，支撑 20+ 真实并发下的平均 TTFT 压到了 180ms 以内，吞吐提升了近 4 倍。今天把整套落地架构、核心配置参数以及排障踩坑经验完整复盘出来。
一、为什么传统推理方案扛不住多并发？
要解决并发吞吐问题，必须先看清显存和计算时间到底花在哪儿了：
- KV Cache 显存碎片化 ：传统 Hugging Face 方案预先分配连续的显存块存放 KV Cache，由于每条请求输出长度不可预知，显存常常被过度预留（浪费高达 60%-80%），导致并发数根本提不上去。
- Prefill 与 Decode 资源争抢 ：输入长 Prompt 的“预填充（Prefill）”阶段是计算密集型，而逐字输出的“解码（Decode）”阶段是显存带宽受限型。长文本进来时会长时间霸占算力，让正在持续流式吐字的其他请求瞬间顿挫。
- 流式长连接泄漏 ：FastAPI 配合
StreamingResponse时，如果客户端异常断开（比如用户关闭了浏览器 Tab），后台生成任务如果没感知并取消，GPU 依然会在后台狂算，白白烧尽显存与算力。
针对这三大痛点，vLLM 的 PagedAttention 机制（像操作系统虚拟内存一样把 KV Cache 分成 Block 分散存储）加 Chunked Prefill 是目前最务实的解法。
二、生产级 Dockerfile 与环境基础镜像
不要在本地机器直接用 pip 乱装环境，CUDA 版本和 PyTorch 的 ABI 冲突极易让人抓狂。建议直接使用官方经过量化优化的 runtime 镜像作为基座：
FROM vllm/vllm-openai:v0.6.3.post1
# 配置国内 pip 源加速插件安装
RUN pip config set global.index-url https://pypi.tuna.tsinghua.edu.cn/simple
# 安装 Ray 与系统监控依赖
RUN pip install --no-cache-dir ray[default]==2.38.0 prometheus-client httpx
# 设定模型挂载路径与工作目录
WORKDIR /workspace
ENV MODEL_NAME="Qwen/Qwen2.5-7B-Instruct"
ENV VLLM_WORKER_MULTIPROC_METHOD="spawn"
EXPOSE 8000 8265
三、vLLM 核心启动参数深度调优
vLLM 启动命令里的每一个参数都直接决定了服务能否榨干 GPU 性能。这是我在 RTX 4090 上验证过最稳定、吞吐表现最好的生产参数组合：
python3 -m vllm.entrypoints.openai.api_server \
--model /models/Qwen2.5-7B-Instruct \
--served-model-name qwen-7b \
--tensor-parallel-size 1 \
--gpu-memory-utilization 0.92 \
--max-model-len 8192 \
--max-num-seqs 64 \
--max-num-batched-tokens 4096 \
--enable-chunked-prefill \
--kv-cache-dtype auto \
--trust-remote-code \
--port 8000
核心参数实战解析：
--gpu-memory-utilization 0.92：默认是 0.9。对于 24G 显存卡，模型权重占约 14.5G，留 0.08（约 1.9G）作为 PyTorch 动态临时开销完全足够，剩下的显存全部打给 KV Cache 分配池。--enable-chunked-prefill： 关键调优项 。将大 Prompt 拆分成多个分块（由--max-num-batched-tokens控制）与 decode 阶段任务交替处理，彻底消除长 prompt 插入时现有流式输出的掉帧与卡顿。--max-num-seqs 64：限制调度池中同时处理的 Sequence 上限。小团队内网场景设为 32~64 足矣，避免极端高并发下排队队列无序暴增导致请求全量超时。
四、高并发流式代理：处理客户端中断与 SSE
直接把 vLLM 暴露给前端是不明智的。我们通常会在前面挂一层基于 FastAPI 的业务网关，负责 Token 鉴权、审计日志和流式推送。这里踩过的一个深坑是： 必须正确捕获客户端的断开事件，及时向上游传递 Cancellation。
import asyncio
from fastapi import FastAPI, Request
from fastapi.responses import StreamingResponse
import httpx
app = FastAPI()
VLLM_UPSTREAM_URL = "http://127.0.0.1:8000/v1/chat/completions"
# 必须使用长连接 Client 并配置合理的连接池
http_client = httpx.AsyncClient(timeout=httpx.Timeout(60.0, connect=5.0))
@app.post("/api/v1/chat/stream")
async def chat_stream(request: Request):
payload = await request.json()
payload["stream"] = True
async def stream_generator():
try:
async with http_client.stream("POST", VLLM_UPSTREAM_URL, json=payload) as response:
if response.status_code != 200:
yield f"data: {{\"error\": \"Upstream returned {response.status_code}\"}}\n\n"
return
async for chunk in response.aiter_text():
# 检查客户端是否已经关闭连接
if await request.is_disconnected():
# 客户端挂断，中断消费，触发 upstream 连接关闭
break
yield chunk
except asyncio.CancelledError:
# 捕获协程被取消信号，保证释放资源
pass
return StreamingResponse(stream_generator(),
media_type="text/event-stream",
headers={
"Cache-Control": "no-cache",
"Connection": "keep-alive",
"X-Accel-Buffering": "no" # 核心：防止 Nginx 默认缓冲导致流式输出变成一次性吐出
}
)
五、前置 Nginx 反向代理避坑：关掉 Buffering
很多开发者发现本地 curl 流式正常，但一上域名通过 Nginx 访问就变成“憋半天然后一次性把全文吐出来”。这是因为 Nginx 默认开启了 proxy buffering。
server {
listen 80;
server_name llm.nassky.top;
location /api/v1/chat/stream {
proxy_pass http://127.0.0.1:8080;
proxy_http_version 1.1;
proxy_set_header Connection "";
# 核心：必须禁用代理缓冲，否则 SSE 无法实时分块吐字
proxy_buffering off;
proxy_cache off;
# 延长超时时间，防止长文本生成被中间网关切断
proxy_read_timeout 300s;
proxy_send_timeout 300s;
# 透传客户端 IP
proxy_set_header Host $host;
proxy_set_header X-Real-IP $remote_addr;
proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
}
}
六、压测对比与实战避坑心得
在 RTX 4090 机器上，使用 locust 对 Qwen2.5-7B-Instruct（4k prompt 输入，512 tokens 输出）进行负载压测，对比直接用 FastAPI 封装 Hugging Face Pipeline 与使用 vLLM 调优后的表现：
| 架构方案 | 并发量 (Clients) | 首字延迟 (TTFT P95) | 系统总吞吐 (Tokens/s) | 显存 OOM 概率 |
|---|---|---|---|---|
| HuggingFace + FastAPI | 8 | 4.82s | 48.2 | 极高 (偶发崩溃) |
| vLLM 默认配置 | 30 | 820ms | 210.5 | 0% |
| vLLM + Chunked Prefill | 30 | 215ms | 285.3 | 0% |
运维排障经验速记：
- 关于显存量化选择（AWQ vs GPTQ）：在单卡 24G 跑 14B 模型时必须量化。推荐使用 AWQ，在 vLLM 下其 Triton 算子优化度高于 GPTQ，且推理延迟更平稳。
- 模型权重加载内存爆满（Host RAM）：启动时可能会发现系统内存瞬间被吞噬 30-40G，触发系统 OOM Killer。这是因为多个 Worker 进程并行反序列化。加上环境变量
VLLM_WORKER_MULTIPROC_METHOD=spawn，并确认机器 Swap 分配充裕。 - 关于 Tensor Parallelism：单节点双卡（如 2x 3090/4090）如果走的是 PCIe 插槽而非 NVLink，
--tensor-parallel-size 2的跨卡通信开销会非常明显。如果单卡放得下模型，跑两个独立的单一副本（Data Parallel）做负载均衡，吞吐收益反而远高于无 NVLink 的模型并行。
总结与结语
在算力成本居高不下的今天，跑大模型服务绝不仅仅是 model.generate() 那么简单。通过 PagedAttention 解决显存浪费、Chunked Prefill 消除长文本卡顿、FastAPI 严密捕获中断信号、Nginx 关停缓冲区 ，这一套打通下来，即便是消费级的单张 24G 显卡，也完全有能力稳定抗住中小型团队的日常业务流。这套配置你拿去改改路径就能直接进生产，建议直接收藏备用。
