一个 App 如何同时对接云端 AI 与本地 AI

发贴员

一个按钮、四个后端：一个桌面应用如何让 Replicate、Runware、Ollama 和进程内 ONNX 表现得像同一个东西。里面有真实的取舍。

用户选一个模型、敲一句提示词、点"生成"。在那个按钮背后，我们的桌面应用可能向从 Replicate 租来的 GPU 开一条 HTTPS 连接，或通过 WebSocket 把任务推给 Runware，或调用一个它自己起在 localhost 上的 HTTP 服务器，又或者根本不建立任何连接、直接在自己进程里跑一个 ONNX 模型。同一个按钮、同一条进度条、最后项目文件夹里同一种文件。

本文是一次工程巡礼：CSuite 这个 App，如何把云端 API 和本地运行时当作同一套东西、藏在一个接口后面。它通过五个真正让这事变难的问题展开：描述模型、路由请求、过滤参数、流式返回结果、以及守住信任边界。这个模式不只为这个产品有用。每一个长大到单一服务商装不下的 AI 应用，都会变成一个路由器。



一个"模型"意味着四台不同的机器

Replicate 是经典云 API：你通过 HTTPS 创建一个预测，它经历各个状态，你轮询或流式接收，一次运行最长可达 30 分钟。Runware 偏好一条持久 WebSocket：你每条连接认证一次，发射带着 UUID 标记的任务，响应乱序回来时按标记匹配。

本地那一半更怪。Ollama 是一个恰好住在你自己机器上的 HTTP 服务器；transformers.js 把服务器整个拿掉：它在应用的子进程里、通过 ONNX Runtime 跑 ONNX 导出的模型。没有 socket、没有端口、没有网络。

不对称一路向下。云端模型需要 API 密钥；本地模型需要几十 GB 磁盘和足够内存。云端故障长得像限流和超时；本地故障长得像内存不足被杀。一个假装这些差异不存在的抽象，会在最糟的时刻把它们漏出来。

一份目录胜过四份模型清单

CSuite 把它反过来：一份目录文件、按模态组织，每个模型是一条单独条目，声明自己能在哪些平台上跑。截至目前，这份文件通过 151 个平台块描述了 107 个模型：Replicate 上 49 个、Runware 上 49 个、Ollama 上 47 个。被两家云同时提供的模型，是一条条目两个块，而不是两行。



这就是回报：路由不再是一棵决策树，而是一次查表。本地运行时拿到固定的哨兵 id；云端服务商是存好的、带 UUID 的凭证。路由器本身保持无聊，因为每个模型相关的决定在请求到达之前就已经被目录做完了。

是目录、不是 UI，充当参数契约

在 CSuite 的目录里，模型条目一共声明了 559 个输入参数，设置面板就是从这些声明渲染出来的：一个没有 temperature 参数的模型，干脆不显示温度滑块。同一套 schema 在边界做反向的活：在请求离开 App 之前，目标模型没声明的一切都被丢掉，于是 UI 不可能发出模型不接受的东西。

活下来的教训有两条。第一，严格的 API 是礼物：一个能点名哪个键有问题的错误，是集成能拥有的最好失败模式。第二，能力是按模型算的，不是按平台算的。

流整个字符串，而不是差异



流式文本是传输方式分歧最大的地方。CSuite 的契约故意冗余：每一块推给 UI 的 chunk 都带着到目前为止的完整字符串，渲染器替换已有的内容而不是追加。

增量是教科书答案，因为它字节最少。但在聊天量级，字节微不足道。增量省下来的效率是用脆弱换的：它假设生产者和屏幕之间什么都不会丢、不会重、不会乱序。累积 chunk 是自愈的。丢一条消息代价是少重绘一帧，下一条消息就把屏幕完全修好。

API 密钥从不与接口见面

桌面应用有一条 Web 应用不会让你去想的信任边界。CSuite 把 Electron 的进程模型当成安全架构：每一次服务商调用、每一次凭证读取、每一次文件写入都发生在特权一侧，接口通过一条经过校验的消息通道请求干活，而不是自己干。

密钥只存在特权一侧，静止时用 Electron 的 safeStorage 加密，后者委托给操作系统密钥链。接口根本收不到密钥；它只渲染一个末四位提示。

这个抽象花了什么

这一切都不是免费的。目录是一份维护承诺：每个新模型都意味着去研究它真实的参数表面。本地那一半扛着云端那一半永远不会有的重量：首次安装时下载的固定运行时、以 GB 计的模型——而一个云端模型不过是请求里的一个名字。

有些不对称拒绝被藏起来，而正确的动作是停止藏它们。一个抽象赢得信任，靠的是对自己的边缘诚实，而不是把边缘磨平。