Vercel AI SDK 详解：TypeScript 全栈 AI 应用工具包
在 TypeScript 里接大模型，最怕的是换一家供应商就重写一遍调用代码、流式解析、UI 状态管理。vercel/ai（AI SDK）把这层麻烦全部抽掉：Vercel 与 Next.js 团队出品的供应商无关 TypeScript 工具包，一套 API 通吃 OpenAI、Anthropic、Google 等主流模型商，配 React、Svelte、Vue、Angular hooks 与 Node.js 运行时，从生成文本、结构化输出到 Agent 与聊天 UI 一站覆盖。本文从核心架构、四大能力、UI 集成到上手实践，完整拆解。
1、项目概述
AI SDK 定位为 provider-agnostic TypeScript toolkit：以统一 API 屏蔽各家模型差异，模型只变成一个字符串或一个 provider 实例。由 Vercel 与 Next.js 团队核心成员打造，开源社区共建，配套完整文档站 ai-sdk.dev 与官方模板生态。
基本形态与生态：
- 环境：Node.js 22+，npm install ai 一条命令起步
- 默认走 Vercel AI Gateway：传模型字符串即可访问所有主流供应商
- 可直连：装 @ai-sdk/openai 等官方 provider 包绕开网关
- 编码 Agent 支持：npx skills add vercel/ai 一条命令装官方技能
- 社区：Vercel Community 的 AI SDK 板块
2、四大核心能力
AI SDK 的能力可以归成四根支柱，覆盖 AI 应用从后端到前端的完整链路。
四根支柱：
- 统一 Provider 架构：一套 API 对接 OpenAI、Anthropic、Google 等所有主流模型商
- 文本与结构化生成：generateText / streamText，配合 zod schema 输出可靠结构化数据
- Agent 构建：ToolLoopAgent 等开箱代理，工具循环、系统提示一应俱全
- AI SDK UI：框架无关 hooks（useChat 等），聊天与生成式 UI 快速搭建
能力要点：
1. 模型即字符串：anthropic/claude-opus-4.6、openai/gpt-5.4 直接传参，换商零改造
2. TypeScript 全链路类型安全，从 schema 到 UI 消息类型推导
3. 官方模板覆盖不同用途、供应商与框架组合
3、统一 Provider 架构
两种接模型的方式：默认网关字符串，或直连 provider 包。
// 方式一：Vercel AI Gateway（默认，免装各家 SDK）
import { generateText } from 'ai';
const { text } = await generateText({
model: 'anthropic/claude-opus-4.6', // 或 'openai/gpt-5.4'
prompt: 'Hello!', // 'google/gemini-3-flash' 等
});
// 方式二：直连 provider 包（绕开网关）
// npm install @ai-sdk/openai @ai-sdk/anthropic @ai-sdk/google
import { anthropic } from '@ai-sdk/anthropic';
const result = await generateText({
model: anthropic('claude-opus-4-6'),
prompt: 'Hello!',
});架构要点：
1. 网关模式开箱即用，所有主流供应商一个入口
2. 直连模式用各 provider 函数，密钥与计费走自家账户
3. 两种方式 API 完全一致，切换只改 model 参数
4、结构化输出与 Agent
zod schema 约束输出、工具循环组装 Agent，是后端两大高频场景。
// 结构化输出：Output.object + zod，JSON 可靠落库
import { generateText, Output } from 'ai';
import { z } from 'zod';
const { output } = await generateText({
model: 'openai/gpt-5.4',
output: Output.object({
schema: z.object({
recipe: z.object({
name: z.string(),
ingredients: z.array(
z.object({ name: z.string(), amount: z.string() }),
),
steps: z.array(z.string()),
}),
}),
}),
prompt: 'Generate a lasagna recipe.',
});
// Agent：ToolLoopAgent + 工具定义
import { ToolLoopAgent } from 'ai';
const sandboxAgent = new ToolLoopAgent({
model: 'openai/gpt-5.4',
system: 'You are an agent with access to a shell environment.',
tools: {
shell: openai.tools.localShell({
execute: async ({ action }) => {
const [cmd, ...args] = action.command;
const sandbox = await getSandbox(); // Vercel Sandbox
const command = await sandbox.runCommand({ cmd, args });
return { output: await command.stdout() };
},
}),
},
});后端要点：
1. 结构化输出由 schema 保证类型，省去手写解析与校验
2. Agent 用类实例声明：model + system + tools 三要素
3. 工具 execute 内可对接 Vercel Sandbox 等执行环境
5、AI SDK UI：聊天与生成式 UI
前端侧用框架无关 hooks 组装聊天界面，工具调用可渲染成自定义组件。
// Agent 定义（可共享给前后端）
export const imageGenerationAgent = new ToolLoopAgent({
model: 'openai/gpt-5.4',
tools: { generateImage: openai.tools.imageGeneration({ partialImages: 3 }) },
});
export type Message = InferAgentUIMessage<typeof imageGenerationAgent>;
// Next.js 路由：三行接通流式响应
import { createAgentUIStreamResponse } from 'ai';
export async function POST(req: Request) {
const { messages } = await req.json();
return createAgentUIStreamResponse({
agent: imageGenerationAgent, messages,
});
}
// React 页面：useChat + parts 渲染
import { useChat } from '@ai-sdk/react'; // npm install @ai-sdk/react
export default function Page() {
const { messages, status, sendMessage } = useChat<Message>();
return (
<div>
{messages.map(message => (
<div key={message.id}>
{message.parts.map((part, index) => {
switch (part.type) {
case 'text':
return <div key={index}>{part.text}</div>;
case 'tool-generateImage':
return <ImageGenerationView key={index} invocation={part} />;
}
})}
</div>
))}
</div>
);
}UI 要点：
1. hooks 框架无关：React / Svelte / Vue / Angular 各有对应包
2. InferAgentUIMessage 从 Agent 定义推导消息类型，前后端同源
3. parts 模型把文本、工具调用、图片统一为消息片段，渲染分支清晰
4. 工具组件按 invocation.state 区分加载中与完成态
6、典型应用场景
凡是 TypeScript 技术栈要接大模型的应用，都在射程之内。
常见场景：
- 聊天助手：useChat + 流式响应，半天出可用原型
- 生成式 UI：工具调用直接渲染组件，而非纯文本回复
- 数据抽取：zod schema 约束，抽取结果直接入业务库
- 多供应商应用：一套代码，模型按场景/成本动态切换
- Agent 产品：工具循环 + 沙箱执行，跑自动化任务
使用提醒：
1. 默认网关路径经过 Vercel，数据敏感场景评估合规或走直连
2. Node 22+ 起步，老项目先升运行时再接 SDK
3. 用 Claude Code / Cursor 的团队，先装官方技能再开发
7、定位对比：TypeScript AI 方案三选一
把 AI SDK、LangChain.js 与各家原生 SDK 放在一张桌上，各自的位置清晰起来。
三者对比：
- AI SDK：TS 原生、前后端一体、统一 Provider，Vercel 生态加持
- LangChain.js：组件与链最丰富，但抽象层厚、TS 体验偏移植
- 原生 SDK（openai 等）：功能最新最全，但绑死单一供应商
选型建议：
1. Next.js / React 全栈应用 → AI SDK 顺水推舟
2. 复杂链式编排、重度 RAG 管线 → LangChain.js
3. 深度绑定单一供应商的专有功能 → 原生 SDK
4. 组合玩法：AI SDK 做应用层与 UI，专有能力按需补原生 SDK
8、总结
AI SDK 是 Vercel 与 Next.js 团队打造的 TypeScript AI 工具包：统一 Provider 架构一套 API 通吃主流模型商（网关字符串或直连 provider 包），generateText + zod 保证结构化输出，ToolLoopAgent 声明式构建代理，AI SDK UI 用框架无关 hooks 把聊天与生成式 UI 做到几行代码级；Node 22+ 起步，配套 ai-sdk.dev 文档、官方模板与编码 Agent 技能（npx skills add vercel/ai），Vercel Community 承载社区。
上手路径：新项目 npm install ai 起步，先用网关字符串跑通 generateText，再按需切直连；聊天场景直接上 useChat + createAgentUIStreamResponse 三行流式骨架；用 InferAgentUIMessage 让前后端消息类型同源，避免手写接口；数据敏感或成本敏感时，网关与直连的路由策略需要单独评估。
