ai-sdk-core

AI SDK Core

使用 Vercel AI SDK v5 和 v6 Beta 构建后端 AI。

安装：

npm install ai @ai-sdk/openai @ai-sdk/anthropic @ai-sdk/google zod
# Beta: npm install ai@beta @ai-sdk/openai@beta

---

AI SDK 6 Beta（2025 年 11 月）

状态： Beta（计划于 2025 年底发布稳定版） 最新版本： [email protected]（2025 年 11 月 22 日）

新功能

1. Agent 抽象 使用 ToolLoopAgent 类构建 Agent 的统一接口：

• 全面控制执行流程、工具循环和状态管理
• 取代手动编排工具调用

2. 工具执行审批（人机协同） 在执行工具前请求用户确认：

• 静态审批：始终询问是否使用特定工具
• 动态审批：根据工具输入决定是否询问
• 原生人机协同模式

3. 重排序支持 通过重新排列文档来提升搜索相关性：

• 支持的提供商：Cohere、Amazon Bedrock、Together.ai
• 专用于 RAG 工作流的重排序模型

4. 结构化输出（稳定版） 将多步骤工具调用与结构化数据生成结合起来：

• 多种输出策略：对象、数组、选项、文本格式
• 现已在 v6 中稳定，可用于生产环境

5. 调用选项 动态运行时配置：

• 类型安全的参数传递
• RAG 集成、模型选择、工具自定义
• 调整提供商专属设置

6. 图像编辑（即将推出） 原生支持图像转换工作流。

从 v5 迁移

与 v4→v5 不同，v6 的重大变更很少：

• 基于 v3 Language Model Specification
• 大多数用户无需更改代码
• Agent 抽象为新增功能（可选启用）

安装 Beta 版：

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

官方文档： https://ai-sdk.dev/docs/announcing-ai-sdk-6-beta

---

最新 AI 模型（2025 年）

OpenAI

GPT-5（2025 年 8 月 7 日）：

• 与 GPT-4o 相比，幻觉减少 45%
• 在数学、编码、视觉感知和健康领域达到最先进水平
• 可在 ChatGPT、API、GitHub Models、Microsoft Copilot 中使用

GPT-5.1（2025 年 11 月 13 日）：

• 相比 GPT-5，速度和效率有所提升
• 可通过 API 平台使用

import { openai } from '@ai-sdk/openai';
const gpt5 = openai('gpt-5');
const gpt51 = openai('gpt-5.1');

Anthropic

Claude 4 系列（2025 年 5 月至 10 月）：

• Opus 4（5 月 22 日）：最适合复杂推理，每百万 token 收费 $15/$75
• Sonnet 4（5 月 22 日）：性能均衡，每百万 token 收费 $3/$15
• Opus 4.1（8 月 5 日）：强化 Agent 任务能力，擅长实际编码
• Sonnet 4.5（9 月 29 日）：编码、Agent 和计算机使用能力最强
• Haiku 4.5（10 月 15 日）：小型、快速、低延迟模型

import { anthropic } from '@ai-sdk/anthropic';
const sonnet45 = anthropic('claude-sonnet-4-5-20250929');  // Latest
const opus41 = anthropic('claude-opus-4-1-20250805');
const haiku45 = anthropic('claude-haiku-4-5-20251015');

Google

Gemini 2.5 系列（2025 年 3 月至 9 月）：

• Pro（2025 年 3 月）：智能程度最高，发布时在 LMArena 排名第一
• Pro Deep Think（2025 年 5 月）：增强推理模式
• Flash（2025 年 5 月）：快速且经济高效
• Flash-Lite（2025 年 9 月）：更新后的高效版本

import { google } from '@ai-sdk/google';
const pro = google('gemini-2.5-pro');
const flash = google('gemini-2.5-flash');
const lite = google('gemini-2.5-flash-lite');

---

v5 核心函数（基础）

generateText() - 使用工具完成文本生成 streamText() - 实时流式生成 generateObject() - 结构化输出（Zod 模式） streamObject() - 流式生成结构化数据

用法请参阅官方文档：https://ai-sdk.dev/docs/ai-sdk-core

---

Cloudflare Workers 启动修复

问题： AI SDK v5 + Zod 会导致启动时间超过 270ms（超出 Workers 的 400ms 限制）。

解决方案：

// ❌ BAD: Top-level imports cause startup overhead
import { createWorkersAI } from 'workers-ai-provider';
const workersai = createWorkersAI({ binding: env.AI });

// ✅ GOOD: Lazy initialization inside handler
app.post('/chat', async (c) => {
  const { createWorkersAI } = await import('workers-ai-provider');
  const workersai = createWorkersAI({ binding: c.env.AI });
  // ...
});

补充建议：

• 尽量减少顶层 Zod 模式
• 将复杂模式移入路由处理程序
• 使用 Wrangler 监控启动时间

---

v5 工具调用变更

重大变更：

• parameters → inputSchema（Zod 模式）
• 工具属性：args → input，result → output
• 已移除 ToolExecutionError（现在使用 tool-error 内容部分）
• 已移除 maxSteps 参数 → 使用 stopWhen(stepCountIs(n))

v5 新增功能：

• 动态工具（根据上下文在运行时添加工具）
• Agent 类（使用工具进行多步骤执行）

---

v4→v5 重大迁移

AI SDK v5 引入了大量重大变更。如果要从 v4 迁移，请遵循本指南。

重大变更概览

1. 参数重命名

   • maxTokens → maxOutputTokens
   • providerMetadata → providerOptions

2. 工具定义

   • parameters → inputSchema
   • 工具属性：args → input，result → output

3. 消息类型

   • CoreMessage → ModelMessage
   • Message → UIMessage
   • convertToCoreMessages → convertToModelMessages

4. 工具错误处理

   • 移除了 ToolExecutionError 类
   • 现在使用 tool-error 内容部分
   • 支持自动重试

5. 多步执行

   • maxSteps → stopWhen
   • 使用 stepCountIs() 或 hasToolCall()

6. 消息结构

   • 简单的 content 字符串 → parts 数组
   • 部分类型：文本、文件、推理、工具调用、工具结果

7. 流式传输架构

   • 单个数据块 → 开始／增量／结束生命周期
   • 为并发流分配唯一 ID

8. 工具流式传输

   • 默认启用
   • 移除了 toolCallStreaming 选项

9. 包重组

   • ai/rsc → @ai-sdk/rsc
   • ai/react → @ai-sdk/react
   • LangChainAdapter → @ai-sdk/langchain

迁移示例

之前（v4）：

import { generateText } from 'ai';

const result = await generateText({
  model: openai.chat('gpt-4'),
  maxTokens: 500,
  providerMetadata: { openai: { user: 'user-123' } },
  tools: {
    weather: {
      description: 'Get weather',
      parameters: z.object({ location: z.string() }),
      execute: async (args) => { /* args.location */ },
    },
  },
  maxSteps: 5,
});

之后（v5）：

import { generateText, tool, stopWhen, stepCountIs } from 'ai';

const result = await generateText({
  model: openai('gpt-4'),
  maxOutputTokens: 500,
  providerOptions: { openai: { user: 'user-123' } },
  tools: {
    weather: tool({
      description: 'Get weather',
      inputSchema: z.object({ location: z.string() }),
      execute: async ({ location }) => { /* input.location */ },
    }),
  },
  stopWhen: stepCountIs(5),
});

迁移检查清单

• 将所有 maxTokens 更新为 maxOutputTokens
• 将 providerMetadata 更新为 providerOptions
• 将工具的 parameters 转换为 inputSchema
• 更新工具执行函数：args → input
• 将 maxSteps 替换为 stopWhen(stepCountIs(n))
• 更新消息类型：CoreMessage → ModelMessage
• 移除 ToolExecutionError 处理
• 更新包导入（ai/rsc → @ai-sdk/rsc）
• 测试流式传输行为（架构已变更）
• 更新 TypeScript 类型

自动化迁移

AI SDK 提供了迁移工具：

npx ai migrate

此工具会自动更新大多数重大变更。请仔细检查更改。

官方迁移指南： https://ai-sdk.dev/docs/migration-guides/migration-guide-5-0

---

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 issues 中搜索“Workers startup limit”

---

4. streamText 静默失败

原因： createDataStreamResponse 可能会吞掉流错误。

状态： ✅ 已解决 - 已在 [email protected] 中修复（2025 年 2 月）

解决方案（推荐）：

// Use the onError callback (added in v4.1.22)
const stream = streamText({
  model: openai('gpt-4'),
  prompt: 'Hello',
  onError({ error }) {
    console.error('Stream error:', error);
    // Custom error logging and handling
  },
});

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

替代方案（手动使用 try-catch）：

// Fallback if not using onError callback
try {
  const stream = streamText({
    model: openai('gpt-4'),
    prompt: 'Hello',
  });

  for await (const chunk of stream.textStream) {
    process.stdout.write(chunk);
  }
} catch (error) {
  console.error('Stream error:', error);
}

预防措施：

• 使用 onError 回调以妥善捕获错误（推荐）
• 实施服务器端错误监控
• 明确测试流错误处理
• 在生产环境中始终记录服务器端日志

GitHub Issue： #4726（已解决）

---

5. AI_LoadAPIKeyError

原因： 缺少或无效的 API 密钥。

解决方案：

import { AI_LoadAPIKeyError } from 'ai';

try {
  const result = await generateText({
    model: openai('gpt-4'),
    prompt: 'Hello',
  });
} catch (error) {
  if (error instanceof AI_LoadAPIKeyError) {
    console.error('API key error:', error.message);

    // Check:
    // 1. .env file exists and loaded
    // 2. Correct env variable name (OPENAI_API_KEY)
    // 3. Key format is valid (starts with sk-)
  }
}

预防措施：

• 在应用启动时验证 API 密钥
• 使用环境变量验证（例如 zod）
• 在开发环境中提供清晰的错误消息
• 记录所需的环境变量

---

6. AI_InvalidArgumentError

**原因：**传递给函数的参数无效。

解决方案：

import { AI_InvalidArgumentError } from 'ai';

try {
  const result = await generateText({
    model: openai('gpt-4'),
    maxOutputTokens: -1,  // Invalid!
    prompt: 'Hello',
  });
} catch (error) {
  if (error instanceof AI_InvalidArgumentError) {
    console.error('Invalid argument:', error.message);
    // Check parameter types and values
  }
}

预防措施：

• 使用 TypeScript 进行类型检查
• 调用 AI SDK 函数前验证输入
• 仔细阅读函数签名
• 查看官方文档，了解参数限制

---

7. AI_NoContentGeneratedError

**原因：**模型未生成内容（安全过滤器等）。

解决方案：

import { AI_NoContentGeneratedError } from 'ai';

try {
  const result = await generateText({
    model: openai('gpt-4'),
    prompt: 'Some prompt',
  });
} catch (error) {
  if (error instanceof AI_NoContentGeneratedError) {
    console.error('No content generated');

    // Possible causes:
    // 1. Safety filters blocked output
    // 2. Prompt triggered content policy
    // 3. Model configuration issue

    // Handle gracefully:
    return { text: 'Unable to generate response. Please try different input.' };
  }
}

预防措施：

• 清理用户输入
• 避免可能触发安全过滤器的提示词
• 准备备用提示信息
• 记录发生情况以供分析

---

8. AI_TypeValidationError

**原因：**生成的输出未通过 Zod 模式验证。

解决方案：

import { AI_TypeValidationError } from 'ai';

try {
  const result = await generateObject({
    model: openai('gpt-4'),
    schema: z.object({
      age: z.number().min(0).max(120),  // Strict validation
    }),
    prompt: 'Generate person',
  });
} catch (error) {
  if (error instanceof AI_TypeValidationError) {
    console.error('Validation failed:', error.message);

    // Solutions:
    // 1. Relax schema constraints
    // 2. Add more guidance in prompt
    // 3. Use .optional() for unreliable fields
  }
}

预防措施：

• 从宽松的模式开始，逐步收紧
• 对可能并非总是存在的字段使用 .optional()
• 在字段描述中添加验证提示
• 使用各种提示词进行测试

---

9. AI_RetryError

**原因：**所有重试均失败。

解决方案：

import { AI_RetryError } from 'ai';

try {
  const result = await generateText({
    model: openai('gpt-4'),
    prompt: 'Hello',
    maxRetries: 3,  // Default is 2
  });
} catch (error) {
  if (error instanceof AI_RetryError) {
    console.error('All retries failed');
    console.error('Last error:', error.lastError);

    // Check root cause:
    // - Persistent network issue
    // - Provider outage
    // - Invalid configuration
  }
}

预防措施：

• 调查失败的根本原因
• 根据需要调整重试配置
• 在提供商服务中断时实施熔断器模式
• 准备备用提供商

---

10. 速率限制错误

**原因：**超出提供商的速率限制（RPM/TPM）。

解决方案：

// Implement exponential backoff
async function generateWithBackoff(prompt: string, retries = 3) {
  for (let i = 0; i < retries; i++) {
    try {
      return await generateText({
        model: openai('gpt-4'),
        prompt,
      });
    } catch (error) {
      if (error instanceof AI_APICallError && error.statusCode === 429) {
        const delay = Math.pow(2, i) * 1000;  // Exponential backoff
        console.log(`Rate limited, waiting ${delay}ms`);
        await new Promise(resolve => setTimeout(resolve, delay));
      } else {
        throw error;
      }
    }
  }
  throw new Error('Rate limit retries exhausted');
}

预防措施：

• 监控速率限制标头
• 对请求进行排队，确保不超出限制
• 根据需要升级提供商套餐
• 实施请求节流

---

11. 使用 Zod 时的 TypeScript 性能问题

**原因：**复杂的 Zod 模式会拖慢 TypeScript 类型检查。

解决方案：

// Instead of deeply nested schemas at top level:
// const complexSchema = z.object({ /* 100+ fields */ });

// Define inside functions or use type assertions:
function generateData() {
  const schema = z.object({ /* complex schema */ });
  return generateObject({ model: openai('gpt-4'), schema, prompt: '...' });
}

// Or use z.lazy() for recursive schemas:
type Category = { name: string; subcategories?: Category[] };
const CategorySchema: z.ZodType<Category> = z.lazy(() =>
  z.object({
    name: z.string(),
    subcategories: z.array(CategorySchema).optional(),
  })
);

预防措施：

• 避免使用顶层复杂模式
• 对递归类型使用 z.lazy()
• 将大型模式拆分为较小的模式
• 在适当情况下使用类型断言

官方文档： https://ai-sdk.dev/docs/troubleshooting/common-issues/slow-type-checking

---

12. 无效的 JSON 响应（特定于提供商）

**原因：**某些模型偶尔会返回无效的 JSON。

解决方案：

// Use built-in retry and mode selection
const result = await generateObject({
  model: openai('gpt-4'),
  schema: mySchema,
  prompt: 'Generate data',
  mode: 'json',  // Force JSON mode (supported by GPT-4)
  maxRetries: 3,  // Retry on invalid JSON
});

// Or catch and retry manually:
try {
  const result = await generateObject({
    model: openai('gpt-4'),
    schema: mySchema,
    prompt: 'Generate data',
  });
} catch (error) {
  // Retry with different model
  const result = await generateObject({
    model: openai('gpt-4-turbo'),
    schema: mySchema,
    prompt: 'Generate data',
  });
}

预防措施：

• 在可用时使用 mode: 'json'
• 结构化输出优先使用 GPT-4
• 实施重试逻辑
• 验证响应

GitHub 问题：#4302（Imagen 3.0 无效 JSON）

---

**更多错误：**https://ai-sdk.dev/docs/reference/ai-sdk-errors（共 28 种）

---

何时使用此技能

在以下情况下使用 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
• 需要在不同的大模型提供商之间使用一致的 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）

---

版本

AI SDK：

• 稳定版：[email protected]（2025 年 11 月 20 日）
• Beta 版：[email protected]（2025 年 11 月 22 日）
• 同时支持 Zod 3.x/4.x（推荐使用 3.23.8）

最新模型（2025）：

• OpenAI：GPT-5.1、GPT-5、o3
• Anthropic：Claude Sonnet 4.5、Opus 4.1、Haiku 4.5
• Google：Gemini 2.5 Pro/Flash/Lite

查看最新信息：

npm view ai version
npm view ai dist-tags  # See beta versions

---

Official Docs

Core:

• AI SDK 6 Beta: https://ai-sdk.dev/docs/announcing-ai-sdk-6-beta
• AI SDK Core: https://ai-sdk.dev/docs/ai-sdk-core/overview
• v4→v5 Migration: https://ai-sdk.dev/docs/migration-guides/migration-guide-5-0
• All Errors (28): https://ai-sdk.dev/docs/reference/ai-sdk-errors
• Providers (25+): https://ai-sdk.dev/providers/overview

GitHub:

• Repository: https://github.com/vercel/ai
• Issues: https://github.com/vercel/ai/issues

---

Last Updated: 2025-11-22 Skill Version: 1.2.0 AI SDK: 5.0.98 stable / 6.0.0-beta.107