ai-sdk-core

AI SDK Core

使用 Vercel AI SDK v5 构建可用于生产环境的后端 AI。

最后更新：2025-11-21

目录

1. 快速入门
2. 核心函数
3. 提供商设置与配置
4. 工具调用与 Agent
5. 关键的 v4→v5 迁移
6. 12 个常见错误及解决方案
7. 生产环境最佳实践
8. 何时加载参考资料
9. 何时使用此技能
10. 依赖项与版本
11. 官方文档链接
12. 模板与参考资料

---

快速入门（5 分钟）

安装

bun add ai @ai-sdk/openai @ai-sdk/anthropic @ai-sdk/google workers-ai-provider zod  # preferred
# or: 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: 'What is 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: 'Tell me a story' },
  ],
});

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: 'Generate a person profile for a software engineer',
});

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

安全安装

此操作会同时安装 6 个以上的 AI 提供商软件包，依赖面较广，需要进行审计。安装前，请遵循供应链安全最佳实践：

• 阻止安装后脚本 — npm config set ignore-scripts true（或 Bun：默认禁用）
• 冷却期 — 等待 7 天，让社区审查新软件包版本
• 安装前审计 — 运行 socket package score npm <pkg>，或使用 socket npm install <pkg> 检查软件包

加载 dependency-upgrade 技能，获取完整的安全配置，包括 Socket CLI 集成、冷却期设置、锁文件验证和 CI 强制执行。

---

核心函数

加载 references/core-functions.md，查看全部 4 个核心函数的完整 API 参考。

快速概览

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: 'Explain quantum computing',
});

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 key from environment
const result = await generateText({
  model: openai('gpt-4-turbo'),
  prompt: 'Hello',
});

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

---

工具调用与 Agent

加载 references/tools-and-agents.md，查看完整的工具和 Agent 文档。

快速概览

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

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: 'Get weather for a location',
      inputSchema: z.object({ location: z.string() }),
      execute: async ({ location }) => {
        return { temperature: 72, condition: 'sunny' };
      },
    }),
  },
  prompt: 'What is the weather in Tokyo?',
});

→ 加载 references/tools-and-agents.md，查看： Agent 类的用法、多步骤执行、动态工具、停止条件

---

关键的 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  # Auto-migrates most changes

→ 加载 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: 'Hello',
  });
} catch (error) {
  if (error instanceof AI_APICallError) {
    console.error('API call failed:', error.message);
    console.error('Status code:', error.statusCode);
    console.error('Response:', error.responseBody);

    // Check common causes
    if (error.statusCode === 401) {
      // Invalid API key
    } else if (error.statusCode === 429) {
      // Rate limit - implement backoff
    } else if (error.statusCode >= 500) {
      // Provider issue - retry
    }
  }
}

预防措施：

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

---

2. AI_NoObjectGeneratedError

原因： 模型未生成符合架构的有效对象。

解决方案：

import { AI_NoObjectGeneratedError } from 'ai';

try {
  const result = await generateObject({
    model: openai('gpt-4'),
    schema: z.object({ /* complex schema */ }),
    prompt: 'Generate data',
  });
} catch (error) {
  if (error instanceof AI_NoObjectGeneratedError) {
    console.error('No valid object generated');

    // Solutions:
    // 1. Simplify schema
    // 2. Add more context to prompt
    // 3. Provide examples in prompt
    // 4. Try different model (gpt-4 better than gpt-3.5 for complex objects)
  }
}

预防措施：

• 从简单架构开始，逐步增加复杂度
• 在提示词中加入示例：“按以下格式生成人员信息：{ name: 'Alice', age: 30 }”
• 复杂结构化输出使用 GPT-4
• 先用样本数据测试架构

---

3. Worker 启动限制（270ms+）

原因： AI SDK v5 和 Zod 的初始化开销导致 Cloudflare Workers 超出启动限制。

解决方案：

// BAD: Top-level imports cause startup overhead
import { createWorkersAI } from 'workers-ai-provider';
import { complexSchema } from './schemas';

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

// GOOD: Lazy initialization inside handler
export default {
  async fetch(request, env) {
    const { createWorkersAI } = await import('workers-ai-provider');
    const workersai = createWorkersAI({ binding: env.AI });

    // Use workersai here
  }
}

预防措施：

• 将 AI SDK 导入移至路由处理程序内部
• 尽量减少顶层 Zod 架构
• 监控 Worker 启动时间（必须低于 400ms）
• 使用 Wrangler 的启动时间报告

GitHub Issue： 在 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. 使用 Zod 时的 TypeScript 性能问题 12. 无效 JSON 响应（特定提供商）

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

---

生产环境最佳实践

加载 references/production-guide.md，查看完整的生产部署指南。

主要类别

1. 性能：流式传输模式、令牌限制、提供商缓存、Zod 优化
2. 错误处理：try-catch 模式、重试逻辑、适当的日志记录
3. 成本优化：模型选择、令牌限制、响应缓存
4. Cloudflare Workers：延迟导入、启动监控、流式响应
5. Next.js/Vercel：Server Actions、Server Components、加载状态

快速示例

// Use streaming for user-facing responses
const stream = streamText({
  model: openai('gpt-4'),
  prompt: 'Long essay',
  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 工作流
• 有关 Agent 类与原始 generateText 的问题
• 使用 stopWhen 设置多步执行
• 动态工具或复杂的 Agent 模式

在以下情况下加载 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 Agent（多步工作流）
• 集成多个 AI 提供商（OpenAI、Anthropic、Google、Cloudflare）
• 将 AI SDK v4 迁移到 v5
• 遇到 AI SDK 错误（AI_APICallError、AI_NoObjectGeneratedError 等）
• 在 Cloudflare Workers 中使用 AI（搭配 workers-ai-provider）
• 在 Next.js Server Components/Actions 中使用 AI
• 需要不同 LLM 提供商之间保持一致的 API

在以下情况下不要使用此技能：

• 构建 React 聊天 UI（改用 ai-sdk-ui 技能）
• 需要 useChat 等前端钩子（改用 ai-sdk-ui 技能）
• 需要嵌入或图像生成等高级主题（请查阅官方文档）
• 构建不使用多提供商的原生 Cloudflare Workers AI 应用（改用 cloudflare-workers-ai 技能）
• 需要 Generative 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 仍处于 Beta 阶段，本技能不涉及
• 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  # Check for Zod 4.x updates

---

官方文档链接

核心文档

• AI SDK 简介： https://ai-sdk.dev/docs/introduction
• AI SDK Core 概览： https://ai-sdk.dev/docs/ai-sdk-core/overview
• 生成文本： https://ai-sdk.dev/docs/ai-sdk-core/generating-text
• 生成结构化数据： https://ai-sdk.dev/docs/ai-sdk-core/generating-structured-data
• 工具与工具调用： https://ai-sdk.dev/docs/ai-sdk-core/tools-and-tool-calling
• Agent 概览： https://ai-sdk.dev/docs/agents/overview
• 基础知识： https://ai-sdk.dev/docs/foundations/overview

高级主题（本技能未涵盖）

• 嵌入： https://ai-sdk.dev/docs/ai-sdk-core/embeddings
• 图像生成： https://ai-sdk.dev/docs/ai-sdk-core/generating-images
• 转录： https://ai-sdk.dev/docs/ai-sdk-core/generating-transcriptions
• 语音： https://ai-sdk.dev/docs/ai-sdk-core/generating-speech
• MCP 工具： https://ai-sdk.dev/docs/ai-sdk-core/mcp-tools
• 遥测： https://ai-sdk.dev/docs/ai-sdk-core/telemetry
• 生成式 UI： https://ai-sdk.dev/docs/ai-sdk-rsc

迁移与故障排除

• v4→v5 迁移指南： https://ai-sdk.dev/docs/migration-guides/migration-guide-5-0
• 所有错误类型（共 28 种）： https://ai-sdk.dev/docs/reference/ai-sdk-errors
• 故障排除指南： https://ai-sdk.dev/docs/troubleshooting

提供商文档

• OpenAI 提供商： https://ai-sdk.dev/providers/ai-sdk-providers/openai
• Anthropic 提供商： https://ai-sdk.dev/providers/ai-sdk-providers/anthropic
• Google 提供商： https://ai-sdk.dev/providers/ai-sdk-providers/google
• 所有提供商（25+）： https://ai-sdk.dev/providers/overview
• 社区提供商： https://ai-sdk.dev/providers/community-providers

Cloudflare 集成

• Workers AI 提供商（社区）： https://ai-sdk.dev/providers/community-providers/cloudflare-workers-ai
• Cloudflare Workers AI 文档： https://developers.cloudflare.com/workers-ai/
• workers-ai-provider GitHub： https://github.com/cloudflare/ai/tree/main/packages/workers-ai-provider
• Cloudflare AI SDK 配置： https://developers.cloudflare.com/workers-ai/configuration/ai-sdk/

Vercel / Next.js 集成

• Vercel AI SDK 5.0 博客： https://vercel.com/blog/ai-sdk-5
• Next.js App Router 集成： https://ai-sdk.dev/docs/getting-started/nextjs-app-router
• Next.js Pages Router 集成： https://ai-sdk.dev/docs/getting-started/nextjs-pages-router
• Vercel Functions： https://vercel.com/docs/functions
• Vercel 流式传输： https://vercel.com/docs/functions/streaming

GitHub 与社区

• GitHub 仓库： https://github.com/vercel/ai
• GitHub Issues： https://github.com/vercel/ai/issues
• Discord 社区： https://discord.gg/vercel

---

模板与参考资料

此技能包含：

• 13 个模板： templates/ 中可直接使用的代码示例
• 5 份参考文档： references/ 中的详细指南
• 1 个脚本： scripts/ 中的版本检查器

所有文件均已优化，可直接复制粘贴到你的项目中。

---

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