Vercel AI SDK v7 深度评测：优秀的 TypeScript 应用层，但不是完整 AI 平台
Vercel AI SDK 是面向 Web 与 Node.js 应用的 Provider 中立 TypeScript 工具包。核心价值并不神秘：AI SDK Core 统一文本生成、结构化输出和工具调用；AI SDK UI 提供不同前端框架的 hooks 与数据流协议；Provider packages 把这些调用翻译成各模型 API。当前仓库要求 Node.js 22 或更高版本，开源代码使用 Apache 2.0 许可。
本文以 2026 年 8 月 19 日发布的 [email protected] 为核查基线。官方同时维护 v5、v6 分支，因此旧教程里的代码可能曾经正确，却不是当前 v7 写法。现行 Agent 文档使用 ToolLoopAgent 与 stopWhen；useChat 从 v5 起已转向 transport 架构，并不再内部管理输入框状态。复制代码前先看 lockfile。
还必须拆清产品边界：开源 SDK 可以直接调用 Provider package；Vercel AI Gateway 是独立的托管路由、账单与预算服务；AI Elements 是基于 shadcn/ui 的可选组件库；Vercel Cloud 的部署和观测也是另一套商业服务。把它们统称为“AI SDK 能力”，会掩盖真实数据流、费用与锁定。
2026 年当前状态
| 项目 | 截至 2026-08-20 的核实状态 | 决策影响 |
|---|---|---|
| 当前主版本 | [email protected]；v5/v6 仍有维护版本 | 固定 major，并阅读对应迁移文档 |
| 运行时 | 当前仓库要求 Node.js 22+ | 核对 serverless 与企业运行时政策 |
| 许可 | Apache License 2.0 | 模型、Provider 与托管服务另有条款 |
| Core | generateText、streamText、结构化输出、tools | 统一调用形状，不统一模型行为 |
| Agent | ToolLoopAgent，默认 stepCountIs(20) | 必须另设任务级步骤、时间和成本上限 |
| UI | React/Vue/Svelte/Angular transport 与富消息流 | 认证、持久化、断线恢复仍由应用负责 |
| 默认路线 | 当前 README 示例默认使用 AI Gateway | 仍可直接使用 Provider packages |
| Telemetry | 实验性 OpenTelemetry，逐次调用 opt-in | prompt、output 可能进入观测后端 |
哪些属于 SDK，哪些不是
| 层 | 提供什么 | 必须自己负责的边界 |
|---|---|---|
| AI SDK Core | 生成、流式、tool schema/result、结构化输出、usage | Provider 能力、finish reason 和 usage 并非完全可移植 |
| Provider packages | 模型 API adapter 和特有 options/metadata | 版本兼容与 feature parity 会变化 |
| AI SDK UI | useChat、transport、UI message/data stream | 认证、存储、重连与错误 UX |
| ToolLoopAgent | 多步工具循环、callback、停止与 approval | 不是 durable runtime、策略引擎或队列 |
| MCP client | 接入 MCP tools/resources/prompts；生产推荐 Streamable HTTP | MCP server 信任、凭据和 tool 授权 |
| AI Elements | 可选 UI component registry | 不是 Core runtime 的必需部分 |
| AI Gateway | 托管统一 endpoint、路由、预算、usage、fallback | 独立数据面、账户、价格与路由政策 |
| Vercel Cloud | 托管和 Observability 产品 | 安装 Apache SDK 不会自动获得 |
Provider 抽象、流式传输与 Agent 循环
Provider abstraction 真正有价值的范围，是文本、消息、tool call、structured result 和归一化 usage 这些公共交集。它不会让模型可互换：reasoning 字段、cached token、图片与文件输入、hosted tool、安全拒绝、tool-call ID、错误和 Provider options 都可能不同。测试日志应保留 providerMetadata、raw finish reason 与 warning；如果没有 capability matrix，所谓可移植性只是把差异推迟到线上暴露。
Streaming 分两层：服务端 streamText 产生模型与工具事件，AI SDK UI 再通过 transport 传到界面。纯文本协议很简单，但官方明确它无法携带 tool call、usage 与 finish reason。生产聊天必须定义 abort、retry、部分工具输出、重复事件、断线、重连和服务端错误的状态机。收到首 token 只证明连接开始工作，不证明最终消息、工具状态或计费记录一致。
ToolLoopAgent 是方便的循环，不是可靠性系统。模型不再调用工具、某工具没有 execute、需要人工批准或达到 stop condition 时循环才会结束。默认二十步对交互请求可能非常昂贵；应按任务设置更小的 step limit、总 timeout、AbortSignal、token/金额预算与工具权限。对结算、审批、数据同步等可重复业务，优先使用显式 workflow，把 Agent 限定在真正需要非确定性判断的节点。
可执行的迁移与评测流程
- 在 lockfile 固定 Node.js、
ai、UI 与 Provider package 版本，记录 major 和 release note。 - 画出当前 prompt、message、Provider option、tool schema、stream protocol、retry、存储与计费字段清单。
- 建立 capability matrix：tool calling、structured output、reasoning、文件/图片、安全字段、usage、context 与地区。
- 构建去敏 golden set，并加入 prompt injection、畸形参数、拒绝权限和重复副作用等对抗案例。
- 用薄的应用 adapter 包装 generateText/streamText；Provider 特有 option 保持显式，不要假装不存在。
- 加入服务端身份认证、tenant 授权、tool allowlist、approval、idempotency、timeout 与 step/token/cost budget。
- 观测归一化指标以及 raw warning/finish reason；未经政策许可，不把敏感 prompt 与 tool payload 写入 telemetry。
- Shadow 新路径，再按租户或流量 canary；比较质量、stream 完整性、tool success、latency 与真实账单。
- 测试 abort、断线、retry、Gateway/Provider failure；旧 adapter 保留到 rollback 演练成功。
- SDK major、adapter、model、prompt、tool 或 Gateway route 改变后，重跑全部回归。
切换 Provider 前应测什么
| 指标 | 测试方式 | 为什么重要 |
|---|---|---|
| 答案质量 | 任务 rubric 与盲测 pairwise review | 统一 API 不会统一模型行为 |
| 结构化输出 | schema 有效率与语义正确率 | 合法 JSON 也可能做错决定 |
| 工具行为 | 选择、参数、执行、approval、重复率 | 副作用是 Agent 最高风险面 |
| 流完整性 | 首/末事件、顺序、重连、取消 | UI 与服务端状态可能分叉 |
| 延迟 | 按模型/Provider 记录 p50/p95 首事件与完成 | route 和 tool 会影响体验 |
| Usage/成本 | 归一 token 对账 Provider invoice | 缓存/reasoning 计费口径不同 |
| 安全 | 注入、外泄、拒绝与权限测试 | tool output 是不可信输入 |
| 可靠性 | timeout、Provider error、fallback、rollback | Demo 通常没覆盖失败路径 |
迁移不能从改 import 开始。先盘点每个模型调用、system prompt、消息结构、tool schema、流式事件、retry、usage 字段和 Provider 特有 option；在去除隐私信息后冻结一批代表性生产 trace。Golden set 既要有正常请求，也要覆盖长上下文、多语言、拒绝、错误 tool argument、并发 tool、Provider error、断流以及刻意无法回答的问题。旧路径和新路径必须跑同一输入，并同时保存归一化结果与 raw provider 结果。
评测要拆阶段：模型答案质量、schema 有效、tool 选择正确、tool 执行成功、最终回答忠实度不是一个指标。还要记录首事件延迟、完整延迟、输入/输出/缓存 token、账单成本、取消是否成功、stream 是否正常结束。Agent 另外统计每次步数、重复调用、approval、timeout 与副作用重复率。先 shadow，再按租户或小流量 canary，并保留旧 adapter 和协议版本，才有真正 rollback。
OpenTelemetry 集成很实用，但官方仍标记为 experimental，并通过 experimental_telemetry 逐次启用。它可以记录 prompt、response text、tool call 与 attributes，所以应该把 telemetry 当成新的数据出口：默认删减敏感值、限制属性基数、设定 sampling、retention 与访问权限。Vercel 托管 Observability 是另一个产品；安装 ai 并不会自动得到完整 eval suite、trace store 或 incident workflow。
安全、隐私、成本与锁定边界
| 风险 | 具体控制 | 剩余边界 |
|---|---|---|
| Prompt injection | 分离 instruction/data；tool allowlist；验证目的地和输出 | 模型仍可能跟随恶意内容 |
| 越权工具操作 | 服务端解析身份/tenant，逐次授权 | Schema 不是 access control |
| 重复副作用 | idempotency key、transaction log、确认 UI | retry/重连仍可能重复 |
| Agent 成本失控 | stopWhen、timeout、token/step/tool budget | 默认二十步不是业务预算 |
| Telemetry 泄露 | 选择性启用、删敏、sample、限制 retention/access | 实验性 OTel 可导出 prompt/output |
| Gateway 漂移 | 固定 Provider/model/region 或限制路由 | fallback 用可复现性换可用性 |
| 版本错配 | 固定所有 AI SDK packages 并按 major 测试 | v5/v6 教程仍像新内容 |
| 虚假可移植 | 能力矩阵与 Provider 特有回归 | 公共类型不等于相同语义 |
与真实替代方案对比
| 方案 | 最适合 | 相对 AI SDK 的取舍 |
|---|---|---|
| Vercel AI SDK v7 | TypeScript 产品 UI、streaming、多 Provider | 应用体验强；durability 与 governance 自己做 |
| OpenAI Node SDK | 以 OpenAI Responses/Realtime/hosted feature 为中心 | 原生能力最快，Provider 耦合最强 |
| LangChain JS | 大量 integration、middleware、标准 Agent pattern | 概念面更大；配 LangGraph 可获得 runtime 能力 |
| LangGraph JS | 持久状态、checkpoint、interrupt、显式 graph | 编排更重，但可恢复性更强 |
| OpenAI Agents SDK TS | handoff、guardrail、session、内置 tracing 符合需求 | 以 Agent/OpenAI 为中心，可定制 model |
| 自写 fetch/Provider SDK | 单一模型、极小 surface、完全协议控制 | 依赖少；UI stream、tool 与 portability 自建 |
| AI SDK + Gateway | 统一账单、budget、route、fallback 有价值 | 便利增加 Vercel 数据与商业边界 |
安全职责主要位于 SDK 之上。Zod/JSON schema 只验证参数形状，不能证明当前用户有权退款、读取某 tenant 或发送邮件。每次 tool 调用都要在服务端解析身份与租户、执行授权、最小化 credential、验证 tool output、为副作用设置 idempotency key，并对高影响操作要求人工确认。检索文档、网页、MCP response 与历史 tool output 都是不可信数据，可能包含 prompt injection。
Gateway 自动路由和 fallback 可提升可用性，却可能改变模型行为、数据处理方、地区与价格。合规或可复现任务应固定 Provider，或至少限制 allowed set。作为时间快照，2026 年 2 月官方价格页列有每月免费 credits、PAYG 不加 token markup、BYOK 不收 Gateway fee；商业政策会变化，部署前必须查实时页面。直接 Provider package 减少 Vercel 数据面依赖，但预算、fallback 和统一 usage 要自己建设。
编辑结论：对需要多 Provider、流式 UI 和 TypeScript 全栈体验的产品团队，AI SDK v7 是目前很强的应用层选择，类型、UI 协议和 tool primitives 能显著减少胶水代码。但它并不自动解决 durable execution、权限、评测与运维。长时间、可恢复、多 Agent 后台任务更适合 LangGraph 或 workflow engine；强依赖 Provider 原生能力时，直接 SDK 更清楚。选择它应因为工程体验，而不是误以为安全、可移植性与生产治理免费附送。
常见问题
Vercel AI SDK 免费开源吗？
SDK 仓库是 Apache-2.0；模型 Provider、AI Gateway、Vercel Cloud 与付费依赖有各自价格和条款。
必须部署到 Vercel 吗？
不需要。它是 TypeScript library，可用于其他 Node.js 环境。Gateway 是当前示例的便利默认路线，但不是强制。
当前 major 是多少？
截至 2026-08-20，主版本为 [email protected]；v5/v6 仍有维护发布，因此一定检查 lockfile。
AI Gateway 属于开源 SDK 吗？
不属于。它是独立托管路由与账单服务；SDK 也能直接调用 Provider。
ToolLoopAgent 能安全地自主操作吗？
不能单靠它。仍需授权、allowlist、approval、idempotency、timeout、stop condition、audit 与对抗测试。
Provider abstraction 能保证相同输出吗？
不能。它统一常见请求形状，但模型行为、option、usage、error、安全字段与 feature 仍不同。
纯文本 stream 还是 UI message stream？
只有简单文本界面适合纯文本；tool call、usage、finish reason 与 rich part 需要 UI data/message protocol。
Telemetry 会发送 prompt/output 吗？
可能。实验性 OTel 是 opt-in，但支持敏感属性；必须明确删敏、采样、保留和访问策略。
何时选择 LangGraph？
当 durable execution、持久状态、interrupt、长任务与恢复是主要需求时。
如何安全迁移？
固定版本，保存旧 stream contract，运行 golden/failure suite，shadow、canary，并保留已验证 rollback adapter。
来源与核查
- AI SDK repository
- AI SDK releases
- Apache 2.0 license
- Core: generateText and streamText
- Tool calling
- ToolLoopAgent reference
- AI SDK UI transports
- AI SDK stream protocol
- MCP integration
- OpenTelemetry integration
- Vercel AI Gateway overview
- AI Gateway pricing
- AI Elements component library
- LangGraph JavaScript overview
- OpenAI Node SDK
- OpenAI Agents SDK for TypeScript
独立核查日期：2026 年 8 月 20 日。版本、Provider 支持、默认值和商业价格变化很快；上线前请核对实际安装包与官方实时页面。