Vercel AI SDK

一、Vercel AI SDK 的核心功能有哪些？

1. 统一的模型调用接口

• AI SDK 提供 generateText 和 streamText 两个核心函数，开发者使用相同的代码即可切换不同模型提供商
• 支持通过字符串形式指定模型，如 openai/gpt-5.5、anthropic/claude-sonnet-4-6，无需安装各提供商的独立 SDK
• 内置模型回退机制，当主模型不可用时可自动切换到备用模型

2. 流式响应处理

• streamText 函数支持逐 token 输出，实现实时打字机效果
• 提供 textStream、dataStream 等多种消费方式，适配不同 UI 框架
• 内置流式错误处理和自动重连能力

3. 结构化数据输出

• generateObject 函数支持基于 Zod Schema 生成类型安全的结构化数据
• 模型返回的对象自动通过 Schema 校验，确保数据格式符合预期
• 适用于数据提取、表单填充、API 响应生成等场景

4. 工具调用能力

• 通过 tool 函数定义可被模型调用的外部工具
• 支持参数校验、异步执行、结果回传完整流程
• 模型可自主决定何时调用工具、调用哪个工具

5. 多模态内容生成

• 支持文本、图像、视频、语音等多种模态的生成与处理
• generateImage 支持文生图，generateSpeech 支持文本转语音
• v7 版本新增实验性实时语音和视频生成 API

6. AI Agent 构建

• 提供 ToolLoopAgent 类实现自主多步推理的 Agent
• 支持工具审批、运行时上下文、持久化执行等生产级特性
• 可集成 Claude Code、Codex、OpenCode 等外部 Agent 框架

二、Vercel AI SDK 的 generateText 和 streamText 有什么区别？

1. 返回值类型不同

• generateText 返回完整的生成结果对象，包含 text、toolCalls、usage 等属性
• streamText 返回流式结果对象，包含 textStream、dataStream、fullStream 等可迭代流

2. 适用场景不同

• generateText 适用于需要完整结果的场景，如后台任务处理、数据提取、批量生成
• streamText 适用于需要实时反馈的场景，如聊天对话、长文本生成、进度展示

3. 消费方式不同

• generateText 的结果通过 await 一次性获取，代码结构更简洁
• streamText 的结果通过 for await 循环逐块消费，需要处理流式生命周期

4. 错误处理机制不同

• generateText 的错误在 await 时抛出，可用 try-catch 捕获
• streamText 的错误可能在流式过程中异步抛出，需要在消费循环中处理

三、如何使用 Vercel AI SDK 实现流式文本输出？

1. 基础流式调用

import { streamText } from 'ai';

const result = streamText({
  model: 'openai/gpt-5.5',
  prompt: '写一个关于机器人的短篇故事',
});

for await (const textPart of result.textStream) {
  process.stdout.write(textPart);
}

2. 在 Next.js 中使用

• 创建 API 路由处理流式响应
• 使用 result.toDataStreamResponse() 生成可被前端消费的响应
• 前端通过 useChat Hook 自动处理流式更新

3. 流式结果的结构

• textStream：纯文本 token 流，适合简单展示
• dataStream：包含元数据的数据流，可携带工具调用信息
• fullStream：完整事件流，包含开始、增量、结束等所有事件

4. 错误处理与中断

• 在 for await 循环中使用 try-catch 捕获流式错误
• 通过 AbortController 支持用户主动中断生成
• 流式过程中发生错误时，已输出的内容不会丢失

四、Vercel AI SDK 如何实现结构化数据输出？

1. 使用 generateObject

import { generateObject } from 'ai';
import { z } from 'zod';

const { object } = await generateObject({
  model: 'anthropic/claude-sonnet-4-6',
  schema: z.object({
    name: z.string(),
    age: z.number(),
    city: z.string(),
  }),
  prompt: '提取信息：张三今年 25 岁，住在北京',
});

console.log(object); // { name: '张三', age: 25, city: '北京' }

2. Schema 定义规范

• 使用 Zod 库定义数据结构，支持字符串、数字、布尔、数组、对象等类型
• 支持嵌套结构和复杂类型，如联合类型、枚举、日期等
• Schema 会自动转换为 JSON Schema 传递给模型

3. 类型安全保障

• 返回的 object 自动通过 TypeScript 类型推断
• 运行时通过 Zod 校验确保数据符合 Schema 定义
• 校验失败时抛出明确错误，便于定位问题

4. 适用场景

• 从非结构化文本中提取结构化信息
• 生成符合特定格式的 API 响应
• 填充表单或数据库记录
• 构建类型安全的 Agent 工具输出

五、Vercel AI SDK 的 Tool Calling 功能如何使用？

1. 定义工具

import { generateText, tool } from 'ai';
import { z } from 'zod';

const result = await generateText({
  model: 'openai/gpt-5.5',
  tools: {
    getWeather: tool({
      description: '获取指定城市的当前天气',
      parameters: z.object({
        city: z.string().describe('城市名称，如"北京"'),
      }),
      execute: async ({ city }) => {
        // 调用天气 API
        return { city, temperature: 25, condition: '晴' };
      },
    }),
  },
  prompt: '北京今天天气怎么样？',
});

console.log(result.toolResults); // 包含工具调用结果

2. 工具执行流程

• 模型分析用户输入，决定是否调用工具
• 若需调用，模型生成工具名称和参数
• SDK 执行工具函数，将结果回传给模型
• 模型基于工具结果生成最终回复

3. 工具上下文（v7 新增）

• 通过 contextSchema 为工具定义专属上下文结构
• 通过 toolsContext 传入每个工具所需的配置（如 API Key）
• 上下文作用域限定在单个工具内，防止第三方工具越权访问

4. 工具审批机制

• 支持配置工具执行前的审批策略
• 可选模式：自动批准、自动拒绝、用户确认、自定义函数
• v7 版本支持 HMAC 签名审批，防止参数篡改

六、Vercel AI SDK 如何实现多模态内容生成？

1. 图像生成

• 使用 generateImage 函数实现文生图
• 支持 OpenAI DALL-E、Google Imagen 等模型
• 返回图像 URL 或 Base64 编码数据

2. 语音合成

• generateSpeech 函数支持文本转语音（v7 已稳定）
• 支持 OpenAI、Google、xAI 等提供商的语音模型
• 可配置语速、音调、音色等参数

3. 语音转录

• transcribe 函数支持语音转文本（v7 已稳定）
• 支持上传音频文件进行转录
• 适用于会议记录、语音输入等场景

4. 视频生成（实验性）

• v7 版本新增实验性视频生成 API
• 支持 OpenAI、Google 等提供商的视频模型
• API 设计可能在未来版本调整

5. 文件处理

• uploadFile 函数支持上传文件到模型提供商
• 返回轻量级引用对象，避免重复上传
• 适用于 PDF、图片、数据集等大文件处理场景

七、Vercel AI SDK 支持哪些前端框架？

1. React 与 Next.js

• 提供 @ai-sdk/react 包，包含 useChat、useCompletion 等 Hook
• useChat 自动处理流式消息更新、工具调用 UI、错误状态
• Next.js 项目可直接集成，支持 App Router 和 Pages Router

2. Vue

• 提供 @ai-sdk/vue 包，包含对应的 Composable 函数
• 支持响应式数据绑定和自动更新
• v7 版本对 Vue 支持进行了重构优化

3. Svelte

• 提供 @ai-sdk/svelte 包
• 遵循 Svelte 的响应式编程模型
• 支持 runes 语法（Svelte 5）

4. 框架无关的 UI 组件

• 提供 AI Elements 组件库，可适配任意前端框架
• 包含消息气泡、输入框、加载动画等常用聊天 UI 组件
• 支持自定义样式和交互行为

八、如何在 Next.js 项目中使用 Vercel AI SDK？

1. 安装依赖

npm install ai @ai-sdk/openai @ai-sdk/react

2. 配置 API 密钥

• 在项目根目录创建 .env.local 文件
• 添加对应提供商的 API Key，如 OPENAI_API_KEY=your-key
• Vercel 部署时可通过环境变量或 OIDC 认证

3. 创建 API 路由

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

export async function POST(request: Request) {
  const { messages } = await request.json();
  
  const result = streamText({
    model: openai('gpt-5.5'),
    messages,
  });
  
  return result.toDataStreamResponse();
}

4. 构建前端界面

'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>
  );
}

九、Vercel AI SDK 如何构建 AI Agent？

1. ToolLoopAgent 基础用法

import { ToolLoopAgent } from 'ai';

const agent = new ToolLoopAgent({
  model: 'openai/gpt-5.5',
  instructions: '你是一个旅行助手，帮助用户规划行程',
  tools: {
    searchFlights: tool({ /* ... */ }),
    bookHotel: tool({ /* ... */ }),
  },
});

const result = await agent.generate({
  prompt: '帮我规划一次从北京到上海的三天旅行',
});

2. Agent 执行流程

• Agent 接收用户输入后，自主分析任务需求
• 根据任务需要，自动调用相应工具获取信息
• 基于工具返回结果，决定下一步行动
• 循环执行直到任务完成或达到停止条件

3. 运行时上下文（runtimeContext）

• 通过 runtimeContext 定义 Agent 运行时的共享状态
• 在 prepareStep 函数中访问和修改上下文
• 适用于需要跨步骤维护状态的场景，如多轮对话中的用户偏好

4. 工具上下文（toolsContext）

• 为每个工具配置专属的 API Key 或配置信息
• 上下文作用域限定在单个工具内，保障安全性
• 适用于集成第三方工具时的凭证管理

5. WorkflowAgent 持久化执行

• 从 @ai-sdk/workflow 包导入，用于需要持久化的场景
• 每个工具调用成为工作流中的一个步骤，支持自动重试
• 支持人工审批挂起，用户可在数小时后恢复执行
• 适用于订单处理、退款流程、多步骤研究任务等生产场景

十、Vercel AI SDK 如何实现多步骤推理和工具编排？

1. 自主多步推理

• ToolLoopAgent 内置推理循环，模型自主决定执行步骤
• 通过 stopWhen 参数控制停止条件，如最大步数、特定结果
• 每步执行结果自动作为上下文传递给下一步

2. 工具编排模式

• 串行编排：工具按顺序执行，后一步依赖前一步结果
• 并行编排：无依赖关系的工具可同时执行
• 条件编排：根据中间结果动态决定执行哪些工具

3. 推理控制（v7 新增）

• 通过 reasoning 参数控制模型推理深度，可选 low、medium、high
• 统一接口映射到各提供商的原生推理设置
• 复杂任务使用高推理模式，简单任务使用低推理模式以节省成本

4. 步骤准备函数

• prepareStep 函数在每步执行前调用
• 可动态调整提示词、模型选择、工具集
• 基于运行时上下文实现个性化处理

十一、Vercel AI SDK 如何处理模型调用的错误和回退？

1. 内置回退机制

• 支持配置多个模型作为主备切换
• 主模型调用失败时自动尝试备用模型
• 回退策略可基于错误类型、响应时间等条件

2. 错误分类处理

• 网络错误：自动重试，支持指数退避
• 速率限制：等待后重试，或切换到备用模型
• 内容过滤：返回明确错误，由应用层处理
• 上下文超限：自动截断或摘要历史消息

3. 超时控制（v7 新增）

• 支持总超时、单步超时、单 chunk 超时等多级配置
• 支持默认工具超时和单工具自定义超时
• 超时原因通过流和 UI 协议传递，便于前端展示

4. 生产环境建议

• 为关键路径配置多个模型提供商
• 设置合理的超时阈值，避免长时间阻塞
• 使用 telemetry 监控错误率和响应时间
• 对敏感操作启用工具审批机制

十二、Vercel AI SDK 如何实现 Agent 的可观测性和监控？

1. 遥测系统（v7 重构）

• registerTelemetry 全局注册遥测配置
• 自动收集 Agent 执行过程中的关键指标
• 支持 OpenTelemetry 标准，可对接 Langfuse 等监控平台

2. 生命周期回调

• 提供 onStart、onStep、onEnd 等生命周期钩子
• 可在每个阶段执行自定义逻辑，如日志记录、指标上报
• 支持访问运行时上下文和步骤性能统计

3. 步骤性能统计

• 记录每个工具调用的输入、输出、耗时、重试次数
• 在 WorkflowAgent 中，每个步骤在仪表板独立展示
• 便于定位性能瓶颈和异常步骤

4. Node.js 追踪通道

• v7 新增 Node.js diagnostics channel 支持
• 无需额外配置即可将追踪数据发送到兼容后端
• 与现有 APM 工具集成，实现全链路追踪

十三、Vercel AI SDK 如何保障生产环境的安全性？

1. 工具审批机制

• 高风险工具可配置执行前审批
• 支持用户确认、自动拒绝、自定义策略等模式
• v7 版本支持 HMAC 签名审批，防止参数篡改

2. 上下文隔离

• 工具上下文作用域限定在单个工具内
• 第三方工具无法访问其他工具的配置或密钥
• 运行时上下文与工具上下文分离管理

3. 密钥管理

• API Key 通过环境变量注入，不硬编码在代码中
• Vercel 部署支持 OIDC 无密钥认证
• 遥测数据默认脱敏，不记录敏感信息

4. 沙箱执行

• 支持在 Vercel Sandbox 中运行 Agent 生成的代码
• 隔离执行环境，防止恶意代码影响宿主系统
• 适用于需要动态执行用户输入或模型生成代码的场景

5. 输入校验

• 工具参数通过 Zod Schema 严格校验
• v7 版本在重放时重新校验工具输入和策略
• 防止注入攻击和参数越界

十四、Vercel AI SDK 支持哪些文件上传和处理能力？

1. uploadFile API（v7 新增）

import { readFile } from 'node:fs/promises';
import { openai } from '@ai-sdk/openai';
import { uploadFile } from 'ai';

const { providerReference } = await uploadFile({
  api: openai.files(),
  data: await readFile('./document.pdf'),
  filename: 'document.pdf',
});

2. 文件引用机制

• 上传一次后返回轻量级引用对象
• 后续模型调用直接传递引用，避免重复上传
• 适用于多轮对话中反复引用同一文件的场景

3. 支持的文件类型

• 文档类：PDF、Word、文本文件
• 图像类：PNG、JPG、GIF 等常见格式
• 数据类：CSV、JSON、Excel 等结构化数据
• 音频类：MP3、WAV 等语音文件

4. 技能文件上传（uploadSkill）

• v7 新增 uploadSkill 函数，用于上传 Agent 技能定义
• 支持 Claude 等提供商的技能容器
• 可将技能文件与 Agent 关联，实现能力扩展

十五、Vercel AI SDK 适合构建哪些类型的 AI 应用？

1. 对话式应用

• 智能客服、虚拟助手、聊天机器人
• 支持多轮对话、上下文记忆、工具调用
• 流式输出提供自然的人机交互体验

2. 内容生成应用

• 文章撰写、文案创作、代码生成
• 结构化数据提取和填充
• 多模态内容（文本、图像、语音）生成

3. 数据分析应用

• 自然语言查询数据库
• 自动生成分析报告和可视化
• 结合外部 API 获取实时数据

4. 工作流自动化

• 订单处理、退款审批、行程规划
• 多步骤任务编排和状态持久化
• 与现有业务系统集成

5. 开发辅助工具

• AI 代码审查、自动补全、重构建议
• 文档生成、测试用例编写
• 集成到 IDE 或开发平台

十六、Vercel AI SDK 与 LangChain、LlamaIndex 等框架相比有什么特点？

1. 定位差异

• Vercel AI SDK：聚焦前端 AI 应用开发和 TypeScript 生态，提供从 UI 到后端的完整解决方案
• LangChain：通用 LLM 应用框架，覆盖 Python 和 JavaScript，强调链式编排和 Agent 抽象
• LlamaIndex：专注数据索引和检索增强生成（RAG），在知识库问答场景积累深厚

2. 技术栈适配

• Vercel AI SDK：原生支持 React、Next.js、Vue、Svelte，与前端工程化深度集成
• LangChain：提供 JavaScript 版本，但核心生态和最新特性通常先在 Python 版发布
• LlamaIndex：主要面向 Python，TypeScript 支持相对有限

3. 部署与运行时

• Vercel AI SDK：与 Vercel 平台深度集成，支持边缘部署、无服务器函数、流式响应
• LangChain：框架无关，可部署到任意环境，但需要自行处理部署优化
• LlamaIndex：侧重数据处理和索引构建，部署方式灵活

4. 学习曲线

• Vercel AI SDK：API 设计贴近前端开发习惯，上手门槛较低
• LangChain：概念较多（Chain、Agent、Memory、Tool 等），学习曲线较陡
• LlamaIndex：数据索引概念直观，但高级功能需要深入理解

5. 选型建议

• 前端团队构建 Web AI 应用：优先考虑 Vercel AI SDK
• 需要复杂编排和跨语言支持：LangChain 更合适
• 专注知识库和 RAG 场景：LlamaIndex 是专业选择
• 生产级 Agent 需要持久化和可观测性：Vercel AI SDK v7 提供了原生支持