ai-sdk-ui

AI SDK UI - 前端 React Hooks

使用 Vercel AI SDK v5/v6 为 AI 驱动的用户界面提供前端 React Hooks。

版本：AI SDK v5.0.99（稳定版）/ v6.0.0-beta.108（Beta） 框架：React 18+、Next.js 14+ 最后更新：2025-11-22

---

AI SDK 6 Beta（2025 年 11 月）

状态： Beta（计划于 2025 年底发布稳定版） 最新版本： [email protected]（2025 年 11 月 22 日） 迁移： 从 v5 → v6 的破坏性变更极少

v6 Beta 中的全新 UI 功能

1. Agent 集成 使用 InferAgentUIMessage<typeof agent> 与 Agent 进行类型安全的消息交互：

import { useChat } from '@ai-sdk/react';
import type { InferAgentUIMessage } from 'ai';
import { myAgent } from './agent';

export default function AgentChat() {
  const { messages, sendMessage } = useChat<InferAgentUIMessage<typeof myAgent>>({
    api: '/api/chat',
  });
  // messages are now type-checked against agent schema
}

2. 工具审批工作流（人在回路中） 执行工具前请求用户确认：

import { useChat } from '@ai-sdk/react';
import { useState } from 'react';

export default function ChatWithApproval() {
  const { messages, sendMessage, addToolApprovalResponse } = useChat({
    api: '/api/chat',
  });

  const handleApprove = (toolCallId: string) => {
    addToolApprovalResponse({
      toolCallId,
      approved: true,  // or false to deny
    });
  };

  return (
    <div>
      {messages.map(message => (
        <div key={message.id}>
          {message.toolInvocations?.map(tool => (
            tool.state === 'awaiting-approval' && (
              <div key={tool.toolCallId}>
                <p>Approve tool call: {tool.toolName}?</p>
                <button onClick={() => handleApprove(tool.toolCallId)}>
                  Approve
                </button>
                <button onClick={() => addToolApprovalResponse({
                  toolCallId: tool.toolCallId,
                  approved: false
                })}>
                  Deny
                </button>
              </div>
            )
          ))}
        </div>
      ))}
    </div>
  );
}

3. 自动提交功能 处理完审批后自动继续对话：

import { useChat, lastAssistantMessageIsCompleteWithApprovalResponses } from '@ai-sdk/react';

export default function AutoSubmitChat() {
  const { messages, sendMessage } = useChat({
    api: '/api/chat',
    sendAutomaticallyWhen: lastAssistantMessageIsCompleteWithApprovalResponses,
    // Automatically resubmit after all approval responses provided
  });
}

4. 聊天中的结构化输出 在调用工具的同时生成结构化数据（此前仅在 useObject 中提供）：

import { useChat } from '@ai-sdk/react';
import { z } from 'zod';

const schema = z.object({
  summary: z.string(),
  sentiment: z.enum(['positive', 'neutral', 'negative']),
});

export default function StructuredChat() {
  const { messages, sendMessage } = useChat({
    api: '/api/chat',
    // Server can now stream structured output with chat messages
  });
}

---

useChat Hook - v4 → v5 破坏性变更

重要：v5 中的 useChat 不再管理输入状态！

v4（旧版 - 请勿使用）：

const { messages, input, handleInputChange, handleSubmit, append } = useChat();

<form onSubmit={handleSubmit}>
  <input value={input} onChange={handleInputChange} />
</form>

v5（新版 - 正确用法）：

const { messages, sendMessage } = useChat();
const [input, setInput] = useState('');

<form onSubmit={(e) => {
  e.preventDefault();
  sendMessage({ content: input });
  setInput('');
}}>
  <input value={input} onChange={(e) => setInput(e.target.value)} />
</form>

v5 变更摘要：

1. 移除输入管理：不再提供 input、handleInputChange、handleSubmit
2. append() → sendMessage()：新增的消息发送方法
3. 移除 onResponse：改用 onFinish
4. initialMessages → 受控模式：使用 messages 属性进行全面控制
5. 移除 maxSteps：仅在服务端处理

完整迁移指南请参阅 references/use-chat-migration.md。

---

useAssistant Hook

通过自动管理 UI 状态，与兼容 OpenAI 的助手 API 交互。

导入：

import { useAssistant } from '@ai-sdk/react';

基本用法：

'use client';
import { useAssistant } from '@ai-sdk/react';
import { useState, FormEvent } from 'react';

export default function AssistantChat() {
  const { messages, sendMessage, isLoading, error } = useAssistant({
    api: '/api/assistant',
  });
  const [input, setInput] = useState('');

  const handleSubmit = (e: FormEvent) => {
    e.preventDefault();
    sendMessage({ content: input });
    setInput('');
  };

  return (
    <div>
      {messages.map(m => (
        <div key={m.id}>
          <strong>{m.role}:</strong> {m.content}
        </div>
      ))}
      <form onSubmit={handleSubmit}>
        <input
          value={input}
          onChange={(e) => setInput(e.target.value)}
          disabled={isLoading}
        />
      </form>
      {error && <div>{error.message}</div>}
    </div>
  );
}

使用场景：

• 构建由 OpenAI Assistant 驱动的 UI
• 管理助手会话线程和运行
• 在管理 UI 状态的同时流式传输助手响应
• 集成文件搜索和代码解释器

完整 API 参考请参阅官方文档：https://ai-sdk.dev/docs/reference/ai-sdk-ui/use-assistant

---

常见 UI 错误及解决方案

完整文档请参阅 references/top-ui-errors.md。速查：

1. useChat 无法解析流

错误：SyntaxError: Unexpected token in JSON at position X

原因：API 路由未返回正确的流格式。

解决方案：

// ✅ CORRECT
return result.toDataStreamResponse();

// ❌ WRONG
return new Response(result.textStream);

2. useChat 无响应

原因：API 路由未正确流式传输。

解决方案：

// App Router - use toDataStreamResponse()
export async function POST(req: Request) {
  const result = streamText({ /* ... */ });
  return result.toDataStreamResponse(); // ✅
}

// Pages Router - use pipeDataStreamToResponse()
export default async function handler(req, res) {
  const result = streamText({ /* ... */ });
  return result.pipeDataStreamToResponse(res); // ✅
}

3. 部署后流式传输无法正常工作

原因：部署平台缓冲了响应。

解决方案：Vercel 会自动检测流式传输。其他平台可能需要配置。

4. useChat 的 body 值过时

原因：body 选项仅在首次渲染时捕获。

解决方案：

// ❌ WRONG - body captured once
const { userId } = useUser();
const { messages } = useChat({
  body: { userId },  // Stale!
});

// ✅ CORRECT - use controlled mode
const { userId } = useUser();
const { messages, sendMessage } = useChat();

sendMessage({
  content: input,
  data: { userId },  // Fresh on each send
});

5. React 更新深度超出最大值

原因：useEffect 中出现无限循环。

解决方案：

// ❌ WRONG
useEffect(() => {
  saveMessages(messages);
}, [messages, saveMessages]); // saveMessages triggers re-render!

// ✅ CORRECT
useEffect(() => {
  saveMessages(messages);
}, [messages]); // Only depend on messages

另外 7 个常见错误请参阅 references/top-ui-errors.md。

---

流式传输最佳实践

性能

始终使用流式传输以获得更好的用户体验：

// ✅ GOOD - Streaming (shows tokens as they arrive)
const { messages } = useChat({ api: '/api/chat' });

// ❌ BAD - Non-streaming (user waits for full response)
const response = await fetch('/api/chat', { method: 'POST' });

用户体验模式

显示加载状态：

{isLoading && <div>AI is typing...</div>}

提供停止按钮：

{isLoading && <button onClick={stop}>Stop</button>}

自动滚动到最新消息：

useEffect(() => {
  messagesEndRef.current?.scrollIntoView({ behavior: 'smooth' });
}, [messages]);

加载期间禁用输入：

<input disabled={isLoading} />

全面的最佳实践请参阅 references/streaming-patterns.md。

---

何时使用此技能

适用于以下场景：

• 构建 React 聊天界面
• 在 UI 中实现 AI 补全
• 将 AI 响应流式传输到前端
• 构建 Next.js AI 应用
• 处理聊天消息状态
• 在 UI 中显示工具调用
• 管理 AI 文件附件
• 从 v4 迁移到 v5（UI Hooks）
• 遇到 useChat/useCompletion 错误

不适用于以下场景：

• 需要后端 AI 功能 → 请改用 ai-sdk-core
• 构建非 React 前端（Svelte、Vue）→ 请查阅官方文档
• 需要 Generative UI / RSC → 请参阅 https://ai-sdk.dev/docs/ai-sdk-rsc
• 构建原生应用 → 需要使用其他 SDK

相关技能：

• ai-sdk-core - 后端文本生成、结构化输出、工具、Agent
• 将两者结合，用于构建全栈 AI 应用

---

软件包版本

稳定版（v5）：

{
  "dependencies": {
    "ai": "^5.0.99",
    "@ai-sdk/react": "^1.0.0",
    "@ai-sdk/openai": "^2.0.68",
    "react": "^18.2.0",
    "zod": "^3.23.8"
  }
}

Beta 版（v6）：

{
  "dependencies": {
    "ai": "6.0.0-beta.108",
    "@ai-sdk/react": "beta",
    "@ai-sdk/openai": "beta"
  }
}

版本说明：

• AI SDK v5.0.99（稳定版，2025 年 11 月）
• AI SDK v6.0.0-beta.108（Beta 版，2025 年 11 月 22 日）- 最小化破坏性更改
• React 18+（支持 React 19）
• 建议使用 Next.js 14+（13.4+ 也可运行）
• 使用 Zod 3.23.8+ 进行架构验证

---

官方文档链接

核心 UI Hooks：

• AI SDK UI 概览：https://ai-sdk.dev/docs/ai-sdk-ui/overview
• useChat：https://ai-sdk.dev/docs/ai-sdk-ui/chatbot
• useCompletion：https://ai-sdk.dev/docs/ai-sdk-ui/completion
• useObject：https://ai-sdk.dev/docs/ai-sdk-ui/object-generation

高级主题（仅提供链接）：

• 生成式 UI（RSC）：https://ai-sdk.dev/docs/ai-sdk-rsc/overview
• 流式传输协议：https://ai-sdk.dev/docs/ai-sdk-ui/stream-protocols
• 消息元数据：https://ai-sdk.dev/docs/ai-sdk-ui/message-metadata

Next.js 集成：

• Next.js App Router：https://ai-sdk.dev/docs/getting-started/nextjs-app-router
• Next.js Pages Router：https://ai-sdk.dev/docs/getting-started/nextjs-pages-router

迁移与故障排除：

• v4→v5 迁移：https://ai-sdk.dev/docs/migration-guides/migration-guide-5-0
• 故障排除：https://ai-sdk.dev/docs/troubleshooting
• 常见问题：https://ai-sdk.dev/docs/troubleshooting/common-issues

Vercel 部署：

• Vercel Functions：https://vercel.com/docs/functions
• 在 Vercel 上进行流式传输：https://vercel.com/docs/functions/streaming

---

模板

此技能在 templates/ 中包含以下模板：

1. use-chat-basic.tsx - 使用手动输入的基础聊天（v5 模式）
2. use-chat-tools.tsx - 带工具调用 UI 渲染的聊天
3. use-chat-attachments.tsx - 文件附件支持
4. use-completion-basic.tsx - 基础文本补全
5. use-object-streaming.tsx - 流式传输结构化数据
6. nextjs-chat-app-router.tsx - Next.js App Router 完整示例
7. nextjs-chat-pages-router.tsx - Next.js Pages Router 完整示例
8. nextjs-api-route.ts - 适用于 App 和 Pages Router 的 API 路由
9. message-persistence.tsx - 保存／加载聊天历史记录
10. custom-message-renderer.tsx - 使用 Markdown 的自定义消息组件
11. package.json - 依赖项模板

参考文档

请参阅 references/ 中的：

• use-chat-migration.md - 完整的 v4→v5 迁移指南
• streaming-patterns.md - UI 流式传输最佳实践
• top-ui-errors.md - 12 个常见 UI 错误及其解决方案
• nextjs-integration.md - Next.js 设置模式
• links-to-official-docs.md - 分类整理的官方文档链接

---

已通过生产环境测试：WordPress Auditor (https://wordpress-auditor.webfonts.workers.dev) 最后更新：2025-11-22