AI API 接入总是超时该先查哪一层？
AI API 接入出现 30 秒、60 秒或前端等待超时，应把 DNS、代理、网关、模型生成、前端取消和重试策略分层记录。
适用场景：用户看到转圈，开发只看到 timeout
这篇适合聊天窗口、客服摘要、文档生成、AI 自动化办公报表和开发者 AI 调用。表面现象都是“等很久后失败”，但真正原因可能完全不同：DNS 解析慢、代理握手失败、网关空闲超时、模型生成时间过长、前端主动取消、队列排队或重试把请求放大。永沃云枢在 https://ai.jn83.com 维护 AI 模型接口时，会先把超时点分层，而不是直接把所有 timeout 都归为模型慢。
如果用户搜索“GPT 中转超时”，可以在正文里解释这是新手搜索词；规范排查仍要回到 AI 模型接口接入与调用管理。只有知道超时发生在哪一层，才能决定是缩短输入、切换模型、调整网关、增加队列提示，还是修复前端取消逻辑。
操作步骤：先画一条请求链路
第一步，把链路写成浏览器或客户端、业务后端、代理或 CCSwitch、上游 AI API、模型生成、回传给前端。每层记录开始时间、结束时间、状态码、request_id 和错误原文。没有统一 request_id 时，至少用时间、用户、模型名和输入摘要对齐日志。
第二步，做三类最小请求。短提示词测试网络和认证；中等长度测试普通生成；长上下文或文件摘要测试业务真实负载。三类请求不要混在一起看均值，超时阈值也要分开设置。短请求都慢，优先查网络和代理；短请求正常、长请求慢，优先查输入规模和模型生成。
第三步，检查前端超时和后端超时是否一致。前端 30 秒取消，后端 120 秒还在跑，会造成用户以为失败但模型仍在消耗额度。后端提前断开，前端继续等待，也会造成空转。要明确取消请求是否会传到后端，以及结果是否会被废弃。
第四步，调整重试策略。超时重试必须有幂等键和次数限制，不能让用户连续点击生成，把同一任务排成多份。AI API 接入里，自动重试只能解决少量瞬时网络故障，不能解决提示词过长、队列过载或模型本身耗时过长。
排错路径：从可观测字段判断责任层
DNS 或 TLS 问题通常在请求发出前就失败，日志里没有上游 request_id；代理或网关问题可能有 502、504 或连接重置；模型生成慢则上游已接收请求，但响应迟迟不结束；前端取消则浏览器 Network 里可看到 canceled。把这些表现和时间点对应起来，排查会快很多。
如果是流式接口，还要看首 token 时间和完整结束时间。首 token 很慢，说明排队或模型启动慢；首 token 快但中途断，可能是代理缓冲、浏览器连接、网关空闲超时或前端渲染问题。所有结论都要配日志，不要只凭用户感受判断。
常见问题/避坑：不要盲目把 timeout 调大
把所有超时都调成 5 分钟通常会掩盖问题。用户等待体验变差，队列占用更久，失败成本也更高。更合理的做法是给短任务、长任务和后台任务不同阈值；超过阈值时展示排队或稍后查看，而不是让页面一直转圈。
另一个坑是没有区分已提交和已完成。请求发出不代表模型成功生成，推送 URL 不代表搜索引擎已收录，同理，后端收到任务也不代表用户端拿到结果。排查文档里要明确每个状态的边界。
检查清单：超时问题交付前要有证据
三类最小请求已测试；每层都有开始时间和结束时间；前端取消能传到后端；重试次数和幂等键明确；长输入有裁剪或摘要策略；用户提示区分排队、生成中、失败和可重试；站内链接、canonical、JSON-LD 和 sitemap 已同步。
验收时建议把同一条短请求连续跑三次，再把真实长输入跑一次，分别记录 P50、最长耗时和失败原文。若短请求稳定、长请求偶发超时，处理重点是输入规模、队列和用户提示；若短请求也不稳定，才优先看 DNS、代理、证书、网关和上游可用性。不要把两类结果混在同一个平均值里，否则很容易得出错误结论。
FAQ：可以完全交给 Codex 或模型自动处理吗？
可以让 Codex 帮你收集文件、执行低风险检查、整理日志和生成初稿，但涉及生产配置、用户数据、金额、权限、正式发布和搜索提交时，仍要保留人工确认点。自动化的目标是减少重复操作，不是绕过验收。