SuperAPI AI 工具集
合作ENAI 行业资讯收藏
Skill 广场ai-sdk

ai-sdk

编程与开发

查看项目

更新于 10-14 23:22

技能介绍

用途

AI SDK by Vercel（npm 上的 ai 包）是一个用于构建 AI 应用的 TypeScript 工具包。它提供跨模型提供商的统一 API，覆盖文本生成、结构化输出、工具调用、智能体、嵌入与框架 UI 集成。

  • 仓库：https://github.com/vercel/ai
  • 文档：https://ai-sdk.dev/docs

核心前提：不要信任自己的记忆

资料明确指出：你对 AI SDK 的记忆很可能已经过时。SDK 跨版本变化频繁，API 会被重命名、移除和新增。训练数据几乎必然包含过时 API、已废弃模式和不再存在的模型 ID。useChat 这类 UI hook 属于变化最频繁的 API，客户端代码尤其需要谨慎。

因此：永远不要凭记忆写 AI SDK 代码，务必针对项目实际安装版本，对照文档和源码核实每一个 API、选项和模式。

使用方式：使用随包自带的、与版本匹配的文档

ai 包会在 node_modules 内附带完整文档和源码，它们始终与安装版本匹配，应优先于记忆。

  • 确认已安装 ai：检查 node_modules/ai/，或在 monorepo 中定位依赖 ai 的工作区包（如 apps/<name>/node_modules/ai/）。若项目中任何位置都未安装 ai，只把 ai 包装进目标包，使用项目自身的包管理器（例如 pnpm add ai --filter <pkg> 或 npm install ai）。提供商包（如 @ai-sdk/openai）和框架包（如 @ai-sdk/react）应在任务需要时再安装。
  • 阅读并用 grep 检索自带文档 node_modules/ai/docs/（或 <package>/node_modules/ai/docs/）以及源码 node_modules/ai/src/。
  • 提供商与框架包在 node_modules/@ai-sdk/<name>/docs/（或 <package>/node_modules/@ai-sdk/<name>/docs/）自带各自文档。
  • 若自带文档中没有，可搜索 https://ai-sdk.dev/docs。在任何文档页 URL 后追加 .md 可获得其 markdown，也可通过 https://ai-sdk.dev/api/search-docs?q=your_query 搜索。
  • 如果在文档或源码中找不到支持答案的依据，要明确说明，不要猜测。

AI Gateway：最快的入门方式

Vercel AI Gateway 是开始使用 AI SDK 最快的方式。它通过单一 API 提供对 OpenAI、Anthropic、Google 等提供商模型的访问，无需安装提供商包，也无需管理多个 API key。

设置方式：

  1. 使用 OIDC 认证（用于 Vercel 部署）或获取 AI Gateway API key。
  2. 通过 AI_GATEWAY_API_KEY 环境变量提供给应用。
  3. 使用 provider/model 字符串引用模型。

具体设置、认证与用法，请阅读自带指南和 AI Gateway 文档。

选择模型

永远不要凭记忆使用模型 ID——模型发布和退役都很频繁。在编写引用模型的代码前，先获取当前模型列表。不要截断列表（例如使用 head），以便找到最新模型：

# 所有可用模型
curl -s https://ai-gateway.vercel.sh/v1/models | jq -r '.data[].id'

# 按提供商过滤（如 anthropic、openai、google）
curl -s https://ai-gateway.vercel.sh/v1/models | jq -r '[.data[] | select(.id | startswith("anthropic/")) | .id] | reverse | .[]'

当同一模型存在多个版本时，优先选择版本号最高的那个。

构建和消费智能体

应使用 SDK 内置的智能体抽象（例如 ToolLoopAgent），而不是手工编写工具调用循环。为获得端到端类型安全，在客户端消费智能体时，从智能体定义推断 UI 消息类型（例如配合 useChat）。消费智能体与具体框架相关：检查 package.json 以识别技术栈，然后follow对应的 quickstart。

当前的智能体、工具与类型安全 API，请在自带文档中查找（node_modules/ai/docs/，特别是 agents 部分）或访问 https://ai-sdk.dev/docs。

DevTools

AI SDK DevTools 会捕获你的 AI SDK 调用——请求、响应、工具调用、token 用量以及多步运行——让你能准确检查智能体做了什么。在开发期间用它调试生成结果。它是独立包，仅用于本地开发。

设置说明请阅读自带的 DevTools 文档。

保持 SDK 为最新版本

过旧的安装是最常见的错误来源。将安装版本与最新版对比：

  • 已安装版本：node_modules/ai/package.json 中的 version 字段。
  • 最新版本：运行 npm view ai version。

如果安装版本落后最新版一个或更多大版本，应告知用户其处在旧版本上，并建议在继续之前升级。迁移指南见 https://ai-sdk.dev/docs/migration-guides。

修改之后

运行项目的类型检查器。保持最小化——只设置与默认值不同的选项，默认值应查阅文档或源码，而不是过度指定。大多数类型错误来自记忆中已变更的 API；出现时应重新核对当前文档和源码。