SuperAPI AI 工具集

ai-core/custom-backend-integration

编程与开发

查看项目

更新于 10-16 09:59

技能介绍

用途:把 useChat 连接到非 TanStack AI 后端,通过连接适配器对接自定义协议。该技能基于 ai-core 与 ai-core/chat-experience,需先阅读它们。

主要能力:提供两种开箱适配器。fetchServerSentEvents 用于后端以 SSE(text/event-stream,data: {json}\n\n 分帧)通信,为推荐默认方式;fetchHttpStream 用于后端发送 NDJSON(application/x-ndjson),每行一个 JSON StreamChunk。两者均接受静态或动态 URL(字符串或返回字符串的函数)与 options(对象或同步/异步函数),每次请求时求值,因此可动态传 auth token 与 URL 而不必重建适配器;options 的 body 字段会与 messages、data 合并进 POST 请求体。二者都支持传入自定义 fetchClient(与 globalThis.fetch 签名一致),便于代理、拦截、重试。

使用方式:对不适用 SSE 或 NDJSON 的协议(WebSocket、gRPC-web、自定义二进制、server functions),直接实现 ConnectionAdapter,有两种互斥模式。ConnectConnectionAdapter 为拉取式,实现 async *connect(messages, data, abortSignal) 生成 StreamChunk(含 WebSocket 示例);SubscribeConnectionAdapter 为推送式,subscribe(abortSignal) 返回长期 AsyncIterable<StreamChunk>,send(messages, data) 负责发送。stream() 辅助函数可从异步生成器快速创建 ConnectConnectionAdapter。

限制与注意事项:适配器不可同时提供 connect 和 subscribe+send,否则运行时抛错,应二选一。浏览器对同域 SSE 连接数有限制(HTTP/1.1 约 6-8 条),多会话或多标签页可能耗尽,可用 HTTP/2、改用 fetchHttpStream、空闲关闭或单条持久 WebSocket 缓解。HTTP stream 无内置重连,断流会静默丢失部分响应,需自行实现重试(资料给出指数退避示例);fetchServerSentEvents 底层用 fetch 而非 EventSource,同样不自动重连。相关文档见协议与 chat-experience 交叉引用。