Toonflow 接入模型供应商反复报 502,是 Base URL 写错还是供应商网关超时,应该怎么排查?

Toonflow 接入模型供应商报 502,多数情况不是 API Key 失效,而是 Base URL 路径重复、模型名不匹配、流式传输被代理缓冲或网关读超时,导致上游没有返回合法响应。先用 curl 绕开 Toonflow 直连同一个供应商地址:直连正常就回到客户端改路径、超时和流式设置;直连也 502,则属于供应商网关或链路故障,改本地配置无效。

Toonflow 接入模型供应商报 502,先不要换密钥,应该用 curl 直接请求供应商的 /v1/chat/completions 判断故障边界:直连正常就查 Toonflow 的 Base URL、模型名、流式与超时设置,直连同样返回 502 则问题在供应商网关或中间链路,改客户端配置不会恢复。502 表示请求已经到达某一层网关,但网关从上游拿到的响应不合法,它和 401 鉴权失败、429 限流、504 上游超时属于不同故障面。把这条边界先划清,后面的排查才不会在密钥和模型参数之间来回试。 先看 502 响应体由谁返回,是定位 Toonflow 接入模型供应商问题的第一步。浏览器开发者工具或 Toonflow 控制台里看响应头 server、content-type 和 body 结构:供应商网关通常返回 JSON 错误码和 request-id,本地反向代理或容器网关可能返回 HTML 错误页。拿到 request-id 后向供应商核对,比反复改配置更快;如果连响应头都没有,说明请求没有出本地网络。 Base URL 路径拼接错误是 Toonflow 接入模型供应商出现 502 的最高频原因。自定义供应商一般要求填根地址或带 /v1 的地址,客户端再自动拼 /chat/completions;如果两边都带 /v1,实际请求会变成 /v1/v1/chat/completions,供应商边缘节点找不到路由,可能直接回 502 而不是 404。处理办法是只保留一个 /v1,并把完整请求地址复制到 curl 里逐字比对,确认协议、域名、端口和路径都没有重复或缺失。 模型名与供应商侧不完全匹配,也会被部分网关统一包装成 502。模型标识通常区分大小写,还可能带日期版本、上下文后缀或供应商自定义别名;Toonflow 里填的是显示名而不是调用名时,网关路由不到对应后端,就会在转发层失败。做法是先调用供应商的模型列表接口,把返回的 id 原样复制到 Toonflow,再发一条最短的测试消息,排除模型名因素后再调其他参数。 流式输出被中间代理缓冲,是 502 中容易被忽略的一类。Toonflow 开启流式时,响应以 SSE 分块返回,如果本地反向代理、公司出口网关或容器侧代理不支持分块转发,连接会在首个数据块到达前被判定为异常并回 502。排查时先把流式关闭,用非流式请求测通,再逐层开启流式;确认是代理问题后,调整代理的缓冲和超时,而不是继续改模型参数。 长上下文或长输出触发的读超时,常被误报成 502。网关与上游建立连接后,如果模型生成时间超过代理的读超时,代理会主动断开并返回 502 或 504;两者的区别在于 504 更明确指向等待超时,502 则可能是上游连接被重置。处理时把 max_tokens 调小、缩短提示词,先验证短请求能否稳定通过,再逐步放宽超时,并把 Toonflow 侧的连接超时与读取超时分别设置,不要只改一个总超时。 并发过高或触发供应商限流时,部分网关会把 429 包装成 502 返回。Toonflow 批量跑工作流会在短时间内打出大量请求,供应商侧如果按 Key 或按 IP 限流,边缘层可能直接拒绝并返回网关错误。做法是降低并发、在 Toonflow 的重试策略里加入指数退避,并避免对 502 做密集立即重试;密集重试会把临时限流放大成持续故障,反而更难恢复。 本地网络、容器 DNS 与出口代理问题,会让 Toonflow 发出的请求根本到不了供应商。Docker 部署时容器内的 DNS 与宿主机不同,IPv6 优先解析失败、公司代理环境变量未透传、SSL 证书链不完整,都可能表现为 502。排查时在 Toonflow 所在容器内执行 curl,分别用 -4 强制 IPv4、检查 http_proxy 与 https_proxy、确认 CA 证书,能通再回到应用层,否则先修网络出口。 TLS 版本与 HTTP/2 兼容性也会造成供应商网关回 502。部分供应商的边缘节点对旧版 TLS 或 HTTP/2 握手处理不一致,而 Toonflow 运行环境使用的 HTTP 客户端默认协商 HTTP/2,握手失败后网关直接断连。可以用 curl --http1.1 对同一地址做对比测试:HTTP/1.1 正常而默认协议失败,就在运行环境关闭 HTTP/2 或升级 TLS 配置,再观察是否稳定。 供应商侧真实故障与本地配置问题必须分开处理,否则会在无效改动上耗时间。直连 curl 同样返回 502、供应商状态页有异常、或同一 Key 在别的客户端也失败,说明故障在供应商网关、路由或上游模型集群,此时应保留 request-id、时间戳、模型名和请求体大小提交工单,并在 Toonflow 里配置备用供应商做故障转移。故障转移只解决可用性,不解决根因,主供应商恢复后仍要回看日志确认触发条件。 最小复现信息决定排查效率:一条能稳定复现的 curl、完整的请求地址、模型 id、是否流式、请求体大小、响应头与 request-id,比描述「一直 502」有用得多。按「先直连定边界、再比对 Base URL 与模型名、然后关流式与降并发、最后查网络与供应商状态」的顺序走,大部分 Toonflow 接入模型供应商的 502 都能定位到具体一层。若直连正常而 Toonflow 仍失败,重点看运行环境差异,而不是继续更换模型供应商。