医疗项目里接 AI,最容易出的岔子不是模型选错,是把该写在接口里的东西塞进 SDK,或者反过来。前者一换供应商就要重编,后者每次改一个字段都得发版。这篇按「谁管契约、谁管习惯」这条线掰开,配上几张对照表和第一次接入要走的顺序,帮你在动手之前把两层摆对位置。
接 AI 进医疗系统,头一周最容易踩的坑不是模型效果差,而是把两层的活儿装反了。该写在接口层的东西塞进 SDK,换个供应商就得重编译一遍;该封在 SDK 里的细节又散在每个调用处,改一个字段全组发版。这事儿麻烦在它不会当场报错,等到要换供应商或者过院内评审才露出来。
这篇按「谁管契约、谁管习惯」这条线拆。契约指请求长什么样、返回哪些字段、错误码怎么定义;习惯指你怎么少写样板代码、怎么省心处理重试和流式读。先分清这两件事归谁管,再谈用哪个。
先把「谁管契约、谁管手感」分清楚
接口这一层的价值在于稳定:今天用 Python 调,明年换成 Java 写,请求体和返回结构还是那一套。跨团队、跨语言、跨年份还能对得上,这是接口该守住的底线。SDK 管的是另一回事——把你反复写的那几行封装成一个函数,顺带处理鉴权刷新、超时重试、流式分块读取,让你本组少写点样板代码。
判断口诀很朴素:要跨团队、跨语言、跨年份还能用,就落在接口上;只是让本组少敲几行,才轮到 SDK。不过这套分法有前提。如果团队只有一种语言、项目生命周期就几个月,那分那么细意义不大,挑个顺手的包能用就行,别为了架构正确给自己加活。
医疗软件里那几个具体岔口
影像调阅、检验报告回写这类对接,对方给的多半是接口文档加鉴权方式,SDK 往往没人持续维护。你以为拿到的是一份现成的客户端库,翻到最后发现只有半页说明和一个过期的示例,这种情况不在少数。指望它省事,最后是自己在填坑。
- 院内系统每改一次要过评审排期,「不发版就能调整」比「写得爽」重要得多,这时接口优先
- SDK 生成的依赖锁死在某几个运行时版本上,医院老服务器跑不动,硬上就是给自己挖坑
- 反过来,流式返回、断点重试、分块校验这些细节自己写容易漏,一层薄封装省下来的时间是实打实的
- 报告回写接口的字段校验规则会随院内规范变,这类变动落在配置里比落在代码里好改
实际用下来,误判最多的是把 SDK 当成「省事」的代名词。它省的是调用处的字数,不是理解成本;封装层内部做了几次重试、缓存了什么、超时怎么算,这些你照样得搞清楚,不然出问题时连从哪查都不知道。
一张对照表,按这几个格子勾
别急着选边,先按下面这几个维度给自己项目打勾。哪边占得多,就往那边靠,但同一件事别两边都做——重复封装最容易埋下不一致的坑,接口改了封装层没跟上,问题只在某个科室的环境里复现。
| 维度 | 接口更适合 | SDK 更适合 |
|---|---|---|
| 变更频率 | 多方协调、改一次要评审 | 只改本组调用处,点头就动 |
| 可替换性 | 换供应商改配置和映射 | 换供应商往往要重写调用处 |
| 排错成本 | 看请求和返回就能定位 | 还得先判断是封装层还是远端惹的 |
| 合规审计 | 调用留痕清楚,好复述 | 内部重试和缓存要额外确认 |
| 团队语言 | 多语言并存、长期维护 | 单一技术栈、迭代快 |
这张表不是让你二选一,而是帮你确认哪一层该放什么。表里没列「性能」和「安全」两栏,因为这两件事两层都得管,不属于取舍项。
第一周按这个顺序走,别倒过来
- 先用最笨的方式打通一次照文档手动发一次请求,把返回结构、字段含义、错误码截图存下来。这份记录是后面所有封装的基准,别跳过去直接装包,装错了包排查半天才发现文档里早写了。
- 再决定要不要包一层只有当同一段请求要写三遍以上,才值得抽成封装。写两遍就抽,往往抽早了,字段一变又要拆。
- 封装时把可调项留出来超时、重试次数、日志开关都做成初始化参数,填在创建客户端那一格,别散落在每个调用处。写死在函数里,后面调一次得改源码。
- 补一条最小回归用例接口或封装任一改动后跑一遍,尤其是报告回写和影像调阅这两条链路,避免只在某个院内环境下才炸。
什么情况下这套分工不适用
这套分法不是万能药。单体内部的小工具,调用方和提供方是同一个人,分那么细纯属自找麻烦,怎么顺手怎么来。还有一种情况是供应商只提供 SDK 不提供文档化接口,那没得选,但要把版本升级当成一次正式发布来排期,别在周五下午顺手升。
第三种是已经有一层统一网关收口的情况。契约在网关那层已经稳住了,客户端里用什么封装都行,这时候再纠结接口还是 SDK 意义不大,重点该放在网关的鉴权和日志上。至于各家模型的调用方式和价格差异,到 /sites 和 /price-watch 看当时的数字,别凭印象记。
下一步看完还拿不准自己项目该往哪边靠?先把当前接入方案的调用链画出来,再到站内指南中心对照排查顺序过一遍,比闷头装包省事。→常见问题
医疗项目里只给 SDK 不给接口文档,能接吗?
能接,但要把它当成一个会变的外部依赖来管。先把 SDK 版本锁住,升级当成一次正式发布来排期;在它外面再包一层薄接口,让自己的业务代码只认你这层,这样将来供应商换 SDK 大版本时,改动面能压到最小。
接口和 SDK 同时用,会不会重复?
常见也确实合理,关键看各自管什么。接口管契约和数据形状,SDK 管重试、流式读取这类手感。只要不在两边都做参数校验和缓存,就不算重复。怕的是同一份逻辑在两个地方各写一遍,出问题时不知道是哪边在起作用。
怎么判断现在的封装该不该拆掉?
看它有没有挡住你变更。如果每次调个新字段都要改封装、发版本、走一遍评审,那这层就该瘦身或者拆掉,把可变的部分挪回配置。反过来,如果它一直很稳、只是让调用处少写几行,那就留着,别为了架构好看去动它。