Vercel AI SDK 接了3个项目后,我总结出这套「防翻车」指南

你有没有遇到过这种情况：照着官方文档写了个 AI 聊天页面，useChat 一跑，消息倒是能出来，但每次回复都会闪一下空白，用户体验直接拉胯？

翻了半天 issue 才发现，不是你代码写错了，是流式响应的状态管理有个隐藏的时序问题——而官方文档压根没提。

这就是 Vercel AI SDK 的典型体验：上手极快，但坑藏得极深。今天这篇，是我用它做了 3 个项目后，把所有踩过的坑、摸出的最佳实践，一次性讲清楚。

先搞明白一件事：AI SDK 现在到底是什么版本？

很多人上来就 npm install ai，装完也不看版本号就开干。但 2026 年的 AI SDK 生态已经不是一年前的样子了。

目前的情况是：稳定版 AI SDK 5，Beta 版 AI SDK 6。如果你是新项目，建议直接上 v6 Beta；如果是老项目维护，先别急着升——v4 到 v6 的 breaking changes 能让你改到怀疑人生。

举个真实的例子：maxTokens 改成了 maxOutputTokens，CoreMessage 改成了 ModelMessage，generateObject() 被废弃，tool 调用的 args 改成了 input。这些改动分散在十几个文件里，编译器不会提醒你，只有运行时才会崩。

一个血泪教训：升级前先锁版本，逐个文件排查 API 变更，别想着一把梭。

useChat 用起来爽，但这 3 个坑你一定会踩

useChat 是 AI SDK 最核心的 React Hook，一行代码就能搞定聊天界面的状态管理。但"能用"和"好用"之间，隔着三个大坑。

坑一：消息闪烁的元凶——状态更新时序

用 useChat 的时候，你大概率会写出这样的代码：

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

export default function Chat() {
  const { messages, input, handleInputChange, handleSubmit } = useChat();

  return (
    <div>
      {messages.map((m) => (
        <div key={m.id}>{m.content}</div>
      ))}
      <form onSubmit={handleSubmit}>
        <input value={input} onChange={handleInputChange} />
      </form>
    </div>
  );
}

看起来没毛病对吧？但实际运行时，AI 回复的第一帧会出现一个空消息气泡，然后才开始填充内容。原因是 useChat 在收到流的第一个 chunk 之前，就已经往 messages 数组里 push 了一条空的 assistant 消息。

解决方案很简单，渲染时过滤掉空内容：

{messages
  .filter((m) => m.content.trim() !== '')
  .map((m) => (
    <div key={m.id}>{m.content}</div>
  ))}

一行代码的事，但不知道原因的话能调半天。

坑二：多轮对话的内存泄漏

useChat 默认会把所有历史消息都存在内存里，每次请求都带上完整的 messages 数组发给后端。聊个 20 轮，请求体就膨胀到几十 KB，token 消耗也跟着飙升。

我的做法是在后端做消息截断：

import { streamText } from 'ai';
import { openai } from '@ai-sdk/openai';

export async function POST(req: Request) {
  const { messages } = await req.json();
  // 只保留最近 10 轮对话 + system prompt
  const recentMessages = messages.slice(-20);

  const result = await streamText({
    model: openai('gpt-4-turbo'),
    messages: recentMessages,
  });

  return result.toDataStreamResponse();
}

别在前端截断，因为 useChat 的内部状态和你手动改的 messages 会打架。后端截断是最干净的方案。

坑三：错误处理的"沉默失败"

useChat 默认的错误处理是——没有错误处理。API 返回 500，前端不报错，消息列表里也不会显示任何提示，用户只会看到"AI 不说话了"。

必须手动加上 onError 回调：

const { messages, input, handleSubmit } = useChat({
  onError: (error) => {
    toast.error('AI 开小差了，请稍后重试');
    console.error('Chat error:', error);
  },
});

这三个坑，官方文档一个都没重点提。但凡做过真实项目的人，100% 会遇到。

streamText vs generateText：选错了性能差 10 倍

AI SDK 提供了两种核心的文本生成方式：streamText（流式）和 generateText（一次性返回）。很多人觉得"流式更酷"就无脑用 streamText，但实际上选错场景会严重影响性能。

什么时候用 streamText： - 聊天界面，需要逐字显示 - 长文本生成，用户需要看到进度 - 任何需要"打字机效果"的场景

候用 generateText：* - 后台任务，比如批量生成摘要 - 结构化数据提取，比如从文本中提取 JSON - 不需要实时展示的场景

我在一个项目里犯过的错：用 streamText 做批量内容审核，100 条内容串行流式处理，耗时 3 分钟。改成 generateText + Promise.all 并发，15 秒搞定。

// ❌ 错误：串行流式处理批量任务
for (const item of items) {
  const result = await streamText({
    model: openai('gpt-4-turbo'),
    prompt: `审核以下内容：${item.text}`,
  });
  // 还得等流读完...
}

// ✅ 正确：并发一次性生成
const results = await Promise.all(
  items.map((item) =>
    generateText({
      model: openai('gpt-4-turbo'),
      prompt: `审核以下内容：${item.text}`,
    })
  )
);

记住：，不是给机器用的。

Provider 切换：一行代码的事，但 90% 的人架构都写错了

AI SDK 最大的卖点之一是"多 Provider 支持"——OpenAI、Anthropic、Google、DeepSeek，换模型只需要改一行代码。

理论上是这样：

// 从 GPT-4 切到 Claude
- model: openai('gpt-4-turbo'),
+ model: anthropic('claude-3-5-sonnet'),

但实际项目中，你的模型配置散落在 15 个文件里，每个 API 路由都硬编码了 provider。想切模型？得改 15 个文件，漏一个就是线上事故。

正确的做法是用 Adapter 模式做一层抽象：

// lib/ai-provider.ts
import { openai } from '@ai-sdk/openai';
import { anthropic } from '@ai-sdk/anthropic';

const providers = {
  openai: (model: string) => openai(model),
  anthropic: (model: string) => anthropic(model),
} as const;

type ProviderKey = keyof typeof providers;

export function getModel(
  provider: ProviderKey = 'openai',
  model?: string
) {
  const defaultModels: Record<ProviderKey, string> = {
    openai: 'gpt-4-turbo',
    anthropic: 'claude-3-5-sonnet',
  };
  return providers[provider](model ?? defaultModels[provider]);
}

然后所有 API 路由统一调用：

import { getModel } from '@/lib/ai-provider';

const result = await streamText({
  model: getModel(), // 默认 OpenAI
  messages,
});

切模型？改一处配置，全局生效。这不是过度设计，这是基本的工程素养。

最近有篇案例：一个团队 15 个文件都直接依赖 SDK，每次升级都是噩梦。后来用 Ports and Adapters 模式重构，把 SDK 依赖收敛到 2 个文件，下次升级改动范围从 15+ 文件压缩到 2 个，28 个业务文件零变更。

结构化输出：generateObject + Zod 才是真正的杀手锏

很多人用 AI SDK 只用到了聊天功能，但其实 generateObject 才是生产环境里最值钱的 API。

传统做法：让 AI 返回 JSON，然后 JSON.parse 赌运气，解析失败了再重试。

AI SDK 的做法：用 Zod 定义 schema，generateObject 直接返回类型安全的对象。

import { generateObject } from 'ai';
import { openai } from '@ai-sdk/openai';
import { z } from 'zod';

const { object } = await generateObject({
  model: openai('gpt-4-turbo'),
  schema: z.object({
  ntiment: z.enum(['positive', 'negative', 'neutral']),
    confidence: z.number().min(0).max(1),
    keywords: z.array(z.string()).max(5),
  }),
  prompt: '分析这段用户评价的情感倾向：...',
});

// object.sentiment 自动推导为 'positive' | 'negative' | 'neutral'
// object.confidence 自动推导为 number
// 写错字段名？编译期直接报错

这比运行时抓 JSON 解析错误体面多了。 尤其是把 AI 输出喂给下游系统时，类型安全等于少写一半防御代码。

我在一个内容管理项目里，用 generateObject 做文章标签提取、情感分析、摘要生成，准确率比手写 prompt + JSON.parse 高了一截，代码量反而少了 60%。

工具调用：让 AI 不只是"嘴强"

streamText 支持 tools 参数，这是构建 AI Agent 的基础能力。定义好工具的描述、参数 schema 和执行函数，模型会自己判断什么时候调用。

const result = await streamText({
  model: openai('gpt-4-turbo'),
  messages,
  tools: {
    getWeather: {
      description: '获取指定城市的天气信息',
      parameters: z.object({
        city: z.string().describe('城市名称'),
      }),
      execute: async ({ city }) => {
        const res = await fetch(`/api/weather?city=${city}`);
        return res.json();
      },
    },
  },
});

用户问"北京明天穿什么"，AI 自动识别意图、填参数、调你的函数、拿结果、组织回复。整个过程对用户来说是无缝的。

但有个坑：工具调用的超时处理。如果你的工具函数调了一个慢接口（比如第三方 API），默认没有超时机制，AI 会一直等。建议给每个工具函数加上超时：

execute: async ({ city }) => {
  const controller = new AbortController();
  const timeout = setTimeout(() => controller.abort(), 5000);
  try {
    const res = await fetch(`/api/weather?city=${city}`, {
      signal: controller.signal,
    });
    return res.json();
  } catch {
    return { error: '天气服务暂时不可用' };
  } finally {
    clearTimeout(timeout);
  }
},

写在最后

Vercel AI SDK 确实是目前前端接入大模型最省心的方案——统一的 Provider 抽象、开箱即用的 React Hooks、类型安全的结构化输出，这些设计都很优雅。

但"省心"不等于"无脑用"。真正的最佳实践，从来不是照着文档抄代码，而是理解每个 API 背后的设计意图，然后根据自己的场景做取舍。

你在用 AI SDK 的过程中踩过什么坑？评论区聊聊。

这是「Hans碎碎念」的文章，欢迎关注