从AI SDK v6升级到v7:OpenRouter ai-sdk-provider迁移清单与破坏性变更详解
从AI SDK v6升级到v7:OpenRouter ai-sdk-provider迁移清单与破坏性变更详解
对于使用 Vercel AI SDK 接入 OpenRouter 的开发者来说,从 AI SDK v6 升级到 v7 是一次需要认真对待的大版本迁移。OpenRouter 官方的 AI SDK Provider(@openrouter/ai-sdk-provider)在 v3.0.0 中针对 AI SDK v7 做了 v7-only 的重大版本发布:peer 依赖改为 ai@^7.0.0、强制要求 Node.js 22+、只发布 ESM 产物。本文将带你梳理全部破坏性变更,并给出一份可照做的迁移清单,帮助你在 10 分钟内安全完成升级。
一、先看懂版本对应关系:v6 和 v7 各用哪个 Provider?
在动手之前,先明确一个最容易踩的坑:Provider 的主版本号和 AI SDK 的主版本号是绑定的。对应关系如下:
| 你的 AI SDK 版本 | 应安装的 Provider 版本 | 说明 |
|---|---|---|
AI SDK v6(ai@6.x) |
@openrouter/ai-sdk-provider@2.9.1 |
旧版兼容线,已标记 LEGACY |
AI SDK v7(ai@7.x) |
@openrouter/ai-sdk-provider@3.x |
当前主线,v7-only |
官方 README 中已经明确区分了两条安装线,v6 线被标注为 (LEGACY)。如果你的项目还在 ai@6 上,建议先升到 ai@7,再升级 Provider,不要只升其中一边,否则 peer 依赖校验会直接报错。
升级命令很简单,以 npm 为例:
npm install ai@latest @openrouter/ai-sdk-provider@latest
如果你的项目需要自行构建或排查问题,仓库可以这样获取:
git clone https://gitcode.com/gh_mirrors/ai/ai-sdk-provider
二、5 个破坏性变更逐一详解
以下是 CHANGELOG.md 中 3.0.0 主版本发布的官方说明,共包含 5 项关键变更。
1. Peer 依赖收紧为 ai@^7.0.0
Provider 现在只接受 ai@^7.0.0。如果你的 package.json 里还装着 ai@6,包管理器在 install 阶段就会提示 peer 依赖冲突。这是本次迁移的第一道"关卡",也是提醒你同步升级 AI SDK 的信号。
2. 强制要求 Node.js 22+
package.json 中通过 engines 字段声明了 node >= 22:
- 如果你的运行环境还是 Node.js 18 或 20,CI 与本地都会报错
- 升级前建议先升级 Node.js 运行时(包括 Dockerfile 基础镜像、CI 环境、Serverless 平台运行时配置)
具体声明可见 package.json 中的 engines 字段。
3. 只发布 ESM 产物,CJS 项目要改导入方式
构建配置 tsup.config.ts 中 format 只保留了 ['esm'],不再输出 CommonJS。这意味着:
- 如果你的项目是
"type": "module"或 ESM 环境(Next.js、现代 Vite 项目),几乎无感,import { openrouter } from '@openrouter/ai-sdk-provider'写法不变 - 如果你是纯 CJS 项目(
require()风格),需要把项目迁移到 ESM,或改用动态import()加载该包
4. 模型实现升级为 @ai-sdk/provider@4 的 V4 接口
chat、completion、embedding、image、video 五类模型实现全部迁移到 V4 接口,带来两个实际影响:
- 文件载荷(file payloads)格式变化:V4 的文件部分使用新的载荷结构,涉及 PDF、图片、音视频等文件输入的场景需要回归测试
- 工具改用 provider-defined tool factory:Provider 内置的服务端工具(如
openrouter.tools.webSearch())现在基于createProviderToolFactory机制实现,自定义工具的写法与 v6 时代有所不同
模型入口源码分别在 src/chat/index.ts、src/completion/index.ts、src/embedding/index.ts、src/image/index.ts 和 src/video/index.ts,排查行为差异时可以直接对照。
5. Usage 统计形状改为 AI SDK v7 规范
这是日常开发中唯一需要改代码的变更。v7 中 token 明细换了访问路径:
| 数据 | v6 旧路径(示意) | v7 新路径 |
|---|---|---|
| 缓存命中的输入 token | 旧字段 | usage.inputTokenDetails.cacheReadTokens |
| 推理(思考)token | 旧字段 | usage.outputTokenDetails.reasoningTokens |
如果你的监控面板、成本报表或计费逻辑读取了这两个值,请务必按新路径调整。好消息是:OpenRouter 特有的元数据(cost、BYOK、reasoning details、annotations、cache-control)位置不变,仍然在 providerMetadata.openrouter 下,这部分代码无需改动。
三、迁移检查清单(照做即可)
按顺序执行,每完成一项打一个勾:
- [ ] 检查运行时:Node.js 是否 ≥ 22?(
node -v验证) - [ ] 升级依赖:
ai升到 7.x,@openrouter/ai-sdk-provider升到 3.x - [ ] 检查模块体系:确认项目为 ESM,或已改造
require引入方式 - [ ] 搜索代码:全局搜索 token 明细读取处,替换为
inputTokenDetails.cacheReadTokens/outputTokenDetails.reasoningTokens - [ ] 回归测试三类场景:带文件的对话(PDF/图片)、流式工具调用、
generateImage/videoModel多模态生成 - [ ] 验证元数据:请求一次后确认
providerMetadata.openrouter中的 cost、reasoning_details 等字段仍存在
四、升级后顺带获得的福利
升到 v3 线不只是"还债",还拿到了 2.x 后期积累的一批能力(详见 CHANGELOG.md):
- 🖼️ 独立图像生成端点:
imageModel从 chat completions 切换到专用/images端点,单次支持最多 10 张图 - 🎬 视频生成:
videoModel()支持文生视频与图生视频 - 🌐 服务端网络搜索:
openrouter.tools.webSearch()一行接入 - 💰 更精细的 usage:
noCache、cacheWrite等 token 明细自动补齐 - 🎯 3.1.0 新增:
evaluationModel()评测模型,支持 AI SDK 7.0.103+ 的experimental_evaluate
五、常见问题速答
Q:能只升 Provider 不升 AI SDK 吗?
不能。3.x 是 v7-only 的 major 版本,peer 依赖强制 ai@^7.0.0,必须两个一起升。
Q:暂时不想升 v7,还能留在 v6 吗?
可以。固定使用 @openrouter/ai-sdk-provider@2.9.1 配合 ai@6,这是官方维护的最后一条 v6 兼容线,但该线已进入 LEGACY 状态,后续功能不会再跟进。
Q:ESM-only 对 Next.js 项目有影响吗?
基本没有。Next.js 的 App Router 与服务端运行时天然支持 ESM,import 写法照常工作即可。
总结:本次 v6 → v7 迁移的核心动作只有四件事——升 Node 22、升 ai@7、确认 ESM 环境、改两处 token 明细读取路径。跟着上面的检查清单逐项核对,绝大多数项目可以一次通过。迁移完成后,别忘了在下一轮迭代中顺手体验一下图像批生成和视频生成这些新端点带来的便利。
