告别OOM与假死：基于vLLM构建高并发多Agent流式网关实战指南

12次阅读

共计 4972 个字符，预计需要花费 13 分钟才能阅读完成。

最近在团队内部折腾基于多 Agent 协同的代码审查系统时，我们遇到了一个极其典型的架构瓶颈：前端 4 个不同角色的 Agent 频繁发起并发请求，随着对话轮次增加，单张 RTX 4090（24G 显存）在运行 Qwen-2.5-14B 时频频告警。更令人头疼的是，一旦用户在前端取消生成或网络稍有抖动，下游微服务却还在死命占用 GPU 推理，导致显存直接打满爆 OOM（Out Of Memory），反向代理层接着抛出一堆 504 Gateway Timeout。

很多开发者在做本地大模型或私有化部署时，第一反应往往是上 Ollama 或者 HuggingFace Text-Generation-Inference（TGI）。但如果你要跑多 Agent 工作流——特点是 系统提示词极长（2k~4k tokens）、并发轮次高、交互高度依赖 SSE（Server-Sent Events）流式响应——默认配置基本撑不过 10 个并发。上周我花了两天时间，用 vLLM 配合定制的高性能 FastAPI 异步网关重构了整套架构，不仅解决了显存碎片化与假死问题，还把吞吐量提升了将近 3 倍。今天把整套实战调优和避坑细节拆解出来，直接上硬核干货。

普通单轮问答和多 Agent 流式编排在 GPU 负载特征上有着本质差异。多 Agent 场景主要有两个致命痛点：

KV Cache 重复膨胀：每个 Agent 的 System Prompt（角色设定、Tool Schema、Few-Shot 示例）通常非常冗长，但同一个任务流内这些前缀高度一致。如果推理引擎没有开启有效的缓存共享机制，每来一个请求就会重新计算并占用巨量显存。
长连接断开导致的计算资源黑洞：多 Agent 链式调用依赖流式 SSE。一旦上游客户端网络闪断或超时取消，如果网关没有精准捕捉 client_disconnected 信号并向推理内核发送终止中断，推理引擎会一直计算完整轮次，持续空耗 GPU 算力。

很多同学跑 vLLM 就一行 python -m vllm.entrypoints.openai.api_server --model ...，这在生产环境极易踩坑。针对多 Agent 长前缀场景，核心必须要开启 Automatic Prefix Caching (APC)，并对显存利用率做严格切分。

这是我经过多轮压测后稳定使用的启动脚本（以单卡 24G 跑 14B AWQ 模型为例）：

#!/usr/bin/env bash
export CUDA_VISIBLE_DEVICES=0
export NCCL_IGNORE_DISABLED_P2P=1

# 关键参数解析：# --gpu-memory-utilization 0.90: 预留 10% 显存给 CUDA 运行时上下文与系统缓冲区，避免峰值瞬时 OOM
# --max-model-len 8192: 根据 Agent 业务严格限制最大上下文长度，防止恶意超长输入直接击穿
# --enable-prefix-caching: 核心！多 Agent 共享 Prompt 显存命中率可达 60% 以上
# --swap-space 4: 分配 4GB Host 内存作为 KV Cache 置换缓冲，防止瞬时并发暴增直接崩掉服务

python3 -m vllm.entrypoints.openai.api_server \
    --model /data/models/Qwen2.5-14B-Instruct-AWQ \
    --port 8000 \
    --host 127.0.0.1 \
    --dtype half \
    --gpu-memory-utilization 0.90 \
    --max-model-len 8192 \
    --max-num-seqs 64 \
    --enable-prefix-caching \
    --swap-space 4 \
    --disable-log-requests

踩坑提醒：如果你使用的是 AWQ 或 GPTQ 量化模型，务必注意 --dtype half 或 --dtype auto 的适配，不要强行指定 bfloat16，部分旧架构卡或量化算子在 BF16 下反而会导致 GEMM 计算变慢甚至报错。

直接将 vLLM 的 8000 端口暴露给业务端是不明智的。我们需要在业务层和 vLLM 之间架设一个轻量级代理网关，负责三件事：输入 Schema 校验 、 客户端断开连接感知（立即取消下游生成）以及 流式 SSE 格式清洗与令牌速率限流。

以下是使用 httpx.AsyncClient 搭配 FastAPI 实现的生产级流式转发中间件核心代码：

# gateway.py
import json
import httpx
from fastapi import FastAPI, Request, HTTPException
from fastapi.responses import StreamingResponse

app = FastAPI(title="Agent-Inference-Gateway")

VLLM_API_URL = "http://127.0.0.1:8000/v1/chat/completions"

# 必须调大连接池，保持 HTTP Keep-Alive
limits = httpx.Limits(max_keepalive_connections=50, max_connections=200)
timeout = httpx.Timeout(connect=5.0, read=60.0, write=5.0, pool=5.0)
client = httpx.AsyncClient(limits=limits, timeout=timeout)

@app.post("/v1/agent/chat")
async def agent_chat_proxy(request: Request):
    try:
        body = await request.json()
    except Exception:
        raise HTTPException(status_code=400, detail="Invalid JSON payload")

    # 强制确保流式输出开启
    body["stream"] = True

    async def stream_generator():
        try:
            # 使用流式请求透传至 vLLM
            async with client.stream("POST", VLLM_API_URL, json=body) as resp:
                if resp.status_code != 200:
                    error_detail = await resp.aread()
                    yield f"data: {json.dumps({'error': error_detail.decode()})}\n\n"
                    return

                async for line in resp.aiter_lines():
                    # 关键特性：检测客户端连接状态
                    # 如果上游客户端断开，立即终止生成器，httpx 会自动断开下游连接，触发 vLLM 终止推理
                    if await request.is_disconnected():
                        # 主动记录断连日志，释放资源
                        print("[Gateway] Client disconnected, aborting stream task.")
                        break

                    if line:
                        yield f"{line}\n\n"
        except httpx.RequestError as exc:
            yield f"data: {json.dumps({'error': f'Upstream inference failed: {str(exc)}'})}\n\n"

    return StreamingResponse(stream_generator(),
        media_type="text/event-stream",
        headers={
            "Cache-Control": "no-cache",
            "Connection": "keep-alive",
            "X-Accel-Buffering": "no"  # 禁用 Nginx 缓冲区，保证逐 token 实时推送
        }
    )

@app.on_event("shutdown")
async def shutdown_event():
    await client.aclose()

这个网关里最核心的一行是 await request.is_disconnected()。在原生多 Agent 递归调用中，经常会有分支决策失败直接 abort() 的情况。加入这个判断后，下游 vLLM 会在 50ms 内收到连接重置（RST），立即将该请求绑定的 KV Cache 标记为可回收，有效避免了无意义的 GPU 持续空转。

在生产架构中，通常会在 API Gateway 前面挂一层 Nginx。如果你的 SSE 流经常出现“卡顿 5 秒然后突然喷出一大坨文字”，或者经常莫名奇妙收到 502 Bad Gateway，99% 是因为 Nginx 的 Buffering 和超时参数没调对。

请直接对照检查以下生产级 Nginx 配置片段：

upstream agent_gateway {
    server 127.0.0.1:8080;
    keepalive 32;
}

server {
    listen 443 ssl http2;
    server_name llm-agent.internal.domain;

    # SSL 证书配置略...

    location /v1/agent/chat {
        proxy_pass http://agent_gateway;
        proxy_http_version 1.1;
        
        # 核心设置：关闭响应缓冲，实现逐 Token 实时传输
        proxy_buffering off;
        proxy_cache off;
        proxy_set_header Connection "";
        
        # 延长读取超时时间，防止 Agent 深度思考（Reasoning）阶段导致超时断连
        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;
        
        # 针对大并发场景，适当增加输出缓冲区（非缓冲模式下用于平滑 TCP 发送）proxy_buffer_size 4k;
    }
}

我们使用 locust 模拟了典型的 4-Agent 协同工作流（每个请求包含 2.5k tokens 的 System Prompt，输出约 500 tokens），在单张 RTX 4090 上进行压测对比：

部署方案与配置	稳定并发数	首字延迟 (TTFT)	吞吐量 (Tokens/s)	异常情况
原生框架默认部署	6	1850 ms	~78	并发达 8 时显存溢出 OOM
vLLM 基础参数 (无 APC)	16	920 ms	~210	客户端断连后 GPU 依然满载 3-5 秒
本方案 (vLLM APC + 断连中断网关)	36	260 ms	~580	显存平稳，无 OOM，取消任务即刻释放

从实测数据可以明显看出：开启 --enable-prefix-caching 后，因为 Agent 的角色设定指令命中了 KV Cache，首字延迟（TTFT）从将近 1 秒骤降到 260 毫秒；配合应用层的断连感知，即便大量客户端并发快速切换任务，GPU 的显存利用率依然平稳在 88%~92% 的健康区间，彻底告别了显存溢出导致的崩溃。

在大模型进入工程落地阶段后，算法模型本身的微调是一方面，底层的系统级架构调优才是决定业务能否稳定跑起来的关键。如果你的团队也正准备落地高并发 Agent 或长文档交互，建议按以下三点严格自查：

善用共享前缀：只要业务有固定 Prompt 结构，必须强制开启引擎的 Prefix Caching，不要让 GPU 在相同的前缀上浪费矩阵乘法算力。
全链路治理连接状态：从前端 EventSource、Nginx 反代到 FastAPI 代理层，每一级都要明确传递并处理“中断信号”，这是防止并发峰值算力雪崩的核心。
显存预留绝对不能省：--gpu-memory-utilization 绝对不要手贱设为 0.98 或 1.0，必须留出至少 1~2GB 给 PyTorch 和 CUDA 动态执行分配空间，否则偶发的大 Batch 直接让你在深夜收到报警短信。

正文完