Vercel AI SDK 深度解析

王小酱
0 阅读5分钟

这是一个由 Vercel（Next.js 的创造者）打造的 TypeScript AI 应用开发工具包，⭐ 已超过 23,000 星。下面我从多个维度帮你彻底搞清楚这个项目。

github.com/vercel/ai

一、项目定位与核心价值

这个 SDK 解决的核心痛点是：AI 模型提供商（OpenAI、Anthropic、Google 等）各有一套 API，开发者需要为每个服务写不同的对接代码。AI SDK 提供了一套统一的抽象层，让你写一次代码，可以无缝切换任意模型提供商。

它面向的场景：

  • 构建聊天机器人、AI 助手
  • 生成结构化数据（JSON）
  • 构建可自主执行任务的 Agent（智能体）
  • 在 Next.js / React / Svelte / Vue / Angular 等框架中集成 AI 功能

二、仓库整体结构

这是一个 pnpm monorepo，用 Turborepo 管理构建，主要目录如下：

vercel/ai
├── packages/          ← 所有 NPM 包（核心）
├── examples/          ← 各框架完整示例项目
├── architecture/      ← 架构设计文档
├── contributing/      ← 贡献者详细指南
├── content/           ← 官方文档内容源文件
├── skills/            ← AI Coding Agent 技能定义
└── tools/             ← 内部工具脚本

技术栈： TypeScript + pnpm 10 + Node.js 22 + Turborepo + oxlint/oxfmt（代码规范）

三、packages/ 目录详解（最重要的部分）

共 56 个包，按职责分为以下几类：

1. 核心包（必须掌握）

包名作用
ai（packages/ai）主包，所有核心 API 入口：generateText、streamText、generateObject、ToolLoopAgent 等
@ai-sdk/provider定义所有模型接口规范（LanguageModelV4、EmbeddingModelV4 等）
@ai-sdk/provider-utils提供商开发工具库，处理流解析、错误处理、类型转换等

2. 模型提供商包（按需安装）

包括 @ai-sdk/openai、@ai-sdk/anthropic、@ai-sdk/google、@ai-sdk/azure、@ai-sdk/deepseek、@ai-sdk/groq 等共 约 40 个，覆盖几乎所有主流 AI 服务。

3. UI 框架集成包

包名对应框架
@ai-sdk/reactReact / Next.js（最成熟）
@ai-sdk/svelteSvelteKit
@ai-sdk/vueVue / Nuxt
@ai-sdk/angularAngular
@ai-sdk/rscReact Server Components（实验性）

4. 扩展能力包

  • @ai-sdk/mcp：Model Context Protocol 支持（与 MCP Server 对接）
  • @ai-sdk/workflow：新增的 WorkflowAgent，用于有状态的多步骤任务
  • @ai-sdk/otel：OpenTelemetry 可观测性支持
  • @ai-sdk/valibot：用 Valibot（替代 Zod）做结构化输出验证
  • @ai-sdk/langchain / @ai-sdk/llamaindex：与这两个 AI 框架互通的适配器
  • @ai-sdk/devtools：开发调试工具
  • @ai-sdk/gateway：统一网关，通过 Vercel AI Gateway 访问所有提供商

四、核心架构设计（两个关键概念）

1. Provider 抽象层（三层结构）

你写的代码（generateText 等 AI 函数）
        ↕ 依赖
模型规范接口（LanguageModelV4 等 Interface）
        ↕ 实现
具体提供商实现（OpenAIChatLanguageModel、AnthropicMessagesLanguageModel 等）

这种设计让你换模型只需改一行代码。支持的模型类型有：

  • LanguageModelV4 → 文本生成（generateText、streamText）
  • EmbeddingModelV4 → 向量嵌入（embed、embedMany）
  • ImageModelV4 → 图像生成（generateImage）
  • SpeechModelV4 → 语音合成（generateSpeech）
  • TranscriptionModelV4 → 语音转文字（transcribe）
  • VideoModelV4 → 视频生成（generateVideo）
  • RerankingModelV4 → 文档重排序（rerank）

2. 四层消息架构

UI Messages        → 含 parts 字段，专为 UI 渲染设计
      ↕
Model Messages     → 对开发者友好的抽象，用于 generateText/streamText 入参
      ↕
Language Model Messages → 稳定的规范层（LanguageModelV4 协议）
      ↕
Provider Messages  → 最终转换为各提供商的具体 API 格式

理解这四层对调试消息传递问题非常关键。

五、三大核心功能模块

AI SDK Core（后端/服务端）

import { generateText, streamText, generateObject } from 'ai';

// 生成文本
const { text } = await generateText({ model: 'openai/gpt-4o', prompt: '...' });

// 流式输出
const result = streamText({ model: 'anthropic/claude-opus-4', prompt: '...' });

// 生成结构化 JSON（配合 Zod）
const { object } = await generateObject({ model: '...', schema: z.object({...}), prompt: '...' });

AI SDK UI（前端 Hooks）

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

// 聊天 Hook（自动处理流式响应、消息历史、状态管理）
const { messages, input, handleSubmit, status } = useChat({ api: '/api/chat' });

AI SDK Agents（智能体）

import { ToolLoopAgent } from 'ai';

// 自动循环调用工具直到任务完成
const agent = new ToolLoopAgent({ model: '...', tools: { ... } });

六、22 个官方示例项目

examples/ 目录提供了完整的可运行项目，覆盖：

  • ai-functions：纯 Node.js 环境下的所有核心 API 用法（最佳入门示例）
  • next：Next.js App Router 完整聊天应用
  • next-agent：Agent 智能体示例
  • next-workflow：WorkflowAgent 多步骤任务示例
  • next-openai-telemetry：接入 OpenTelemetry 监控
  • sveltekit-openai / nuxt-openai / angular：各框架集成
  • express / fastify / hono / nest：各 Node.js 服务端框架
  • mcp：MCP 协议集成
  • next-langchain：与 LangChain 结合使用

七、学习路线建议

第一阶段：快速上手（1-2天）

  1. 阅读 packages/ai 的 README（主包）
  2. 跑通 examples/ai-functions 中的例子（需要一个 API Key）
  3. 掌握 generateText、streamText、generateObject 三个核心函数

第二阶段：理解架构（3-5天）

  1. 精读 architecture/ 下的 4 篇设计文档，特别是 provider-abstraction.md 和 message-layers.md
  2. 看 packages/provider/src/ 下的接口定义（LanguageModelV4）
  3. 跑通 examples/next 理解前后端如何配合

第三阶段：深入进阶（1-2周）

  1. 学习 @ai-sdk/react 中 useChat 的源码，理解流式响应是如何工作的
  2. 研究 ToolLoopAgent 的实现，理解 Agent 循环机制
  3. 看 @ai-sdk/openai 提供商实现，学会如何自己写一个 Provider
  4. 探索 @ai-sdk/workflow 和 @ai-sdk/mcp 这两个新能力

第四阶段：实战贡献

  1. 按 CONTRIBUTING.md，用 pnpm + Node 22 搭建本地环境
  2. 从 Good First Issue 入手，尝试提交 PR

八、值得特别关注的新特性（近期动态）

从 commit 历史来看，这个项目非常活跃（每天都有更新），近期重点：

  • WorkflowAgent（@ai-sdk/workflow）：用于构建持久化、有状态的工作流智能体
  • ToolLoopAgent 替代了早期的 Agent 模式，更简洁
  • toolApproval（Human-in-the-loop）：人工审批工具调用的机制
  • OTel 步骤级 Span：更细粒度的可观测性支持
  • provider-defined vs provider-executed tools 的区分

这个项目是目前 TypeScript 生态中最完整、最生产就绪的 AI 开发工具包，非常值得深入学习！

avatar
文章
阅读
粉丝