从 vercel/ai 看 TypeScript 构建 LLM 应用的工程路径

在 TypeScript 生态里构建 LLM 应用长期存在一个工程痛点模型厂商的 SDK 接口、流式协议、工具调用格式各不相同前端框架又各有自己的状态管理方式。vercel/aiAI SDK试图用一层 provider-agnostic 的抽象把这两端都收敛起来。它由 Vercel 与 Next.js 团队成员创建采用开源许可GitHub 上已有约 27k star、5.2k fork仓库 topics 明确标注了 openai、anthropic、gemini、language-model、generative-ui、nextjs、react、svelte、vue 等关键词。定位不是模型封装而是接入层官方 README 对它的定义是“provider-agnostic TypeScript toolkit”目标是帮助开发者用 Next.js、React、Svelte、Vue、Angular 等 UI 框架以及 Node.js 等运行时构建 AI 应用与 Agent。注意这里的措辞它不训练模型也不托管推理而是把“调用模型”这件事标准化。安装门槛是 Node.js 22 与 npm或其他包管理器核心包只有一个npm install ai。统一 Provider 架构字符串即模型AI SDK 的默认路径是走 Vercel AI Gateway开发者只需传一个模型字符串const result await generateText({ model: anthropic/claude-opus-5.5, prompt: Hello!, });README 中给出的示例还包括openai/gpt-6-astra、google/gemini-3.8-flash等写法。这种设计的工程价值在于切换模型不需要改调用代码结构只改一个字符串。如果不想经过 Gateway也可以直连厂商 SDK 包例如安装ai-sdk/openai、ai-sdk/anthropic、ai-sdk/google然后以函数形式传入模型import { anthropic } from ai-sdk/anthropic; const result await generateText({ model: anthropic(claude-opus-5-5), prompt: Hello!, });两条路径共用同一套generateText等上层 API差异被压缩在 model 参数的构造方式上。这是该库处理多 Provider 差异的核心思路把差异挡在参数层而不是让业务代码感知。结构化输出用 schema 约束返回值LLM 应用里另一类高频需求是拿到可解析的结构化数据。AI SDK 提供了Output.object配合 zod schema 的方式import { generateText, Output } from ai; import { z } from zod; const { output } await generateText({ model: openai/gpt-6-astra, output: Output.object({ schema: z.object({ recipe: z.object({ name: z.string(), ingredients: z.array( z.object({ name: z.string(), amount: z.string() }) ), steps: z.array(z.string()), }), }), }), prompt: Generate a lasagna recipe., });从工程角度看这相当于把“提示词工程”部分转化为“类型契约”schema 既是运行时校验也是 TypeScript 类型来源。对需要把模型输出直接喂给下游系统的场景这比手工解析 JSON 更可控。AgentToolLoopAgent 与工具循环README 中 Agent 能力由ToolLoopAgent承载。示例构造了一个带 shell 工具的 sandbox agentimport { ToolLoopAgent } from ai; const sandboxAgent new ToolLoopAgent({ model: openai/gpt-6-astra, system: You are an agent with access to a shell environment., tools: { shell: openai.tools.localShell({ execute: async ({ action }) { const [cmd, ...args] action.command; const sandbox await getSandbox(); const command await sandbox.runCommand({ cmd, args }); return { output: await command.stdout() }; }, }), }, });这里可以看到几个关键设计工具以对象形式注册execute是普通异步函数返回值即工具结果模型侧的工具定义如openai.tools.localShell与执行逻辑分离执行环境由开发者自己决定示例中是 Vercel Sandbox。ToolLoopAgent这个名字本身暗示了它会自动处理“模型请求工具 → 执行 → 回传结果 → 继续推理”的循环开发者不必手写 while 循环。生成式 UI把工具调用状态映射到组件AI SDK UI 模块提供了一组框架无关的 hooks可用于 Next.js、React、Svelte、Vue。以 React 为例需要安装ai-sdk/react。一个完整的图像生成 Agent 链路在 README 中被拆成四层第一层是 Agent 定义用InferAgentUIMessage导出消息类型export const imageGenerationAgent new ToolLoopAgent({ model: openai/gpt-6-astra, tools: { generateImage: openai.tools.imageGeneration({ partialImages: 3 }), }, }); export type ImageGenerationAgentMessage InferAgentUIMessagetypeof imageGenerationAgent;第二层是 Next.js App Router 的路由用createAgentUIStreamResponse把 agent 与 messages 转成流式响应export async function POST(req: Request) { const { messages } await req.json(); return createAgentUIStreamResponse({ agent: imageGenerationAgent, messages, }); }第三层是工具 UI 组件通过UIToolInvocation接收调用状态按input-available、output-available等 state 分支渲染export default function ImageGenerationView({ invocation }: { invocation: UIToolInvocation ReturnTypetypeof openai.tools.imageGeneration ; }) { switch (invocation.state) { case input-available: return divGenerating image.../div; case output-available: return img src{data:image/png;base64,${invocation.output.result}} /; } }第四层是页面组件用useChat拿到 messages、status、sendMessage然后遍历message.parts按part.type分派到文本或tool-generateImage组件。这条链路体现了“生成式 UI”的落地方式模型输出的不是纯文本而是带类型的 part 序列前端按 part 类型渲染不同组件。工具调用的中间状态生成中、已完成直接暴露给 UI开发者可以据此做加载态、流式图片等交互。适用边界与工程取舍从官方资料能确认的边界包括需要 Node.js 22默认走 Vercel AI Gateway直连厂商则需额外安装对应ai-sdk/*包UI hooks 覆盖 Next.js、React、Svelte、VueREADME 提到 Angular 属于支持框架之一但未给出对应示例代码。需要区分的是以下属于工程判断而非官方事实其一走 Gateway 还是直连厂商涉及网络路径、计费与合规官方 README 未展开对比其二ToolLoopAgent的循环终止条件、最大步数、错误重试策略等细节README 未说明实际使用需查阅 API Reference 与 Documentation其三结构化输出依赖 zod若项目已有其他校验方案需要评估引入成本。对正在选型的 TypeScript 团队来说这个库的吸引力在于它把多 Provider 差异、流式协议、工具调用循环、前端状态同步这几件重复劳动收敛成一套 API且与 Next.js 生态同源。代价是抽象层带来的调试复杂度以及默认路径对 Vercel 基础设施的倾向性。是否采用取决于项目对 Provider 可替换性的需求强度以及团队是否愿意接受这层抽象。