sdk和api的接入区别

很多人接了模型之后才发现问题不在能不能调通，而在后面半年怎么维护：SDK 一行代码跑通，但想改超时、加 header、抓原始响应时发现处处被包住；裸 API 什么都自己写，灵活是灵活，可每加一个模型就要重抄一遍重试和鉴权。这篇不说选哪个好，只说在什么阶段、什么团队规模下该走哪条路，以及两条路各自怎么把坑提前堵上。

很多人接了模型之后才发现，真正麻烦的不是能不能调通，而是后面半年怎么维护。SDK 一行代码跑通，等到想改超时、加个自定义 header、抓一份原始响应时，发现处处被包在里面；裸 API 什么都自己写，灵活是灵活，可每加一个模型、每换一家供应商，重试和鉴权就得重抄一遍。这篇不替你选哪个好，只说在什么阶段、什么团队规模下该走哪条路，以及两条路各自怎么把坑提前堵上。

先把概念放一边。SDK 和裸 API 的差别，本质上是「谁来决定那些你没写进代码的默认行为」。SDK 替你决定，你省事但失去了知情权；裸 API 由你决定，你自由但也得为每一个细节负责。想清楚这一点，后面所有判断都顺了。价格、额度这类会变动的数字，各家不一样，去站内价格库逐项对比当时的报价，别凭印象。

先看清 SDK 到底替你包了什么

别把 SDK 当成「调用模型的唯一方式」，它只是官方给你写的一层客户端。想知道它到底帮你做了多少事，最直接的办法是把它的配置项摊开看一遍：哪些能改，哪些写死了。能改的是它留的口子，写死的就是它替你做的决定，而这些决定往往在你出问题时才浮出水面。

鉴权与 header 拼装

帮你把 key、版本头、内容类型拼进请求，你不用管字段名，但想加自定义头就得看它开没开这个口。

请求序列化

把你的参数对象转成服务端认识的格式，字段名对不上时它可能直接吞掉，不报错。

重试与退避

失败自动重发，省了你写循环，但重试几次、隔多久、哪些错误才重试，默认值通常藏得很深。

流式分片解析

把流式返回的碎片拼成完整内容，省事，但拼装逻辑出错时你很难定位是哪一块丢了。

判断封装度的土办法：把 SDK 里所有能配置的项列一遍，凡是改不了的，就是它替你做了决定。常见的默认超时、默认重试次数、默认代理设置，这三项最容易被忽略，也最容易在换网络环境时出问题。

哪些情况下 SDK 明显更省事

SDK 的优势不只在少写代码，还在于它把「协议细节」这件事外包出去了。只要你的场景不复杂，用 SDK 往往比自建一层更稳，因为人家比你更熟自己的服务端。

• 项目还没定型、要快速验证能不能跑通：SDK 能省掉一轮调协议的时间，适合先出结果再谈优化。
• 只用一家、协议单一：默认值基本够用，没必要为了灵活度自己重写一遍请求层。
• 团队里没人愿意长期维护请求层代码：用 SDK 把这块责任外包，比写一半半成品更靠谱。
• 上线节奏紧、先要能跑：SDK 出问题是别人的文档，自建出问题是你自己的锅，早期这点区别很值钱。

反过来说，如果以上几条你都不占，那 SDK 省下的时间可能不够你后面填坑。这不是 SDK 不好，是它适合的场景和你当前的需求错位了。

哪些情况下裸 API 反而更稳

裸 API 的吸引力不在于「更底层」，而在于它是条通用契约。HTTP 请求长什么样，任何语言、任何团队都能对齐；SDK 只在你用的那门语言里有，换个人接手、换个服务端实现，抽象层就开始漏水。

一个常见误区是「裸 API 就是更专业」。不是，它只是更透明。透明带来的维护成本，得有人扛。小团队两三个人接三家模型，统一走裸 API 加薄封装，通常比堆三个 SDK 好管；但如果只接一家，这套自建的性价比就很低。

封装度换来的隐性成本

SDK 把复杂度收起来，代价是你失去了对那部分复杂度的可见性。平时没事，出问题时就难受了。下面这些成本不会出现在接入当天的对比表里，但会在第几个月冒出来。

• 报错栈指向 SDK 内部，排查要从它的源码或文档绕一圈，裸 API 至少错在哪一层是清楚的。
• 抽象会掩盖真实请求体，对接非标准字段或中转站改写过的兼容层时，容易前后对不上。
• 锁死一家 SDK 后，迁移成本不在替换代码，而在重新对齐那些你一直没关心的默认行为。
• SDK 版本跟着服务端字段走，升级一次可能静默改变默认超时或重试次数，这类变化不进你的代码 diff。

SDK 让你少写代码，但把「知道发生了什么」这件事也一起收走了。

判断要不要接受这个代价，问自己一句：如果半年后服务端改了个字段，你希望是从 SDK 的更新说明里知道，还是从你自己的监控告警里知道？前者快但被动，后者慢但主动。

更常见的做法：自己写一层薄适配

真实项目里，纯 SDK 和纯裸 API 都不是多数答案。更稳的做法是：自己写一层很薄的适配，把请求层抽象成一个只管发 HTTP 的函数，SDK 和裸 API 都从这层后面进出。这样切换供应商只改适配层内部，业务代码不动。

1. 定一个固定签名形如 send(request)，参数里固定包含超时、重试次数、是否流式、自定义 header 四项，少一个以后都得改签名。
2. 把厂商差异关在里面适配层内部按厂商分支处理鉴权和字段名，外部调用方永远只看到统一入参。
3. 统一埋点在这层里统一打日志、记耗时、记请求 ID，换厂商时监控不跟着重写。
4. 做降级开关同一个函数支持主备两个上游，主挂了一行配置切备，不用改业务代码。

这层的价值在于：它把「封装度」和「灵活度」从二选一变成了可以分档调。早期可以这层里直接调 SDK，后面要精细控制再换成裸 HTTP，调用方无感。

两条路各自的典型故障长什么样

知道两条路各自最容易在哪翻车，比背一堆优缺点有用。先说结论：SDK 侧的故障往往和「你控制不了的东西」有关，裸 API 侧的故障往往和「你漏写的东西」有关。

排查顺序建议固定成一条：先看原始请求和原始响应，再看封装层，最后才看业务代码。顺序反了，会一直在抽象层里打转。抓原始请求这件事，SDK 不一定让你方便做，这也是很多人后期转向裸 API 的直接原因。

按项目阶段做的选择清单

不用纠结哪个更先进，按你现在的阶段对号入座就行。下面是四条按阶段分的判断标准，每条都写了什么情况下不适用。

• 无论走哪条，上线前都跑一遍真实失败场景：超时、限流、返回格式异常。
• 把超时、重试次数、是否流式、自定义 header 这四项写进自己的配置文件，别依赖默认值。
• 文档里记一句「当初为什么选它」，半年后接手的人会谢你。
• 定期去站内价格库和可信度检测页核对上游报价与状态，别等账单出来才发现变了。

最后提醒一句：路线不是一次定终身的。验证期用 SDK、上生产换薄适配，是很常见的演进路径。关键是让切换的成本可控，而不是一开始就赌对。