你在写一个 AI 编程工具——IDE 插件、CLI 助手、代码审查机器人,功能都想好了,卡在「模型怎么接进来」这一步:该配几个参数、Key 放哪、超时和重试怎么定、换源要多久。这篇把接入环节拆成可勾选的几步,每步给判断标准和排查顺序,不涉及任何具体产品和数字。
你在写一个 AI 编程工具,IDE 插件也好、CLI 助手也好、代码审查机器人也好,功能都想清楚了,结果卡在「模型怎么接进来」这一步。要配哪几个参数、Key 放在哪、超时重试怎么定、换一家服务商要改多少东西,这些问题不解决,功能写得再漂亮也跑不起来。
下面按接入的实际顺序拆成四块:先把可配置的部件分清楚,再决定走哪套协议,然后看请求怎么组装,最后给一份上线前的自查清单和排错顺序。每一块都给出判断标准,也会说清楚什么情况下这些做法并不适用。
先把模型接入拆成几块可配置的部件
最容易踩的坑是把端点、Key、模型名、请求体全拼在一个字符串或者一个常量里,结果换服务商时要翻遍源码。正确做法是四块分开管,每块都有独立的配置项和独立的日志字段。这样出问题时看日志就能判断:是端点写错了、Key 失效了,还是模型名没对上。
- 端点、鉴权、模型名、请求体四块分开配置,换服务商只改配置不动业务代码
- 模型名和端点解耦,同一份业务逻辑对多家服务商,靠一张映射表切换,映射表放配置文件不放源码
- 鉴权信息先定存放位置:本地工具走环境变量,服务端工具走后端代理,别让 Key 进到用户机器或前端包里
- 每块部件留一个可观测的日志字段,排查时能一眼看出是哪一块出的问题
- 配置加载失败要有明确报错,别默默用默认值跑,默认值接错环境最难查
| 部件 | 放哪里 | 出错时的典型表现 |
|---|---|---|
| 端点地址 | 配置文件或环境变量 | 连接超时、域名解析失败 |
| 鉴权信息 | 本地用环境变量、服务端用后端代理 | 鉴权失败或权限不足 |
| 模型名 | 映射表,按场景分组 | 模型不存在或参数不被支持 |
| 请求体字段 | 代码里的组装层,字段可选可关 | 字段校验报错或返回格式异常 |
什么情况下不适用?如果你的工具只服务一家模型、也不会换,那就没必要搭映射表,直接写死反而更省事。映射表的价值在「要换」这件事上,没有换的需求,它就是多余的一层。
走哪套协议、要不要加兼容层
不同服务商的协议风格不一样,请求体字段名、流式事件格式、工具调用的表达方式都可能有差异。动手之前先确认目标模型的原生协议是哪种风格,再决定代码是按原生格式写,还是中间加一层适配。
- 原生格式直连
- 业务代码直接按目标服务的字段组装请求,适合只接一家、短期不打算换的场景
- 薄适配层
- 业务侧定义统一的内部请求结构,再由适配层翻译成各家格式,适合要多家的场景
- 字段丢失告警
- 适配层把不支持的字段显式记下来并告警,避免静默降级导致行为不一致
判断标准很简单:团队要接多家,就加一层薄适配;只有一家且短期不换,直接按原生格式写更省事。加适配层属于典型的过度设计场景是:你只有一个上游,而且半年内没有换的打算。反过来,适配层一定要记录「哪些字段被丢了」,比如工具定义、系统提示的位置,丢了要显式告警,不能默默降级,否则同一个提示词在不同上游表现不一样,你根本不知道问题出在哪。
请求组装:上下文、流式与工具调用
请求组装这一层,编程工具和普通聊天工具有个明显区别:上下文里塞的是代码片段、项目结构和最近改动,体积大且结构复杂。所以上下文截断要按 token 预算来,不能按字符数切;编程场景里把项目结构和最近改动放在靠前位置,模型对靠前内容的利用通常更充分。
- 上下文按 token 预算截断,不能按字符数切,中文和代码的 token 密度差别很大
- 流式与否在接入阶段就定下来,编程工具一般要流式;注意首包延迟和断流重连是两件事,分开处理
- 要用工具调用就先把工具描述写成结构化字段,别指望靠自然语言提示让模型稳定调函数
- 超时分成连接、首包、整体三层分别设,只设一个总超时会让你分不清是网络慢还是模型慢
- 把每次请求的实际上下文长度记进日志,方便事后判断是不是上下文超限导致的截断
工具调用这块尤其要小心:工具描述的字段格式、必填项、参数类型,各家要求不完全一致。接入时先在一两个固定场景上把工具调用跑通,再扩展到更多工具。如果你的工具本身就不需要模型去调外部函数,那这套结构化描述可以先不做,等有需求再说。
上线前的自查清单与排错顺序
接入做完不等于能上线,出问题时最忌讳东试一下西试一下。按固定顺序排查,从前往后查、不跳步,通常几分钟就能定位到是哪一环。下面这份清单可以直接当上线检查表用。
- 端点可达用最小请求确认地址能连通,看到的是连接错误还是业务错误
- 鉴权通过确认 Key 有效且权限够,鉴权失败和权限不足要分开处理,前者是 Key 问题、后者是账号或模型开通问题
- 模型名存在用配置里的模型名发一次请求,报模型不存在就回去查映射表
- 请求体字段合法逐个字段核对必填项和类型,报字段错误时别急着重试
- 流式解析正确看首包能否正常解析、断流后能否重连,事件格式对不上多半是适配层翻译错了
重试策略要按错误类型区分:限流用退避重试,超时可以有限次重试,请求体字段错误重试一万次也没用,只会浪费额度。换源或换模型之后,用一组固定的小用例回归一遍,确认输出格式没变形——这一步很多人会跳过,结果线上才发现返回结构变了。
关于各家服务商的协议细节、错误码含义和当前可用模型,站内资料库有按服务商整理的页面,接入前先去核对一遍,比在网上翻零散帖子靠谱。价格和额度相关的事,同样以站内页面当时的数字为准。
下一步:核对上游资料协议字段和错误码各家不一样,接入前到资料库按服务商核对当时的模型清单与字段要求,能少踩不少坑。→常见问题
接入是不是先选一个大模型再写代码?
建议反过来:先把配置结构和适配层定好,模型名当成一个可替换参数。这样换模型只是改映射表里的一行,不用回头动业务逻辑。如果是一次性小脚本、明确不会换模型,那就别折腾适配层,直接按原生格式写。
工具要同时支持多家模型,最省事的做法是什么?
内部统一一套请求结构,出口处做一层翻译,把各家协议差异集中在一个文件里。代价是多一层维护,好处是新接入一家只改一个地方。如果只是两家且结构差别不大,写两套分支也比抽象过度好读。
接入阶段最容易埋的坑是什么?
把超时、重试和 Key 散落在各处。超时只设一个总时长、重试不分错误类型、Key 直接写进配置模板,这三样在本地跑得通,一上真实用户环境就变成难查的偶发失败。接入时就集中放到一个配置模块,后面省很多事。