很多团队第一次接入大模型 API 时最关心的往往是“能不能跑通”拿到 API Key把 messages 拼好接口返回一段文本Demo 看起来就算成功了。但真到了生产环境情况就完全不一样了。线上会遇到的东西要复杂得多比如 429 限流、接口超时、流式响应突然断掉、JSON 解析失败、上下文超长、token 成本飙升、API Key 泄露甚至模型输出质量波动带来的业务风险。所以大模型 API 的生产化绝不是简单地调一个接口。更准确地说它是一整套围绕稳定性、性能、成本、安全和可观测性搭起来的工程体系。本文不绑定某一家厂商主要从通用的大模型 API 报错处理和性能优化角度整理一些更适合线上系统的实践经验。为什么大模型 API 到生产环境会比 Demo 难很多Demo 阶段通常很简单一个用户、一个请求、一段固定 prompt最多再加一点参数调试。但线上系统不是这样。生产环境里会有高并发、多租户、长上下文、流式输出、批处理任务、模型切换、费用结算、合规审计等一堆现实问题。比较常见的事故有这些高峰期请求突然打满触发大量 429用户端一直转圈模型只返回了一半内容前端流式输出卡住不知道该结束还是继续等结构化输出偶尔不是合法 JSON后面的业务流程直接失败历史对话越拼越长最后超过上下文限制重试逻辑没控制好一次失败被放大成多次计费请求API Key 被写进前端代码或日志里引发安全和成本风险。所以线上系统的目标不是保证“每次调用都成功”。这不现实。更重要的是失败能分类、能重试、能降级、能观测而且局部故障不会拖垮整个系统。大模型 API 常见报错分类哪些能重试哪些别重试处理大模型 API 报错时第一件事就是别把所有错误都扔给同一个 retry 逻辑。不同错误背后的原因完全不同处理方式也不一样。类型常见状态码 / 表现常见原因是否重试处理建议参数错误400 / 422messages 格式不对、模型名写错、参数范围非法否提前做参数校验记录请求摘要认证错误401 / 403API Key 错误、权限不足、Key 被禁用否立即告警检查密钥和权限配置资源不存在404模型不可用、endpoint 写错通常否检查模型名、区域和接口路径上下文超限context length exceededprompt 太长、RAG 内容过多、历史未裁剪否裁剪上下文、做摘要压缩动态计算 max_tokens限流429RPM、TPM、RPS 或并发超限是指数退避、客户端限流、队列削峰服务端错误500 / 502 / 503 / 504供应商服务波动、网关超时、模型负载高是有限重试超过阈值后熔断或切换模型网络错误timeout、connection reset网络出口问题、连接池异常、读取超时是设置 timeout、复用连接、检查出口网络流式中断SSE 断开、输出半截网络抖动、网关超时、客户端断开视情况记录 partial output前端做超时兜底输出格式错误JSON parse error、字段缺失模型输出不稳定、约束不够强可重试一次使用 JSON mode、schema 校验和修复逻辑内容安全拦截内容为空、finish_reason 为 safety输入或输出触发安全策略否返回合规提示优化输入审核成本异常token 激增、账单异常上下文失控、死循环重试、Key 泄露否预算告警、频控、Key 轮换、日志审计大体结论很清楚像 400、401、403、404、422 这类错误通常不要重试而 408、429、500、502、503、504 可以做有限重试。盲目重试不仅解决不了问题还会让延迟和成本一起上升。生产级重试策略指数退避、jitter、幂等和熔断一个真正能在线上用的重试策略至少要回答几个问题哪些错误可以重试最多重试几次每次间隔多久一直失败之后怎么办最基础的分类可以这样写retryable_status{408,429,500,502,503,504}non_retryable_status{400,401,403,404,422}实际生产里更推荐使用“指数退避 随机抖动”。比如第一次等 500ms第二次等 1s第三次等 2s同时再叠加一点随机 jitter。这样可以避免大量请求在同一时间重新打到供应商接口造成二次拥堵。重试次数一般控制在 2 到 3 次具体要看业务 SLA、供应商限流规则和成本预算。这里还有一个经常被忽略的问题幂等性。如果只是普通文本生成失败后再试一次风险通常还算可控。但如果大模型 API 触发了 function calling 或 tool calling比如创建订单、扣减库存、发送消息那就必须给外部动作加幂等键。否则一次模型调用失败可能会变成多次真实业务写入后果就比较麻烦了。另外当某个 provider 或某个模型连续出现大量 5xx、超时、流式中断时不应该继续把流量往上打。更合理的做法是进入熔断状态。熔断后可以短时间切换到备用模型也可以直接返回降级结果。等到半开恢复时只放少量请求进去探测确认稳定后再逐步恢复全部流量。每一次重试都应该记录 attempt、error_type、status_code、latency、request_id、provider、model 和 token 用量。没有日志的重试出了问题基本只能靠猜线上排查会非常被动。限流与并发控制不要等 429 出来了才补救不少团队会把大模型 API 性能优化理解成“把并发调高”。其实这很容易踩坑。并发太高不仅会触发 429还可能让失败率升高最后整体吞吐反而下降。限流时至少要区分几个概念RPM每分钟请求数RPS每秒请求数TPM每分钟 token 数并发数同一时间正在处理的请求数量。只控制请求数远远不够。两个请求的成本可能差很多一个可能只是 200 token 的分类任务另一个可能是 10 万字长文总结。后者更容易触发 TPM 或上下文长度限制。更稳妥的方式是在客户端主动做限流同时控制请求数、并发数、输入 token 和预计输出 token。在线聊天类请求优先保证低延迟可以设置更短的超时并使用流式输出批量总结、批量改写这类任务则更适合进入异步队列由 worker 按配额慢慢消费低优先级任务在高峰期可以延后处理。如果是多租户系统还要做租户级限流避免某个用户或某个客户把全部额度打满。企业应用里高优先级任务和低优先级任务最好分队列不然很容易互相影响。性能优化先看指标TTFT、P95、token/s、缓存命中率优化大模型 API不能只盯着平均响应时间。平均值经常会掩盖问题尤其是线上长尾请求。更值得关注的是 P95、P99 和错误率。下面这些指标建议长期监控指标含义优化方向TTFT首 token 延迟使用流式输出、缩短 prompt、减少排队时间Total Latency总响应时间控制输入和输出 token选择合适模型token/s生成速度观察模型能力、供应商负载和网络状况P95 / P99慢请求体验发现高峰期问题、长尾任务和供应商波动429 Rate限流比例调整客户端限流、队列和配额5xx Rate服务端错误比例重试、熔断、启用备用模型Cache Hit Rate缓存命中率优化缓存 key 和适用场景Cost per Request单次请求成本控制 token、减少重试、做模型分层路由首 token 延迟对聊天类产品尤其关键。即使总耗时没有明显变化流式响应也能让用户更早看到结果体感会好很多。不过流式输出并不代表性能问题就消失了后端仍然要监控 TTFT、完整输出耗时以及 stream_interrupted 这类中断情况。降低延迟的 8 个实用方法第一用流式响应。聊天、写作、问答这类场景用 SSE 或 stream 可以让用户更早看到内容明显降低等待感。第二缩短 prompt。把无效背景、重复规则、过长示例删掉很多时候比单纯提高并发更有效。第三控制 max_tokens。不要所有任务都给一个很大的输出上限。分类、抽取、标签生成这类任务本来就应该限制输出长度。第四把历史对话摘要化。多轮对话不要无限拼接历史。通常可以保留最近几轮再用摘要承载长期上下文。第五RAG 要控制 top_k 和 chunk 长度。检索结果不是越多越好。塞太多上下文不仅会增加 TTFT 和成本还可能提高幻觉风险。第六简单任务交给小模型。比如意图识别、分类、短文本改写等可以优先用低成本、低延迟模型。真正需要复杂推理时再升级到更强的模型。第七复用连接池。服务端调用大模型 API 时要配置 HTTP 连接池并设置合理的 connect timeout、read timeout 和 total timeout避免每次都重新建连。第八缓存高频请求。FAQ、固定知识库问答、分类标签、模板化改写等场景都很适合做缓存。降低成本的 7 个关键动作成本优化的第一步其实不是马上换更便宜的模型而是先把 token 记录清楚。每次调用都应该记录 input_tokens、output_tokens、total_tokens、retry_count 和 cost_estimate。没有 token 日志就很难判断钱到底花在哪里。具体可以从这几件事入手第一限制用户输入长度避免恶意文本或异常长文本直接进入模型。第二对重复请求做缓存减少相同 prompt 的重复调用。第三使用模型分层路由。简单任务走小模型复杂任务再走强模型。第四避免无效重试尤其是 400、401、403、上下文超限这类本来就不该重试的错误。第五管理 prompt 模板版本避免一次模板变更导致 token 用量突然暴涨。第六长文本任务做分块、摘要和合并不要一次性把内容全部塞进上下文。第七设置预算告警、单用户频控和异常用量监控。需要注意的是多 key、多线路、多供应商路由确实能提升可用性但不能把它理解成“可以无限调用”。不同平台都有自己的配额、风控和使用政策具体规则还是要以各平台最新说明为准。如果使用 ClaudeAPI 这类第三方 Claude API 兼容接入服务也要明确它不是 Anthropic 官方服务可以关注它在兼容接入、多线路选择、中文支持、企业充值、开票和基础技术协助等方面的能力具体价格、额度和政策仍以官网最新说明为准。缓存策略缓存什么怎么缓存风险在哪里缓存不是把所有大模型 API 响应都存起来。比较适合缓存的场景包括 FAQ 问答、分类标签、固定 prompt 的文本改写、结构化抽取、固定知识库问答以及批处理任务。但也有很多场景不适合缓存比如强实时问题、强个性化对话、包含敏感隐私的数据以及随机性很高的创作类任务。缓存 key 也不能只用用户输入文本。一个相对完整的 key通常要包含这些信息provider 和 modelprompt_template_version用户输入 hashtemperature、top_p、max_tokens工具版本知识库版本业务租户或权限范围。缓存也会带来风险。比如旧答案可能已经不准确权限隔离没做好可能造成数据泄露模型升级后结果也可能和之前不一致。所以缓存需要 TTL、版本号、权限隔离和失效机制不能只图省钱省时间。输出不稳定怎么办JSON、函数调用和结构化结果处理很多生产流程都依赖结构化输出比如分类、抽取、审核、表单填充和工具调用。这种情况下不能直接相信模型返回的内容。更稳妥的做法是优先使用供应商支持的 JSON mode、response_format 或 function calling明确 schema限制字段名、字段类型和枚举值把 temperature 设低一些提高输出稳定性对返回结果做 schema 校验JSON 解析失败时可以做一次自动修复或有限重试对外部工具调用参数再次校验不要让模型直接决定高风险动作。像“markdown 包着 JSON”“字段缺失”“最后多输出一段解释”这类问题不能只靠 prompt 里写一句“请严格输出 JSON”。prompt 约束当然有用但到了生产环境还需要解析、校验、修复和兜底机制配合。监控与日志上线后必须记录哪些字段大模型 API 的线上问题通常很难靠用户截图定位。真正出了事故还是要靠提前设计好的结构化日志。建议记录这些字段字段用途request_id串联一次完整调用user_id / tenant_id定位用户和租户级异常provider / model / endpoint区分供应商和模型问题prompt_template_version追踪 prompt 变更带来的影响input_tokens / output_tokens / total_tokens分析成本和上下文问题latency_ttft / latency_total分析首 token 和总耗时status_code / error_code做错误分类retry_count判断重试是否放大了问题finish_reason判断截断、安全拦截等情况cache_hit评估缓存效果stream_interrupted监控流式中断json_parse_success监控结构化输出稳定性cost_estimate粗略估算调用成本告警可以先从这些指标做起5xx 错误率、429 错误率、P95 / P99 延迟、TTFT 异常升高、token 用量异常、单用户调用异常、JSON 解析失败率、缓存命中率下降、备用模型切换次数。另外日志里不要记录完整的敏感 prompt。必要时做脱敏、截断或 hash尤其是涉及用户隐私、商业数据、密钥等内容时更要谨慎。安全与成本避坑API Key 绝对不能写在前端也不要提交到 Git 仓库。生产环境里应该使用环境变量、密钥管理服务或配置中心并且尽量设置最小权限。对外提供能力时最好在后端做代理层不要让用户直接拿到真实 Key。还需要做几类保护设置单用户、单租户、单 IP 的调用频率限制限制输入长度和文件大小对异常调用做风控定期轮换 API Key设置预算上限和费用告警对日志里的敏感信息做脱敏确认供应商的数据保留和合规策略。很多安全问题并不是模型能力不够而是工程边界没守住。一旦 Key 泄露或者频控缺失成本风险会被迅速放大。上线前 Checklist大模型 API 生产环境检查清单API Key 没有暴露在前端API Key 没有提交到 Git已设置 connect timeout、read timeout 和 total timeout已区分可重试错误和不可重试错误已配置指数退避和 jitter已限制最大重试次数已配置客户端限流和并发控制在线请求和离线批处理已分队列已记录 input_tokens、output_tokens 和 total_tokens已配置 P95、P99 和 TTFT 监控已配置 429、5xx、timeout 告警已设置预算告警和异常用量监控JSON 输出已有 schema 校验流式响应有中断检测和前端兜底已准备备用模型或降级策略模型和 prompt 变更有灰度机制日志已脱敏不记录完整敏感输入。总结生产环境优化优先级大模型 API 生产化可以按这个顺序推进第一先做好 timeout、错误分类和有限重试避免系统被单次调用卡死。第二再补上限流、队列和熔断防止高峰期出现雪崩。第三建立性能指标体系重点关注 TTFT、P95、P99、错误率和 token 用量。第四继续优化 prompt、上下文裁剪、缓存和模型分层路由。第五再完善成本治理、多供应商容灾、安全审计和灰度发布。真正可靠的大模型 API 系统不是永远不报错而是每一种错误都有清楚的处理路径也不是一味追求更高并发而是在延迟、吞吐、稳定性和成本之间做出可观测、可调整的工程取舍。