文档

文档

React 客户端 SDK

ModelRiver React SDK 提供一等公民的 useModelRiver Hook，可自动管理 WebSocket 连接、AI 流式响应和请求生命周期状态。

安装

Bash
npm install @modelriver/client

React 适配层已包含在核心包 @modelriver/client 中。

快速开始

useModelRiver 是在 React 组件中接入实时 AI 的最简单方式。

TSX
1import React, { useState } from 'react';
2import { useModelRiver } from '@modelriver/client/react';
3 
4export function ChatComponent() {
5 const [input, setInput] = useState('');
6 
7 const {
8 connect,
9 response,
10 error,
11 isConnected,
12 steps,
13 status
14 } = useModelRiver({
15 baseUrl: 'wss://api.modelriver.com/socket',
16 persist: true
17 });
18 
19 const handleSend = async () => {
20 const res = await fetch('/api/ai/chat', {
21 method: 'POST',
22 body: JSON.stringify({ prompt: input })
23 });
24 
25 const { ws_token, channel_id } = await res.json();
26 connect({ wsToken: ws_token, channelId: channel_id });
27 setInput('');
28 };
29 
30 return (
31 <div className="chat-container">
32 <div className="steps-progress">
33 {steps.map((step) => (
34 <div key={step.id} className={`step ${step.status}`}>
35 {step.name}: {step.status}
36 </div>
37 ))}
38 </div>
39 
40 <div className="response-area">
41 {status === 'loading' && <p>AI is thinking...</p>}
42 {response && (
43 <div className="ai-message">
44 {response.content}
45 {response.data && <pre>{JSON.stringify(response.data, null, 2)}</pre>}
46 </div>
47 )}
48 </div>
49 
50 <input
51 value={input}
52 onChange={(e) => setInput(e.target.value)}
53 disabled={status === 'loading'}
54 />
55 <button onClick={handleSend} disabled={!input || status === 'loading'}>
56 Send
57 </button>
58 
59 {error && <p className="error-message">{error}</p>}
60 </div>
61 );
62}

关键能力

useModelRiver Hook

Hook 会返回以下状态与方法：

  • isConnected：WebSocket 是否已连接
  • status：'idle' | 'loading' | 'success' | 'error'
  • response：完整 AIResponse 对象，包含 content、data 和 meta
  • steps：WorkflowStep 数组，表示队列、处理、接收、完成等阶段
  • error：请求失败时的错误信息
  • connect(options)：使用 wsToken 发起连接

持久化与恢复

开启 persist: true 后，SDK 会把当前 channel_id 存到 localStorage。如果用户在请求处理中刷新页面，你可以恢复连接。

在 React 中构建 AI 交互的建议

  1. 使用 response.content 实时渲染流式文本
  2. 使用 steps 向用户展示当前处理进度
  3. 始终处理 error 状态，并提供重试入口
  4. 在发送后立即清空输入框并展示 pending 状态，提升交互体感

下一步