Toonflow 接入模型供应商返回 502 Bad Gateway，该先查网关超时、接口路径还是上游限流？

Toonflow 接入模型供应商后请求返回 502，多数情况下不是模型推理失败，而是 Toonflow 与供应商之间的某一跳网关没有拿到完整的上游响应。502 属于网关类状态码，含义是代理层无法从上游获得有效应答，因此排查顺序应当是先确定 502 由哪一跳产生，再分别处理路径、超时与限流三类成因；如果直连供应商就能稳定复现同样的 502，则问题在供应商侧或链路上，继续改 Toonflow 的节点参数不会有效果。 第一步要用命令行绕过 Toonflow 直连供应商的对话补全接口，把 502 从应用层剥离出来。取 Toonflow 中配置的 base URL、API Key 和模型名，用 curl 发一个最小请求，观察返回状态码与响应头；如果 curl 正常而 Toonflow 报 502，故障点就在 Toonflow 到供应商之间的代理配置，反之则要看供应商侧的健康状态。复现时务必保留响应头里的请求标识，这是后续向供应商提工单时唯一有效的凭据。 Base URL 多写或少写一段路径，是 Toonflow 配置模型供应商时最常见的 502 诱因。OpenAI 兼容协议通常要求地址指向 /v1 这一级，末尾多一个斜杠、误用 http、端口写成 443 而协议写 http，都可能让前置网关把请求转到不存在的上游而返回 502。多供应商混用时还要核对模型名与供应商的映射表，部分网关对未注册的模型名不做 404 处理，直接以 502 抛出，看起来像网络故障，实际是配置拼写问题。 长输出场景下的 502，几乎都与网关读超时有关，而不是模型算不出来。非流式请求要等整段回答生成完才返回，反向代理默认的读超时通常只有 60 秒，一旦推理超过这个时间，代理层就会先断开并回 502。处理办法是优先改用流式输出让数据持续回传，其次才是在 Nginx 中调大 proxy_read_timeout 与 proxy_send_timeout，两个值要同时调整，只改其中一个仍然会在另一端断流。 开了流式仍然 502 或长时间没有输出，要检查代理层的缓冲是否把事件流数据攒住了。Nginx 默认开启 proxy_buffering，会把上游的分块响应缓存后再转发，对 SSE 来说是致命的，需要在对应的 location 上关闭缓冲并显式声明不缓存。自建 Toonflow 时还可能叠了 CDN，CDN 对长连接有自己的空闲回收策略，这一层要单独确认是否支持流式透传。 上下文过长或携带图片的请求，会以 502 的面目出现在请求体超限这一类问题上。多模态请求把图片转成 base64 后体积明显膨胀，部分网关对请求体大小设有上限，超出时并不总是返回 413，而是直接掐断连接由前端记为 502。可行的做法是压缩历史消息、限制单次附带的图片数量与分辨率，把长文档拆成多次调用，而不是一次性塞进上下文。 并发一高就零星出现 502，通常不是网络抖动，而是上游限流被中间层改写后的表现。供应商的真实返回多为 429 或带限流说明的错误体，但部分反向代理或自建网关会统一包装成 502，掩盖了原始原因。排查时先看同一时间段的请求量与失败比例，再把 Toonflow 的并发数降到个位数做对照测试，确认是限流后再上指数退避重试，且重试必须带幂等控制，否则会把限流放大成雪崩。 服务器出口链路异常会在 Toonflow 上表现为全部供应商同时 502，这一点可以用来快速区分。判断方法是同时向两个不同供应商各发一个最小请求，如果两者都失败，问题多半在本地出口、DNS 解析或 TLS 证书校验；只连某一家失败，则更可能是该供应商的区域可用性问题。跨境访问场景还要留意 IPv6 优先导致的解析到不可达地址，临时禁用 IPv6 或指定 IPv4 解析往往能立刻验证结论。 模型能力与请求参数不匹配，也可能被供应商网关翻译成 502。给不支持工具调用的模型传 tools 字段、给纯文本模型传图像内容、或把上下文长度设到超出模型上限，部分供应商返回的是明确的参数错误，部分则直接在网关层拒绝。此时对照供应商的模型能力表逐项删减参数，用最小可用请求跑通后再逐项加回，比逐条读错误日志更快定位。 把 502 从现象变成可定位的问题，关键是在链路上留下可对比的观测数据。Toonflow 侧至少要记录请求发起时间、首字节时间、上游状态码与供应商返回的请求标识；代理侧要打开访问日志与错误日志，看清 502 是由 upstream timed out 还是 connect refused 触发。首字节时间为零通常是连接阶段失败，首字节时间接近超时阈值则指向读超时，两种情况的处理方向完全不同。 单一供应商接入的 Toonflow 工作流，稳定性上限就等于这条链路的上限，因此在配置层做多供应商路由是必要的兜底。做法是给同一模型能力配置主备两条供应商线路，加上健康检查与熔断，主线路连续失败时自动切到备用线路，并在切换时记录原因供复盘。采用按量计费的第三方 API 中转服务作为备用线路，也不失为一种低成本的验证手段，但要注意其请求路径与错误码定义可能与直连供应商不同，排障时不能混用同一套判断标准。 有些 502 无论怎样调整配置都不会消失，这类情况应当直接交给供应商处理。典型特征是同一 API Key 换网络、换机器仍然稳定复现，且供应商状态页或公告中已有异常说明；此时继续在 Toonflow 侧改参数只会浪费时间。反过来，只在特定工作流、特定长输出、特定并发下出现的 502，基本都能在本地通过超时、缓冲与限流三项配置收敛。