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只是占位,实际必须替换。
高并发转发的关键参数
- 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日志,而不是只压低延迟。
遇到问题按下面方向回退:
- 如果401,先在网关里临时注释掉auth_request,直接透传,确认vLLM的Key是否正确。
- 如果出现连接失败,把keepalive调小或注释掉,先回到逐连接转发,确认问题出在连接复用上。
- 如果客户端能直连但网关超时,检查proxy_read_timeout和vLLM的启动参数里的并发限制。
最后,这组配置只能作为起点。Nginx keepalive、auth_request的实现、vLLM的并发参数都需要结合自己的服务设计来定,替换前记得用nginx -t测试。