接入大模型前要准备什么

很多人写代码只花了半天，卡在准备环节却耗掉一周：Key 不知道放哪、余额够不够心里没数、报错了不知道先怪谁、Demo 跑通了却说不清效果好不好。这篇不讲具体接口怎么写，只给一份动手前的准备清单——按顺序把该开的、该量的、该定的都落下来，后面调起来才不慌。

很多人写代码只花了半天，卡在准备环节却耗掉一周：Key 不知道放哪、余额够不够心里没数、报错了不知道先怪谁、Demo 跑通了却说不清效果好不好。这篇不讲具体接口怎么写，只给一份动手前的准备清单——把该开的、该量的、该定的都落下来，后面调起来才不慌。

先说清一件事：这份清单不是每一条都必须做。只是自己试试水，准备可以砍到最小集；一旦要给团队、客户看，或者要接进已经有用户在用的系统，那就按完整版走。下面按动手顺序排，从验收线一直排到上线前最后一次对表。

先定「跑通」的验收线，再谈准备

最容易被跳过的一步，是先想清楚这次接入到底要交付什么。如果你只是想看看返回长什么样，那准备的东西很少；如果是要接进已有系统稳定跑下去，账号、额度、日志、降级路径一个都绕不开。两者的准备量差一个数量级，先分清能省掉大量无用功。

把验收标准写成能观测的三条，写在项目说明或者笔记里，别只放在脑子里：能出一次正确返回、错误能被捕获、持续调用不掉线。这三条看起来朴素，但每一条后面都对应一组准备动作，缺一条就会在后面某个环节返工。

账号、Key 与额度：三样都要提前落位

账号层面最先卡人的，往往不是技术，而是主体信息没补齐。有些平台没走完这一步，连计费开关都打不开，你后面写的代码再对也调不通。所以动手第一件事是登进控制台，把该填的主体资料、验证步骤走完，确认账号状态是可用的。

Key 的管理原则很简单：只留一份主 Key，其余按用途拆子 Key。开发用一个、测试用一个、线上用一个，出问题只吊销一支，不会连累其他环境。子 Key 的命名建议带上环境前缀，三个月后回头看还认得出哪支是干什么的。

• 账号主体信息先补齐，确认控制台里计费和调用开关都能打开
• 主 Key 只留一份，按用途拆子 Key，命名带环境前缀
• 余额和额度上限一起设：留够试错量，同时给单日或单项目设上限
• 把 Key 的创建时间和用途记在一个只有团队能看的地方
• 账号与 Key 的详细配置口径，到 first-recharge-key-setup 与 first-call-prep-checklist 核对

额度上限这件事值得单独强调。不设上限，脚本一跑飞就是持续消耗；设了上限，最多是当天被打断，你还有机会复盘。两条路的结果差别很大，而动动手只需要几分钟。

网络通路与接口地址要能自己验

不要一上来就把调用写进业务代码。先用 curl 或平台自带的调试面板打通一次，确认地址、鉴权、请求体三样都对。理由很实际：网络错误混在业务逻辑里是最难查的一类问题，你分不清是自己参数写错还是链路不通。

接下来要分清你走的是哪条路：官方直连、中转站、还是本地模型。三条路的地址字段和鉴权写法不一样，切换之前先确认字段含义，别把 A 家的地址格式套到 B 家上。地址与鉴权字段的读法可以对照 base-url-field-guide，不确定该选哪条路，先看 four-access-routes。

1. 用最小请求打通一次只带必要字段，观察返回结构和状态码，确认链路本身没问题
2. 记下实际生效的地址与字段名不要凭记忆写，把调试面板里实际用的那一份抄进笔记
3. 换一条路再验一次如果计划有备用通道，同步验一遍，确认切换时只需要改地址和 Key
4. 确认错误形态故意用错 Key 或发错字段，看返回的错误信息能不能一眼看懂

花多少钱、用多少量：先估一遍再动手

成本这一步不用算得很精确，算到量级就够。方法是：单次请求大概多少 token，乘以预计调用次数，得到一个数量级。这个数字的作用不是报销，而是让你知道大概在什么范围，心里有底。

估完之后，拿结果和官方价目核对一遍。具体数字到 /official-api 与 /price-watch 看当时的口径，别用几个月前的印象做判断，价格是会变的。核对的目的也不是为了精确，而是确认你的估算没有差出一个数量级。

给自己定一条止损线，是这一步最有价值的产出。日用量到了某个量级就停下来复盘，而不是等账单出来才发现。成本口径和用量估算的方法，站内 ai-project-cost-estimation 讲得更细，这里只列执行动作。

开发环境与密钥安全：别把 Key 写进代码

Key 走环境变量或本地配置文件，仓库里放的是示例文件而不是真 Key。提交前扫一遍，用工具或者肉眼都行，关键是建立这个习惯。Key 进了版本历史，就算后面删掉也还在历史里，处理起来很麻烦。

本地留一份可复现的最小调用脚本。它的作用不是功能，而是排障：出问题时先跑它，如果它也失败，说明问题在链路或 Key；如果它成功，说明问题在你的业务代码。这一下能省掉大量来回猜的时间。

• Key 放环境变量或本地配置，仓库只放示例文件
• 提交前扫一遍，确认没有真 Key 进版本历史
• 本地保留一份最小调用脚本，作为排障基线
• 团队里约定谁能看 Key、谁能改额度，人数一多这条必须写清楚
• 密钥与数据边界的判断标准，到 /safety 与 /ai-dict/category/safety 核对

团队协作时最容易被忽略的是权限约定。谁能看 Key、谁能改额度、谁能在出事后吊销，这三件事不写清楚，人一多就会出问题。写一条规则花不了几分钟，但能避免后面扯皮。

效果怎么判、日志怎么留：跑通之后马上要做

跑通不代表效果可控。准备一组固定测试输入，十几条就够，覆盖你关心的场景。每次换模型或改参数都跑一遍，这样你才有一致的参照，而不是凭感觉说「好像变好了」。固定测试集的价值在于可重复，不在于多。

日志要记三类东西：请求耗时、返回长度、错误类型。有这三样，首字慢还是整体慢、是偶发还是必现，一看数据就知道了。延迟基线可以先用 /tools/speed-test 量一次，后面判断快慢才有参照物。

模型对比不能只看一次结果。同一条输入在不同时段、不同负载下的表现会有差异，多人多时段交叉验证的做法见 model-comparison-testing-methods。如果你的场景对稳定性要求高，这一步别省。

固定测试集

一组覆盖核心场景的输入，每次改动都跑一遍，用于横向对比

延迟基线

正常情况下的耗时水平，用来判断某次变慢是异常还是波动

错误类型分布

把错误分类统计，先解决占比最高的那一类

数据能发什么：先划边界再动手

在写第一行调用代码之前，把要发出去的内容分成三类：可以发、脱敏后可以发、绝不能发。这份分类贴在项目说明里，团队每个人都看得到。等到出事再讨论什么该发什么不该发，成本高得多。

涉及个人信息、客户数据、内部文档的，先确认所选通道的留存与使用条款，再决定走哪条路。不同通道的条款不一样，不能默认都一样。拿不准的字段一律脱敏或换成假数据，等业务稳定了再谈放开。

• 把内容分成可发、脱敏后可发、绝不发三类，写进项目说明
• 涉敏数据先确认通道的留存与使用条款，再决定走哪条路
• 拿不准的字段先脱敏或换假数据，稳定后再评估放开
• 把这份分类做成新人 onboarding 的一部分，别只存在某个人脑子里
• 概念口径见 data-boundary-explained，这里只做动作清单

上线前对着清单过一遍

上线前把所有准备动作对一遍，四条打勾再谈上线：Key 与额度已配好、错误分支已覆盖、固定测试集已跑过、日志能定位问题。这四条任何一条不满足，上线之后都会以更麻烦的形式回来找你。

再准备一份「出事怎么办」。降级到备用模型、切备用地址、临时关掉功能，三个动作至少有一个能立刻执行。不要写一份到时候没人找得到、也没演练过的方案，那不叫预案。

1. 对表四条打勾项Key 与额度、错误分支、固定测试集、日志，逐条确认
2. 确认至少一个降级动作可用实际执行一次，不是只看文档写没写
3. 上线后第一周每天看用量和错误率发现异常趋势比上线当天反复改参数有用得多
4. 把这次准备过程中踩的坑记下来下次接新模型直接复用，省一轮返工