1. 从“还得装SDK吗”这个问题说起第一次看到“都 AI 时代了还得装 SDK 吗”这个标题我的反应是这问题问得挺刁钻但确实戳中了很多开发者的真实困惑。过去十几年我们做即时通讯、做推送、做音视频几乎绕不开一个动作——集成厂商提供的客户端 SDK。下载、导入、初始化、处理回调、适配各种机型一套流程走下来顺利的话半天不顺利的话一周都在填坑。所以当 AI 能力开始大规模进入应用尤其是 Agent 这种需要实时对话、上下文管理、工具调用的场景出现后大家自然会想能不能别再让我装 SDK 了这个问题的核心其实不是“SDK 好不好”而是接入方式在 AI 时代是否应该发生变化。融云 AICP 这个系列的第一篇标题就抛出了这个疑问说明它要讨论的正是 AI 能力接入的形态问题。我把它理解为一个面向开发者的架构选择话题当你要给自己的产品加上 AI 对话、智能客服、Agent 助手这类能力时是继续走传统 SDK 集成的老路还是转向更轻量的服务化接入先说结论免得大家看得着急SDK 不会消失但它的角色在变。在 AI 场景下尤其是 Agent 场景纯客户端 SDK 的局限性越来越明显而“服务端编排 轻量客户端”的组合正在成为主流。融云 AICP 这个系列想聊的大概率就是这件事。这篇文章我会从 SDK 的历史包袱讲起拆解 AI Agent 对接入方式提出的新要求再结合常见的工程实践给出几种可落地的接入方案对比。不管你是刚接触 SDK 集成的新手还是已经集成过十几款 SDK 的老手都能从中找到对自己有用的部分。2. SDK 的前世今生它到底解决了什么问题2.1 传统 SDK 的价值与历史必然性要回答“还得装 SDK 吗”得先搞清楚 SDK 当初为什么存在。在移动互联网早期网络环境复杂、设备性能参差不齐、协议栈不统一如果让每个业务团队自己去实现一套即时通讯协议那简直是灾难。SDK 的出现本质上是把复杂的底层通信、编解码、连接管理、重连策略封装成一个黑盒让业务开发者只需要调用几个高层 API 就能完成消息收发。我拿即时通讯 SDK 举例。一个成熟的 IM SDK 内部通常包含这些模块长连接管理心跳、断线重连、多路复用、消息编解码Protobuf 或自定义二进制协议、本地存储消息漫游、会话列表、推送通道适配各厂商推送通道的差异抹平、以及各种边界情况处理弱网、切换网络、后台保活。这些东西如果让业务团队自己写没有半年根本下不来而且稳定性很难保证。所以 SDK 的价值是实打实的它把通用能力沉淀下来让业务聚焦在自己的差异化逻辑上。但 SDK 也有代价。最直接的就是包体积增大一个功能完整的 IM SDK 动辄几 MB 到十几 MB。其次是版本升级困难用户不更新 App你就没法升级 SDK老版本 SDK 的 bug 只能靠服务端兼容来兜底。再者是平台适配成本Android、iOS、Web、小程序、桌面端每个平台都要维护一套 SDK厂商的维护成本最终会转嫁到接入方身上。这些问题在传统场景下尚可接受但到了 AI 时代矛盾就被放大了。2.2 AI 场景对 SDK 提出的新挑战AI 能力接入和传统 IM 接入有一个本质区别AI 的逻辑重心在服务端而且变化极快。传统 IM 的协议相对稳定一套 SDK 可以用好几年。但 AI 不一样今天用这个模型明天换那个模型今天 prompt 这么写明天要加工具调用今天上下文窗口是 8K明天要支持 128K。如果这些逻辑都塞在客户端 SDK 里那每次调整都要发版这在移动端几乎是不可接受的。更关键的是 Agent 场景。Agent 不是简单的“发消息-收消息”它涉及多轮对话管理、工具调用编排、记忆存储、任务规划。这些逻辑放在客户端做一来算力不够二来安全风险大API Key 暴露在客户端三来无法复用。所以 Agent 的编排层天然应该在服务端。那客户端还需要 SDK 吗需要但需要的不是“大而全的通信 SDK”而是“轻量的会话通道 事件回调”。我实测过一个典型的 AI 客服场景用户在小程序里提问服务端 Agent 调用知识库检索、再调用大模型生成回答、最后通过消息通道推回给用户。整个链路里客户端只负责“发出去”和“收回来”中间的所有智能逻辑都在服务端。这种情况下如果还强行集成一个几十 MB 的 IM SDK就有点杀鸡用牛刀了。用 WebSocket 或者 HTTP 流式接口配合一个轻量的消息封装反而更灵活。2.3 融云 AICP 的切入点分析从标题“解构融云 AICP”来看这个系列应该是要系统性地讲清楚 AICP 这套 AI 通信平台的设计思路。第一篇拿“还得装 SDK 吗”开刀说明它想先解决开发者的心理门槛问题。我的判断是AICP 大概率提供了服务端 API 优先、客户端轻量化的接入模式同时保留 SDK 作为可选方案覆盖那些需要深度集成、离线能力、或者已有 IM 体系的场景。这种“两条腿走路”的策略其实很务实。因为现实世界里不是所有团队都有能力自己搭一套服务端编排。有些小团队就是想要一个开箱即用的 SDK集成完就能跑。而有些中大型团队已经有自己的服务端架构只想要一个干净的 API 来对接 AI 能力。AICP 如果能把这两种需求都覆盖到那它的适用面就会很广。接下来我会从技术选型、实操步骤、常见坑几个维度把这件事拆开讲透。3. 不装 SDK 的接入方式服务端 API 与轻量客户端3.1 纯 API 接入的架构与适用场景不装 SDK最直接的方式就是走服务端 API。客户端通过 HTTP 或 WebSocket 与服务端通信服务端再与 AI 平台交互。这种架构下客户端几乎不需要任何厂商特定的代码用标准的网络库就能完成。我画一个典型的链路客户端发起请求 → 业务服务端接收 → 调用 AICP 的 API 创建会话/发送消息 → AICP 编排 Agent 逻辑 → 结果通过回调或轮询返回 → 业务服务端推送给客户端。这种模式的优势非常明显。第一客户端零依赖不用引入任何第三方库包体积不增加。第二升级无感服务端改逻辑客户端完全不用动。第三安全可控API Key、模型配置、工具凭证全部在服务端不会泄露。第四多端一致Web、App、小程序、桌面端用同一套 API不用为每个平台单独适配。但它也有代价。最突出的是实时性依赖网络质量如果走 HTTP 轮询延迟会比较高走 WebSocket 的话需要自己维护连接状态和重连逻辑。另外离线消息需要自己实现SDK 帮你做好的那些脏活累活现在要自己扛。所以纯 API 接入更适合那些对实时性要求不是极致、且团队有一定服务端能力的场景。比如企业内部的知识库问答、后台管理系统的 AI 助手这类场景用户量不大但对可控性要求高纯 API 就很合适。3.2 WebSocket 长连接与流式响应处理如果场景对实时性有要求比如 AI 对话需要逐字输出打字机效果那 WebSocket 几乎是必选项。大模型的响应通常是流式的token 一个一个吐出来如果等全部生成完再返回用户体验会很差。用 WebSocket 可以把每个 token 实时推给客户端实现流畅的对话体验。这里有个实操细节值得展开。流式响应的处理关键在于消息分片和重组。服务端推送过来的数据可能是这样的结构{type: delta, content: 你}、{type: delta, content: 好}、{type: done}。客户端需要维护一个缓冲区把 delta 内容拼接起来遇到 done 才结束本轮渲染。如果中间有工具调用还会插入{type: tool_call, name: search, args: {...}}这类事件客户端可以选择展示“正在搜索...”的提示。我踩过的一个坑是心跳与超时。WebSocket 连接在移动网络下很容易被运营商掐断如果不做心跳客户端可能以为连接还在实际上早就断了。我的做法是客户端每 30 秒发一个 ping服务端回 pong连续两次没收到 pong 就主动重连。重连时要带上上次的消息 ID让服务端补发遗漏的消息。这套逻辑如果自己写大概两三百行代码不算复杂但必须写扎实否则线上会出各种“消息丢失”的投诉。3.3 轻量客户端封装的必要性与边界完全不装 SDK不代表客户端什么都不用做。实际上把 WebSocket 管理、消息分片、重连、本地缓存这些逻辑散落在业务代码里很快就会变得难以维护。所以我的建议是即使不用厂商 SDK也应该在客户端做一层轻量封装。这层封装不是厂商提供的而是团队自己维护的可能只有几百行但能把通信细节和业务逻辑隔离开。这层封装应该包含什么我的经验是这几块连接管理建立、断开、重连、心跳、消息队列发送队列、接收队列、失败重试、事件分发把不同类型的消息分发给对应的业务处理器、以及状态同步在线/离线、会话列表。它不应该包含什么不应该包含 AI 相关的业务逻辑比如 prompt 拼接、工具选择这些应该在服务端。也不应该包含复杂的 UI 逻辑UI 应该订阅事件后自己处理。这样划分的好处是客户端封装层可以跨项目复用。今天做 AI 客服用它明天做 AI 助手还用它只需要换服务端的 Agent 配置。而且这层封装足够薄出问题容易排查不会像大型 SDK 那样变成一个黑盒。我个人的体会是客户端代码超过 500 行的封装就要警惕了很可能把不该放的东西放进来了。4. 如果还是要装 SDK什么情况下值得4.1 需要离线能力与本地存储的场景虽然我上面一直在说轻量化但有些场景确实离不开 SDK。最典型的就是离线消息和本地存储。比如一个社交 App用户希望打开就能看到历史消息没网也能翻看之前的对话。这种需求如果纯靠服务端 API每次都要拉取全量数据体验很差。SDK 通常会在本地建一个数据库消息先落盘再同步打开就能秒显。AI 场景下也有类似需求。比如一个 AI 学习助手用户在地铁上没信号但还想复习之前的对话记录这时候本地存储就很重要。再比如 Agent 需要维护长期记忆部分记忆可以缓存在本地减少服务端往返。这些场景下集成一个带本地存储能力的 SDK 是合理的。但要注意本地存储会带来数据一致性问题多端同步时容易出现冲突需要设计好版本号和冲突解决策略。4.2 深度集成系统能力的情况另一类需要 SDK 的场景是深度集成系统能力。比如推送Android 上要适配各家厂商的推送通道iOS 上要处理 APNs这些如果自己写工作量巨大且容易出错。SDK 把这些差异抹平了你只需要调用一个接口就能发推送。再比如音视频WebRTC 的适配在不同设备上差异很大成熟的 SDK 能帮你省掉大量调试时间。AI 场景下如果 Agent 需要调用系统能力比如读取通讯录、发送短信、调用摄像头那客户端就需要相应的权限和原生代码。这种情况下SDK 提供的桥接能力就有价值。但我的建议是只集成需要的那部分不要为了一个推送功能引入整个 IM SDK。现在很多厂商支持模块化集成按需引入这个特性要充分利用。4.3 SDK 与 API 混合模式的实践现实中最务实的方案往往是混合模式核心通信走 SDKAI 编排走 API。具体来说客户端集成一个轻量的 IM SDK 负责消息通道和本地存储AI 相关的逻辑全部通过服务端 API 完成。SDK 收到消息后如果是普通消息就正常展示如果是 AI 相关的指令就转发给服务端的 Agent 处理处理结果再通过 SDK 的通道推回来。这种模式的好处是兼顾了稳定性和灵活性。SDK 负责它最擅长的通信和存储API 负责快速迭代的 AI 逻辑。我实测下来这种架构的改动成本最低因为大部分团队已经有 IM SDK 的集成经验只需要在服务端加一层 Agent 编排即可。融云 AICP 如果支持这种混合模式那对存量客户会非常友好不需要推翻现有架构就能接入 AI 能力。5. 实操从零搭建一个不装 SDK 的 AI 对话链路5.1 服务端 Agent 编排的最小实现假设我们要做一个最简单的 AI 对话服务不装任何客户端 SDK纯靠服务端 API。第一步是搭建服务端的 Agent 编排。我用 Python 写一个最小示例核心逻辑是接收用户消息 → 拼接上下文 → 调用大模型 → 流式返回结果。import asyncio from fastapi import FastAPI, WebSocket from openai import AsyncOpenAI app FastAPI() client AsyncOpenAI(api_keyyour-key, base_urlyour-endpoint) sessions {} app.websocket(/ws/{session_id}) async def chat(websocket: WebSocket, session_id: str): await websocket.accept() history sessions.setdefault(session_id, []) try: while True: user_msg await websocket.receive_text() history.append({role: user, content: user_msg}) stream await client.chat.completions.create( modelyour-model, messageshistory, streamTrue ) full_reply async for chunk in stream: delta chunk.choices[0].delta.content or if delta: full_reply delta await websocket.send_json({type: delta, content: delta}) history.append({role: assistant, content: full_reply}) await websocket.send_json({type: done}) except Exception as e: await websocket.send_json({type: error, message: str(e)})这段代码虽然简单但包含了几个关键点。第一会话隔离用 session_id 区分不同用户history 存在内存里生产环境要换成 Redis。第二流式转发大模型每吐一个 token 就立刻推给客户端不攒批。第三错误处理异常时给客户端发 error 事件避免连接静默断开。这个最小实现大概 30 行跑起来就能用适合快速验证。5.2 客户端 WebSocket 封装与重连策略客户端这边我用 JavaScript 写一个轻量封装核心是连接管理和自动重连。注意这里不依赖任何第三方库纯原生 WebSocket。class ChatClient { constructor(url) { this.url url; this.ws null; this.handlers {}; this.reconnectDelay 1000; this.maxDelay 30000; this.heartbeatTimer null; this.connect(); } connect() { this.ws new WebSocket(this.url); this.ws.onopen () { this.reconnectDelay 1000; this.startHeartbeat(); this.emit(open); }; this.ws.onmessage (e) { const msg JSON.parse(e.data); this.emit(msg.type, msg); }; this.ws.onclose () { this.stopHeartbeat(); this.scheduleReconnect(); }; this.ws.onerror () this.ws.close(); } startHeartbeat() { this.heartbeatTimer setInterval(() { if (this.ws.readyState WebSocket.OPEN) { this.ws.send(JSON.stringify({ type: ping })); } }, 30000); } stopHeartbeat() { clearInterval(this.heartbeatTimer); } scheduleReconnect() { setTimeout(() this.connect(), this.reconnectDelay); this.reconnectDelay Math.min(this.reconnectDelay * 2, this.maxDelay); } send(text) { if (this.ws.readyState WebSocket.OPEN) { this.ws.send(JSON.stringify({ type: user, content: text })); } else { this.emit(error, { message: 连接未就绪 }); } } on(event, handler) { this.handlers[event] this.handlers[event] || []; this.handlers[event].push(handler); } emit(event, data) { (this.handlers[event] || []).forEach(fn fn(data)); } }这个封装大概 60 行包含了指数退避重连1 秒开始每次翻倍最大 30 秒、心跳保活30 秒一次 ping、事件订阅on/emit 模式。业务代码只需要client.on(delta, ...)就能处理流式内容非常干净。我实测下来这套逻辑在弱网环境下表现稳定断线后平均 2 到 3 秒能恢复。5.3 消息协议设计与错误码约定不装 SDK 的一个隐性成本是消息协议要自己设计。SDK 通常帮你定义好了消息格式现在你得自己来。我的建议是保持简单用 JSON 就好字段名要语义清晰。下面是我常用的一套协议字段类型说明typestring消息类型user/delta/done/error/ping/pongcontentstring文本内容delta 和 user 类型使用message_idstring消息唯一 ID用于去重和补发timestampnumber毫秒时间戳codenumber错误码error 类型使用messagestring错误描述error 类型使用错误码的约定也很重要。我一般这样划分1xxx 表示客户端错误参数错误、未连接2xxx 表示服务端错误模型超时、内部异常3xxx 表示限流和配额问题。客户端收到 error 后根据 code 决定是重试、提示用户、还是静默降级。这套约定看起来简单但能省掉大量联调时的扯皮。我见过太多项目因为错误码不统一前端只能靠字符串匹配来判断错误类型非常脆弱。6. 常见问题与排查技巧实录6.1 连接建立失败与跨域问题不装 SDK 后第一个拦路虎往往是连接建立失败。WebSocket 的握手阶段容易出问题最常见的是跨域。浏览器对 WebSocket 的跨域检查虽然不像 HTTP 那么严格但服务端如果没正确处理 Origin 头还是会被拒绝。我的做法是服务端显式校验 Origin允许的域名放在配置里不要用通配符避免安全风险。另一个常见问题是反向代理配置。Nginx 默认不支持 WebSocket 的 Upgrade需要在 location 里加这几行proxy_http_version 1.1; proxy_set_header Upgrade $http_upgrade; proxy_set_header Connection upgrade; proxy_read_timeout 3600s;proxy_read_timeout特别关键默认 60 秒如果超过这个时间没有数据传输Nginx 会主动断开连接。AI 对话有时候思考时间比较长60 秒很容易超时设成 3600 秒比较稳妥。这个坑我踩过不止一次现象是连接莫名其妙断开查日志才发现是代理超时。6.2 流式响应中断与消息乱序流式响应最怕的是中途中断。用户看到一半突然没下文了体验极差。造成中断的原因有很多网络抖动、服务端超时、模型接口限流。我的处理策略是分段确认 断点续传。服务端每发送 N 个 delta 就带一个序号客户端记录最后收到的序号。如果连接断了重连时带上这个序号服务端从下一个序号继续发。这样即使中断用户也只会丢失很少的内容。消息乱序是另一个隐蔽的问题。WebSocket 本身保证有序但如果服务端用了多个协程并发推送就可能乱序。我的做法是单会话单协程一个会话的所有消息由一个协程按顺序发出避免并发。如果确实需要并发比如同时调用多个工具那就在服务端做好排序按时间戳或序号排好再发。客户端这边也可以做一层缓冲收到乱序消息先缓存等齐了再渲染。6.3 排查速查表与独家避坑技巧下面这张表是我在实际项目中总结的常见问题速查表遇到问题可以先对照排查现象可能原因排查方法解决方案连接立即断开鉴权失败/Origin 拒绝看服务端日志的握手记录检查 token 和 Origin 配置连接几分钟后断开代理超时/心跳缺失抓包看最后一条消息时间加心跳调大 proxy_read_timeout消息发送成功但收不到回复会话 ID 不匹配打印 session_id 对比确保收发用同一会话流式内容重复重连后重复推送检查序号去重逻辑客户端按 message_id 去重中文乱码编码不一致检查 Content-Type统一用 UTF-8移动端后台断连系统省电策略查看 App 后台存活时间引导用户加白名单或降级为推送独家避坑技巧分享两个。第一永远不要相信客户端的时钟时间戳只用来排序不要用来做业务判断因为用户手机时间可能不准。第二日志要带 trace_id从客户端到服务端到模型调用全链路一个 ID 串起来出问题时能快速定位是哪一环。这两个习惯帮我省了无数排查时间。7. 我的选型建议与后续扩展思路聊了这么多回到最初的问题都 AI 时代了还得装 SDK 吗我的答案是看场景但趋势是轻量化。如果你做的是标准 IM 功能需要离线、推送、音视频那成熟 SDK 依然是最高效的选择没必要重复造轮子。如果你做的是 AI 对话、Agent 助手这类以服务端智能为核心的场景那纯 API 加轻量客户端封装会更灵活迭代速度也更快。融云 AICP 这个系列既然拿这个问题开篇我猜后续会展开讲它的服务端编排能力、Agent 管理、以及如何与现有 IM 体系结合。如果你正在做技术选型我的建议是先明确自己的核心需求是要快速上线还是要长期可控是要覆盖全端还是聚焦某一端是要开箱即用还是要深度定制想清楚这几个问题选型自然就清晰了。最后分享一个我个人的判断标准如果 AI 逻辑的变更频率高于客户端发版频率那就把逻辑放服务端。这个标准帮我做过很多次决策基本没出过错。客户端发版要审核、要等用户更新周期以周甚至月计服务端改完就能上线周期以小时计。AI 这个领域变化太快把易变的部分放在服务端是更明智的选择。至于 SDK它不会消失但会从“必选项”变成“可选项”从“大而全”变成“小而精”。这个趋势值得每个做技术的人关注。