先看状态码和错误正文,再把问题归到本机网络、鉴权额度、限流并发、模型服务端四层之一。重试和备用模型的规则由人事先定好。
要点速览
- 先看有无状态码与错误正文,再归到四层之一
- 连接超时查网络,等待生成超时调超时或改流式
- 401、403、404和上下文超长不应重试
- 429先用换Key、换模型、看他人三组对照判断范围
- 备用模型清单由人审批,敏感请求不得自动外发
大模型API调用报错、超时或被限流,多数情况不需要先怀疑模型本身。比较稳的做法是先读报错信息:有没有状态码,错误正文写了什么,请求卡在哪个阶段。然后把问题归到四层中的一层,分别是请求发出前的本机与网络、鉴权与额度、限流与并发、模型服务端。层级定下来,由谁确认、怎么处置也就清楚了。另外,重试和切换备用模型不要等出了问题再临时决定。这类规则应当由人事先定好,否则容易出现失败请求反复重试、重复计费,或者把敏感内容发到未经批准的模型上。
先看报错信息,再定层级
动手改配置之前,先把下面几样信息记下来。它们决定往哪一层查,也决定找谁确认。
- 有没有拿到HTTP状态码。如果只有连接失败、证书错误或超时,没有任何状态码,请求很可能没有到达服务端,问题多出在请求发出前。
- 状态码属于哪一类。4xx一般是请求本身或调用身份有问题,其中429单独归为限流;5xx一般是服务端出了状况。
- 错误正文里的类型和提示。同样是4xx,正文可能写着Key无效、模型不存在、额度不足或上下文超长,处置方法差别很大。
- 请求的上下文信息。包括请求标识、发生时间、使用的Key别名、模型名、输入长度、是否流式输出。后面向平台管理员或服务方求证时都要用到。
确认的分工大致如下:本机和网络问题由开发者自己先复现,代理和出口由网络管理员确认;Key、权限和额度由平台管理员确认;限流要结合团队整体调用量来判断;服务端问题需要外部服务方或内部模型运维方确认。
层级一:请求发出前,查本机与网络
这一层的典型现象是没有状态码,只有连接被拒、无法解析域名、证书校验失败或超时。按顺序看四处:
- 域名解析。接口域名能否解析,解析结果是否符合预期。内网环境如果配了自定义解析,可能还指向旧地址。
- 代理。本机或容器是否需要经过代理才能出网,代理环境变量是否在当前进程里生效。常见的情况是命令行能通、服务进程不通,原因是两者读到的代理配置不一样。
- 出口地址。有些服务或企业内部网关只放行特定出口地址。服务器换了机房或网络线路,出口地址变了,请求就会被拦下。
- 证书。企业网络里如果有做中间人解密的安全设备,客户端不信任它的证书时会直接握手失败。系统时间不准也会导致证书校验出错。
超时要分清是哪一种。连接超时指连接都没建立起来,基本可以归到网络层,按上面四处排查;链路质量问题可以参考服务器丢包按本机、机房、跨网、对端四段定位的方法。等待生成超时,也就是读取超时,指连接已经建立、请求已经送达,但模型生成的时间超过了客户端设置的等待时长。长输出加上非流式调用很容易出现这种情况。对应的处理是调整读取超时或改用流式输出,而不是立刻重试,因为重试只会再等一轮,还可能重复计费。
判断方法很简单:在同一台机器、同一网络环境下,用命令行工具发一个尽量简单的短请求。短请求能通,就把注意力转到超时设置和请求内容上;短请求也不通,就留在网络层继续查。
层级二:鉴权与额度,对应401、403、404类报错
请求到达了服务端,但被身份或资源校验挡了回来。常见对应关系如下:
- 401类:身份没被认出来。Key无效、已过期或已被吊销;复制时带了空格或换行;请求头格式不对;配置文件改了,但环境变量或服务进程没有重新加载。
- 403类:身份认出来了,但没有权限。Key有效,却没有被授权调用这个模型,或者所属项目、所在网络不在允许范围内。
- 404类:找不到要的东西。模型名拼写错误、大小写不一致、接口路径写错,或者模型已经下线、改名。
- 额度或余额用尽。各家服务的表现不一样,有的返回专门的状态码,有的返回429并在正文里说明额度不足。所以看到429也要读正文,分清是调用太快还是额度没了。
这一层由平台管理员确认。开发者要做的是提供Key别名、模型名、时间和完整错误正文,而不是换用同事的Key把问题绕过去。临时借用Key会让额度归属、调用记录和泄露责任都变得模糊,相关风险在团队共用大模型API Key有哪些风险里有更细的说明。
层级三:限流与并发,429类报错先判断范围
429的意思是请求频率或用量超出了允许范围。处理之前,先弄清限流落在哪个范围,可以用三组对照来判断:
- 换Key不换模型。用另一个Key调用同一个模型,如果正常,说明限制在单个Key上。
- 换模型不换Key。用同一个Key调用另一个模型,如果正常,说明限制在单个模型的配额上。
- 看同一时段其他人。团队里其他人同时出现429,往往是整个团队共用一个账户或一组配额,被某个批处理任务占满了。
处置方式有三种,各有取舍:
- 排队。请求进入队列按顺序发出,任务能完成,但延迟会变长,适合批量处理、离线生成这类不着急的任务。
- 降并发。主动减少同时在途的请求数。调用更稳定,整体吞吐会下降。
- 退避重试。失败后等一段时间再试,每次等待时间递增并加入随机抖动,避免大量客户端同时重试再次撞上限制。如果响应头里给了建议等待时间,优先按它来。重试必须设上限。
更根本的做法是把交互类调用和批量任务分开,分别使用不同的Key或不同的配额,避免一个夜间批处理任务拖住白天的对话入口。具体能给到多少配额,要以服务方的说明和团队的合同为准,不要凭经验估数。
层级四:模型服务端,5xx、上下文超长与流式中断
这一层的问题不在调用方,但调用方怎么处理,会影响损失的大小。
- 5xx类。500通常是服务内部错误,502、504多与网关和上游超时有关,503常见于过载或维护。可以有限次重试或切换到备用模型,但次数和切换范围要按事先定好的规则执行。
- 长文本超出上下文。一般返回4xx并提示长度超限。这是模型能力的边界,重试不会好转。处理方法是裁剪历史对话、把文档分段、先做摘要,或者换用上下文更长的模型,前提是这个模型在批准范围内。计算长度时要把输出预留也算进去,只算输入很容易踩线。
- 流式输出中断。内容收到一半连接断开。要区分是网关空闲超时、客户端读取超时,还是服务端主动中止。已经收到的部分应当保留,再决定续写还是重发。不加判断地整段重来,同一段生成会被计费两次。
外部服务要看服务方公布的状态信息,或者提交工单;企业内部私有化部署的模型,由模型运维方查看服务日志和资源占用。调用方要做的是把时间点、请求标识和错误正文交过去。
重试和切换备用模型,规则由人先定
很多事故并不是报错本身造成的,而是报错之后的自动处理失控:脚本对401无限重试,批处理在额度用尽后仍在排队重发,或者主模型限流时程序自动把请求转给一个从未评估过的外部模型。下面几条建议由负责人提前写成规则,再交给程序执行:
- 可重试与不可重试分开列。网络抖动、429、部分5xx可以有限次重试;401、403、404和上下文超长不应重试,重试只会制造噪音和费用。
- 设定次数和总时长上限。超过上限就报错,交给人处理,不再继续消耗。
- 考虑计费与重复执行。长生成和带工具调用的请求,重试可能导致重复计费或重复执行操作,要先确认能否安全重放。
- 备用模型清单需要审批。涉及客户资料、个人信息或内部敏感数据的请求,只能发往经过批准的模型,例如企业内部私有化部署的模型。主模型不可用时宁可排队等待,也不能自动外发。这与《中华人民共和国数据安全法》《中华人民共和国个人信息保护法》对数据处理的要求方向一致,具体口径由企业的合规负责人确认。
- 切换要留记录。每次重试和切换记下原因、目标模型和结果,方便事后复盘。
统一接入时,怎样更快定位到哪一层
如果团队里每个人、每个项目各自直连不同的模型服务,出问题时只能一台台机器去翻日志,很难看出是哪个Key、哪个模型出了状况。润迅的模型统一管理平台MaxModel,用一个Key接入各类大模型,并提供调用审计和多模型路由。放到这个问题里,调用审计让分散的调用有据可查,排查时可以对照着看问题集中在哪个Key、哪个模型上,再判断落在四层中的哪一层;多模型路由让调用经由统一入口分发到不同模型,团队不必在每个项目里各自维护一套接入方式。哪些模型可以作为备用、重试和切换的规则怎么定,仍由负责人决定;具体能落到什么程度,以产品实际能力和方案沟通为准。
对开发者来说,终端AI编程Agent同样依赖这些接口。迅码XunCode这类工具在调用模型报错时,也适合按四层来查:先看本机代理和网络,再看配置的接口地址、Key和模型名,然后看是否触发了限流,最后看服务端返回。XunCode可以帮忙读日志、整理报错信息、提示可能的层级;改配置、换Key、调整路由这些动作,由开发者和平台管理员确认后再做。相关配置项可以参考AI编程Agent接入公司大模型的四项配置。
行动建议:把四层排查写成团队的固定动作
- 统一报错记录格式。要求提交问题时附上状态码、错误正文、请求标识、时间、Key别名和模型名,缺一项就先补齐。
- 明确每层的确认人。网络找谁、Key和额度找谁、内部模型找谁,写在团队文档里,不靠口头转述。
- 分开交互与批量的配额。至少做到两类任务使用不同的Key,避免互相挤占。
- 写下重试与备用规则。列出可重试的错误类型、次数上限和批准的备用模型,经负责人签字后再配置到程序里。
- 把调用收拢到统一入口。调用分散、难以定位时,可以先了解大模型统一管理平台的一个Key、路由、审计三件事,再评估是否用MaxModel统一接入。需要沟通具体方案,可以拨打润迅业务咨询热线400-854-5566。
常见问题
大模型API返回429是什么意思?
429表示请求频率或用量超过了允许范围。先读错误正文,分清是调用太快还是额度用尽,再用换Key、换模型、看同事是否也报错三组对照,判断限制落在单个Key、单个模型还是整个团队。
大模型API调用超时,一定是网络问题吗?
不一定。连接超时多与网络、代理、出口地址有关。等待生成超时说明请求已送达,但生成时间超过了客户端的等待时长,常见于长输出的非流式调用,适合调大读取超时或改为流式输出。
API报401和403有什么区别?
401通常表示身份没被认出,比如Key无效、过期或格式错误;403表示身份已识别但权限不够,比如Key未被授权调用该模型。两者都应由平台管理员确认,不要换用他人的Key绕过。
调用失败后可以自动重试吗?
网络抖动、429和部分5xx可以有限次退避重试,但要设次数和总时长上限。401、403、404和上下文超长重试不会好转。长生成或带工具调用的请求在重试前,还要确认会不会重复计费或重复执行。
主模型限流时能自动切到其他模型吗?
可以切换,但备用模型清单要事先由负责人审批。涉及客户资料、个人信息等敏感内容的请求,只能发往经过批准的模型。主模型不可用时宁可排队,也不应自动发往未评估的外部模型。