LLM 接口和普通 HTTP 接口不同,重试不是简单的把请求重新发一遍。模型推理消耗时间长,一个超时任务可能已经在远端跑了大部分计算,盲目重试会重复计费,还可能把上游打挂。所以给 LLM 网关做条件重试,先要确定错误边界,再决定什么时候短路。下面这套做法不依赖第三方库,在 APISIX 的 Lua 插件里就能实现。
为LLM网关配置条件重试前,先要明确哪些错误值得重试。通常,HTTP 429(限流)和 5xx(网关或上游临时故障)属于可重试范围,而 400 或 401 表明请求本身有误或鉴权失效,重试只会浪费资源。在 APISIX 的 Lua 插件中,可在 `log` 阶段读取 `ngx.status`,结合 `ngx.var.upstream_response_time` 判断超时类异常。若上游返回 429,还应根据 `Retry-After` 头决定等待时长,避免密集重试加剧限流。
在 APISIX 中实现条件重试与熔断联动,可自写一个插件:在 `access` 阶段检查共享字典中的熔断开关,若已开启则直接返回 503 或预定义错误体;若关闭才真正发起请求。在 `log` 阶段根据 `ngx.status` 更新失败计数器。使用 `ngx.shared.dict` 存储计数器和时间戳,比如以路由 ID 为 key 记录连续失败次数,超过阈值后设置熔断截止时间。注意每次成功请求要清零计数,失败计数仅在可重试错误类型上增加,非可重试错误应直接放行或单独处理。
先分清楚哪些错误值得重试
为LLM网关配置条件重试前,先要明确哪些错误值得重试。通常,HTTP 429(限流)和 5xx(网关或上游临时故障)属于可重试范围,而 400 或 401 表明请求本身有误或鉴权失效,重试只会浪费资源。在 APISIX 的 Lua 插件中,可在 log 阶段读取 ngx.status,结合 ngx.var.upstream_response_time 判断超时类异常。若上游返回 429,还应根据 Retry-After 头决定等待时长,避免密集重试加剧限流。
APISIX 的 route 和 upstream 配置里有一个 retry 字段,但那是给 Nginx 连接重试用,不会识别 HTTP 状态码。所以上面的判断必须放到插件里。下面这段代码放在 log 阶段,读取状态码和管理 Retry-After 的等待值:
local status = ngx.status
local retry_after = ngx.var.upstream_http_retry_after
if status == 429 then
local wait = tonumber(retry_after) or 1
-- wait 准备写入共享字典,后续重试或熔断判断会用到
end
if status >= 500 and status < 600 then
-- 在 log 阶段只做统计,真正的重试由访问前的熔断控制
end这个片段在 APISIX 的 log 阶段执行,此时响应已经返回给客户端,不能直接在原请求上重试,所以这里只做统计。验证方式:在 APISIX 的 error log 中看是否有 Lua 报错;优先检查 ngx.var.upstream_http_retry_after 是否存在,如果上游没返回该头,变量会为空。
用共享字典管理熔断开关
在 APISIX 中实现条件重试与熔断联动,可自写一个插件:在 access 阶段检查共享字典中的熔断开关,若已开启则直接返回 503 或预定义错误体;若关闭才真正发起请求。在 log 阶段根据 ngx.status 更新失败计数器。使用 ngx.shared.dict 存储计数器和时间戳,比如以路由 ID 为 key 记录连续失败次数,超过阈值后设置熔断截止时间。注意每次成功请求要清零计数,失败计数仅在可重试错误类型上增加,非可重试错误应直接放行或单独处理。
要使用共享字典,需要先在 APISIX 的 config.yaml 里声明。下面是一个最小配置:
nginx_config:
http:
shared_dict:
llm_breaker: 10m这个配置要放在 config.yaml 的 nginx_config.http 下,重启 APISIX 后生效。key 建议用 route.id 拼上错误状态码,比如 route_1001_502。这样不同路由、不同错误类别不会互相干扰。验证方式:APISIX 启动日志中会显示共享字典大小,如果配置错误,插件里获取 dict 时会返回 nil。优先检查配置层级是否缩进正确。
重试与熔断联动
熔断与重试的联动关键在于状态转换。当熔断处于关闭时,允许按条件重试,例如在 body_filter 阶段检测到上游返回 502 后,微调重试计数并重发一次请求;但一旦连续失败达到阈值,进入开启状态,此时应跳过重试,直接短路。熔断结束后进入半开状态,可放一个试探请求,若成功则立即恢复关闭状态,否则继续开启并延长冷却时间。这样能避免上游尚未恢复时反复重试,同时保证恢复后的快速响应。
实现时可以把状态判断收敛成一个函数。下面这段代码放在插件公共模块里,access 阶段调用它决定是否允许请求进入上游:
local function should_allow(dict, key, now)
local open_at = dict:get(key .. ':open_at')
if not open_at then
return true
end
local open_for = now - tonumber(open_at)
local cool_down = tonumber(dict:get(key .. ':cool_down') or 30)
if open_for < cool_down then
return false
end
-- 冷却期已过,放行一个试探请求
dict:set(key .. ':half_open', true, 10)
return true
end这个函数返回 false 时,access 阶段直接返回 503,不再发往上游。如果成功,进入半开状态,log 阶段看到成功要删除 half_open 和 open_at 键;如果失败,则继续延长冷却时间,并把 half_open 清除。这里的 cool_down 可以根据上游历史响应时间动态调整,但需要由你在插件里计算。验证方式:在插件里加一个临时接口输出 dict 的内容,观察 open_at 和 half_open 的切换。优先检查 key 是否一致,常见问题是 log 阶段和 access 阶段用了不同 key。
流式接口与边界条件
对 LLM 网关来说,流式响应是最容易出问题的地方。上游先返回 200 和一部分 body,然后连接中断,此时 ngx.status 仍然是 200,上面的状态码判断根本拿不到异常。建议对非流式接口启用条件重试,流式接口只做熔断。要判断一个请求是不是流式,可以在插件的 access 阶段检查请求头里的 Accept: text/event-stream,或者通过 ngx.var.upstream_http_content_type 在 log 阶段看到 text/event-stream。如果想让流式接口也具备重试能力,需要额外处理 SSE 的缓存和重放,那就不只是一个重试插件,而是一套消息缓存方案。
还有一个容易被忽略的点:熔断阈值和冷却时间不能设得太小,否则上游一次抖动就会误伤所有请求;设得太大又会导致恢复缓慢。可以在插件里对熔断开启状态增加一个平滑退化逻辑,比如直接返回提示信息,而不是无限重试阻塞 worker。
验证方法与常见坑
验证时,先准备一个可 mock 的上游,在 APISIX 所在机器上用 curl 指向网关。观察两个地方:APISIX 的 access log 里的实际请求次数,以及共享字典里的计数变化。下面是一个最小验证命令:
curl -i http://127.0.0.1:9080/llm/chat \
-H 'Content-Type: application/json' \
-d '{"prompt":"test"}'
# 上游模拟返回 429 或 503 时,观察响应头和 access log
# 上游模拟返回 400 时,确认没有计数增加执行位置在 APISIX 所在机器或能访问 9080 端口的机器。验证方式是对比上游 Nginx 的 access log 和 APISIX 的 access log,判断重试次数。失败时优先检查路由是否匹配这个插件。
最容易踩的坑是条件重试与熔断的计数器互相干扰。有人在 log 阶段统计所有 5xx,导致偶发 500 直接打开熔断,而实际上 LLM 服务返回 500 有时只是单次请求上下文超长,并非系统不可用。建议对错误码做细分,例如 429 单独计数用于限流退避,502/503 配合响应时间作为熔断依据。另一个坑是重试时没有增加随机抖动,当多个请求同时失败后同时重试,会造成上游二次雪崩。每次重试的 sleep 应在基础间隔上加随机扰动,并使用 ngx.sleep 而非阻塞式等待。
这套联动的核心是把“是否可重试”和“是否允许发请求”分成两个决策点,一个管错误识别,一个管上游压力。实际部署时,先确认共享字典配置和 key 设计,再逐步加熔断阈值,不要在第一次上线时把阈值设得太激进。用 curl 和 mock 上游验证之后再接入真实流量。