Vercel AI SDK：TypeScript 多模型接入的工程选型分析

原创 1小时前 3

#AI SDK #TypeScript #Vercel #AI Agent #LLM 集成

在 TypeScript 项目里接入语言模型，通常要面对每个 provider 都有自己的 SDK、请求格式和流式协议的问题。Vercel AI SDK 的做法是先用一个统一 API 包住差异。按照 GitHub README 的公开描述，这是一个 provider-agnostic 的 TypeScript toolkit，适用于 Next.js、React、Svelte、Vue、Angular 以及 Node.js 运行时。本文只基于 README 中明确写出的能力做拆解，并给出选型时需要进一步验证的工程点。

安装入口与运行前提

README 明确要求本地环境为 Node.js 22+，安装命令是：

npm install ai

这里有一个容易被忽略的细节：如果使用 Claude Code 或 Cursor 这类 coding agent，官方建议执行 npx skills add vercel/ai 把 AI SDK skill 加入仓库。这说明 SDK 不仅面向应用开发，也在为 agent 编码场景提供标准化知识。

对团队而言，Node.js 22+ 的要求意味着旧项目直接接入需要先升级运行时。这本身可能就是一个选型门槛。

统一 Provider 架构：两种接入路径

AI SDK 的核心设计是统一 API。README 给出的示例是，通过默认的 Vercel AI Gateway，直接传模型字符串即可：

const result = await generateText({
  model: 'anthropic/claude-opus-4.6', // 或 'openai/gpt-5.4'
  prompt: 'Hello!',
});

这里的模型字符串采用 provider/model 格式，由网关负责路由。另一种方式是安装对应的 provider SDK 包直连：

npm install @ai-sdk/openai @ai-sdk/anthropic @ai-sdk/google

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

const result = await generateText({
  model: anthropic('claude-opus-4-6'),
  prompt: 'Hello!',
});

注意，README 中的 claude-opus-4.6、gpt-5.4、gemini-3-flash 都属于示例字符串，不能当作已验证的模型清单。真正接入前需要在官方文档或产品列表中确认当前可用的模型名。

从工程角度看，这两种路径解决的是不同问题：默认网关能快速开始，省去管理多个密钥和协议细节；直连包则适合需要对数据路径完全可控的场景。但两者切换时，模型参数从字符串变成了 provider 函数调用，代码结构会变，不是简单的配置替换。

从文本生成到结构化数据

基础能力是 generateText，用于文本补全。更值得关注的是结构化输出：

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

const { output } = await generateText({
  model: 'openai/gpt-5.4',
  output: Output.object({
    schema: z.object({ ... }),
  }),
  prompt: 'Generate a lasagna recipe.',
});

结合 zod schema，模型输出会被约束成类型安全的对象，而不是一段等着自己解析的 JSON。这对对接业务系统是有实际价值的：你可以在 schema 层定义接口契约，省掉一层手写校验。

Agent 抽象：ToolLoopAgent

README 展示了基于工具的 agent 抽象。ToolLoopAgent 接收 model、system 和 tools，其中工具示例是 openai.tools.localShell：

const sandboxAgent = new ToolLoopAgent({
  model: 'openai/gpt-5.4',
  system: 'You are an agent with access to a shell environment.',
  tools: {
    shell: openai.tools.localShell({
      execute: async ({ action }) => { ... },
    }),
  },
});

这个示例表明，AI SDK 的 agent 模型是“循环执行工具调用”的结构，工具定义就是普通的对象加 execute 函数。README 里使用了 Vercel Sandbox 来跑命令，但关于 Sandbox 的具体用法不在 README 范围内，需要单独查文档。

这里真正值得注意的是：如果你已经在用其他 agent 框架，需要看它的工具协议是不是足够通用。AI SDK 的 agent 工具是本地 TypeScript 函数，和外部工具生态的衔接方式还比较原始，需要自己写适配层。

UI 集成与生成式 UI

AI SDK 单独有 UI module。官方 README 里强调 @ai-sdk/react 这类 hooks 是框架无关的，可用于 Next.js、React、Svelte、Vue。服务端通过 createAgentUIStreamResponse 把 agent 执行结果流式推给前端，前端用 useChat 消费消息。

官方还给出了一个完整的图像生成 agent 示例，其结构很典型：

服务端用 openai.tools.imageGeneration 定义工具，partialImages: 3 表明生成过程中的中间结果。
Next.js Route Handler 调用 createAgentUIStreamResponse。
前端组件根据 UIToolInvocation 的状态（input-available / output-available）渲染不同内容。
useChat 的 sendMessage 发送消息，status 控制 UI 状态。

这套设计把模型的工具调用变成了前端可感知的组件状态。对构建生成式 UI 的团队来说，这比自己在 socket 上做消息协议要省事。但同样，前后端都需要接 AI SDK 的流协议，等于引入了一个自己的通信层。

选型时值得验证的五个问题

基于 README 的公开信息，以下问题需要在正式接入前确认：

Node.js 22+ 的运行时要求是否被现有 CI/CD 和线上环境接受。
默认走 Vercel AI Gateway 是否满足数据合规要求；如果不满足，直连 provider SDK 的接入成本是否可接受。
示例中的模型字符串是否可用、最新版本是什么（README 不保证）。
ToolLoopAgent 的工具循环机制与项目现有 agent 架构是否兼容，特别是错误处理和重试策略。
UI 模块的流式协议是否与现有渲染链路匹配，尤其是非 React/Vue 场景。

结论

Vercel AI SDK 的价值在于把“多模型接入”这一个问题统一了，同时向上延伸到结构化输出、agent 和 UI 层，形成了从模型到界面的完整链路。它更适合那些愿意在早期就采用统一抽象、且能接受 Vercel 生态约定的 TypeScript 项目。至于 agent 的内部循环、网关的稳定性、直连包在具体 runtime 下的行为，README 没有展开，只能通过官方文档和实际压测来验证。

暂无评论，来说两句吧