如何发现、定位并处理大模型 API 调用失败？

核心回答

发现模型 API 调用失败，不能只等用户反馈或检查状态码。我会在调用入口记录请求、步骤和每次尝试的标识，检查连接异常、非成功响应、流式错误和异常终止，再分别统计调用成功、结果完整与业务完成情况。

定位时先确认故障时间和影响范围，沿 trace_id 找到具体外部尝试，结合供应商请求 ID、错误体、响应头和分阶段耗时，区分请求参数、凭证权限、限流配额、网络、供应商故障与解析问题。采取对应修复或受控恢复后，用原失败场景验证，并补成回归用例。

展开解析

1. 建立可靠的失败信号

调用封装需要捕获并规范化 SDK 异常，同时记录供应商、模型、接口、提示词版本、输入大小、各阶段耗时、终止状态与错误类型。敏感原文按需要脱敏或受控留存，不能把完整凭证放进日志。

对流式请求，收到 HTTP 200 只说明流已开始，还要处理错误事件、连接提前关闭和没有正常结束的输出。对于结构化结果，需要独立记录解析与业务校验失败；模型拒答、无足够证据也不能与网络故障混为一谈。

指标按供应商、模型、版本和任务类型分层。总体成功率可能掩盖某个模型或区域全失败，原始请求成功率也不能掩盖大量重试后才成功的成本与延迟。

2. 用证据逐步缩小范围

排查步骤	要看的证据	能区分的问题
确认时间与人群	发布记录、配置变更、错误趋势、失败样本	新版本问题还是所有版本的公共依赖问题
判断是否发到下游	客户端异常、DNS/TLS/连接耗时、网关记录	本地连接失败还是已有供应商响应
检查请求契约	模型名、接口、消息角色、参数、工具 schema、输入长度	适配错误、能力不支持、上下文过长
检查身份与额度	状态码、错误类型、项目/区域、配额与限流头	凭证、权限、短期限流和长期额度问题
检查响应全过程	首个有效输出、事件序列、终止原因、解析结果	排队、断流、截断、格式或消费端问题
对照同类成功请求	相近时间、同模型、同区域和输入规模	是否与长度、并发、路径或版本相关

供应商请求 ID 要按每次尝试保留，便于关联外部问题；没有得到响应时它可能不存在，这本身也是定位线索。状态页只能辅助判断，不能代替具体请求证据。

3. 超时要查“时间花在哪里”

总耗时可能来自应用排队、连接建立、模型首字等待、后续生成或客户端处理。先拆时间，再决定策略：连接慢查代理、解析域名、证书、连接池；首字慢看输入长度、并发与服务负载；持续输出但总时长过长则看输出需求与截止时间；上游已完成而前端仍等待，继续查服务端转发、缓冲和结束事件。

不能只把超时统一调大。调大可能减少表面错误，却让资源长时间占用并扩大积压；重试也可能让过载更严重。

4. 对症处理，并用同一场景验证

参数错误修适配，鉴权失败核对有效凭证和权限；短期限流减少并发并按契约退避，额度耗尽先解决额度；瞬时故障在预算内重试，持续不可用切合格备用路径。写操作结果未知时查状态或幂等恢复，避免整段工作流重复执行。

复现时固定失败请求的必要输入、版本和环境，缩成不含敏感数据的最小请求；比较修复前后的错误类型、完整性、尾延迟和额外尝试，而不是只看某次调用成功。

可以在测试客户端或代理中模拟限流响应、等待提示、连接重置、延迟和流中错误，检查重试间隔、取消、停止条件与最终状态。模拟验证的是处理逻辑，不证明真实供应商的容量；真实配额与网络仍需单独观察。

追问

除了限流，还常见什么失败？

模型或接口配置不匹配、输入超限、凭证失效、网络与代理问题、服务端过载、输出截断、流式中断、解析错误都可能出现。排查应沿实际信号定位，不能见到“无结果”就归因于限流。

恢复成功后还要做什么？

确认受影响任务是否完成、是否存在未知写入或重复动作，再把根因、版本与回归用例补齐。单次成功只能说明那次请求成功，不能证明故障整体已经消失。

对应教程

参考资料