Vercel AI SDK 完全指南——OpenAI / Anthropic / Gemini 统一 API（2026）

"我用 OpenAI API 上线了，但也想试试 Claude 和 Gemini"——结果你花两小时把同一套逻辑在三个不同的 SDK 之间重写，手动转换请求和响应格式。Vercel AI SDK（2026 年起简称 "AI SDK"）把这件事压缩成 "一次 import、一个函数、所有 provider"。这是一个 TypeScript 开源库，月下载量超 2000 万；AI SDK 6 自带 Agents、MCP、tool approval 和 DevTools，截至 2026 年 5 月，它已是 统一 LLM 接口的事实标准。

先把话说清：2026 年从 Web 应用或 Node.js 项目调 LLM，AI SDK 就是默认正解，没有之一。仍然直接写 OpenAI 或 Anthropic SDK 的理由只有两个——"已有代码库" 或 "需要刚发布的 provider 独占特性（Anthropic computer use 等）"。除此之外，AI SDK 给你 "轻松切换、1/3 实现量、类型安全、React 集成"，优势压倒性。

个人立场先摆出来：AI SDK 真正的价值在于摆脱厂商锁定。OpenAI 涨价了？三行代码切到 Anthropic。Gemini 出新模型？同一处试一下。这一切都在 同一份代码里。正如 什么是 AI API 中讨论的，2026 年的现实是 "按任务用不同模型" 已成默认，而 AI SDK 把切换成本渐进逼向零。本文涵盖 AI SDK 是什么、为什么用、5 分钟快速上手、结构化输出、tool calling 与 agents、React 集成、provider 切换以及三个生产环境的坑——全部基于 2026 年 5 月的 AI SDK 6。

1. AI SDK 是什么——"OpenAI/Anthropic/Gemini 一个 API 通吃"

AI SDK 是 Vercel 出品的开源 TypeScript 库。GitHub: vercel/ai，许可证 Apache 2.0，截至 2026 年 5 月 月下载量超 2000 万。Vercel 出品，但 不需要 Vercel 才能跑——Cloudflare Workers、AWS Lambda、Deno、自建 Node.js、浏览器都行。

核心思路是 "切换 LLM provider 的适配层"。例如：

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

const { text } = await generateText({
  model: openai('gpt-5'),
  prompt: 'Tell me today\'s weather',
});

把它换成 Anthropic，只要改 3 行：

import { generateText } from 'ai';
import { anthropic } from '@ai-sdk/anthropic';  // ← 改了

const { text } = await generateText({
  model: anthropic('claude-opus-4-7'),  // ← 改了
  prompt: 'Tell me today\'s weather',
});

调用代码完全不变。这就是 "一个 API 适配所有 provider" 在实战中的含义。各家 provider 有自己的 消息格式、stop sequence、tool schema、system prompt 位置和响应 JSON 结构——而 AI SDK 把这些差异全部在底层吸收掉。

2. 为什么用 AI SDK——3 个实战理由

三个具体理由："轻松切换、1/3 实现量、类型安全。"

AI SDK 不合适的场景：① 当你需要在发布后立刻用上 provider 的最前沿特性（Anthropic computer use 等），而 AI SDK 还没来得及封装；② 当你只用 Python（AI SDK 仅限 TypeScript）；③ 当现有 OpenAI-SDK 代码库工作良好且没有重写理由。除此之外，2026 年的默认就是 AI SDK。

3. 5 分钟跑起来——从 generateText 到 streamText

最小配置 三步。在 Node.js / Next.js 上演示。

# 第 1 步：安装
npm install ai @ai-sdk/openai
# env: OPENAI_API_KEY=sk-...

# 第 2 步：建文件 (app/api/chat/route.ts 或 index.ts)

// 第 3 步：代码
import { generateText } from 'ai';
import { openai } from '@ai-sdk/openai';

const { text, usage } = await generateText({
  model: openai('gpt-5'),
  system: 'You are a careful, helpful assistant.',
  prompt: 'List three benefits of the AI SDK.',
});

console.log(text);
console.log(`tokens: ${usage.totalTokens}`);

这是 非流式、一次返回完整文本。运行后几秒响应就落到 text 里。usage 自动给你 token 数——省 token 一文 中的成本控制纪律可以直接套用。

切到 流式（打字机 UX）就 把函数名改成 streamText 就行：

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

const result = streamText({
  model: openai('gpt-5'),
  prompt: 'List three benefits of the AI SDK.',
});

for await (const chunk of result.textStream) {
  process.stdout.write(chunk);  // 一个 token 一个 token 输出
}

用裸 OpenAI SDK 你得手写 SSE 解析、chunk 拼接、流结束检测（30–50 行）。AI SDK 是 一个 for-await 循环。同一份代码原封不动地能跑 Anthropic 和 Gemini。

4. 结构化输出——用 generateObject 拿到类型安全的 JSON

叫 LLM "返回 JSON"，偶尔会拿到 包在 Markdown 代码块里、夹杂注释、或者结构悄悄变化 的东西。generateObject 从根本上解决：用 Zod schema 描述形状，AI SDK 自动处理 解析、校验和重试。

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

const { object } = await generateObject({
  model: openai('gpt-5'),
  schema: z.object({
    title: z.string(),
    tags: z.array(z.string()).max(5),
    sentiment: z.enum(['positive', 'neutral', 'negative']),
    summary: z.string().max(200),
  }),
  prompt: 'Analyze the article: "AI SDK 6 has..." [body]',
});

// object.title、object.tags 等都是类型化的
console.log(object.tags);  // string[]

真正的好处："object 的类型由 `z.infer<typeof schema>` 决定。" TypeScript 自动推断，所以在 IDE 里输入 object. 时，会自动补全 title / tags / sentiment / summary。运行时校验在 SDK 内部进行——违反 schema 会触发自动重试。"AI 返回了坏 JSON、解析失败" 这一类故障基本消失。

5. Tool calling 与 Agents——AI SDK 6 的核心

2026 年 AI 开发的前沿是 "调用工具的 Agent"，AI SDK 6 最大的跃迁就在这里。用 tools 和 stopWhen，你可以直接写 "调用工具 → AI 决策 → 调用下一个工具" 的循环。

import { generateText, tool, stepCountIs } from 'ai';
import { anthropic } from '@ai-sdk/anthropic';
import { z } from 'zod';

const { text, steps } = await generateText({
  model: anthropic('claude-opus-4-7'),
  tools: {
    weather: tool({
      description: 'Get the weather for a city',
      inputSchema: z.object({ city: z.string() }),
      execute: async ({ city }) => {
        // 真实 API 调用
        return { temp: 22, condition: 'sunny' };
      },
    }),
    convertToFahrenheit: tool({
      description: 'Convert Celsius to Fahrenheit',
      inputSchema: z.object({ celsius: z.number() }),
      execute: async ({ celsius }) => celsius * 9/5 + 32,
    }),
  },
  stopWhen: stepCountIs(5),  // 循环最多 5 步
  prompt: 'What is the weather in Tokyo, in Fahrenheit?',
});

AI 现在 自主排出 "weather('Tokyo') → convertToFahrenheit(22)" 的顺序，依次执行并整合结果。steps 暴露每一步的执行历史。

AI SDK 6 还提供 ToolLoopAgent 类，面向对象风格（等价于 generateText + stopWhen）。它增加了 工具执行审批（人类在工具运行前确认）和 完整的 MCP（Model Context Protocol）集成。接入 MCP 服务器（见 什么是 MCP）在 2026 年 5 月只要 三行代码。

6. React 集成——用 useChat 10 行写聊天 UI

AI SDK 的 另一颗明星 是 React Hooks。用 useChat，类 ChatGPT 的 UI 就 10 行代码。

'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.role}: {m.content}</div>
      ))}
      <form onSubmit={handleSubmit}>
        <input value={input} onChange={handleInputChange} />
      </form>
    </div>
  );
}

服务端（Next.js API Route）：

// app/api/chat/route.ts
import { streamText, convertToModelMessages } from 'ai';
import { openai } from '@ai-sdk/openai';

export async function POST(req: Request) {
  const { messages } = await req.json();
  const result = streamText({
    model: openai('gpt-5'),
    messages: convertToModelMessages(messages),
  });
  return result.toUIMessageStreamResponse();
}

仅此就给你 SSE 连接、消息状态管理、loading 与错误处理——全部自动。AI SDK 6 的 useChat 还原生处理 工具审批 UI（用户点击批准 "这个工具该运行吗？"）。Vue（@ai-sdk/vue 的 useChat）、Svelte 和 Solid 的 hooks 也一并提供。

7. 切换 Provider——Claude ↔ GPT ↔ Gemini 3 行搞定

截至 2026 年 5 月，AI SDK 官方支持的主要 provider：

切换：一行 import + 一行 model。AI SDK 5 加入了 global provider 特性，可以用字符串 ID 指定模型（例如 'openai/gpt-5'）。把它和 LLM 知识截止日期对比 与 Claude vs ChatGPT 价格对比 配合，可以按 "成本、性能、地域要求" 自信地选模型。

8. 生产环境的 3 个坑

AI SDK 很方便，但每个团队上线后 都会撞到 3 个坑。事先知道能避免 80% 的事故。

再补一点：AI SDK 是 "LLM 适配器"，不是 "LLM 成本转售商"。各 provider 的 API key 是 你的责任，账单直接寄给你。如 什么是 AI API 中所讲，费用由 OpenAI/Anthropic/Google 直接计费。AI SDK 本身免费，你只为用到的 LLM 付费。

总结

"Web 应用怎么调 LLM？"——到 2026 年 5 月，这个设计决策已经收敛到 "AI SDK，没别的。" 月下载量 2000 万+，AI SDK 6 自带 Agents、MCP、tool approval、DevTools，从 同一份代码 就能调 OpenAI/Anthropic/Google/Mistral/xAI/本地 LLM。一次拿到三件事："摆脱厂商锁定"、"1/3 实现成本" 与 "类型安全的结构化输出"。

上手简单：① npm install ai @ai-sdk/openai，② 设置 API key，③ 一行 generateText({ model, prompt })。跑通后再叠加 streamText 做流式、generateObject 拿 JSON、tools 做 agent、useChat 做 UI。上生产前，先把 三个坑（provider 特性差异、流中断计费、类型推断爆炸） 印在脑子里。

相关阅读：什么是 AI API（基础）、AI 推荐 Vercel、什么是 MCP、省 token。

FAQ

Q. 必须部署在 Vercel 才能用吗？
A. 不必。AI SDK 是 纯 TypeScript 库——Cloudflare Workers、AWS Lambda、Deno、自建 Node.js 服务器、浏览器都能跑。"Vercel 出品" 不等于 "只能在 Vercel 上跑"。

Q. 收费吗？
A. AI SDK 本身 完全免费，MIT 风格许可证。成本只有 你调用的那个 LLM provider 的 API 用量（OpenAI/Anthropic 等）。SDK 不加任何溢价。

Q. 与 LangChain 或 LlamaIndex 的区别？
A. 角色不同。AI SDK 是 "为 Web 应用集成而优化的薄 LLM 调用适配器"。LangChain 是 "RAG 与 agent 工作流的全功能框架"。实战分工："TypeScript + Web UI 集成" → AI SDK；"Python + 复杂 agent 流水线" → LangChain。

Q. 从已有 OpenAI SDK 代码迁移难吗？
A. 简单的 openai.chat.completions.create 调用，大约 10 分钟 就能改完——换成 generateText 并传 messages。复杂特性（function calling、vision）需要少量格式转换，但官方文档自带迁移指南。

Q. 能跟本地 LLM（Ollama）一起用吗？
A. 能。@ai-sdk/openai-compatible 包让你能打到任意 OpenAI 兼容的 API endpoint——Ollama、LM Studio、vLLM、自建服务器都行。"本地 LLM 开发，云上发布" 的工作流就变成 改一个 baseURL 而已。