TGI 的 max_total_tokens 与 max_input_length 联动导致的 422 错误处理

文章导读
遇到 422 Unprocessable Entity,先不要急着改端口或重启服务。这个错误在 TGI(Text Generation Inference)里通常与两个参数有关:max_total_tokens 和 max_input_length。它们不是独立生效的,前者是本次请求允许的最大 token 数(输入 + 输出),后者是输入内容的上限。当请求的输入长度接近或超过 max_input_
📋 目录
  1. A 先确认两个参数的边界关系
  2. B 检查服务端启动参数
  3. C 检查请求侧参数
  4. D 分支排查清单
  5. E 验证信号
A A

遇到 422 Unprocessable Entity,先不要急着改端口或重启服务。这个错误在 TGI(Text Generation Inference)里通常与两个参数有关:max_total_tokens 和 max_input_length。它们不是独立生效的,前者是本次请求允许的最大 token 数(输入 + 输出),后者是输入内容的上限。当请求的输入长度接近或超过 max_input_length,同时你又设置了过高的输出长度,导致输入加输出超过 max_total_tokens,服务端就会返回 422。下面按排查顺序拆开讲。

先确认两个参数的边界关系

基本约束是:max_total_tokens >= max_input_length + 最少输出长度。如果服务端把 max_total_tokens 设成 512,而 max_input_length 也是 512,那么一个 512 token 的输入就没有任何剩余空间生成输出;如果输入不到 512,但生成长度拉满,也会触发 422。客户端请求里通常还有单独的 max_tokens 或 max_new_tokens 参数,这个值必须小于 max_total_tokens - 本次输入 token 数。注意,这里的输入 token 数需要看服务端实际切分结果,不是简单数文字长度。

检查服务端启动参数

先确认 TGI 服务启动时是否设置了这两个边界。通常通过命令行参数或环境变量传入,不同部署方式写法有差异。典型 Docker 启动示例:

docker run -p 8080:80 ghcr.io/huggingface/text-generation-inference:latest `--model-id` your-model `--max-total-tokens` 2048 `--max-input-length` 1024

这里刻意用了 2048 和 1024,读者应根据实际显存和模型上下文长度调整。建议让 `--max-total-tokens` 至少比 `--max-input-length` 大出你允许的最大生成长度。如果服务已经在运行,可以查看进程启动命令或环境变量文件,确认这两个值是否合理。

检查请求侧参数

如果服务端配置没问题,再看请求传参。TGI 的 HTTP API 里,生成参数通常放在 JSON body 中。下面是一个通用请求骨架:

TGI 的 max_total_tokens 与 max_input_length 联动导致的 422 错误处理
curl http://your-tgi-server:8080/generate -H 'Content-Type: application/json' -d '{"inputs":"这里是用户输入的文本,可能很长","parameters":{"max_tokens":512}}'

重点检查 parameters.max_tokens。这个值表示“本次生成允许的最大新 token 数”,它和输入长度共同作用。如果输入文本已经有 1500 token,max_tokens 设为 512,而服务端 max_total_tokens 是 2048,那么 1500 + 512 = 2012 还可以接受;但如果输入是 1800 token,就会超过 2048 触发 422。客户端侧需要先估算输入 token 数,或者减少 max_tokens 让总和低于服务端上限。

分支排查清单

按下面顺序逐项检查,先定位再修改:

  1. 确认服务端实际生效的 max_total_tokens 和 max_input_length。不要凭启动参数猜测,直接看容器环境变量或进程参数。
  2. 确认这两个参数满足 max_total_tokens > max_input_length。如果不满足,优先调整启动参数,这是最常见配置错误。
  3. 定位 422 返回的具体错误信息。TGI 的错误响应里通常会写明是输入过长,还是总长度超限。记录 body 中的 message,不要只盯着状态码。
  4. 检查请求侧 max_tokens 是否过大。可以临时调小到 1,看是否还报 422,以此区分是请求参数问题还是服务端配置问题。
  5. 检查输入内容本身是否超过 max_input_length。对于长文本场景,需要先做截断或摘要。

验证信号

修改配置或请求后,用最小输入做一次回归测试。建议用一两句短文本请求,确认不再返回 422,再逐步增加输入长度。也可以通过服务端日志观察这次请求是否进入推理阶段。一个可用的验证命令是反复调 /generate 接口,分别用短输入和长输入对比返回状态码。如果长输入仍然 422,可以把 max_tokens 调低到 1 重试;如果 1 都能通过,说明之前是生成长度和输入长度叠加超限。注意调整后要等待服务端完成加载(如果重启),避免误判。

另一个思路是主动在客户端侧做 input 长度预估,把超过比例的请求直接拦下,避免浪费一次 HTTP 往返。具体实现可以用 tokenizer 或按字符粗略估计,但这需要结合自己模型的实际 token 化方式,不能一刀切。