从 curl 到生产:一份能直接用的接入检查清单
「接入一个 API 网关」听起来是个半小时的任务,实际上踩坑点有二十多个。与其靠运气,不如把检查项列成清单,挨个过一遍。
第一步永远是最小请求
最短 prompt、关闭流式、不带工具、不带图片。先把链路跑通,再逐项加东西——一次加多项,排障时很难定位。
最小请求的价值在于排除干扰:先用最短的 prompt、关闭流式、不带任何工具,把链路跑通。
一次加多项,排障时会很难定位到底是哪一项出的问题。
凭据从环境变量来
.env + .gitignore 是底线;团队内共享用密钥管理工具,不要放共享文档。本地备份放仓库外,目录 700、文件 600。
一个起码的 .env + .gitignore 组合是底线;如果要同步给团队,用密钥管理工具,而不是共享文档。
哪怕只有一个后端,也建议把 Base URL 抽成环境变量或配置中心的一项。
排障顺序:先模型列表,再状态码
「调不通」的绝大多数情况最后都能归结为「Key 能访问的模型和你想调的不是一回事」。所以第一步永远是 GET /v1/models。
所以排障的第一步永远是把 GET /v1/models 的返回拿出来对着看。
别忘了工具链路的验证
跑通文本之后,一定要单独跑一轮工具调用。工具相关的错误往往不会在文本请求上暴露出来。
实际请求里,工具结果和普通文本往往是混在一起的——模型调用完工具,拿到结果,然后继续说一段话。
转换层要能处理「连续多个工具结果 → 再接一段普通文本」这种序列,而不是假设一轮只有一个工具结果。
实操:先查模型列表,确认你的 Key 到底能访问哪些模型。
把这一步做成启动自检脚本,能省掉未来大量扯皮。
curl "https://aiminis.info/v1/models" \
-H "Authorization: Bearer sk-gw-你的密钥"
# 返回里每项都带上所属平台、支持的能力和是否在售,
# 写代码前先对着这份列表确认模型 ID,别抄文档里的旧名字。
几个容易踩的坑
- 把 API Key 硬编码在代码里然后提交到仓库。
- 每次失败都重试,包括参数错误、额度不足这类永远不会成功的错误。
- 没有对已经产生上游用量的请求做重放保护,账单翻倍。
- 模型 ID 从旧文档里抄,实际 Key 没有该模型权限。
小结
先跑通最小请求,再逐项加功能——这是接入任何网关都适用的节奏。
如果你也碰到上面这些问题,可以看看 https://aiminis.info/ —— 一个把协议适配、渠道调度、用量与额度都收敛在一起的 AI API 网关,OpenAI 与 Anthropic 两套协议都能直接接。
- 点赞
- 收藏
- 关注作者
评论(0)