调用大模型 API 接口这件事乍看只是把一串 API Key 塞进请求头、往接口地址 POST 一段 JSON 就完事了我最初也是这么想的直到第一次把 demo 交给业务方跑才在半小时内被四个问题按在地上摩擦Key 写死在前端被打包进去了、超时没设导致页面转圈转到用户以为死机、429 一来整个功能全挂、月底账单比预算高了六倍。所以才有了这篇东西。它讲的不是“怎么点一下按钮生成密钥”而是面向境内开发团队把调用大模型 API 接口这件事从拿API Key到上线跑稳的全过程拆开密钥怎么申请与管理、请求体里每个参数到底在干什么、流式输出怎么接、网关要做哪几件事、限流重试退避怎么算、账单怎么控、报错怎么排。刚接触的新手可以照着步骤跑通第一条请求已经在维护线上服务的老手也可以直接跳到工程化和排查两节抄配置。需要提前说明的边界本文只讨论在遵守平台服务条款与所在地相关规定的前提下使用官方开放平台提供的合法服务网络访问层面的操作不在讨论范围内也不建议任何绕过服务条款的做法——技术上能跑通和商业上能长期跑是两件完全不同的事。1. 先把调接口这件事拆开看1.1 一条请求从键盘到模型中间经过了几道手很多人对这条链路的想象是一条直线我的代码 → 模型 → 结果。真实链路更像一条流水线中间有七八个工位任何一个工位堵住你看到的现象都是没有返回。理解这条流水线是后面所有排查工作的地基。完整的路径大致是你的客户端发起请求 → 到达你的后端服务 → 经过你自己搭的统一接入层如果有→ 出网到平台边缘节点 → 平台做身份鉴权 → 校验请求体格式与上下文长度 → 扣减配额 → 排队进推理集群 → 模型逐 token 生成 → 结果按你要求的形态一次性返回或流式推送回传 → 平台侧计量落库 → 你的服务收到并做后处理 → 客户端渲染。这条链路上只有模型生成这一段是慢的其他环节都是毫秒级。这解释了一个非常实用的现象如果你的请求 200ms 就报错了那问题一定在鉴权、参数或配额上跟模型没关系如果请求挂了 60 秒才超时那才是推理侧或网络侧的问题。我在排查时习惯先看响应耗时一秒以内挂掉的直接去翻错误码三十秒以上挂掉的第一时间去看超时配置和上下文长度。另一个容易忽略的点是计量。平台计费发生在服务端完成生成之后也就是说你主动断开连接并不能省下已经生成的 token。有同事做过实验流式输出跑了 300 字然后用户关掉页面账单照样按 300 字计。所以真正的省钱动作发生在发请求之前——控制max_tokens、精简提示词、做缓存而不是在中途掐断。1.2 API Key 到底是什么为什么它比密码更危险大部分人把 API Key 当成高级一点的密码这是个很危险的类比。密码通常配合账号、二次验证、异地登录提醒被盗了还有一层缓冲而 API Key 在绝大多数平台上是Bearer 凭证——谁拿到这串字符谁就完整地拥有了你账号在该 Key 权限范围内的全部能力不需要任何额外验证平台也没法区分这是你本人在调还是这是别人拿着你的 Key 在调。更麻烦的是它的计费属性。密码泄露的损失是数据Key 泄露的损失是持续流出的钱。我见过最典型的事故模式是前端项目里为了快速联调把 Key 写进了环境变量文件构建时被打进 bundle上线后被人从静态资源里扒出来然后就是一夜之间跑掉一个月的预算。这类事情的技术根因其实非常朴素——Key 出现在了一个不该出现的位置。所以我在任何项目里都会先立三条规矩不分项目大小Key 只允许出现在服务端进程的内存或服务端环境变量里绝不进前端代码、绝不进 Git 仓库、绝不进日志。每个环境本地开发、测试、预发、生产用不同的 Key出事时能精准吊销不至于一刀切停掉全公司。每个 Key 绑定明确的用途和负责人命名里写清项目与场景比如proj-xxx-chat-prod-202503。注意哪怕只是给自己电脑上的脚本用也不要把 Key 硬编码在.py文件里再同步到网盘或笔记软件。我习惯的做法是本地.env文件加.gitignore以及一个开机时手动export的 shell 变量多花十秒省掉后面一堆麻烦。1.3 三条接入路径的取舍别一上来就选最复杂的实际可选的接入形态基本就三种我把它们的差异整理成一张表你可以直接按自己的场景对号入座路径适合谁优点代价官方开放平台直连个人开发者、早期验证、单一模型需求参数最全、新能力第一时间可用、文档最权威需要自己处理密钥安全、重试、限流云厂商托管的模型服务已有云上基础设施的团队与既有账号体系、计费、审计打通开票和合规流程顺模型版本更新可能滞后参数有裁剪自建统一接入网关多业务线、多模型并存的中大型团队密钥不出内网、可做配额分摊、可做多模型路由与降级前期投入大需要人维护我自己的经验路径是验证阶段一定走官方直连用最原始的方式把参数摸熟一旦有两个以上业务方要用立刻上网关哪怕只是一个 200 行的服务。中间那层网关的价值不在于转发而在于它是唯一知道所有 Key 的地方业务方拿到的是一张内部签发的令牌永远看不到上游密钥。这个隔离做不做直接决定了你未来某天要不要半夜起来换 Key 并通知五个团队。如果模型选型还没定还有一个折中做法在网关里做一层协议适配把各家略有差异的请求体归一成一套内部接口业务代码只面向内部接口编程。这样将来换模型供应商时改动量集中在网关的适配层业务侧一行不动。我在一个项目里就是因为早期偷懒没做这层后来换模型时改了十几个调用点每个的入参结构都不一样那两天改得相当难受。2. 密钥申请与账号体系从注册到拿到第一把 Key2.1 注册之前先把三件事想清楚很多人注册完才发现卡在某个环节来回折腾。这三件事提前准备好能省掉大量返工。第一是用途说明。主流平台在创建应用时通常要求填写用途描述写得含糊比如测试有可能触发额外审核写得具体为客服工单系统提供自动摘要与分类能力通常过得更顺。这不是形式主义平台需要判断你的调用场景是否属于允许范围。第二是支付方式。免费额度能撑起验证但撑不起上线。建议在验证阶段就跑通一次最小额度的充值流程把发票信息、付款主体、预算告警一起配好。我吃过一次亏功能上线当天才发现财务流程需要提前走审批结果免费额度耗尽后服务直接不可用业务方在群里问了一下午。第三是配额与限流的初始值。新账号的默认并发和日调用上限通常比较保守如果你的场景是批量处理比如一次性给几千条历史工单打标签需要提前申请提额提额一般需要说明预估调用量和业务背景审批需要时间。这件事一定要在上线前一周做不要等到跑批那天。2.2 控制台里那四个必须弄懂的概念进去之后别急着点创建密钥先把这四个东西的分层关系搞清楚能避免后面 80% 的混乱。组织/账号计费和结算的主体一个组织下可以有多个项目。项目/应用逻辑隔离单位配额、用量统计、密钥一般挂在项目下面。密钥API Key真正用于鉴权的凭证一个项目下可以有多把用于区分不同环境或不同调用方。配额Quota / Rate Limit分两层一层是 RPM/TPM每分钟请求数/每分钟 token 数一层是账单额度上限。前者决定你会不会被 429后者决定你会不会被停服。这几层的意义在于故障隔离。举个例子市场部的活动页要接一个文案生成功能如果它和你核心业务共用一把 Key活动一爆量核心业务就被 429 打死。正确做法是给它单独开一个项目、单独一把 Key、单独设一个额度上限它怎么疯都撞不到你。2.3 创建第一把 Key 的实操步骤与命名规范流程本身各家平台大同小异我按通用步骤写你对照自己控制台的按钮找即可登录开发者控制台进入API 密钥或应用管理页面。新建应用/项目填写名称与用途描述选择要开通的模型能力。在项目下点击创建密钥部分平台会让你选择权限范围只读、仅推理、含管理权限生产环境一定只给推理权限。密钥只在创建时完整展示一次之后只能看到前后几位。这时候立刻复制到一个安全的地方别指望等会儿再复制页面一刷新就没了只能重新创建。顺手把用量告警和账单上限设置好阈值建议设在预算的 60% 和 90% 两档。命名这件事值得单独说。我现在的命名格式是{项目}-{场景}-{环境}-{年月}例如kb-assistant-prod-202503。好处是三个月后你翻控制台一眼就能看出哪把 Key 是可以删的历史遗留哪把是正在跑的。曾经有个项目我图省事建了五把名字叫test、test2、new的 Key半年后完全不敢删因为不知道哪把还有调用方——最后只能靠翻网关日志一个个比对花了大半天。2.4 密钥的生命周期轮换、吊销、分环境密钥不是建完就一劳永逸的东西。我建议给每把生产 Key 设一个最长 90 天的轮换周期流程是新建一把新 Key → 在网关里配置双 Key 并存 → 观察一周确认新 Key 调用正常 → 把旧 Key 下线 → 一周后吊销。这个双活过渡的设计可以做到零停机轮换成本几乎为零。吊销则是应急手段必须提前演练。你要能在五分钟内回答三个问题这把 Key 在哪几个服务里被引用吊销后哪些功能会挂备用 Key 在哪、怎么切如果答不上来说明你的密钥管理还没到位。我的做法是在网关的配置里把 Key 做成列表支持热加载出问题时改一行配置、发个信号三秒生效不用重启服务。注意吊销是立即生效且不可逆的。我见过有人在排查 401 时手滑点了吊销结果把还在跑批的任务打断。所以在做任何吊销操作前先确认调用方的真实身份宁可多查五分钟。3. 第一次跑通调用从 curl 到 SDK3.1 用 curl 先验证鉴权别一上来就写代码我最推荐的第一步永远是 curl。原因很简单它把代码层面的问题从链路里剔除掉了剩下的只有网络、鉴权、参数三件事。如果 curl 通了而代码不通问题一定在你的代码或环境变量里排查范围瞬间缩小一半。curl -X POST https://api.example-llm.com/v1/chat/completions \ -H Authorization: Bearer $LLM_API_KEY \ -H Content-Type: application/json \ -d { model: chat-standard, messages: [ {role: system, content: 你是一名严谨的技术文档编辑。}, {role: user, content: 把下面这段日志归类ERROR db connection timeout after 30s} ], temperature: 0.2, max_tokens: 200 }几个实操细节。第一不要把 Key 直接写在命令行里shell 历史会把它记下来用环境变量的方式引用上面示例用的是$LLM_API_KEY。第二加-i可以看到响应头里面通常有x-request-id这个 ID 在提交工单时是必填项也是你唯一能对上平台侧日志的线索建议每次报错都把它记下来。第三如果只是想测连通性可以先请求一个列出可用模型的接口成本为零成功即说明鉴权和网络都没问题。我习惯在 curl 里加一个-w参数看耗时curl -o /dev/null -s -w status%{http_code} total%{time_total}s\n \ -X POST https://api.example-llm.com/v1/chat/completions \ -H Authorization: Bearer $LLM_API_KEY \ -H Content-Type: application/json \ -d {model:chat-standard,messages:[{role:user,content:hi}],max_tokens:10}这样一眼就能看出是快失败还是慢失败前面讲过的判断法在这里就派上用场了。3.2 请求体里每个参数到底在干什么这一段是很多人跳过、然后反复踩坑的地方。我按重要性排序讲。messages是核心。它是一个数组每个元素有role和content。system用来定角色和约束只输出 JSON不要解释user是用户输入assistant是历史回复。多轮对话的本质就是把历史消息全部带上重发一遍——模型本身是无状态的它不记得上一轮说了什么。这也解释了为什么多轮对话越聊越贵上下文在累积。max_tokens是最该设的参数。它限制输出的最大长度直接影响最坏情况下的花费和响应时间。不设或者设得过大一旦模型开始发散你能收到几千字的废话和一张昂贵的账单。我的经验值分类/抽取类任务设 100~300摘要类设 500~800长文生成设 2000 以上并配合超时。计算方式很简单预估花费 输入 token 数 × 输入单价 输出 token 数 × 输出单价。假设某平台输入单价 0.000002 元/token、输出单价 0.000006 元/token示例数值实际以你平台的价目表为准一次请求输入 1200 token、输出 800 token单次成本就是 1200×0.000002 800×0.000006 0.0024 0.0048 0.0072 元。如果你的日调用量是 1 万次日成本就是 72 元月成本约 2160 元。这个算式一定要在需求评审阶段就摆到桌面上因为它往往会改变产品设计——比如把每次都生成改成缓存命中优先。temperature和top_p建议只调一个。这两个都是控制随机性的同时调容易互相干扰。分类、抽取、代码生成这类要确定性的任务用temperature0~0.3创意文案用0.7~1.0。我遇到过线上偶发同一输入返回不同分类结果的问题最后发现是 temperature 设了 0.9模型在边界样本上左右摇摆。stream决定返回形态。设为 true 时服务端会边生成边推用户体验好很多但客户端处理逻辑要复杂一些下一节细讲。response_format或类似的 JSON 约束参数在做结构化抽取时非常好用能显著降低模型返回了一段解释而不是 JSON的翻车率。但即使开启也要在代码里做容错解析——我至今没有见过哪个系统能完全免疫这个问题。3.3 流式输出的接入要点坑比你想的多流式返回用的是 SSEServer-Sent Events风格的文本流服务端持续推送形如data: {...}的块最后以一个data: [DONE]之类的结束标记收尾。看起来简单实际有几个必踩的坑第一个是粘包/半包。网络传输不会保证每次读到的都是一个完整的 SSE 事件你可能读到半个 JSON。正确做法是维护一个缓冲区按换行符切分只有当一行以data:开头且能被完整解析时才处理剩下的部分留在缓冲区等下一批数据。第二个是结束标记不等于连接关闭。有些实现收到结束标记后连接还在挂着如果你用同步阻塞的读法会一直等下去。必须显式判断结束标记并主动关闭。第三个是错误也可能以流的形式出现。请求已经返回 200 开始推流了中途模型侧出错错误信息会作为流里的一个事件推过来。如果你的代码只处理正常增量这个错误会被静默吞掉用户看到的是输出到一半停住了。我给的一个最小可用处理骨架Python通用伪结构具体字段名按平台文档调整buffer for chunk in response.iter_lines(decode_unicodeTrue): if not chunk: continue buffer chunk \n while \n in buffer: line, buffer buffer.split(\n, 1) line line.strip() if not line.startswith(data:): continue payload line[5:].strip() if payload in ([DONE], DONE): return try: obj json.loads(payload) except json.JSONDecodeError: continue # 不完整的块等下一批 delta obj.get(choices, [{}])[0].get(delta, {}).get(content) if delta: yield delta第四个是前端体验。流式输出必须配一个停止生成按钮用户随时能中断。中断时要真的把后端连接关掉否则你的服务会一直挂着读完整个流白白占用连接和并发额度。3.4 多语言 SDK 与环境变量配置直接用官方或社区 SDK 能省掉不少样板代码但有两个纪律必须守。纪律一SDK 客户端的初始化只做一次。我见过在每次请求里 new 一个客户端的写法结果连接池完全失效高并发下大量时间花在建连上。正确做法是在应用启动时创建一个全局客户端复用连接。纪律二所有配置从环境变量读不从代码读。至少四项LLM_API_KEY、LLM_BASE_URL、LLM_MODEL、LLM_TIMEOUT。把 base_url 和 model 也做成可配的好处是切换模型或切换接入点比如从直连切到网关时不用改代码改配置重启就行。这个习惯在后来我迁移供应商时救过一次急——业务代码零改动。import os, httpx client httpx.Client( base_urlos.environ[LLM_BASE_URL], headers{Authorization: fBearer {os.environ[LLM_API_KEY]}}, timeouthttpx.Timeout(connect5.0, read60.0, write10.0, pool5.0), )注意超时是分段的connect短一点5 秒足够建连建不上说明网络有问题read长一点给模型生成留时间。千万不要用一个笼统的timeout30那会导致长文本生成永远被掐断。分四段配置是我现在所有项目的默认写法。4. 工程化落地把 demo 变成能上线的服务4.1 统一接入层到底要做哪五件事网关这个词听起来很重其实一个两三百行的服务就能覆盖 90% 的需求。它要做的就五件事我按优先级排第一藏住密钥。业务方调用网关时用的是内部令牌网关在转发时替换成真实的上游 Key。这是最核心的价值。第二统一错误语义。上游返回 429、401、500、超时网关各自映射成内部统一错误码业务方只需要处理一套。没有这一层每个业务方都要自己写一遍错误处理而且一定写得五花八门。第三统一埋点。每次调用记录调用方、模型、输入输出 token 数、耗时、是否成功、request-id。这份日志是后面做成本分摊和容量规划的唯一依据。我强烈建议从一开始就把调用方字段作为必填否则后面算账时会发现一堆无主流量。第四做重试和限流。见后两节。第五做模型路由与降级。主模型超时或不可用时可以按配置降级到备用模型或者直接返回一个降级提示。这在多模型并存的架构里非常有用同时也让 A/B 测试变得容易——按比例分流即可。一个容易被低估的细节网关不要把整个响应缓冲完再返回。如果业务方要的是流式输出网关必须透传流中间不能攒。我见过为了方便记录 token 数而把流读完再转发的实现结果首字延迟从 300ms 变成了 8 秒体验直接崩了。记录 token 数应该从响应尾部的用量字段读不需要缓存正文。4.2 超时、重试与退避参数要算出来而不是拍出来超时配置有个基本原则外层超时必须大于内层超时之和。假设单次请求超时设 20 秒最多重试 2 次那业务方调用网关的超时至少要设 70 秒20×3 缓冲否则会出现网关还在重试业务方已经超时放弃的错位白白消耗配额。重试策略的关键是只重试该重试的。我用的规则是错误类型是否重试说明连接超时 / 读超时重试网络抖动或模型排队重试大概率能成429 限流重试但必须退避立即重试只会加剧拥塞500 / 502 / 503重试服务端临时故障400 参数错误不重试重试一万次也是同样的错误401 / 403 鉴权失败不重试需要人工介入内容被安全策略拦截不重试换个问法才有意义退避要带随机抖动避免大量请求在同一时刻齐刷刷重试形成惊群。一个实用的参数组合是基础延迟 500ms指数因子 2最大重试 3 次每次加 0~30% 的随机抖动。这样三次重试的等待时间大致是 0.5s、1s、2s加上抖动总等待在 3.5~4.5 秒之间配合 20 秒的单次超时整体控制在 70 秒以内可接受。关于重试还有个必须注意的点非幂等场景要小心。如果一次请求已经生成了一部分内容比如流式输出到一半断了重试会导致用户看到重复内容。我的处理方式是流式请求一旦开始推流就不重试只做重新生成的用户级操作非流式请求可以放心重试。4.3 限流与并发算清楚你需要多少并发需求很容易被低估。计算方式其实很简单所需并发数 ≈ 峰值 QPS × 平均响应耗时秒举例如果你的场景是峰值每分钟 300 次调用即 5 QPS平均响应耗时 4 秒那所需并发大约是 5 × 4 20。但如果你的流量是有尖峰的比如整点推送、上班打卡前后峰值 QPS 可能是均值的 5 倍那就要按 25 QPS 算所需并发 100。这个数字直接决定你要向平台申请多少配额。反过来说你也要给自己加保护。我通常会在网关做令牌桶限流按调用方分配额度超出直接返回稍后重试而不是放进去排队。排队的危害在于队列一长所有请求的耗时都变成排队时间 推理时间用户端看到的是全面变慢而不是部分失败。快速失败比慢慢全挂要好得多。还有个细节并发的计量单位各家不同有的按同时在飞的请求数有的按 RPM/TPM。TPM 这个指标在长文本场景下比 RPM 更容易触发——你每分钟只发了 20 个请求但每个输入 3 万 tokenTPM 早就爆了。所以做容量规划时RPM 和 TPM 两个都要算。4.4 成本控制三个立刻能生效的动作动作一精准控制max_tokens。这是最直接的杠杆。把摘要任务的 max_tokens 从 2000 降到 600如果输出真的不需要那么长成本直接砍掉一多半响应也更快。动作二做提示词缓存。如果你的场景里 system prompt 很长且固定比如几百字的角色设定加格式要求把它放在消息数组的最前面并保持完全一致很多平台对相同前缀有缓存机制能显著降低输入侧成本。这个优化在客服、分类这类高频场景里效果非常明显。动作三加一层结果缓存。对于同样输入返回同样结果可接受的场景比如常见问题的标准答复、固定错误码的解释用输入内容的哈希做键缓存 24 小时命中率往往能到 20%~40%。我在一个工单摘要功能上做过统计一周内重复或高度相似的工单占了三分之一加了缓存后成本降了约 28%。同时设两道保险账单告警预算的 60%、90% 各一档发到群里而不是只发邮件邮件没人看和硬上限超过就停而不是继续跑。硬上限一定要设宁可服务不可用也不能出现失控账单——前者是事故后者是事故加财务问题。4.5 日志与可观测性出问题时你只有这些线索要记录的字段我列一个最小集合时间戳、调用方标识、模型名、输入 token、输出 token、总耗时、首字耗时流式、HTTP 状态码、平台返回的 request-id、错误码、错误摘要。其中首字耗时这个指标很有价值很多问题它比总耗时更早暴露。用户感觉慢往往是因为首字慢而不是生成慢。首字耗时突然从 400ms 涨到 3 秒通常意味着平台侧排队严重或者你的请求体突然变大比如上下文没裁剪。注意不要记录请求和响应的完整正文尤其不要记到日志平台里长期留存。这些内容可能包含用户隐私或业务敏感信息。我的做法是只记长度、哈希和必要的元数据需要排查具体内容时靠 request-id 去平台的调用记录里查并且设置保留期限。监控面板我一般做四块调用量趋势、成功率、耗时分布P50/P95/P99、成本日趋势。这四张图放在一屏上绝大多数异常都能在十秒内定位到方向。5. 常见报错与排查实录5.1 鉴权类401 和 403 的区别401 表示我不知道你是谁通常是这几种情况Key 拼错了前后多了空格、复制时漏了字符、环境变量没加载本地跑得好部署后挂十有八九是这个、Key 已被吊销、请求头格式不对少写了Bearer前缀或者写成小写。403 表示我知道你是谁但你不能干这个常见于Key 的权限范围不含目标接口、模型未开通、所在地区或账号状态受限、请求的组织 ID 与 Key 不匹配。遇到 403 先去看控制台里这个项目开通了哪些模型别急着怀疑代码。排查顺序我固定为先用 curl 复现 → 确认 Key 是否有效换个最简单的接口试 → 检查请求头拼写 → 检查环境变量是否正确注入在容器里env | grep LLM看一眼→ 最后才怀疑平台侧。5.2 参数与上下文长度类错误400里最常见的两条是参数格式错误和上下文长度超限。前者多半是 JSON 结构有问题比如messages传成了字符串、temperature传了超出范围的值。后者的表述通常是maximum context length exceeded。上下文超限有个隐蔽的来源多轮对话累积。用户在客服窗口聊了三十轮你还把全部历史都带上必然爆。解决方式是做滑动窗口只保留最近 N 轮加上一条固定的 system 消息必要时把更早的内容压成一段摘要。我一般用最近 6 轮原文 更早内容的 200 字摘要这个组合实测在大多数客服场景够用token 量能压到原来的四分之一。还有一个坑是中文与 token 的比例。中文一个汉字通常对应 1~2 个 token不同分词器差异较大做长度预估时按字符数 × 1.5估比较保险别按字符数 token 数算会低估一半。英文相对接近 4 字符 1 token。写长度校验的时候把这两个系数写进代码注释里省得后人再踩。5.3 限流与超时429 的正确处理姿势429 是高频问题。首先要区分两种短时突发和配额真的不够。前者退避重试就能解决后者再怎么重试也没用必须提额或者削峰。判断方法很简单看 429 的频率。偶尔出现、退避后成功是突发持续出现、重试也失败是配额不足。我在网关里加了个计数器429 在一分钟内超过 10 次就发告警因为这时候基本可以确定不是抖动。削峰的手段有几个把非实时任务批量打标、历史数据清洗挪到低峰时段跑用队列串行化对用户侧做请求合并多个相似请求合成一次给功能加节流用户连续点击只发一次。这三个做得好的话峰值能压掉一半以上。超时的情况更复杂要分建连超时和读超时。建连超时基本是网络层问题检查出口、DNS、目标地址是否可达读超时说明连上了但模型迟迟不返回此时要看请求的输入长度输入过长会导致首字延迟显著上升和平台的负载状况。我遇到过一次大面积读超时最后定位到是某个业务把 3 万字的文档整篇丢进去做摘要输入侧处理就耗掉了大部分时间预算。后来加了超过 8000 token 先分段再摘要的逻辑问题消失。5.4 软故障接口没报错但结果不能用这类问题最难排查因为没有错误码。典型表现返回空内容、返回了一段解释而不是要求的 JSON、返回了重复内容、返回的语言不对。返回空内容通常是max_tokens设得太小或者触发了内容策略被静默截断。先把 max_tokens 调大试试能出内容就说明是这个原因。不返回 JSON的应对方式是双管齐下一方面在提示词里给明确的格式示例给一个完整的 JSON 样例比写十句请输出 JSON有效得多另一方面在代码里做提取第一个{到最后一个}之间的内容的容错解析再加一层 JSON 校验失败则重试一次。我给所有结构化抽取接口都加了这个兜底线上失败率从 3% 降到 0.2%。重复内容往往是 temperature 太低加上提示词里存在重复模式导致的适当提高温度或者调整提示词能缓解。5.5 排查速查表现象最可能的原因第一步动作100ms 内返回 401Key 未注入或拼写错误在容器内打印环境变量确认100ms 内返回 403模型未开通 / 权限不足查控制台该项目的模型权限400 提示上下文超限多轮历史累积或输入过长打印 messages 的总字符数做窗口裁剪429 偶发瞬时突发开退避重试观察是否恢复429 持续配额不足提额 队列削峰30s 读超时输入过长或平台排队缩短输入检查首字耗时曲线返回空字符串max_tokens 过小调大后重试对比输出不是 JSON提示词约束不足加格式示例 代码兜底解析流式中途停住未处理流内错误事件加错误事件监听与用户提示成本异常上涨某业务调用量突增或缓存失效按调用方维度看趋势定位来源心得每次排查完我都会把结论补进这张表里。半年下来它会变成团队最有价值的文档之一因为新问题的第一次出现往往是老问题的变种。6. 合规与安全的几条硬线6.1 数据合规发出去之前先想三秒把数据发到外部服务这件事必须有一套明确的规则不能靠每个人自觉。我参与的团队里通用的三条是不发送可识别个人身份的信息姓名、证件号、联系方式、住址确需处理时先在本地做脱敏替换不发送未公开的商业信息合同条款、财务数据、未发布的产品规划不发送内部系统凭证数据库地址、内部域名、密钥。这三条写在代码评审清单里比写在规范文档里有效得多。技术上可以做一层出站过滤器用正则匹配常见敏感模式手机号、证件号格式、邮箱、内网 IP命中则打码或拦截并记录。这东西写起来不到一百行但要配合误报处理——比如订单号恰好符合手机号格式被打码会导致功能异常。我的做法是先全量记录命中情况但只告警不拦截跑一周看误报率再决定开启拦截。另外用户侧的告知也要做到位。在功能入口明确说明本功能由智能模型提供支持请勿输入敏感信息这句话看着像免责声明实际能显著降低误输入率。6.2 密钥泄露的应急处置万一发现密钥可能泄露比如误提交到了公开仓库、出现在前端产物里、被同事贴到了聊天群按这个顺序处理别犹豫立刻吊销不要先观察一下。这时候每一分钟都在产生可能的费用。创建新 Key更新网关配置确认服务恢复。拉取泄露时间段的用量记录看有没有异常调用量和异常调用来源。复盘它是怎么出去的是代码里硬编码、构建产物带出、还是日志打印堵住这个具体路径而不是笼统地说以后注意。关于第 4 步我想多说一句。我见过的泄露案例里排名第一的原因是本地调试时为了方便临时写死后来忘了删第二名是把 Key 打印在错误日志里方便排查。第二个尤其隐蔽因为日志系统往往有多份副本、保留期很长、访问权限很宽。所以我在代码评审时会专门搜print、log、console.log附近有没有密钥变量这个习惯救过至少两次。最后分享几个我一直在用的小技巧。第一在项目根目录放一个.env.example把所有需要的变量名列出来但值留空新人克隆下来就知道要配什么不用问人。第二给网关加一个/health接口返回当前配置了哪几把 Key、分别指向哪个模型但不返回 Key 本身排查时一眼就能确认配置有没有生效。第三把本文第 5 节那张速查表打印出来贴在显示器边上前两个月你会频繁用到它之后就长在脑子里了。第四也是我最想强调的一点先跑通一次最朴素的 curl再谈架构。我见过太多团队一上手就搭网关、上队列、做多模型路由结果连一次成功的请求都还没发出去最后卡在某个参数名拼错上折腾两天。链路是一段一段打通的别跳步。