使用vLLM作为OpenAI兼容API网关时,上游鉴权与高并发转发的对接实践

文章导读
vLLM自带的OpenAI兼容接口已经能处理单点请求,但接入多客户端或高并发场景时,通常需要在前面加一层网关,负责统一鉴权、限流和请求转发。对接的关键不在vLLM本身,而在网关怎样安全地传递凭证,以及怎样避免转发连接成为瓶颈。以下按前置条件、配置、验证、回退四个部分给出操作路径。
📋 目录
  1. Ⅰ 前置条件与对接方向
  2. Ⅱ 配置网关转发与鉴权
  3. Ⅲ 高并发转发的关键参数
  4. Ⅳ 验证与失败回退
A A

vLLM自带的OpenAI兼容接口已经能处理单点请求,但接入多客户端或高并发场景时,通常需要在前面加一层网关,负责统一鉴权、限流和请求转发。对接的关键不在vLLM本身,而在网关怎样安全地传递凭证,以及怎样避免转发连接成为瓶颈。以下按前置条件、配置、验证、回退四个部分给出操作路径。

前置条件与对接方向

开始前先确认三件事:vLLM服务是否已设定API Key;客户端期望用哪种方式传Token;网关本身是否支持连接复用。如果vLLM设了`--api-key`,那么网关需要在转发时使用这个Key,而不是把客户端的Token直接透传,否则会401。客户端Token通常来自共享密钥或JWT,网关需要先校验这个Token,再将后端Key写入转发请求。

下面示例以Nginx为例。Nginx配置通用,参数可移植到OpenResty或Envoy。

配置网关转发与鉴权

先启动vLLM,并指定后端Key:

vllm serve /path/to/model `--port` 8000 `--api-key` vllm-secret-key

该Key只用于vLLM网关与后端之间的通信,不应泄露给客户端。如果已有网关在内网转发,也可以不启用,但建议保留,防止绕过网关直接请求。

在Nginx中,将/v1/的请求转发到vLLM,并用auth_request校验客户端Token:

upstream vllm_backend {
    server 127.0.0.1:8000;
    keepalive 32;
}

server {
    listen 8443 ssl;
    # ssl_certificate /path/cert.pem;
    # ssl_certificate_key /path/key.pem;

    location /v1/ {
        auth_request /_check_token;
        proxy_pass http://vllm_backend;
        proxy_http_version 1.1;
        proxy_set_header Connection "";
        proxy_set_header Host $host;
        proxy_set_header Authorization "Bearer vllm-secret-key";
        proxy_read_timeout 300s;
        proxy_connect_timeout 5s;
    }

    location = /_check_token {
        internal;
        # 实际校验逻辑:读取Authorization头,与预设Token或JWT验证
        # 校验通过返回200,失败返回401
        return 200;
    }
}

注意这里把Authorization头固定为vllm-secret-key。这样客户端Token即使有效,也不会被传给vLLM。如果后端Key不固定,可以由Lua脚本从环境变量读取后写入,避免明文写在配置里。auth_request的/_check_token需要自己实现,可以通过共享内存或redis验证Token;上面的return 200只是占位,实际必须替换。

使用vLLM作为OpenAI兼容API网关时,上游鉴权与高并发转发的对接实践

高并发转发的关键参数

  • keepalive连接数:upstream中的keepalive 32会保持32个到vLLM的空闲连接,减少TCP握手。数值先按经验设,32不够可以调大,但vLLM实例是GPU推理,连接太多反而增加调度开销。
  • HTTP版本:必须设proxy_http_version 1.1,且清空Connection头,连接才能真正复用。
  • 读超时:推理耗时可能长,尤其是长上下文。proxy_read_timeout需要大于最慢请求,先设300s,再根据实际情况调整。
  • 并发限制:在upstream server加max_conns = 64,当排队请求超过时,网关会返回503,避免vLLM被突发流量打掉。
  • 重试:不建议开启proxy_next_upstream。OpenAI兼容的生成请求不是安全的幂等请求,重试可能造成重复生成和费用翻倍。如果一定要开,只对error超时重试一次,并且确保业务能接受重复。

验证与失败回退

先直连vLLM确认后端正常:

curl http://127.0.0.1:8000/v1/models -H "Authorization: Bearer vllm-secret-key"

再放到网关后面,用客户端Token请求:

curl https://your-domain/v1/models -H "Authorization: Bearer client-valid-token"

预期返回与直连一样;不带Token应返回401。高并发验证建议使用wrk或hey,观察失败率、平响和vLLM日志,而不是只压低延迟。

遇到问题按下面方向回退:

  1. 如果401,先在网关里临时注释掉auth_request,直接透传,确认vLLM的Key是否正确。
  2. 如果出现连接失败,把keepalive调小或注释掉,先回到逐连接转发,确认问题出在连接复用上。
  3. 如果客户端能直连但网关超时,检查proxy_read_timeout和vLLM的启动参数里的并发限制。

最后,这组配置只能作为起点。Nginx keepalive、auth_request的实现、vLLM的并发参数都需要结合自己的服务设计来定,替换前记得用nginx -t测试。