vercel-ai-sdk 项目解读
项目信息
项目名称：vercel/ai
项目描述：Vercel 推出的 TypeScript 生态 AI 应用开发工具包，为前端/全栈开发者提供统一的、跨 40+ AI 提供商的 API 接口。一句话概括：用一套 API 对接所有 AI 模型。
1. 项目概览
1.1 项目定位与核心价值
AI SDK 是 Vercel 推出的 TypeScript 生态 AI 应用开发工具包，为前端/全栈开发者提供统一的、跨 40+ AI 提供商的 API 接口。一句话概括：用一套 API 对接所有 AI 模型。
解决的核心痛点：
- AI 提供商 API 碎片化：不同 AI 服务（OpenAI、Anthropic、Google 等）拥有互不兼容的 API 设计和数据格式，AI SDK 通过统一的适配器模式抹平差异，做到"一次编写，多提供商切换"。
- 前端/全栈开发者接入 AI 门槛高：流式响应、提示词工程、工具调用、结构化输出等 AI 领域常见需求缺乏前端友好的封装。AI SDK 通过统一的适配器模式抹平差异，提供开箱即用的 React/Vue/Svelte hooks。
- AI 应用架构缺乏标准化：Agent 模式、工作流编排、UI 流式协议缺少业界统一方案。AI SDK 提供了从数据流到 UI 层的完整范式。
1.2 目标用户与使用场景
- 主要用户：使用 TypeScript/JavaScript 技术栈构建 AI 功能的全栈开发者和前端开发者。
- 核心场景：AI 聊天助手、结构化数据提取、多模态应用、Agent 自动化工作流等。在 Next.js、Node.js、Express、Hono 等框架中快速集成 LLM 对话、结构化输出、图像/语音生成等 AI 能力。
- 典型代码量：从 API 调用到 UI 渲染，只需不到 20 行代码
typescript
// 服务端
import { generateText } from 'ai';
import { openai } from '@ai-sdk/openai';
const { text } = await generateText({ model: openai('gpt-5'), prompt: 'Hello' });
// 客户端
import { useChat } from '@ai-sdk/react';
const { messages, input, handleSubmit } = useChat();1.3 核心技术亮点
- 统一 Provider 接口：
LanguageModelV4定义了两个核心方法（doGenerate/doStream），40+ Provider 均实现此接口 - Provider 无关的工具调用循环：工具执行完全在核心层处理，Provider 只负责生成工具调用 JSON
- 可组合的中间件系统：通过
reduce().reverse()实现装饰器嵌套（M1(M2(M3(model)))） - 惰性流式执行：
streamText()返回惰性结果对象，按需消费不同类型的流 - 完整的 UI 协议：UIMessageStream 定义了前端与后端的标准通信协议
1.4 技术栈与选型对比
仓库规模：56 个包的 monorepo，3643+ TypeScript 文件，23 个示例项目。
核心技术栈清单
- 语言与运行时：TypeScript 5.8 + Node.js (18/20/22/24)
- 包管理与构建：pnpm 10 + Turborepo 2.4（monorepo 管理）
- 前端集成：React 19、Next.js 15、Vue、Svelte、Angular
- 测试框架：Vitest 4.1 + Playwright（E2E）
- 代码质量：oxlint + oxfmt（Rust 基 Linter/Formatter，替代 ESLint/Prettier）
- 版本管理：Changesets
- 类型系统：Zod 3 + Zod 4 双版本兼容
方案对比与权衡:
| 技术决策 | 选择方案 | 替代方案 | 权衡理由 |
|---|---|---|---|
| 语言与运行时 | TypeScript 5.8 + Node.js 18+ | JavaScript | 无 |
| 类型系统 | Zod 3 + Zod 4 双版本兼容 | 无 | TypeScript + Zod 提供了类型安全和数据验证功能 |
| 包管理与构建 | pnpm 10 + Turborepo | Nx, Lerna | 硬链接节省磁盘，Turborepo 增量构建更快 |
| 代码检查 | oxlint + oxfmt | ESLint + Prettier | Rust 实现，50-100x 速度提升 |
| 架构模式 | 适配器模式 | 直接集成 | 可扩展性强，社区可独立开发 Provider |
| 接口规范 | 独立 @ai-sdk/provider 包 | 内联接口 | 严格管控 Breaking Change |
| 体验特性 | Experimental_ 前缀 | Feature Flag | 编译时类型隔离，无运行时开销 |
2. 整体架构设计
2.1 架构概述
AI SDK 采用分层适配器架构（Layered Adapter Architecture），五层结构从下到上：
- 接口规范层（Spec Layer）：
@ai-sdk/provider— 定义所有模型类型的抽象接口（LanguageModelV4、EmbeddingModelV4 等），不含任何运行时逻辑. - 共享工具层（Utilities Layer）：
@ai-sdk/provider-utils— 提供 100+ 可复用的工具函数（HTTP 请求、JSON 解析、流处理、Schema 转换等）。 - Provider 实现层（Provider Layer）：40+ 独立的
@ai-sdk/<provider>包 — 每个包实现接口规范层定义的抽象接口，对接具体的 AI 服务 API。 - 核心 SDK 层（Core SDK Layer）：
ai— 提供面向开发者的高层 API（generateText、streamText、agent 等），负责提示词处理、工具调用循环、流控制等核心编排逻辑。 - 框架集成层（Framework Layer）：React/Vue/Svelte/Angular/RSC hooks 和组件
markdown
Framework (React/Vue/Svelte hooks) → Core SDK (generateText/streamText) →
Provider Utils (HTTP/JSON/Schema) → Provider Spec (LanguageModelV4) →
Provider Impl (OpenAI/Anthropic/Google...)2.2 整体架构图
text
+===========================================================================+
| 框架集成层 (Framework Layer) |
| +-------------+ +-------------+ +-------------+ +-------------------+ |
| | @ai-sdk/ | | @ai-sdk/ | | @ai-sdk/ | | @ai-sdk/rsc | |
| | react | | vue | | svelte | | (Server Comp.) | |
| | useChat() | | useChat() | | useChat() | | streamUI() | |
| +------+------+ +------+------+ +------+-------+ +--------+----------+ |
+=========+================+================+==================+=============+
| | | |
v v v v
+===========================================================================+
| 核心 SDK 层 (Core SDK Layer) |
| +---------------------------------------------------------------------+ |
| | ai (npm) | |
| | +------------+ +------------+ +------------+ +------------------+ | |
| | | generate- | | stream- | | agent/ | | embed/ | | |
| | | text | | text | | ToolLoop | | embedMany | | |
| | +-----+------+ +-----+------+ +-----+------+ +--------+---------+ | |
| | | | | | | |
| | +-----+------+ +-----+------+ +-----+------+ +--------+---------+ | |
| | | prompt/ | | text- | | generate- | | telemetry/ | | |
| | | (标准化) | | stream/ | | object | | middleware/ | | |
| | +------------+ +------------+ +------------+ +------------------+ | |
| +---------------------------------------------------------------------+ |
+==================================+==========================================+
|
v
+===========================================================================+
| 共享工具层 (Provider Utilities Layer) |
| +---------------------------------------------------------------------+ |
| | @ai-sdk/provider-utils | |
| | +-----------+ +-----------+ +-----------+ +-----------------------+ | |
| | | postToApi | | parseJSON | | Schema | | responseHandler | | |
| | | loadApiKey| | EventStr. | | (json/ | | (stream + non-stream) | | |
| | | fetch | | | | zod) | | | | |
| | +-----------+ +-----------+ +-----------+ +-----------------------+ | |
| +---------------------------------------------------------------------+ |
+==================================+==========================================+
|
v
+===========================================================================+
| 接口规范层 (Provider Spec Layer) |
| +---------------------------------------------------------------------+ |
| | @ai-sdk/provider | |
| | +--------------+ +--------------+ +--------------+ | |
| | | Language | | Embedding | | Image | ProviderV4 | |
| | | ModelV4 | | ModelV4 | | ModelV4 | (工厂接口) | |
| | +--------------+ +--------------+ +--------------+ | |
| | +--------------+ +--------------+ +--------------+ | |
| | | Speech | | Transcription| | Video | AISDKError | |
| | | ModelV4 | | ModelV4 | | ModelV4 | (错误基类) | |
| | +--------------+ +--------------+ +--------------+ | |
| +---------------------------------------------------------------------+ |
+==================================+==========================================+
|
v
+===========================================================================+
| Provider 实现层 (Provider Implementation) |
| +----------------+ +----------------+ +----------------+ |
| | @ai-sdk/ | | @ai-sdk/ | | @ai-sdk/ | ... 40+ |
| | openai | | anthropic | | google | providers |
| | | | | | | |
| | LanguageModel | | LanguageModel | | LanguageModel | |
| | EmbeddingModel | | SkillsV4 | | ImageModel | |
| | ImageModel | | FilesV4 | | VideoModel | |
| | SpeechModel | | Tools | | EmbeddingModel | |
| | Transcription | | | | Tools | |
| | FilesV4 | | | | | |
| | SkillsV4 | | | | | |
| +-------+--------+ +-------+--------+ +-------+--------+ |
+==========+==================+==================+===========================+
| | |
v v v
+----------+ +-----------+ +----------+
| OpenAI | | Anthropic | | Google |
| API | | API | | AI API |
+----------+ +-----------+ +----------+2.3 完整目录结构
shell
ai/
├── packages/ # 【核心基建】monorepo 包目录（56 个包）
│ ├── provider/ # 【核心基建】Provider 接口规范 (LanguageModelV4 等)
│ ├── provider-utils/ # 【核心基建】Provider 共享工具 (100+ 函数)
│ ├── ai/ # 【核心基建】核心 SDK (generateText/streamText/agent)
│ ├── openai/ # 【业务模块】OpenAI Provider
│ ├── anthropic/ # 【业务模块】Anthropic Provider
│ ├── google/ # 【业务模块】Google AI Provider
│ ├── ... (30+ 更多 Provider) # 【业务模块】文本/图像/语音/视频
│ ├── react/ # 【业务模块】React 集成
│ ├── rsc/ # 【业务模块】React Server Components
│ ├── vue/ # 【业务模块】Vue 集成
│ ├── svelte/ # 【业务模块】Svelte 集成
│ ├── workflow/ # 【业务模块】工作流引擎
│ ├── mcp/ # 【业务模块】MCP 协议支持
│ ├── otel/ # 【工具集】OpenTelemetry
│ └── codemod/ # 【工具集】迁移工具
├── examples/ # 【配置】示例项目（23 个）
├── content/ # 【配置】官方文档（MDX）
├── contributing/ # 【配置】贡献者指南 + ADR
├── package.json # 【配置】根配置
└── turbo.json # 【配置】Turborepo 任务编排2.4 最重要的文件
| 文件 | 为什么重要 |
|---|---|
packages/provider/src/language-model/v4/language-model-v4.ts | 最核心的接口定义——所有 Provider 都实现这个 |
packages/ai/src/generate-text/generate-text.ts | 核心文本生成引擎——工具调用循环在这里 |
packages/ai/src/generate-text/stream-text.ts | 流式文本生成——惰性执行 + TransformStream 管道 |
packages/openai/src/openai-provider.ts | Provider 实现的黄金标准——新增 Provider 的参考模板 |
packages/ai/src/middleware/wrap-language-model.ts | 中间件装饰器——reduce().reverse() 嵌套模式 |
packages/react/src/use-chat.ts | React 聊天 Hook——useSyncExternalStore 集成 |
2.5 核心设计模式速查表
| 模式 | 位置 | 说明 |
|---|---|---|
| 适配器模式 | 全部 Provider 包 | 各 AI 服务专有 API → 统一 LanguageModelV4 |
| 工厂模式 | createOpenAI 等 | 封装 Provider 实例创建和配置加载 |
| 模板方法 | generateText/Agent | 固定执行流程，策略参数化 |
| 装饰器 | Middleware (wrapLanguageModel) | reduce+reverse 嵌套包装 |
| 观察者 | 回调系统 (onStart/onFinish) | 生命周期钩子，支持遥测/日志 |
| 策略 | stopWhen / prepareStep | 可插拔的停止条件和步骤准备 |
| 服务定位器 | Registry | 字符串 ID → 模型实例查找 |
| 管道/过滤器 | streamText 管道 | TransformStream 链式处理 |
3. 模块依赖与调用关系
3.1 全局入口与核心路由
逻辑说明：
packages/ai/src/index.ts是核心 SDK 的统一入口，通过export *汇聚了所有子模块的公共 API。第三方 Provider 包通过packages/provider定义的接口与核心 SDK 解耦。- 开发者使用时只需
import { generateText } from 'ai'，核心层负责提示词标准化、模型解析、工具调用循环等编排逻辑，最终通过doGenerate/doStream调用具体 Provider 实现：调用generateText→ 提示词标准化 → 模型解析 → Provider 调用 → 工具循环 → 返回结果。
调用拓扑：
markdown
开发者代码
|
+---> import { generateText } from 'ai'
|
+---> generateText() [packages/ai/src/generate-text/]
|
+---> standardizePrompt() [packages/ai/src/prompt/]
| +---> convertToLanguageModelPrompt()
|
+---> resolveLanguageModel() [packages/ai/src/model/]
| +---> ProviderV4.languageModel()
| +---> OpenAIProvider.languageModel() [packages/openai/]
| +---> new OpenAIResponsesLanguageModel()
|
+---> prepareTools() [packages/ai/src/prompt/]
+---> doGenerate() [LanguageModelV4 接口]
| +---> OpenAI Responses API
|
+---> executeToolCall() [工具调用循环]
+---> GenerateTextResult3.2 核心业务实体与关联
实体定义：
- ProviderV4：AI 服务提供商的工厂接口，负责创建各种模型实例（languageModel、embeddingModel、imageModel 等）。
- LanguageModelV4：语言模型抽象，暴露
doGenerate（非流式）和doStream（流式）两个核心方法。 - ModelMessage：标准化的消息类型（system/user/assistant/tool），是所有 Provider 之间的通用数据交换格式。
- ToolSet：工具集合，定义模型可调用的工具及其输入/输出 Schema。
- UIMessage：UI 层的消息抽象，支持多部分内容（文本、工具调用、工具结果等）。
实体引用拓扑：
markdown
[ProviderV4] 1 ----> N [LanguageModelV4]
[ProviderV4] 1 ----> N [EmbeddingModelV4]
[ProviderV4] 1 ----> N [ImageModelV4]
[LanguageModelV4] 1 ----> N [ModelMessage]
[ModelMessage] 1 ----> N [ToolCallPart]
[ModelMessage] 1 ----> N [FilePart]
[generateText] 1 ----> 1 [LanguageModelV4]
[generateText] 1 ----> N [ToolSet]
[generateText] 1 ----> 1 [GenerateTextResult]
[useChat] 1 ----> 1 [AbstractChat]
[AbstractChat] 1 ----> N [UIMessage]4. 核心模块设计
4.1 text 生成核心 (generateText / streamText)
设计说明：文本生成是 AI SDK 最核心的功能，采用模板方法模式。
generateText和streamText共享相同的提示词标准化、模型解析、工具准备逻辑，但在结果返回方式上不同（非流式返回完整结果 vs 流式返回 AsyncIterableStream）。工具调用循环采用策略模式处理不同的停止条件（stepCount、hasToolCall、isLoopFinished）。内部结构图：
text
+------------------------------------------------------------------+
| generateText() |
| +---------------------------+ +-----------------------------+ |
| | Prompt 标准化 | | Model 解析 | |
| | standardizePrompt() | | resolveLanguageModel() | |
| | - system/user/assistant | | - 处理字符串 ID | |
| | - 多部分内容 (text/image) | | - 中间件包装 | |
| +------------+--------------+ +-------------+---------------+ |
| | | |
| v v |
| +------------------------------------------------------------+ |
| | prepareLanguageModelCallOptions() | |
| | - prepareTools() 工具 Schema 注入 | |
| | - prepareToolChoice() 工具选择策略 | |
| | - prepareRetries() 重试配置 | |
| +----------------------------+-------------------------------+ |
| | |
| v |
| +------------------------------------------------------------+ |
| | Tool Loop (工具调用循环) | |
| | +--------+ +--------+ +--------+ +--------+ | |
| | | Step 1 |->| Step 2 |->| Step 3 |->| Result | | |
| | | doGen | | tool | | doGen | | | | |
| | | | | exec | | | | | | |
| | +--------+ +--------+ +--------+ +--------+ | |
| | | |
| | Stop Conditions: stepCount / hasToolCall / isLoopFinished | |
| +------------------------------------------------------------+ |
| | |
| v |
| +------------------------------------------------------------+ |
| | GenerateTextResult { text, toolCalls, usage, steps, ... } | |
| +------------------------------------------------------------+ |
+------------------------------------------------------------------+关键设计细节：
- 工具调用循环完全 Provider 无关：Provider 只生成工具调用 JSON，后续的解析、审批、客户端执行全部在核心层
- 并行工具执行：
Promise.all(toolCalls.map(executeToolCall)) - 重试机制：
prepareRetries提供指数退避重试包装器 - 超时分层：totalTimeoutMs > stepTimeoutMs > toolTimeoutMs
4.2 Provider 适配器模式
设计说明：每个 Provider 包实现
ProviderV4接口，返回实现了LanguageModelV4等模型接口的实例。采用工厂模式：createOpenAI(options)创建 provider 实例，provider.languageModel('gpt-5')创建具体模型实例。Provider 配置通过环境变量和 options 参数双层加载（loadApiKey+loadOptionalSetting），支持 12-Factor App 规范。内部结构图：
text
+------------------------------------------------------------------+
| createOpenAI(options) |
| |
| 输入: OpenAIProviderSettings { |
| baseURL, apiKey, organization, project, headers, fetch, name |
| } |
| |
| +----------------------------+ +----------------------------+ |
| | loadApiKey() | | loadOptionalSetting() | |
| | - options.apiKey | | - options.baseURL | |
| | - env: OPENAI_API_KEY | | - env: OPENAI_BASE_URL | |
| +----------------------------+ +----------------------------+ |
| | | |
| v v |
| +------------------------------------------------------------+ |
| | getHeaders() | |
| | Authorization: Bearer <key> | |
| | OpenAI-Organization: <org> | |
| | User-Agent: ai-sdk/openai/<version> | |
| +------------------------------------------------------------+ |
| |
| 输出: OpenAIProvider (implements ProviderV4) { |
| languageModel() -> OpenAIResponsesLanguageModel |
| chat() -> OpenAIChatLanguageModel |
| completion() -> OpenAICompletionLanguageModel |
| embedding() -> OpenAIEmbeddingModel |
| image() -> OpenAIImageModel |
| speech() -> OpenAISpeechModel |
| transcription() -> OpenAITranscriptionModel |
| files() -> OpenAIFiles |
| skills() -> OpenAISkills |
| tools -> openaiTools (web_search, code_interpreter) |
| } |
+------------------------------------------------------------------+4.3 UI 消息流与框架集成（useChat / Chat）
设计说明：UI 层采用观察者模式。
AbstractChat是框架无关的聊天状态管理器，useChat（React）是对AbstractChat的 React 绑定（通过useSyncExternalStore订阅消息/状态/错误变更，SerialJobExecutor保证异步消息处理的串行性）。Chat组件封装了AbstractChat的初始化 ——AbstractChat（框架无关状态管理核心）→Chat<ReactChatState>（React 绑定）→useChat（用户 Hook）。消息格式遵循 UI Message Stream 协议，支持流式 UI 更新和工具调用交互。 。内部结构图：
text
+------------------------------------------------------------------+
| UI 消息流架构 |
| |
| +-----------------------------+ |
| | @ai-sdk/react | |
| | useChat() | React Hook 封装 |
| | useCompletion() | |
| | useObject() | |
| +-------------+---------------+ |
| | |
| v |
| +-----------------------------+ |
| | ai (AbstractChat) | 框架无关状态管理 |
| | - sendMessage() | |
| | - regenerate() | |
| | - addToolResult() | |
| | - addToolApprovalResponse()| |
| | - messages: UIMessage[] | |
| +-------------+---------------+ |
| | |
| v |
| +-----------------------------+ +------------------------+ |
| | createUIMessageStream | | UIMessageStream | |
| | Response() | --> | (AsyncIterable< | |
| | | | UIMessageChunk>) | |
| +-----------------------------+ +------------------------+ |
| | |
| v |
| +-----------------------------+ |
| | streamText() | 底层流式文本生成 |
| +-----------------------------+ |
+------------------------------------------------------------------+4.4 Agent 与工作流（ToolLoopAgent / Workflow）
设计说明：Agent 采用工具循环模式（Tool Loop Pattern）。ToolLoopAgent 通过系统提示词定义 Agent 角色，在循环中调用 LLM → 执行工具 → 反馈结果 → 继续调用 LLM，直到达到停止条件。Workflow 包提供更高级的工作流编排（序列化/反序列化、步骤编排），支持长时间运行的 Agent 任务。
ToolLoopAgent是轻量级 Agent 实现，委托给generateText/streamText。WorkflowAgent在此基础上增加了 durable execution（Vercel Workflow'use step'指令），支持跨进程重启的长时间 Agent 任务。内部结构图：
text
+------------------------------------------------------------------+
| ToolLoopAgent |
| |
| ToolLoopAgentSettings { |
| model, system, tools, maxSteps, stopWhen, prepareStep |
| } |
| |
| +--------------------+ |
| | Agent.call() | |
| | +--------------+ | |
| | | Step 1 | | |
| | | LLM call --->|--+---> Tool Execution ---> Tool Result |
| | +--------------+ | | |
| | ^ | | |
| | | | v |
| | +----------+-- (loop) <--------+ |
| | | |
| | Stop: maxSteps / | |
| | stopWhen() / | |
| | isLoopFinished() | |
| +--------------------+ |
| |
| 输出: AgentResult { |
| text, steps, usage, messages, warnings |
| } |
| |
| 流式: AgentStream { |
| fullStream: AsyncIterable<AgentStepEvent> |
| uiMessageStream: UIMessageStream |
| } |
+------------------------------------------------------------------+4.5 模型注册中心（Registry）
设计说明：Registry 提供服务定位器模式（Service Locator），允许开发者通过字符串 ID 引用模型而非直接引入 Provider 包。registry.set('openai:gpt-5', openai('gpt-5')) 注册模型，generateText({ model: 'openai:gpt-5' }) 通过 ID 使用。这使得模型配置可集中管理，便于 A/B 测试和模型切换。
4.6 中间件系统
设计说明：采用装饰器模式。中间件数组通过 .reverse().reduce() 形成嵌套包装链：M1(M2(M3(model)))。反转确保用户数组中第一个中间件成为最外层。提供三种钩子：transformParams（修改参数）、wrapGenerate（拦截非流式调用）、wrapStream（拦截流式调用）。
5. 关键数据流程
5.1 场景一：generateText 带工具调用的完整流程
场景说明：用户发起一次带工具的文本生成请求。AI SDK 先标准化 Prompt，解析模型，注入工具 Schema，然后进入工具调用循环：LLM → 返回工具调用 → 执行工具 → 将结果反馈给 LLM → 继续生成，直到模型返回纯文本或达到最大步数。
流转时序图：
5.2 streamText + useChat 前端流式对话
场景说明：React 前端使用
useChat+ 后端streamText实现流式对话。用户发送消息 → 前端 POST 到 API Route → 后端调用 streamText → 流式返回 UIMessageStream → 前端实时渲染。流转时序图 (Mermaid)：
6. 接口与契约规范
6.1 核心内部模块契约 (TypeScript)
typescript
/**
* Provider 工厂接口 - 所有 Provider 包的核心契约
*/
export interface ProviderV4 {
readonly specificationVersion: 'v4';
languageModel(modelId: string): LanguageModelV4;
embeddingModel(modelId: string): EmbeddingModelV4;
imageModel?(modelId: string): ImageModelV4;
speechModel?(modelId: string): SpeechModelV4;
transcriptionModel?(modelId: string): TranscriptionModelV4;
videoModel?(modelId: string): VideoModelV4;
files?(): FilesV4;
skills?(): SkillsV4;
}
/**
* 语言模型接口 - 最核心的模型规范
* 只暴露 doGenerate 和 doStream（do 前缀防止用户直接调用）
*/
export interface LanguageModelV4 {
readonly specificationVersion: 'v4';
readonly provider: string;
readonly modelId: string;
readonly supportedUrls: PromiseLike<Record<string, RegExp[]>>;
doGenerate(
options: LanguageModelV4CallOptions
): PromiseLike<LanguageModelV4GenerateResult>;
doStream(
options: LanguageModelV4CallOptions
): PromiseLike<LanguageModelV4StreamResult>;
}
/**
* 语言模型调用选项 - 标准化的输入契约
*/
export interface LanguageModelV4CallOptions {
mode: { type: 'regular' } | { type: 'object-json' } | { type: 'object-tool' };
inputFormat: 'messages' | 'prompt';
prompt: ModelMessage[];
tools?: ToolSet;
toolChoice?: ToolChoice;
temperature?: number;
maxTokens?: number;
stopSequences?: string[];
headers?: Record<string, string>;
abortSignal?: AbortSignal;
providerOptions?: Record<string, Record<string, unknown>>;
}
/**
* Schema 转换工具 - 统一 Zod/JSON Schema 的适配器
*/
export interface Schema<INPUT = unknown, OUTPUT = unknown> {
readonly _type: INPUT;
readonly _output: OUTPUT;
validate(value: unknown): ValidationResult<OUTPUT>;
jsonSchema(): JSONSchema7;
}
/**
* 聊天状态管理 - UI 层的核心契约
*/
export interface AbstractChat<UI_MESSAGE extends UIMessage> {
readonly id: string;
readonly status: 'ready' | 'submitted' | 'streaming' | 'error';
readonly messages: UI_MESSAGE[];
readonly error: Error | undefined;
sendMessage(message: string): void;
regenerate(messageId: string): void;
stop(): void;
addToolResult(result: { toolCallId: string; result: unknown }): void;
}6.2 公共 API 契约
typescript
/**
* 文本生成 - AI SDK 最核心的公共 API
*/
export async function generateText<
TOOLS extends ToolSet = undefined,
OUTPUT extends Output = Output<InferCompleteOutput<InferToolSetContext<TOOLS>>>,
>(options: {
model: LanguageModel;
tools?: TOOLS;
toolChoice?: ToolChoice<TOOLS>;
system?: string;
prompt?: Prompt;
messages?: ModelMessage[];
maxSteps?: number;
temperature?: number;
maxTokens?: number;
stopWhen?: StopCondition;
output?: OUTPUT;
onStart?: GenerateTextOnStartCallback;
onStepStart?: GenerateTextOnStepStartCallback<TOOLS>;
onStepFinish?: GenerateTextOnStepFinishCallback<TOOLS>;
onFinish?: GenerateTextOnFinishCallback<TOOLS>;
experimental_telemetry?: TelemetryOptions;
// ... more options
}): Promise<GenerateTextResult<TOOLS, OUTPUT>>;
/**
* 流式文本生成
*/
export function streamText<
TOOLS extends ToolSet = undefined,
OUTPUT extends Output = Output<InferCompleteOutput<InferToolSetContext<TOOLS>>>,
>(options: { /* similar to generateText */ }): Promise<StreamTextResult<TOOLS, OUTPUT>>;
/**
* React Hook - 聊天
*/
export function useChat<UI_MESSAGE extends UIMessage = UIMessage>(
options: UseChatOptions<UI_MESSAGE>
): UseChatHelpers<UI_MESSAGE>;7. Provider 工具系统
每个 Provider 可以定义自己的内置工具（Provider-Defined Tools）。例如 OpenAI 的 web_search、code_interpreter，Anthropic 的 bash、text_editor、web_search 等。这些工具通过 tools 属性暴露：
typescript
// OpenAI provider-defined tools
export const openaiTools = {
webSearch: createProviderDefinedToolFactory({ name: 'web_search' }),
codeInterpreter: createProviderDefinedToolFactory({ name: 'code_interpreter' }),
// ...
};
// Usage
const result = await generateText({
model: openai('gpt-5'),
tools: {
webSearch: openai.tools.webSearch(),
myCustomTool: tool({ ... }),
},
});8. 快速开始
8.1 环境要求
- Node.js 18/20/22/24
- pnpm 10+
8.2 安装与运行
bash
pnpm install # 安装依赖
pnpm build # 构建所有包
pnpm test # 运行所有测试
pnpm check # 代码检查
pnpm fix # 自动修复格式问题8.3 关键目录
| 目录 | 用途 | 关键文件数 |
|---|---|---|
packages/ai/src/ | 核心 SDK | ~418 |
packages/provider/src/ | Provider 接口规范 | ~211 |
packages/provider-utils/src/ | Provider 共享工具 | ~201 |
packages/openai/src/ | OpenAI Provider | ~144 |
packages/react/src/ | React 集成 | ~12 |
content/docs/ | 官方文档 | MDX |