刚拿到 Key、准备把大模型接进项目时,最容易懵的一点是:文档里一会儿给 curl 示例,一会儿让你 pip install 一个包,到底该用哪个?其实这俩是两层东西,选错了不是做不成,而是后续维护、排错都会绕远路。这篇只讲这一个角度:先把概念掰开,再给一条从零到第一次跑通的流程,每步说清用什么、怎么验证。
刚拿到 Key、准备把大模型接进项目时,最容易懵的一点是:文档里一会儿给 curl 示例,一会儿让你 pip install 一个包,到底该用哪个?其实这俩是两层东西,选错了不是做不成,而是后续维护、排错都会绕远路。
这篇只讲一个角度:先把概念掰开,再给一条从零到第一次跑通的流程,每步说清用什么、怎么验证。看完你应该能判断手上这个需求该走 SDK 还是直接拼请求,以及调不通时按什么顺序查。
先把两层关系摆清楚:API 是约定,SDK 是帮你守约定的那套代码
API 本质上是服务端对外的一套规则:地址、方法、鉴权头、请求体和返回结构。你就算只用 curl 或浏览器发请求,也算调了 API。SDK 是把这套规则包成函数和类的代码库,帮你拼参数、管超时、做重试、解析返回,它内部仍然在调同一个 API。所以它们不是二选一的关系。
- API
- 服务端定的通信规则,谁发请求都得按它来,跟用什么语言无关。
- SDK
- 别人替你写好的调用代码,省掉拼参数和解析返回的活儿,底层还是发同一套请求。
- 兼容层
- 按原厂接口的样子转发的中间服务,字段大体一样,细节可能对不上,得自己验证。
判断标准就一条:你要控制的东西,SDK 有没有暴露出来。需要自定义请求头、流式分片处理、精细看原始响应,裸 API 更省心;只想要个整理好的结果,SDK 更快。反过来也有不适用的情况——SDK 版本落后于服务端字段,或者你接的是兼容层而不是原厂,SDK 的默认行为可能和文档对不上,这时退回裸 API 更稳。
什么场景用 SDK、什么场景直接拼请求:一张对照表
| 你的情况 | 更合适的选择 | 原因 |
|---|---|---|
| 语言有官方维护的包,只做普通同步问答 | SDK | 序列化、重试、超时都替你做了,上手快 |
| 要看原始响应排查问题 | 直接拼 API | SDK 常把错误信息吃成一句话,看不到细节 |
| 要接多家厂商做成统一开关 | 直接拼 API | 各家 SDK 风格不同,自己封一层反而好维护 |
| 服务端是冷门语言,没有官方包 | 直接拼 API | 别硬套别的语言的包,拼请求最省事 |
| 团队新人多,怕写错参数 | SDK | 类型提示和默认值能挡掉一批低级错误 |
还有个好用的混合做法:主体用 SDK,同时保留一个最小 curl 或几行原生请求做对照。同一把 Key、同一个地址,两边结果不一致,基本就能断定是 SDK 层的问题,而不是账号或网络。
- 不管走哪条路,地址、Key、模型名这三样必须来自同一个地方,混着抄是最常见的翻车点
- 先用原生请求确认服务通,再接 SDK,顺序反过来会让你分不清错在哪一层
- SDK 装完先跑官方最小示例,跑通再改,别一上来就往自己项目里嵌
- 要比较不同来源的差别,先到 /sites 看各家的接入说明,别凭记忆写地址
新手照着做:从拿到 Key 到第一次跑通的五步
- 锁地址和 Key把服务地址和密钥写进环境变量,不要写死在代码里。验证方法:换个终端重新读一次配置,确认代码里没有硬编码。
- 先用最原始的方式发一次请求用 curl 或几行原生请求打一次,确认能通。这一步排除了 SDK 这个变量,失败就只看地址、鉴权头、请求体三处。
- 再装 SDK 重跑一次同样参数走 SDK,对比两边返回。字段缺了、报错文案不一样,基本都是 SDK 版本或默认参数的问题。
- 加一层最薄的封装一个发请求的函数、一个读配置的入口就够了,别一上来就上框架。封装好之后改地址或换 Key 只动一处。
- 留一份能复现的最小用例把跑通那次请求缩成最小脚本存进仓库。以后调不通先跑它,能分清是环境坏了还是代码改了。
调不通时的排查顺序,别乱试
先说原则:按「能从返回里看出来的信息量」排序,越是能直接读出原因的越先查。下面这个顺序是给新手兜底的,照着走基本不会绕圈。
- 先看状态码再猜原因:鉴权类失败和参数类失败处理方式完全不同,别一上来就怀疑网络
- 再看是不是绕了 SDK:用原生请求发一遍同样的参数,能通就说明问题在你的调用封装里
- 第三看地址拼接:兼容层常见坑是地址多写或少写一段路径,返回的往往不是报错而是另一个页面
- 最后才怀疑服务端:同一时间换一把 Key 或换一个模型名做对照,能快速分清是账号侧还是代码侧的问题
- 每一步做完记一句结论,排查过程中最怕的是改了一圈不知道哪一步真正起了作用
如果排查后怀疑是某个来源本身不稳,可以到 /tools/speed-test 做一次连通性检测,把「代码问题」和「线路问题」分开。各家当前的价格和可用模型,到 /price-watch 核对当时的数字,别照着旧截图配参数。
SDK 不是另一种接入方式,它就是 API 的一层包装;排错时把包装拆掉,剩下的才是问题本身。下一步如果你还没确定用哪家、或者想比较不同来源的接入稳定性,去站内来源目录对着看一遍说明和检测结果,再决定主用哪条路,比拿到 Key 就埋头写代码稳。→
常见问题
只学 API 不学 SDK 行不行?
行,而且早期更推荐。API 是底层约定,懂了它,换语言、换厂商都一样能干活。SDK 只是省事的工具,用之前你仍然要知道它在背后发了什么。等工作里频繁切模型、需要统一封装时,再花时间啃 SDK 更划算。
同一个功能,SDK 和裸 API 的返回会不一样吗?
可能会。SDK 通常会把返回对象再做一层包装,错误也变成异常而不是状态码。所以对照时别直接比对象结构,要比内容字段。差异明显时先查 SDK 版本和你装的包是不是官方维护的那个,再看它的默认超时和重试是不是改动过行为。
用 SDK 是不是就不用管鉴权和限流了?
不是。鉴权仍然要你提供正确的 Key,SDK 只是帮你放到请求头里。限流、并发、超时这些也都在服务端判定,SDK 顶多帮你自动退避。业务上仍要自己设计失败重试和排队,否则高峰一到照样报错。