医院或医疗项目里要接一个AI能力,多半先卡在「这是调接口还是装包」这个问题上。分不清会出两种错:把该放服务端的鉴权写进客户端,或者装了个塞满依赖的SDK,结果过不了合规审查。这篇不打官腔,先说两者的边界,再给你判断顺序和上手动作。
医院或医疗项目里要接一个 AI 能力,最常卡住的不是选哪家,而是「这到底算调接口还是装个包」。这个问题看着小,后面会牵出安全评审、数据外发、依赖冲突三摊事。
分不清的后果通常不在开发时暴露,而是在上线前一周被安全或信息科打回。这篇不打官腔:先把两者的边界摆正,再给一套能照着走的判断顺序和上手动作。看完至少知道第一版代码该写在哪一层。
先把两个词摆正:一个是门,一个是装好的钥匙串
API 是对方开放的一组约定。你用 HTTP 请求去调,请求和响应走网络,返回什么字段、什么状态码,由对方定义。你拿到的是「怎么敲门的说明书」,门本身在对方那边。
SDK 是把调用这套 API 的代码打包给你,通常顺带把鉴权封装、重试、类型定义都塞进去。装进项目里当依赖用,调用方式变成函数调用,看起来省事。代价是这包代码跑在你的进程里,它做什么你得能说清。
- API
- 一组网络约定,你发请求、对方返回结果,边界清楚但重试超时都要自己写
- SDK
- 别人写好的调用代码,装进项目当依赖,省事但要背版本和依赖关系
- 医疗场景的额外前提
- 病历、影像、检验结果往往不出院内网,谁发起请求决定了数据能不能出去
搞混的代价,通常出现在上线前一周
最常见的误判是把 API 密钥填进移动端或桌面客户端。写的时候图快,评审时直接被退回,因为那等于把钥匙贴在门上。改起来不是换个常量的事,整条调用链要挪到服务端。
SDK 那边的坑更隐蔽。有些包默认开日志、默认上传诊断信息,在普通项目里无伤大雅,在医疗场景可能被认定为数据外发。评审问一句「这包里有没有往外发东西」,答不上来就得返工。
- 接口方案要自己管重试、超时、幂等,代码量更大,但每一行都能解释
- SDK 省掉封装工作,版本升级和依赖冲突得你自己背,尤其在和老框架共存的系统里
- 判断在什么情况下不适用:如果对方根本没提供 SDK,或只对公有云开放、不给私有化选项,这节的取舍讨论直接作废,走接口方案
- 还有一类中间态:对方给了 SDK 但源码不开放,这种情况按「不可审计的依赖」对待,先别急着装
怎么选:按这个顺序问四个问题
- 数据能不能出院内网不能,就优先选可私有化部署的接口,或自建一层网关做转发,别让终端直连公网。这一步定不下来,后面的选择都没意义。
- 谁来维护鉴权密钥集中在服务端管,客户端只拿短期业务令牌。这条基本能排除大部分「SDK 直连客户端」的写法。
- 接的是哪类能力调模型、查字典、调影像阅片,响应体积和超时容忍度差别很大。把每类能力的预期耗时和返回大小写进一张小表,作为选型依据。
- 出问题时谁先看见接口方案要自己建日志和监控;SDK 方案要先确认它的报错能不能落到你的日志里,落不进来就等于没有可观测性。
| 判断项 | 倾向接口 | 倾向 SDK |
|---|---|---|
| 数据能否出院内网 | 不能,服务端或网关转发 | 可以,且对方有合规说明 |
| 鉴权放哪 | 服务端集中管密钥 | 仍需服务端换令牌,客户端不碰密钥 |
| 团队维护成本 | 自己写重试超时,代码可控 | 省初期工作量,长期背版本 |
| 可审计性 | 每行代码自己写,好交代 | 要先确认包内行为和日志策略 |
第一版跑通的顺序,别从选库开始
很多人上手第一件事是搜「哪个 SDK 好用」,然后花两天解决依赖冲突,连一次成功请求都没发出去。顺序反了。先用最笨的方式确认链路通,再谈封装。
- 服务端发一次裸请求用 curl 或最简单的 HTTP 客户端,确认地址、鉴权头、字段名三处都对。返回 200 且字段能解析,再往下走。
- 把密钥挪出代码放环境变量或密钥管理里,提交前扫一遍仓库确认没有明文。这一步不做,后面所有工作都白搭。
- 再决定要不要引入 SDK如果只是几类固定调用,自己封一层薄客户端往往更容易过审,也更好排查。
- 记下基线把这次请求的耗时和返回结构记下来,后面性能异常时拿它对照,比凭感觉判断靠谱。
过评审前,把这几项对着勾一遍
评审不是走形式,问的问题都很具体。提前把下面几项写成文档,比临场解释省力得多。顺带说一句,接口的计价方式和限额规则各家不同,别凭印象,去 站内价格页 核对当时的数字再写进方案。
- 数据流向写清楚:谁发请求、经过哪些节点、有没有第三方参与
- 失败时的表现:超时、限流、字段缺失分别怎么处理,别让异常弹到医生面前
- 版本与依赖:SDK 锁版本,升级前在测试环境跑一遍回归
- 日志里不能有患者标识,脱敏要在写日志那一步做,不是事后清理
- 私有化还是公有云,写进方案第一页,别等到部署时才发现对方不支持
还有一点容易漏:出了故障谁先响应。接口方案的监控得自己搭,SDK 方案的错误码映射得自己写,两者都不会自动变成「有人知道出事了」。
下一步想比较几家中转和官方接入方式的实际表现,可以去站内测速页跑一轮,再回来定接口还是 SDK。→常见问题
医疗软件里能不能直接在前端调API?
一般不建议。前端能拿到的东西用户也能拿到,密钥和患者数据都在风险里。常规做法是前端调自己的后端,由后端持有密钥再去调外部接口,中间那一层还能做脱敏和审计。
既然有SDK,为什么还要关心API本身?
SDK只是包装,出问题时要落到请求层看。地址写错、字段名变了、返回结构不一样,这些都得回到API文档确认。另外换成别的厂商时,直接调接口的方案迁移成本通常更低。
什么情况下反而不该自己封装,直接用SDK?
调用类型多、参数复杂、对方更新频繁的时候,SDK省下的维护成本是实在的。前提是你能锁住版本、能看清它的依赖和网络行为,并且合规那边认可它的部署方式。