搞大模型接口调试最烦的不是模型回答得不好而是报错一个接一个。429、500、超时、上下文截断、流式乱码这五个词我最近几乎每天都要见一遍。尤其是429热词里都出现“429总线”了可见大家被限流折磨得有多狠。这篇就把我这段时间排查这五类报错的经验整理一下。我会把每个报错背后的触发原理、排查步骤、应对方案都拆开讲清楚文末附一张速查表方便你直接抄作业。1. 五种报错先分清“敌我”1.1 从错误码看问题归属遇到报错的第一步不是查代码而是先判断问题出在哪一端。我习惯把大模型接口调用拆成三段客户端你的代码、网络链路、服务端模型推理服务。五种报错对应的责任方完全不同。429和超时通常是客户端或配额问题500多半是服务端问题上下文截断和流式乱码则介于参数配置和数据处理之间。这里面有个关键认知4xx开头的错误码大概率不是模型本身的问题而是你的请求方式不对5xx开头的错误码才需要往服务端想。报错类型常见阶段责任方倾向429 Too Many Requests请求发出后被拒客户端并发/配额超限500 Internal Server Error请求到达服务端服务端异常或参数非法超时Timeout请求发出后无响应网络或服务端响应慢上下文截断模型已开始生成参数设置或窗口限制流式乱码生成内容返回途中编码处理/数据拼接1.2 排查的先后顺序我的习惯是“先自身、后外部、再网络”。先用最小请求排除参数问题再查服务商状态页最后看网络链路。顺序反了容易白忙活比如网络本身没问题你非去查DNS浪费时间。还有一条经验不要一报错就重试。429和500的重试策略完全不同后面我会专门说。很多人在429报错后立刻重试结果越试越糟甚至触发更严格的限流连exceeded retry limit这种提示都出来了。2. 429 限流最频繁也最容易被误解2.1 429 到底在说什么429 Too Many Requests表面意思是请求太多但服务商在背后限流时依据的维度其实有好几种。最常见的是 RPM每分钟请求数、TPM每分钟Token数和并发数限制。RPM限制比较好理解一分钟内最多发多少次请求。TPM限制则隐蔽得多它统计的是你请求里input token和output token的总和。如果你每次请求都塞了很长的上下文即使请求次数不多也可能触发TPM上限。还有并发限制同一时刻在途的请求数不能超过某个值。这就能解释为什么热词里会出现codex exceeded retry limit, last status: 429 too many requests, request id这种报错。Codex这类工具的请求量本身就大客户端在遇到429后如果按固定间隔反复重试重试请求本身也占用配额最后就变成“越重试越限流”的死循环。2.2 排查429的正确姿势排查429时先别急着改代码。把请求头打开看看响应头里藏着服务商的限额信息。curl -i https://api.example.com/v1/chat/completions \ -H Content-Type: application/json \ -H Authorization: Bearer YOUR_API_KEY \ -d {model:gpt-4,messages:[{role:user,content:hello}]}观察响应头中是否有Retry-After、x-ratelimit-limit-requests、x-ratelimit-remaining-tokens这类字段。Retry-After直接告诉你需要等多少秒再试这是最权威的参考值。有些服务商不返回这个头那就得看x-ratelimit-*系列计算剩余配额。另一个容易忽略的点429不一定在HTTP层暴露。有的SDK内部做了重试表面只报一次错实际上已经帮你试了好几次。排查时要把SDK自带的重试逻辑关掉或看清楚次数否则你以为是服务商限流其实是SDK自己把配额试完了。2.3 处理429的实战策略遇到429最稳的应对方案是指数退避加抖动Exponential Backoff with Jitter。指数退避让等待时间按倍数增长抖动则是在等待时间上加入随机值防止多个客户端同时重试造成“惊群效应”。import random import time import requests def call_with_retry(url, headers, payload, max_attempts5): for attempt in range(max_attempts): resp requests.post(url, headersheaders, jsonpayload) if resp.status_code ! 429: return resp retry_after resp.headers.get(Retry-After) if retry_after: wait_time float(retry_after) else: wait_time (2 ** attempt) random.uniform(0, 1) print(f429 received, retry after {wait_time:.2f}s) time.sleep(wait_time) return resp如果429还很频繁说明你的请求量已经触碰到账号配额上限。这时候要检查账号套餐而不是继续优化代码。另外可以看服务商是否提供批量接口或异步任务很多场景下异步队列比实时请求更划算。还有个经验把非关键的请求错峰执行。我在做离线批量处理时会把任务打散到凌晨执行避开线上高峰。实测下来429的出现频率能降低一大截。3. 500 内部服务错误两种完全不同的局面3.1 官方 API 的 500先看消息体再看状态页500 Internal Server Error比429更难定位因为“内部错误”四个字包含了太多可能。排查500时第一步永远是看响应体里有没有额外信息。很多服务端会在body里附带错误描述比如invalid url、model not found这些信息能直接定位问题。热词里有一条很典型api error: 500 invalid url. this is a server-side issue, usually temporary。这条报错虽然写着“server-side issue”但实际排查时一定要先检查请求的URL和路径。我遇到过好几次其实是端点拼写错误比如把/v1/completions写成了/v1/complete服务端返回500而不是404误导性很强。如果body里只有笼统的500再去看服务商的状态页。大厂通常会提供运行状态页也能通过状态页判断是全局限流还是局部故障。遇到官方故障你唯一能做的就是等待同时准备好降级方案。降级方案可以是一个备用模型也可以是缓存的旧结果。3.2 自建服务的 500日志是救命稻草自己部署开源模型比如用 llama-server 跑本地推理时500的排查思路完全不同。热词里那条500 internal server error: llama-server process has terminated: exit status我见过很多次这通常意味着推理进程真的崩了。进程终止的原因按概率排序是显存不足OOM、模型文件损坏、依赖库版本冲突、并发请求打爆了进程。排查时先看服务日志日志里通常直接写了崩溃原因和堆栈信息。再看进程退出码exit status 1一般是配置错误exit status 137是被系统杀掉通常是内存超限。自建服务还有一个容易被忽略的坑并发窗口。llama-server 这类服务默认可能只支持少量并发如果你在客户端开了多线程同时请求很容易把进程打崩。解决方式是限制客户端并发数或者给服务端配置请求队列。3.3 客户端面对 500 能做什么先说结论500可以重试但必须有限度、有间隔。官方API的500通常是临时故障隔几秒重试一次往往能成功。但如果连续重试3次还是500就不要再试了说明问题不在你这一侧继续试只是浪费配额。500重试需要注意幂等性。如果请求本身会触发服务端写操作比如带历史记录的会话重试前要确认服务端是否支持幂等键。有些服务商会提供Idempotency-Key请求头设置好之后重试才能避免重复创建数据。4. 超时最让人焦虑的“等待”4.1 超时其实有好几种超时是五种报错里体验最差的因为它不报错就是干等。等你等到怀疑人生的时候它才甩给你一句timeout。排查超时前先搞清楚你设置的是哪种超时。HTTP客户端的超时通常分三种连接超时connect timeout、读超时read timeout、总超时overall timeout。连接超时是TCP握手的最长等待时间读超时是两次数据包之间的最大间隔总超时是整次请求的最长耗时。很多人的误区是只设置一个超时时间。比如Python requests里只传一个timeout30实际上这会把连接和读取都设为30秒。对大模型接口来说这个设置极不友好——连接建立可能只要1秒但模型生成一段长文本可能就要30秒以上结果被读超时一刀切断了。4.2 超时参数的合理设置我的建议是分别设置连接超时和读超时。连接超时可以设短一点因为TCP握手很慢通常意味着网络或DNS有问题没必要等太久读超时要设长一些因为大模型生成文本本身就需要时间。import requests # 连接超时5秒读超时120秒 resp requests.post( url, headersheaders, jsonpayload, timeout(5, 120) )JavaScript侧的处理逻辑类似用AbortController配合setTimeout可以实现分阶段超时。const controller new AbortController(); // 总超时90秒 const timer setTimeout(() controller.abort(), 90000); try { const resp await fetch(url, { method: POST, headers: headers, body: JSON.stringify(payload), signal: controller.signal }); clearTimeout(timer); // 处理响应 } catch (err) { if (err.name AbortError) { console.log(request timeout); } }超时时间没有统一标准我通常按接口用途分档实时对话接口读超时30秒生成较长内容的任务60到120秒批量任务甚至可以到300秒。超时设置的核心原则是“比服务端平均响应时间多出一倍但不超过业务可容忍的最长等待时间”。4.3 超时排查思路排查超时先用curl测试链路判断是哪一段慢。# 查看TCP连接耗时 curl -v -o /dev/null https://api.example.com/v1/chat/completions \ -H Content-Type: application/json \ -H Authorization: Bearer YOUR_API_KEY \ -d {model:gpt-4,messages:[{role:user,content:hi}]} \ --connect-timeout 5 --max-time 60curl的time_total能告诉你总耗时time_connect能告诉你TCP握手耗时。如果time_connect接近或等于超时时间多半是网络问题如果握手很快但迟迟拿不到响应那是服务端生成太慢。排查网络问题时ping只能看主机通不通看不到链路质量。更靠谱的做法是用curl加上-w参数看各阶段耗时或者用traceroute看路由跳数。热词里那条“ping一个IP显示接收第二个数据其他都是请求超时”很典型说明中间某个节点丢包这时候请求超时是必然的不是你代码的问题。4.4 超时后最大的陷阱盲目重试超时重试有一个很隐蔽的风险请求可能已经在服务端被执行了只是响应没回来。此时你重试相当于执行了两次相同请求。如果是生成型任务还好多花一次钱而已如果是带副作用的任务写数据库、发送消息就会产生重复数据。所以超时后的重试策略要格外小心。我建议对于查询类请求可以重试对于写入类请求先查重确认上一次请求没有生效再重试。另外重试间隔不能太短给服务端留出处理上一请求的时间。5. 上下文截断输出“不完整”的隐性杀手5.1 截断的类型上下文截断不像前几种报错那样有明确的错误码它表现为“模型回答到一半突然停了”有时候甚至不会报错只是在文本末尾多了一个奇怪的断句符。这种问题最坑人因为它表面看起来是模型能力问题实际上是参数或窗口问题。截断分两种输入侧截断和输出侧截断。输入侧截断指你塞进模型的对话历史太长超过模型的上下文窗口服务端强制砍掉前半部分内容。输出侧截断指模型生成的回复达到max_tokens上限被迫停止生成。5.2 怎么判断是截断还是模型能力问题判断逻辑很简单。检查API返回里的finish_reason字段如果值是length说明是输出截断如果值是stop说明是正常结束。这个字段是最直接的标准很多开发者在排查时完全忽略它导致把正常回答误判为模型能力不足。resp requests.post(url, headersheaders, jsonpayload) data resp.json() # 检查结束原因 finish_reason data[choices][0][finish_reason] if finish_reason length: print(output truncated, increase max_tokens)输入侧截断的判断稍微麻烦点。如果对话轮次变长后模型突然“忘记”了对话开头的信息很可能就是输入被截断了。你可以对比截断前后的API请求日志看实际发送的token数量是否触及窗口上限。5.3 几类典型场景与解法长对话是最容易出现上下文截断的场景。多轮对话累加下去很快就顶到窗口上限。解法通常是滑动窗口只保留最近N轮加自动摘要把早期的对话总结成一句话。我在项目里会维护一个消息列表超过设定轮数后把最早的两轮替换为一个系统消息摘要。批量任务也是重灾区。很多人写循环任务时把max_tokens固定在一个值比如512。如果某条输入特别长生成的回复也长512就装不下了。解决方法是动态估算根据输入长度调整max_tokens或者把固定值调高一档。代码层面可以写一个简单的token统计函数来估算长度def estimate_tokens(messages): total 0 for msg in messages: total len(msg.get(content, )) // 4 # 粗略估算 return total messages [ {role: system, content: You are a helpful assistant}, {role: user, content: ...}, ] # 估算token数预留输出空间 input_tokens estimate_tokens(messages) max_tokens min(4096 - input_tokens, 2048)注意这个估算方式只是粗略值严格的token计算要用服务商提供的tokenizer库。但作为兜底策略它能避免大部分截断场景。6. 流式乱码显示层的问题6.1 乱码出现的三个层面流式输出Streaming是现在最常用的交互方式一个字一个字往外蹦体验很棒但调试起来也最烦。乱码问题主要出在三个层面编码不一致、数据块截断、压缩格式处理不当。编码不一致最常见。服务端返回的是UTF-8编码的文本你的代码用GBK或其他编码去解码出来的就是“锟斤拷”。这种问题在日志里最隐蔽因为日志显示的是终端字符集处理后的结果可能看起来正常但API响应内容是乱码。数据块截断则和SSEServer-Sent Events的传输特性有关。SSE是流式返回数据是一块一块传过来的。如果某一块恰好把一个多字节字符比如中文的某个字从中间切开你直接解码就会得到半个字符显示为。6.2 排查与处理排查编码问题先确认服务端返回的Content-Type是否带了charsetutf-8。然后用curl看原始字节流别用浏览器控制台。curl -N https://api.example.com/v1/chat/completions \ -H Content-Type: application/json \ -H Authorization: Bearer YOUR_API_KEY \ -d {model:gpt-4,messages:[{role:user,content:讲个笑话}],stream:true}如果原始字节流正常但你的程序输出乱码问题就在解码环节。Python里处理流式响应时要确保每次拿到的chunk都能完整解码不能直接把二进制chunk转字符串要按UTF-8的规则做边界判断。6.3 SSE流式拼接的正确姿势处理SSE流我的做法是“按事件读取按行解析累积buffer”。每次收到数据块先拼接到缓冲区再从缓冲区里按换行符切出完整的SSE事件来处理。这样能避免半个字符的问题。import json import requests def parse_sse_stream(resp): buffer for chunk in resp.iter_content(chunk_size1024): if not chunk: continue buffer chunk.decode(utf-8, errorsignore) while \n in buffer: line, buffer buffer.split(\n, 1) line line.strip() if not line.startswith(data:): continue data line[5:].strip() if data [DONE]: return try: obj json.loads(data) delta obj[choices][0][delta].get(content, ) if delta: print(delta, end, flushTrue) except json.JSONDecodeError: # 数据块不完整继续等待 buffer line \n buffer break还有一个实际经验有些服务端在流式返回时会做压缩如gzip如果你设置Accept-Encoding: gzip而没有正确处理压缩流拿到的是压缩字节流自然乱码。最简单的处理方式是把请求头里的Accept-Encoding设置为identity强制服务端返回不压缩的数据。追求性能的话就要在客户端正确解压不能直接把压缩流当文本拼接。7. 一张“错误速查表”与梳理总结7.1 错误速查表把这五类报错的排查要点汇总成一张表遇到问题照着查能省下不少时间。报错首要动作次选动作兜底方案429看响应头Retry-After检查RPM/TPM配额指数退避重试500看响应body和日志查服务商状态页降级到备用模型超时curl分阶段测耗时调整连接/读超时检查网络链路上下文截断检查finish_reason统计token消耗压缩对话历史流式乱码用curl看原始字节流检查编码声明按buffer正确解析7.2 规范化的日志与监控排查报错时最怕的是没有日志。我强烈建议在调用大模型接口时把以下字段完整记录下来时间戳、模型名称、请求ID如果有、状态码、响应耗时、finish_reason、错误信息。这些日志在做复盘时价值极高。请求ID特别关键。服务端返回的request_id是你向服务商反馈问题时的凭证也是排查时关联服务端日志的唯一线索。热词里的codex exceeded retry limit, last status: 429 too many requests, request id就指明了用request_id定位问题的方式。我在所有日志里都会带上request_id没有的话也要记录完整的请求头。监控指标方面至少要统计请求成功率、429占比、500占比、平均响应时间、P95响应时间、超时次数。429占比突然升高说明客户端并发或配额有问题500占比升高说明服务端不稳定P95响应时间升高说明模型推理变慢。这些指标能帮你提前发现问题而不是等用户反馈。7.3 预防比排查更重要排查能力只是底线真正省心的是做好预防。我目前的习惯是客户端做三层兜底第一层是“合理性检查”参数、URL、编码第二层是“自适应重试”按Retry-After或指数退避第三层是“降级方案”备用模型、缓存结果、人工处理。代码层面还有一个容易被忽略的点处理好并发。很多303/超时问题源头就是客户端同一时间发出太多并发请求。哪怕服务商没限流你的机器也可能因为文件描述符、端口耗尽而出现连接问题。给所有HTTP客户端加上并发池限制能省掉一半的坑。热词里提到pg 对单表500万数据 怎么样这个虽然看起来无关但它背后的思路和接口调优是一样的数据量和并发量上来了很多问题才会暴露。大模型接口也一样开发环境调得再顺上线后一天几十万请求时各种报错都会冒出来。提前做好限流、熔断、监控才是长期稳定的关键。我个人在实际操作中的体会是这五种报错其实不是孤立的它们经常连环出现。429重试太多会变成500超时重试太急会触发429上下文截断后重发长文本又可能引发超时。排查时别只盯着眼前这条错误要把整个请求的生命周期串起来看。日志里记录的每一条时间点都是解开连环报错的线索。
大模型接口调试实战：429限流、超时、500等五类报错排查与应对
搞大模型接口调试最烦的不是模型回答得不好而是报错一个接一个。429、500、超时、上下文截断、流式乱码这五个词我最近几乎每天都要见一遍。尤其是429热词里都出现“429总线”了可见大家被限流折磨得有多狠。这篇就把我这段时间排查这五类报错的经验整理一下。我会把每个报错背后的触发原理、排查步骤、应对方案都拆开讲清楚文末附一张速查表方便你直接抄作业。1. 五种报错先分清“敌我”1.1 从错误码看问题归属遇到报错的第一步不是查代码而是先判断问题出在哪一端。我习惯把大模型接口调用拆成三段客户端你的代码、网络链路、服务端模型推理服务。五种报错对应的责任方完全不同。429和超时通常是客户端或配额问题500多半是服务端问题上下文截断和流式乱码则介于参数配置和数据处理之间。这里面有个关键认知4xx开头的错误码大概率不是模型本身的问题而是你的请求方式不对5xx开头的错误码才需要往服务端想。报错类型常见阶段责任方倾向429 Too Many Requests请求发出后被拒客户端并发/配额超限500 Internal Server Error请求到达服务端服务端异常或参数非法超时Timeout请求发出后无响应网络或服务端响应慢上下文截断模型已开始生成参数设置或窗口限制流式乱码生成内容返回途中编码处理/数据拼接1.2 排查的先后顺序我的习惯是“先自身、后外部、再网络”。先用最小请求排除参数问题再查服务商状态页最后看网络链路。顺序反了容易白忙活比如网络本身没问题你非去查DNS浪费时间。还有一条经验不要一报错就重试。429和500的重试策略完全不同后面我会专门说。很多人在429报错后立刻重试结果越试越糟甚至触发更严格的限流连exceeded retry limit这种提示都出来了。2. 429 限流最频繁也最容易被误解2.1 429 到底在说什么429 Too Many Requests表面意思是请求太多但服务商在背后限流时依据的维度其实有好几种。最常见的是 RPM每分钟请求数、TPM每分钟Token数和并发数限制。RPM限制比较好理解一分钟内最多发多少次请求。TPM限制则隐蔽得多它统计的是你请求里input token和output token的总和。如果你每次请求都塞了很长的上下文即使请求次数不多也可能触发TPM上限。还有并发限制同一时刻在途的请求数不能超过某个值。这就能解释为什么热词里会出现codex exceeded retry limit, last status: 429 too many requests, request id这种报错。Codex这类工具的请求量本身就大客户端在遇到429后如果按固定间隔反复重试重试请求本身也占用配额最后就变成“越重试越限流”的死循环。2.2 排查429的正确姿势排查429时先别急着改代码。把请求头打开看看响应头里藏着服务商的限额信息。curl -i https://api.example.com/v1/chat/completions \ -H Content-Type: application/json \ -H Authorization: Bearer YOUR_API_KEY \ -d {model:gpt-4,messages:[{role:user,content:hello}]}观察响应头中是否有Retry-After、x-ratelimit-limit-requests、x-ratelimit-remaining-tokens这类字段。Retry-After直接告诉你需要等多少秒再试这是最权威的参考值。有些服务商不返回这个头那就得看x-ratelimit-*系列计算剩余配额。另一个容易忽略的点429不一定在HTTP层暴露。有的SDK内部做了重试表面只报一次错实际上已经帮你试了好几次。排查时要把SDK自带的重试逻辑关掉或看清楚次数否则你以为是服务商限流其实是SDK自己把配额试完了。2.3 处理429的实战策略遇到429最稳的应对方案是指数退避加抖动Exponential Backoff with Jitter。指数退避让等待时间按倍数增长抖动则是在等待时间上加入随机值防止多个客户端同时重试造成“惊群效应”。import random import time import requests def call_with_retry(url, headers, payload, max_attempts5): for attempt in range(max_attempts): resp requests.post(url, headersheaders, jsonpayload) if resp.status_code ! 429: return resp retry_after resp.headers.get(Retry-After) if retry_after: wait_time float(retry_after) else: wait_time (2 ** attempt) random.uniform(0, 1) print(f429 received, retry after {wait_time:.2f}s) time.sleep(wait_time) return resp如果429还很频繁说明你的请求量已经触碰到账号配额上限。这时候要检查账号套餐而不是继续优化代码。另外可以看服务商是否提供批量接口或异步任务很多场景下异步队列比实时请求更划算。还有个经验把非关键的请求错峰执行。我在做离线批量处理时会把任务打散到凌晨执行避开线上高峰。实测下来429的出现频率能降低一大截。3. 500 内部服务错误两种完全不同的局面3.1 官方 API 的 500先看消息体再看状态页500 Internal Server Error比429更难定位因为“内部错误”四个字包含了太多可能。排查500时第一步永远是看响应体里有没有额外信息。很多服务端会在body里附带错误描述比如invalid url、model not found这些信息能直接定位问题。热词里有一条很典型api error: 500 invalid url. this is a server-side issue, usually temporary。这条报错虽然写着“server-side issue”但实际排查时一定要先检查请求的URL和路径。我遇到过好几次其实是端点拼写错误比如把/v1/completions写成了/v1/complete服务端返回500而不是404误导性很强。如果body里只有笼统的500再去看服务商的状态页。大厂通常会提供运行状态页也能通过状态页判断是全局限流还是局部故障。遇到官方故障你唯一能做的就是等待同时准备好降级方案。降级方案可以是一个备用模型也可以是缓存的旧结果。3.2 自建服务的 500日志是救命稻草自己部署开源模型比如用 llama-server 跑本地推理时500的排查思路完全不同。热词里那条500 internal server error: llama-server process has terminated: exit status我见过很多次这通常意味着推理进程真的崩了。进程终止的原因按概率排序是显存不足OOM、模型文件损坏、依赖库版本冲突、并发请求打爆了进程。排查时先看服务日志日志里通常直接写了崩溃原因和堆栈信息。再看进程退出码exit status 1一般是配置错误exit status 137是被系统杀掉通常是内存超限。自建服务还有一个容易被忽略的坑并发窗口。llama-server 这类服务默认可能只支持少量并发如果你在客户端开了多线程同时请求很容易把进程打崩。解决方式是限制客户端并发数或者给服务端配置请求队列。3.3 客户端面对 500 能做什么先说结论500可以重试但必须有限度、有间隔。官方API的500通常是临时故障隔几秒重试一次往往能成功。但如果连续重试3次还是500就不要再试了说明问题不在你这一侧继续试只是浪费配额。500重试需要注意幂等性。如果请求本身会触发服务端写操作比如带历史记录的会话重试前要确认服务端是否支持幂等键。有些服务商会提供Idempotency-Key请求头设置好之后重试才能避免重复创建数据。4. 超时最让人焦虑的“等待”4.1 超时其实有好几种超时是五种报错里体验最差的因为它不报错就是干等。等你等到怀疑人生的时候它才甩给你一句timeout。排查超时前先搞清楚你设置的是哪种超时。HTTP客户端的超时通常分三种连接超时connect timeout、读超时read timeout、总超时overall timeout。连接超时是TCP握手的最长等待时间读超时是两次数据包之间的最大间隔总超时是整次请求的最长耗时。很多人的误区是只设置一个超时时间。比如Python requests里只传一个timeout30实际上这会把连接和读取都设为30秒。对大模型接口来说这个设置极不友好——连接建立可能只要1秒但模型生成一段长文本可能就要30秒以上结果被读超时一刀切断了。4.2 超时参数的合理设置我的建议是分别设置连接超时和读超时。连接超时可以设短一点因为TCP握手很慢通常意味着网络或DNS有问题没必要等太久读超时要设长一些因为大模型生成文本本身就需要时间。import requests # 连接超时5秒读超时120秒 resp requests.post( url, headersheaders, jsonpayload, timeout(5, 120) )JavaScript侧的处理逻辑类似用AbortController配合setTimeout可以实现分阶段超时。const controller new AbortController(); // 总超时90秒 const timer setTimeout(() controller.abort(), 90000); try { const resp await fetch(url, { method: POST, headers: headers, body: JSON.stringify(payload), signal: controller.signal }); clearTimeout(timer); // 处理响应 } catch (err) { if (err.name AbortError) { console.log(request timeout); } }超时时间没有统一标准我通常按接口用途分档实时对话接口读超时30秒生成较长内容的任务60到120秒批量任务甚至可以到300秒。超时设置的核心原则是“比服务端平均响应时间多出一倍但不超过业务可容忍的最长等待时间”。4.3 超时排查思路排查超时先用curl测试链路判断是哪一段慢。# 查看TCP连接耗时 curl -v -o /dev/null https://api.example.com/v1/chat/completions \ -H Content-Type: application/json \ -H Authorization: Bearer YOUR_API_KEY \ -d {model:gpt-4,messages:[{role:user,content:hi}]} \ --connect-timeout 5 --max-time 60curl的time_total能告诉你总耗时time_connect能告诉你TCP握手耗时。如果time_connect接近或等于超时时间多半是网络问题如果握手很快但迟迟拿不到响应那是服务端生成太慢。排查网络问题时ping只能看主机通不通看不到链路质量。更靠谱的做法是用curl加上-w参数看各阶段耗时或者用traceroute看路由跳数。热词里那条“ping一个IP显示接收第二个数据其他都是请求超时”很典型说明中间某个节点丢包这时候请求超时是必然的不是你代码的问题。4.4 超时后最大的陷阱盲目重试超时重试有一个很隐蔽的风险请求可能已经在服务端被执行了只是响应没回来。此时你重试相当于执行了两次相同请求。如果是生成型任务还好多花一次钱而已如果是带副作用的任务写数据库、发送消息就会产生重复数据。所以超时后的重试策略要格外小心。我建议对于查询类请求可以重试对于写入类请求先查重确认上一次请求没有生效再重试。另外重试间隔不能太短给服务端留出处理上一请求的时间。5. 上下文截断输出“不完整”的隐性杀手5.1 截断的类型上下文截断不像前几种报错那样有明确的错误码它表现为“模型回答到一半突然停了”有时候甚至不会报错只是在文本末尾多了一个奇怪的断句符。这种问题最坑人因为它表面看起来是模型能力问题实际上是参数或窗口问题。截断分两种输入侧截断和输出侧截断。输入侧截断指你塞进模型的对话历史太长超过模型的上下文窗口服务端强制砍掉前半部分内容。输出侧截断指模型生成的回复达到max_tokens上限被迫停止生成。5.2 怎么判断是截断还是模型能力问题判断逻辑很简单。检查API返回里的finish_reason字段如果值是length说明是输出截断如果值是stop说明是正常结束。这个字段是最直接的标准很多开发者在排查时完全忽略它导致把正常回答误判为模型能力不足。resp requests.post(url, headersheaders, jsonpayload) data resp.json() # 检查结束原因 finish_reason data[choices][0][finish_reason] if finish_reason length: print(output truncated, increase max_tokens)输入侧截断的判断稍微麻烦点。如果对话轮次变长后模型突然“忘记”了对话开头的信息很可能就是输入被截断了。你可以对比截断前后的API请求日志看实际发送的token数量是否触及窗口上限。5.3 几类典型场景与解法长对话是最容易出现上下文截断的场景。多轮对话累加下去很快就顶到窗口上限。解法通常是滑动窗口只保留最近N轮加自动摘要把早期的对话总结成一句话。我在项目里会维护一个消息列表超过设定轮数后把最早的两轮替换为一个系统消息摘要。批量任务也是重灾区。很多人写循环任务时把max_tokens固定在一个值比如512。如果某条输入特别长生成的回复也长512就装不下了。解决方法是动态估算根据输入长度调整max_tokens或者把固定值调高一档。代码层面可以写一个简单的token统计函数来估算长度def estimate_tokens(messages): total 0 for msg in messages: total len(msg.get(content, )) // 4 # 粗略估算 return total messages [ {role: system, content: You are a helpful assistant}, {role: user, content: ...}, ] # 估算token数预留输出空间 input_tokens estimate_tokens(messages) max_tokens min(4096 - input_tokens, 2048)注意这个估算方式只是粗略值严格的token计算要用服务商提供的tokenizer库。但作为兜底策略它能避免大部分截断场景。6. 流式乱码显示层的问题6.1 乱码出现的三个层面流式输出Streaming是现在最常用的交互方式一个字一个字往外蹦体验很棒但调试起来也最烦。乱码问题主要出在三个层面编码不一致、数据块截断、压缩格式处理不当。编码不一致最常见。服务端返回的是UTF-8编码的文本你的代码用GBK或其他编码去解码出来的就是“锟斤拷”。这种问题在日志里最隐蔽因为日志显示的是终端字符集处理后的结果可能看起来正常但API响应内容是乱码。数据块截断则和SSEServer-Sent Events的传输特性有关。SSE是流式返回数据是一块一块传过来的。如果某一块恰好把一个多字节字符比如中文的某个字从中间切开你直接解码就会得到半个字符显示为。6.2 排查与处理排查编码问题先确认服务端返回的Content-Type是否带了charsetutf-8。然后用curl看原始字节流别用浏览器控制台。curl -N https://api.example.com/v1/chat/completions \ -H Content-Type: application/json \ -H Authorization: Bearer YOUR_API_KEY \ -d {model:gpt-4,messages:[{role:user,content:讲个笑话}],stream:true}如果原始字节流正常但你的程序输出乱码问题就在解码环节。Python里处理流式响应时要确保每次拿到的chunk都能完整解码不能直接把二进制chunk转字符串要按UTF-8的规则做边界判断。6.3 SSE流式拼接的正确姿势处理SSE流我的做法是“按事件读取按行解析累积buffer”。每次收到数据块先拼接到缓冲区再从缓冲区里按换行符切出完整的SSE事件来处理。这样能避免半个字符的问题。import json import requests def parse_sse_stream(resp): buffer for chunk in resp.iter_content(chunk_size1024): if not chunk: continue buffer chunk.decode(utf-8, errorsignore) while \n in buffer: line, buffer buffer.split(\n, 1) line line.strip() if not line.startswith(data:): continue data line[5:].strip() if data [DONE]: return try: obj json.loads(data) delta obj[choices][0][delta].get(content, ) if delta: print(delta, end, flushTrue) except json.JSONDecodeError: # 数据块不完整继续等待 buffer line \n buffer break还有一个实际经验有些服务端在流式返回时会做压缩如gzip如果你设置Accept-Encoding: gzip而没有正确处理压缩流拿到的是压缩字节流自然乱码。最简单的处理方式是把请求头里的Accept-Encoding设置为identity强制服务端返回不压缩的数据。追求性能的话就要在客户端正确解压不能直接把压缩流当文本拼接。7. 一张“错误速查表”与梳理总结7.1 错误速查表把这五类报错的排查要点汇总成一张表遇到问题照着查能省下不少时间。报错首要动作次选动作兜底方案429看响应头Retry-After检查RPM/TPM配额指数退避重试500看响应body和日志查服务商状态页降级到备用模型超时curl分阶段测耗时调整连接/读超时检查网络链路上下文截断检查finish_reason统计token消耗压缩对话历史流式乱码用curl看原始字节流检查编码声明按buffer正确解析7.2 规范化的日志与监控排查报错时最怕的是没有日志。我强烈建议在调用大模型接口时把以下字段完整记录下来时间戳、模型名称、请求ID如果有、状态码、响应耗时、finish_reason、错误信息。这些日志在做复盘时价值极高。请求ID特别关键。服务端返回的request_id是你向服务商反馈问题时的凭证也是排查时关联服务端日志的唯一线索。热词里的codex exceeded retry limit, last status: 429 too many requests, request id就指明了用request_id定位问题的方式。我在所有日志里都会带上request_id没有的话也要记录完整的请求头。监控指标方面至少要统计请求成功率、429占比、500占比、平均响应时间、P95响应时间、超时次数。429占比突然升高说明客户端并发或配额有问题500占比升高说明服务端不稳定P95响应时间升高说明模型推理变慢。这些指标能帮你提前发现问题而不是等用户反馈。7.3 预防比排查更重要排查能力只是底线真正省心的是做好预防。我目前的习惯是客户端做三层兜底第一层是“合理性检查”参数、URL、编码第二层是“自适应重试”按Retry-After或指数退避第三层是“降级方案”备用模型、缓存结果、人工处理。代码层面还有一个容易被忽略的点处理好并发。很多303/超时问题源头就是客户端同一时间发出太多并发请求。哪怕服务商没限流你的机器也可能因为文件描述符、端口耗尽而出现连接问题。给所有HTTP客户端加上并发池限制能省掉一半的坑。热词里提到pg 对单表500万数据 怎么样这个虽然看起来无关但它背后的思路和接口调优是一样的数据量和并发量上来了很多问题才会暴露。大模型接口也一样开发环境调得再顺上线后一天几十万请求时各种报错都会冒出来。提前做好限流、熔断、监控才是长期稳定的关键。我个人在实际操作中的体会是这五种报错其实不是孤立的它们经常连环出现。429重试太多会变成500超时重试太急会触发429上下文截断后重发长文本又可能引发超时。排查时别只盯着眼前这条错误要把整个请求的生命周期串起来看。日志里记录的每一条时间点都是解开连环报错的线索。