上线前:超时、重试与工具调用

接入跑通之后、正式上量之前,这一页把几件容易在生产上咬人的事集中说一遍。 细节都在各自的页面里,这里不复述,只说该怎么定。

工具调用(function calling)

tools / tool_choice 这些字段原样透传给上游,我们不改写、不做能力探测。

所以:支不支持、支持到什么程度,取决于你选的那个模型。 同一段代码换一个模型可能就不工作了 —— 有的模型完全不认这些字段(它会忽略), 有的支持但格式细节有差异。以那个模型自己的文档为准,并且换模型之后重测一遍。

模型不认识的字段被忽略时,你收到的是一个正常的回复,只是没有 tool_calls —— 不会报错。所以工具调用这条链路要有"没拿到 tool_calls 时怎么办"的分支。

超时怎么定

分两种:

• 非流式:整段请求要等模型写完。输出越长等得越久,所以超时要按 你允许的最长输出来定,而不是按"一般多快"。
• 流式:该盯的是首字节时间,不是总时长。长时间没有新块通常是上游在排队。

另外网关自己有一道硬时限,整段处理超过它会返回 504。此时零产出,不计费。

⚠️ 重试:先解决重复扣费

网关不做跨请求去重(与 OpenAI 官方对该端点一致)—— 超时后重发同一个逻辑调用, 会被当成一次全新请求并真实扣第二笔钱,而第一次可能已经在上游跑完了。

所以顺序是:

1. 先把 SDK 的自动重试关掉或调低(官方 openai SDK 默认是开的);
2. 需要重试时在你自己这一侧判重(按业务 id 记这一笔发过没有);
3. 收到 rate_limit_exceeded 时按响应里的 Retry-After 退避,别用固定间隔 —— 固定间隔在高峰期会让你和自己抢配额;
4. 每次调用都把 request_id 记进你的日志。出现重复扣费时,它是唯一能对上的线索。

并发

限流是按你的租户与密钥算的,撞上时返回 rate_limit_exceeded, message 里会写明是哪个维度超了(某个模型、你的套餐、还是租户级)。 先看这句话再决定怎么改 —— 是给那个模型降速,还是整体降并发,处置完全不同。

上量前建议按阶梯放:先跑一小时的真实流量,看明细里的耗时分布与失败率,再往上加。

上线前对一遍

• 密钥存在密钥管理里,不在代码、不在前端包、不在 CI 日志;
• 生产用的那把密钥配了 IP 白名单与预算上限(白名单被挡时返回的是 401 invalid_api_key,和密钥无效同码 —— 排查 401 先查来源 IP);
• SDK 自动重试已按上面第 1 条处理;
• request_id 进了日志;
• 有"模型暂不可用"时的降级路径(换模型或排队重试);
• 余额够用,并且知道没有自动充值、归零即停服(见「充值与退款」)。