实时 AI SDK：面向 React、Vue 与 JS 的 WebSocket 流式传输

安装

使用你习惯的包管理器安装 SDK：

Bash

npm install @modelriver/client
# 或
pnpm add @modelriver/client
# 或
yarn add @modelriver/client

如果只是快速原型验证，也可以直接使用 CDN：

HTML

1<script src="https://cdn.modelriver.com/client/latest/modelriver.min.js"></script>

它是如何工作的

你的后端 调用 ModelRiver 的异步 API（例如 /api/v1/ai/async），启动一条后台 AI 请求。
ModelRiver 返回异步响应，其中包含 channel_id、一次性短期有效的 ws_token 和 WebSocket 连接信息。
你的前端 使用 SDK，基于 channel_id + ws_token 建立 WebSocket 连接，并接收流式响应。
SDK 负责心跳、频道加入和瞬时网络抖动下的自动重连（在页面未关闭时）。
如果用户刷新页面，可以结合持久化与重连辅助方法（persist、hasPendingRequest、reconnect、reconnectWithBackend）以及你后端的 /api/v1/ai/reconnect 端点恢复会话。

前端                你的后端                ModelRiver
  │                     │                        │
  │ 1. 发起 AI 请求     │                        │
  │────────────────────>│                        │
  │                     │ 2. POST /api/v1/ai/async │
  │                     │───────────────────────>│
  │                     │                        │
  │                     │ 3. channel_id,        │
  │                     │    ws_token,          │
  │                     │    websocket_url      │
  │                     │<───────────────────────│
  │ 4. 返回连接凭证     │                        │
  │<────────────────────│                        │
  │                     │                        │
  │ 5. SDK 通过 WebSocket 连接                    │
  │─────────────────────────────────────────────>│
  │                     │                        │
  │ 6. AI 响应实时流出                           │
  │<─────────────────────────────────────────────│

快速开始

最快的上手方式是安装核心库，然后选择一个一等适配器接入。

Bash

npm install @modelriver/client

选择你的前端框架

集成方式	说明	指南
React	面向函数组件的 `useModelRiver` Hook	React 指南 →
Vue	适用于 Composition API 的 `useModelRiver` 组合式函数	Vue 指南 →
Angular	基于 Observable 的 `ModelRiverService`	Angular 指南 →
Svelte	面向 AI 流的实时响应式 store	Svelte 指南 →
Vanilla JS	轻量、零依赖的浏览器 SDK	Vanilla JS 指南 →

核心概念

1. 统一的实时流

SDK 负责管理与 ModelRiver 的持久 WebSocket 连接。它会处理心跳、自动重连和状态同步，确保你的前端始终反映最新的 AI 执行状态。

2. 异步生命周期

发起：你的后端调用 ModelRiver 异步 API。
返回凭证：ModelRiver 返回 ws_token 和 channel_id。
建立连接：前端使用该凭证通过 SDK 建立连接。
实时流出：响应数据和工作流步骤会实时推送到前端。

3. 工作流步骤状态

SDK 会跟踪四个固定阶段：

queue：请求正在排队
process：AI 正在处理提示词
receive：AI 已完成，数据正在交付
complete：请求成功结束

配置选项

TYPESCRIPT

1interface ModelRiverClientOptions {
2  baseUrl?: string;          // WebSocket 网关（默认：api.modelriver.com）
3  apiBaseUrl?: string;       // 你的后端地址，用于恢复助手方法
4  debug?: boolean;           // 是否开启控制台调试日志
5  persist?: boolean;         // 是否启用 localStorage 持久化
6  storageKeyPrefix?: string; // 本地存储 Key 前缀
7}

页面刷新恢复

默认情况下，SDK 会把活跃的 channel_id 持久化到 localStorage。如果用户在流式返回过程中刷新页面，SDK 可以通过向你的后端获取新的 token 自动重连到同一会话。

深入接入方式请查看持久化与恢复一节。

下一步

阅读 API 文档完成后端配置。
查看 Workflows 了解模型编排方式。
阅读 Event-driven AI 学习基于 Webhook 的处理模式。

实时 AI 流式 SDK

安装