name: ai-sdk-core description: Vercel AI SDK v5 用于后端AI（文本生成、结构化输出、工具、代理）。多提供商。用于服务器端AI或遇到AI_APICallError、AI_NoObjectGeneratedError、流失败。

关键词：ai sdk core, vercel ai sdk, generateText, streamText, generateObject, streamObject, ai sdk node, ai sdk server, zod ai schema, ai tools calling, ai agent class, openai sdk, anthropic sdk, google gemini sdk, workers-ai-provider, ai streaming backend, multi-provider ai, ai sdk errors, AI_APICallError, AI_NoObjectGeneratedError, streamText fails, worker startup limit ai license: MIT

AI SDK 核心

生产就绪的后端AI使用Vercel AI SDK v5。

最后更新: 2025-11-21

快速开始 (5 分钟)

安装

bun add ai @ai-sdk/openai @ai-sdk/anthropic @ai-sdk/google workers-ai-provider zod  # 推荐
# 或: npm install ai @ai-sdk/openai @ai-sdk/anthropic @ai-sdk/google workers-ai-provider zod

环境变量

# .env
OPENAI_API_KEY=sk-...
ANTHROPIC_API_KEY=sk-ant-...
GOOGLE_GENERATIVE_AI_API_KEY=...

第一个示例：生成文本

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

const result = await generateText({
  model: openai('gpt-4-turbo'),
  prompt: 'TypeScript 是什么？',
});

console.log(result.text);

第一个示例：流式聊天

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

const stream = streamText({
  model: anthropic('claude-sonnet-4-5-20250929'),
  messages: [
    { role: 'user', content: '讲个故事' },
  ],
});

for await (const chunk of stream.textStream) {
  process.stdout.write(chunk);
}

第一个示例：结构化输出

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

const result = await generateObject({
  model: openai('gpt-4'),
  schema: z.object({
    name: z.string(),
    age: z.number(),
    skills: z.array(z.string()),
  }),
  prompt: '为软件工程师生成个人资料',
});

console.log(result.object);
// { name: "Alice", age: 28, skills: ["TypeScript", "React"] }

核心功能

加载 references/core-functions.md 获取完整的API参考 所有4个核心功能。

快速概述

AI SDK v5 提供4个核心功能：

功能	输出	流式	用例
`generateText()`	文本	否	批处理、简单补全
`streamText()`	文本	是	聊天UI、长响应
`generateObject()`	结构化	否	数据提取、JSON生成
`streamObject()`	结构化	是	实时表单、渐进式UI

基本示例

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

const result = await generateText({
  model: openai('gpt-4-turbo'),
  prompt: '解释量子计算',
});

console.log(result.text);

→ 加载 references/core-functions.md 获取： 完整签名、工具使用模式、错误处理、流式示例、比较表

提供商设置与配置

加载 references/provider-setup.md 获取完整的设置说明 所有提供商。

快速概述

AI SDK v5 支持4个主要提供商：

提供商	环境变量	最新模型
OpenAI	`OPENAI_API_KEY`	GPT-5, GPT-4 Turbo
Anthropic	`ANTHROPIC_API_KEY`	Claude Sonnet 4.5, Opus 4
Google	`GOOGLE_GENERATIVE_AI_API_KEY`	Gemini 2.5 Pro/Flash
Cloudflare	Workers AI 绑定	Llama 3.1, Qwen 2.5

基本设置

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

// 从环境变量获取API密钥
const result = await generateText({
  model: openai('gpt-4-turbo'),
  prompt: '你好',
});

→ 加载 references/provider-setup.md 获取： 完整API配置、速率限制、错误处理、Cloudflare Workers优化、模型选择指南

工具调用与代理

加载 references/tools-and-agents.md 获取完整的工具和代理文档。

快速概述

工具允许模型调用外部函数。代理管理多步工作流。

v5 工具变更：

parameters → inputSchema (Zod 模式)
工具属性：args → input, result → output
maxSteps → stopWhen(stepCountIs(n))

基本工具示例

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

const result = await generateText({
  model: openai('gpt-4'),
  tools: {
    weather: tool({
      description: '获取某个位置的天气',
      inputSchema: z.object({ location: z.string() }),
      execute: async ({ location }) => {
        return { temperature: 72, condition: 'sunny' };
      },
    }),
  },
  prompt: '东京的天气怎么样？',
});

→ 加载 references/tools-and-agents.md 获取： 代理类使用、多步执行、动态工具、停止条件

关键 v4→v5 迁移

加载 references/v4-to-v5-migration.md 获取完整的迁移指南。

关键破坏性变更

AI SDK v5 有9个主要破坏性变更：

maxTokens → maxOutputTokens
parameters → inputSchema (Zod)
maxSteps → stopWhen(stepCountIs(n))
CoreMessage → ModelMessage
包重组 (ai/rsc → @ai-sdk/rsc)

自动化迁移

bunx ai migrate  # 自动迁移大多数变更

→ 加载 references/v4-to-v5-migration.md 获取： 完整破坏性变更列表、迁移示例、检查清单、官方迁移指南链接

前12个错误与解决方案

1. AI_APICallError

原因： API请求失败（网络、认证、速率限制）。

解决方案：

import { AI_APICallError } from 'ai';

try {
  const result = await generateText({
    model: openai('gpt-4'),
    prompt: '你好',
  });
} catch (error) {
  if (error instanceof AI_APICallError) {
    console.error('API调用失败：', error.message);
    console.error('状态码：', error.statusCode);
    console.error('响应：', error.responseBody);

    // 检查常见原因
    if (error.statusCode === 401) {
      // 无效API密钥
    } else if (error.statusCode === 429) {
      // 速率限制 - 实现退避
    } else if (error.statusCode >= 500) {
      // 提供商问题 - 重试
    }
  }
}

预防：

在启动时验证API密钥
实现指数退避的重试逻辑
监控速率限制
优雅处理网络错误

2. AI_NoObjectGeneratedError

原因： 模型未生成匹配模式的有效对象。

解决方案：

import { AI_NoObjectGeneratedError } from 'ai';

try {
  const result = await generateObject({
    model: openai('gpt-4'),
    schema: z.object({ /* 复杂模式 */ }),
    prompt: '生成数据',
  });
} catch (error) {
  if (error instanceof AI_NoObjectGeneratedError) {
    console.error('未生成有效对象');

    // 解决方案：
    // 1. 简化模式
    // 2. 在提示中添加更多上下文
    // 3. 在提示中提供示例
    // 4. 尝试不同模型（对于复杂对象，GPT-4比GPT-3.5更好）
  }
}

预防：

从简单模式开始，逐步添加复杂性
在提示中包含示例：“生成类似 { name: ‘Alice’, age: 30 } 的人”
对于复杂结构化输出使用GPT-4
先用样本数据测试模式

3. Worker 启动限制 (270ms+)

原因： AI SDK v5 + Zod 初始化开销在Cloudflare Workers中超出启动限制。

解决方案：

// 错误：顶级导入导致启动开销
import { createWorkersAI } from 'workers-ai-provider';
import { complexSchema } from './schemas';

const workersai = createWorkersAI({ binding: env.AI });

// 正确：在处理器内懒初始化
export default {
  async fetch(request, env) {
    const { createWorkersAI } = await import('workers-ai-provider');
    const workersai = createWorkersAI({ binding: env.AI });

    // 在此使用workersai
  }
}

预防：

将AI SDK导入移到路由处理器内
最小化顶级Zod模式
监控Worker启动时间（必须 <400ms）
使用Wrangler的启动时间报告

GitHub 问题： 在Vercel AI SDK问题中搜索"Workers startup limit"

→ 加载 references/error-catalog.md 获取错误 #4-#12 的完整解决方案。

剩余9个错误： 4. streamText 静默失败（在v4.1.22中已解决） 5. AI_LoadAPIKeyError 6. AI_InvalidArgumentError 7. AI_NoContentGeneratedError 8. AI_TypeValidationError 9. AI_RetryError 10. 速率限制错误 11. TypeScript与Zod的性能 12. 无效JSON响应（提供商特定）

完整错误目录： 查看完整错误参考 https://ai-sdk.dev/docs/reference/ai-sdk-errors

生产最佳实践

加载 references/production-guide.md 获取完整的生产部署指南。

关键类别

性能： 流式模式、令牌限制、提供商缓存、Zod优化
错误处理： try-catch模式、重试逻辑、适当日志记录
成本优化： 模型选择、令牌限制、响应缓存
Cloudflare Workers： 懒导入、启动监控、流式响应
Next.js/Vercel： 服务器操作、服务器组件、加载状态

快速示例

// 使用流式处理用户响应
const stream = streamText({
  model: openai('gpt-4'),
  prompt: '长文章',
  maxOutputTokens: 500,
  maxRetries: 3,
});

return stream.toDataStreamResponse();

→ 加载 references/production-guide.md 获取： 平台特定模式、部署检查清单、优化策略

何时加载参考资料

加载 references/core-functions.md 当：

用户需要 generateText、streamText、generateObject 或 streamObject 的完整API文档
关于函数签名、参数或返回类型的问题
需要详细工具使用模式或流式示例
故障排除函数特定错误

加载 references/provider-setup.md 当：

设置 OpenAI、Anthropic、Google 或 Cloudflare Workers AI
配置API密钥或环境变量
故障排除提供商特定错误（速率限制、认证）
关于模型选择或每个提供商最佳实践的问题
需要Cloudflare Workers启动优化

加载 references/tools-and-agents.md 当：

实现工具调用或代理工作流
关于Agent类与原始 generateText 的问题
使用 stopWhen 设置多步执行
动态工具或复杂代理模式

加载 references/v4-to-v5-migration.md 当：

迁移现有v4代码库到v5
关于破坏性变更的问题
需要迁移示例或自动化迁移工具
故障排除迁移相关错误

加载 references/error-catalog.md 当：

用户遇到12个常见错误中的任何（除了内联显示的前3个）
需要带代码示例的完整错误解决方案
故障排除生产错误
关于错误预防策略的问题

加载 references/production-guide.md 当：

部署到生产（任何平台）
需要性能优化
成本优化问题
平台特定模式（Cloudflare Workers、Next.js/Vercel）
错误处理或日志记录策略

何时使用此技能

使用 ai-sdk-core 当：

构建后端AI功能（服务器端文本生成）
实现服务器端文本生成（Node.js、Workers、Next.js）
创建结构化AI输出（JSON、表单、数据提取）
构建带工具的AI代理（多步工作流）
集成多个AI提供商（OpenAI、Anthropic、Google、Cloudflare）
从AI SDK v4迁移到v5
遇到AI SDK错误（AI_APICallError、AI_NoObjectGeneratedError 等）
在Cloudflare Workers中使用AI（使用 workers-ai-provider）
在Next.js服务器组件/操作中使用AI
需要跨不同LLM提供商的一致API

不要使用此技能当：

构建React聊天UI（使用 ai-sdk-ui 技能代替）
需要像 useChat 这样的前端钩子（使用 ai-sdk-ui 技能代替）
需要高级主题如嵌入或图像生成（查看官方文档）
构建无多提供商的本地Cloudflare Workers AI应用（使用 cloudflare-workers-ai 技能代替）
需要生成式UI / RSC（见 https://ai-sdk.dev/docs/ai-sdk-rsc）

依赖项与版本

{
  "dependencies": {
    "ai": "^5.0.116",
    "@ai-sdk/openai": "^2.0.88",
    "@ai-sdk/anthropic": "^2.0.56",
    "@ai-sdk/google": "^2.0.51",
    "workers-ai-provider": "^2.0.0",
    "zod": "^3.23.8"
  },
  "devDependencies": {
    "@types/node": "^24.10.1",
    "typescript": "^5.9.3"
  }
}

版本说明：

AI SDK v5.0.116+（稳定，截至2025年12月最新）
v6 处于测试版 - 本技能未涵盖
Zod 兼容性： 此技能使用 Zod 3.x，但 AI SDK 5 正式支持 Zod 3.x 和 Zod 4.x（4.1.12最新）
- 新项目推荐 Zod 4（发布于2025年8月）
- Zod 4 有破坏性变更：错误API、.default()行为、ZodError.errors移除
- 使用 Zod 4 时可能出现 zod-to-json-schema 的依赖警告
- 见 https://zod.dev/v4/changelog 迁移指南
提供商包版本 2.0+ 以兼容 v5

检查最新版本：

npm view ai version
npm view @ai-sdk/openai version
npm view @ai-sdk/anthropic version
npm view @ai-sdk/google version
npm view workers-ai-provider version
npm view zod version  # 检查 Zod 4.x 更新

官方文档链接

模板与参考资料

此技能包括：

13 个模板： templates/ 中的即用代码示例
5 个参考资料文档： references/ 中的详细指南
1 个脚本： scripts/ 中的版本检查器

所有文件都优化为可直接复制粘贴到项目中。

最后更新： 2025-12-22 技能版本： 1.1.0 AI SDK 版本： 5.0.116+

AI SDK 核心

目录

快速开始 (5 分钟)

安装

环境变量

第一个示例：生成文本

第一个示例：流式聊天

第一个示例：结构化输出

核心功能

快速概述

基本示例

提供商设置与配置

快速概述

基本设置

工具调用与代理

快速概述

基本工具示例

关键 v4→v5 迁移

关键破坏性变更

自动化迁移

前12个错误与解决方案

1. AI_APICallError

2. AI_NoObjectGeneratedError

3. Worker 启动限制 (270ms+)

生产最佳实践

关键类别

快速示例

何时加载参考资料

何时使用此技能

使用 ai-sdk-core 当：

不要使用此技能当：

依赖项与版本

官方文档链接

核心文档

高级主题（本技能未复制）

迁移与故障排除

提供商文档

Cloudflare 集成

Vercel / Next.js 集成

GitHub 与社区

模板与参考资料