vLLM服务经中转网关转发后的Malformed request错误码含义与请求格式矫正

文章导读
当 vLLM 服务部署在网关之后,客户端报错里出现 Malformed request 时,通常不是因为模型推理出了问题,而是请求在网关转发过程中被改写,导致后端收到的 HTTP 请求不符合 vLLM 的解析预期。vLLM 的 HTTP 层会以 400 响应,并在响应体的 error 字段中给出这种描述,但不会告诉你具体缺哪个字段。以下按“现象—检查点—处理动作—验证信号”说明。
📋 目录
  1. 一 先确认错误落在哪一层
  2. 二 检查点一:网关是否改写请求头
  3. 三 检查点二:路径和前缀重写
  4. 四 检查点三:请求体本身不是合法 JSON
  5. 五 检查点四:HTTP 版本与 keep-alive 配置
  6. 六 分支清单
A A

当 vLLM 服务部署在网关之后,客户端报错里出现 Malformed request 时,通常不是因为模型推理出了问题,而是请求在网关转发过程中被改写,导致后端收到的 HTTP 请求不符合 vLLM 的解析预期。vLLM 的 HTTP 层会以 400 响应,并在响应体的 error 字段中给出这种描述,但不会告诉你具体缺哪个字段。以下按“现象—检查点—处理动作—验证信号”说明。

先确认错误落在哪一层

拿到错误后,先看是连接层还是应用层。如果客户端收到的是 502 Bad Gateway,而 vLLM 日志里出现“Malformed request”,说明请求已经到达 vLLM 应用层;如果客户端收到 400 但 vLLM 日志里没有应用层记录,则可能是网关自身校验或上游连接失败。需要先分离这两个场景,否则后续所有排查都会跑偏。

  • 适用:所有中转网关场景,包括 Nginx、Envoy、云厂商 API 网关。
  • 操作:同时查看客户端响应头、网关访问日志、vLLM 的 access log 和 stderr。
  • 风险:如果日志时间不同步,不要把几条不相关的日志拼在一起判断。

检查点一:网关是否改写请求头

最常见的是 Content-Length 和 Transfer-Encoding 冲突。HTTP/1.1 中,这两个头不能同时存在,但网关重写时可能重复添加。另一种情况是 Host 头被改为网关内部域名,vLLM 本身不校验 Host,但如果网关开启了重写,也会影响路由。

操作动作:在客户端和 vLLM 之间各抓一次请求,比较核心头。可以用 curl 发送两次请求,一次直连 vLLM,一次经网关。不要只对比 headers 里的大小写,要看值。

curl -s -o /dev/null -D - -H "Content-Type: application/json" -d '{"prompt":"test"}' http://网关/llm/v1/completions
curl -s -o /dev/null -D - -H "Content-Type: application/json" -d '{"prompt":"test"}' http://vllm直接地址/v1/completions

对比两组响应头中的 server、content-length,再在 vLLM 日志里查请求是否到达。如果直连正常、经网关报错,重点检查网关是否删掉了 Content-Type,或者将 chunked 与 content-length 同时保留。

检查点二:路径和前缀重写

vLLM 的 API 路径是 /v1/completions、/v1/chat/completions 等。如果网关配置了前缀重写,比如把 /llm/v1/completions 转发给 vLLM 时变成 /v1/completions,一般没问题;但如果重写规则把 /v1 也吃掉了,vLLM 会因为找不到路由而返回 404,而不是 Malformed request。反过来,如果路径正确但多个斜杠、末尾斜杠被规范化,也可能触发解析差异。

vLLM服务经中转网关转发后的Malformed request错误码含义与请求格式矫正

适用:网关配置了 strip_prefix 或 rewrite 指令时,需要核对规则。

动作:用 curl -v 观察发往 vLLM 的实际请求路径,确保 vLLM 收到的 path 是标准 /v1/... 开头。检查网关配置里是否有多条 rewrite 叠加。

验证:在 vLLM 侧使用 access log 打印完整 URL,或者临时关闭网关 rewrite 直接转发一次,确认修复是否有效。

检查点三:请求体本身不是合法 JSON

vLLM 对请求体要求是 JSON 对象,且包含必需字段。Malformed request 在 vLLM 代码里通常发生在解析请求体的时,比如 JSON 解析失败,或字段类型不符。网关一般不会篡改 body,除非做了请求体校验或修改。如果网关开启了 DDoS 防护、WAF 或 body 校验,可能把二进制内容或截断的请求体传给后端,导致 JSON 不完整。

操作:对比客户端发送的原始请求和 vLLM 日志中打印的请求体。可以用 vLLM 的 `--log-requests` 启动参数,或者在网关层用 echo 服务记录。没有日志时,用 tcpdump 抓后端 8000 端口流量,但要留意 TLS 的干扰。

验证信号:如果客户端发送的是标准 JSON,但 tcpdump 里看到 body 被截断,问题出在网关的 proxy_buffering 或 client_max_body_size 配置。如果 body 完整但 vLLM 仍报错,则要检查字段名和类型,例如 prompts 应为数组,且不能为空。

vLLM服务经中转网关转发后的Malformed request错误码含义与请求格式矫正

检查点四:HTTP 版本与 keep-alive 配置

vLLM 默认监听 HTTP/1.1,如果网关使用 HTTP/2 和上游进行通信,且连接复用时出现帧交错,vLLM 的解析器可能抛出 Malformed request。另一种场景是客户端使用 HTTP/2,网关降级到 HTTP/1.1 时,如果没正确设置 Connection 头,也会让 vLLM 误判。

动作:确认网关 upstream 的协议配置。例如 Nginx 的 proxy_http_version 是否为 1.1,是否设置了 proxy_set_header Connection ""。如果网关是 Envoy,检查 http2_protocol_options。

风险边界:不要一上来就禁用 HTTP/2,应先临时把网关对 vLLM 的 upstream 协议改为 HTTP/1.1,验证是否消失。如果消失,再排查是网关还是 vLLM 的兼容问题。

分支清单

根据以上现象,可以按下面的分支快速定位:

  • 直连 vLLM 正常,经网关报错:检查网关的请求头改写、路径重写、body 截断、upstream 协议。
  • 直连也报错:客户端请求本身格式不对,先做一次最小请求测试。
  • 偶尔报错,重试后成功:优先考虑负载均衡、连接复用、超时拆包。
  • vLLM access log 里看到 400 和 Malformed request 同时出现,再检查网关日志中的 upstream_status。

最后提醒一点:Malformed request 不是 vLLM 的模型错误,不需要重启服务。它属于输入侧问题,优先检查网关配置。如果仍然排查不出来,可以在 vLLM 启动参数里增加 `--log-requests` 打印完整请求头,但要注意日志量。安全起见,不要在公网直接暴露 vLLM 调试端口。