ai-sdk/provider 版本演进全解读从 Provider 规范层看 AI SDK 的多模态与异步能力升级【免费下载链接】aiThe AI Toolkit for TypeScript. From the creators of Next.js, the AI SDK is a free open-source library for building AI-powered applications and agents项目地址: https://gitcode.com/GitHub_Trending/ai/aiai-sdk/provider是 AI SDKThe AI Toolkit for TypeScript中定义Provider 与核心运行时之间契约的规范层包所有语言模型、嵌入模型、图像模型、语音/转录/视频模型以及批处理、文件上传等能力都必须实现这里定义的接口才能被 SDK 核心调用。本指南以该包 CHANGELOG.md 为骨架结合 packages/provider 下的源码实现完整梳理从 0.0.1 到 4.0.13 的版本演进脉络——你将掌握 v2/v3/v4 三代规范各自的能力边界、关键破坏性变更以及 batch、Realtime、视频异步生成、Provider References 等新特性的底层接口设计。一、ai-sdk/provider 在 AI SDK 中的定位从包导出入口 src/index.ts 可以看到这个包按模型类型组织成十余个独立模块language-model、embedding-model、image-model、speech-model、transcription-model、speech-translation-model、video-model、reranking-model、realtime-model、batch、files、skills、shared再加上统一的errors错误体系、providerProvider 聚合接口以及json-value等基础类型。换句话说凡是某个模型供应商能提供什么能力、以什么数据结构交互都收敛在这里。当前最新的ProviderV4聚合接口定义在 provider-v4.ts它把此前分散的模型入口统一挂在一个 Provider 对象上languageModel(modelId)/embeddingModel(modelId)/imageModel(modelId)核心三大入口modelId 会传递给 provider 工厂函数不存在的模型抛出NoSuchModelErrortranscriptionModel?/speechModel?/rerankingModel?可选能力只有支持对应模态的 Provider 才实现files?()返回FilesV4文件上传接口可直接传给uploadFileskills?()返回SkillsV4用于按 Provider 能力上传 SkillsspecificationVersion: v4标注本 Provider 实现的是哪一版规范——这正是 CHANGELOG 中反复出现的 spec v2 / v3 / v4 版本标记的运行时体现。语言模型侧由 language-model-v4.ts 定义契约specificationVersion: v4、provider如openai、modelId、supportedUrls按媒体类型声明哪些 URL 可以由模型原生读取、无需预下载以及两个核心方法doGenerate非流式与doStream流式。方法名带do前缀是刻意设计文档注释写明是为了防止用户直接误用真正的调用入口在ai包的generateText/streamText等高层 API。从 package.json 看当前版本为4.0.13type: module且exports只有 ESM 的import条件engines.node 22publishConfig.provenance: truenpm 包签名溯源。这些元数据与 CHANGELOG 4.0.0 中的两条破坏性变更完全对应移除 CommonJS 导出ESM-only与最低 Node.js 版本提升到 22支持 22/24/26。二、v4 规范批处理、异步视频与文件能力4.0.x 系列4.0.x 是当前最活跃的演进区间几乎每一版都引入一类新能力且全部落在上述源码目录中。按版本号逐项展开2.1 批处理BatchAPI 的落地与补全4.0.63469d0c首次引入 batch APIs对应源码 batch/v4 下的text-batch-v4-request.ts文本批处理请求、image-batch-v4-request.ts图像批处理请求与核心的batch-v4.ts4.0.11a4ba394支持 batch 中按请求per-request指定模型同一批次可以混合不同模型4.0.12 / 4.0.13912fb01 / 9942196连续两个 Patch 补齐batch cancel取消与 list列举API即已提交的批任务可以查询状态、中途取消4.0.8591d25b加入 batch 完成回调 Webhookexperimental_startTextBatch开始接受webhookUrlGateway provider 通过 batchcallbackUrl契约注册回调并导出类型化异步任务元数据而 Anthropic、OpenAI 直连 provider 在传入该选项时会返回不支持警告4.0.9aa45741Anthropic provider 修复了 batch 请求中保留原生消息批次计数native message batch request counts的问题并让 batch 请求支持完整的语言模型选项面。2.2 视频生成从同步生成到异步任务化视频模型是 v4 规范中演进最密集的领域源码 video-model/v4 下除了video-model-v4.ts本体还有frame-image首帧/尾帧图像、file视频输入文件、result结果等类型文件4.0.579e133c为实验性视频模型接口VideoModelV4增加异步 start/status 流程——模型可以实现doStart、doStatus、handleWebhookOption来替代或补充doGenerate对应源码video-model-v4-operation-start-result.ts、video-model-v4-operation-status-result.ts、video-model-v4-operation-webhook.ts。高层 APIexperimental_generateVideo相应接受poll轮询与webhook回调两种完成编排方式且轮询配置支持自定义延迟实现便于接入 durable workflow持久化工作流等场景4.0.7ad6a650generateVideo支持aspectRatio: adaptive。部分视频模型如 BytePlus Seedance 2.5 的首帧、首尾帧、编辑与扩展任务会从输入推导输出比例、拒绝显式的{width}:{height}因此VideoModelV3CallOptions与VideoModelV4CallOptions上的aspectRatio类型从纯数字比例扩展为${number}:${number} | adaptive这些调用不再需要类型断言支持与否因 Provider 而异4.0.10274f34视频生成增加一等公民的frameImages与inputReferences调用选项4.0.30f93c57进一步让inputReferences支持视频而不只是图像作为参考输入用于参照视频生成视频。2.3 文件接口 FilesV4 的能力扩展4.0.104.0.105190b67是文件能力的一次大版本级补强对应 files/v4 下十个文件FilesV4接口新增可选的getFileMetadata查询元数据、downloadFile流式下载、deleteFile删除三类操作并有各自独立的 call options / result 类型文件上传与下载调用统一支持abortSignal与headers上传数据新增{ type: stream }变体流式上传上传结果新增byteSize、createdAt、expiresAt字段核心的uploadFile()助手同步透传abortSignal/headersprovider-utils 侧新增postMultipartStreamToApi流式 multipart 上传具有确定性的分片顺序与失败路径流清理、deleteFromApi与createBinaryStreamResponseHandler。2.4 语音翻译与流式转录4.0.41e2f324新增实验性语音翻译模型规范Experimental_SpeechTranslationModelV4与experimental_streamTranslate支持流式语音到语音翻译对应源码 speech-translation-model/v4含六份文件4.0.25c5c0f5转录模型增加实验性流式转录支持示例实现包括 OpenAIgpt-realtime-whisper与 xAI WebSocket STT。2.5 4.0.0v7 预发布与一批架构级 Major Change4.0.0 标记了 AI SDK v7 预发布8359612 Start v7 pre-release并集中落下一批 Major Changesf7d4f01新增reasoning-file内容类型用于标记属于推理过程的文件对应源码 language-model-v4-reasoning-file.ts776b617新增custom内容类型language-model-v4-custom-content.ts为供应商自定义内容留出扩展位34bd95d支持通过 Provider References 抽象上传 Provider Skills配合 4.0.0 中uploadFile/uploadSkill可直接传 Provider 实例e311194c29a26fProvider References 抽象落地支持按 Provider 能力上传文件3887c70规范新增顶层reasoning参数并在generateText/streamText中生效9bd6512文件部件file part的 data 属性改为带类型标签同时移除 image part 类型图像统一收敛为 file part5463d0d工具结果输出的 file part 类型与顶层消息的 file part 类型对齐ef992f8所有包移除 CommonJS 导出全面 ESM-only详见下文迁移章节7fc6bd6最低 Node.js 版本提升至 22支持 22/24/26。三、Realtime 语音对话一类全新的规范模块4.0.0-canary.184.0.0-canary.18ce769dd引入了Experimental_RealtimeModelV4把语音到语音speech-to-speech实时对话提升为一等能力并在 4.0.0 中正式随 v7 预发布。其源码模块 realtime-model/v4 包含八份文件模型本体、标准化客户端事件realtime-model-v4-client-event.ts与服务端事件realtime-model-v4-server-event.ts、会话配置session-config、会话条目conversation-item、临时令牌client-secret、工具定义tool-definition与工厂realtime-factory-v4.ts。配套能力按 CHANGELOG 的记录包括OpenAI、Google、xAI 三家实时 Provider 实现openai.experimental_realtime()、google.experimental_realtime()、xai.experimental_realtime()服务端与浏览器均可使用每个 Provider 提供静态方法.getToken()用于服务端创建临时ephemeral令牌experimental_getRealtimeToolDefinitions助手为 Provider 会话生成工具定义ai-sdk/react提供experimental_useRealtimeHook返回与useChat对齐的UIMessage[]并通过onToolCall与addToolOutput支持客户端驱动的工具执行会话配置inputAudioTranscription可在 Provider 支持时展示用户语音的转写文本消息。这套设计把实时语音会话从 Provider 私有的 WebSocket 协议中抽象成规范化事件流使上层 UI 层与具体供应商解耦。四、v3 规范中间件、工具批准与模型矩阵扩张3.0.x3.0.x 对应 AI SDK 63.0.0 dee8b05 ai SDK 6 beta核心工作是shared spec v30adc679——把各模型规范共用的类型抽到 shared/v3并统一警告体系SharedV3Warninga755db5457318b 统一 warnings。几个关键点4.1 Provider 与模型规范的 v3 化ProviderV3ed329cb引入specificationVersion字段0c3b58b供运行时识别规范版本LanguageModelV38dac895工具参数从args/result演进为input/output63f9e9b 在 v2 阶段完成LanguageModelV3ToolResult[result]类型从unknown收紧为NonNullableJSONValuebb36798EmbeddingModelV30c4822d移除泛型并重命名入口8d9e8ad——从model.textEmbeddingModel(my-model-id)改为model.embeddingModel(my-model-id)旧名字以deprecated textEmbeddingModel别名保留366f50bImageModelV3522f6b8与图像编辑9061dc0、speech model v3 spec046aa3b、reranking modeld1bdadb见 reranking-model/v3embedding 调用警告53f3368与扩展 token usage3bd2689推理 token、缓存输入 token、总 token。4.2 中间件体系wrapLanguageModel / wrapEmbeddingModel / wrapImageModelwrapEmbeddingModel37c58a0带来与wrapLanguageModel相似的嵌入模型定制能力对应源码 embedding-model-middleware/v33.0.2d937c8f新增wrapImageModel与ImageModelV3Middleware把中间件模式扩展到图像模型image-model-middleware/v3。4.3 工具执行与批准Tool Execution Approval这一组变更把工具调用从模型单方决定推进到应用可审批的阶段tool execution approvale8109d3调用工具前可插入批准环节对应 language-model-v4-tool-approval-request.tsv4 中持续演进与 v3 同源类型provider-executed dynamic tools81d4308由 Provider 侧执行的动态工具以及初步的 provider executed tool results2b0caefv2.1.0-beta.4provider tool命名统一544d4e8 将 v3 provider defined tool 更名为 provider tool支持自定义名称954c356tool-specific strict mode1bd7d32严格模式可以按工具单独开启tool input examplesdce03c4工具输入示例便于模型理解调用格式flexible tool output content3794514工具输出内容支持更灵活的多种形态v4 阶段进一步把image-*工具输出类型并入file-*见 4.0.0-beta.12 ff5eba1。4.4 其他 v3 收尾raw finish reason 暴露cbf52cd模型原始结束原因透出JSONObject允许undefined值4c44a5bCallWarning修复并允许字符串作为 type10d819bv3 规范不再复用共享的 v3 类型以外的 v3 类型混用问题5c2a5a2并为 v4 预留了各模型接口拥有各自独立返回类型定义176466a。五、v2 规范命名统一与内容部件重构2.0.x / AI SDK 52.0.0 标记 AI SDK 5d5f588f是一次大规模规范化重构绝大多数改动是改名、合并、重构型 Major Change理解它们对跨版本迁移至关重要5.1 命名统一改了什么变更项变更内容providerMetadata→providerOptions所有模型规范的供应商元数据入参统一命名33f4a6amaxTokens→maxOutputTokens与输出 token语义对齐1766edemimeType→mediaType文件/转录等所有媒体类型字段统一abf9a790a87932ImageModelV1→ImageModelV2图像模型规范升级9301f86getSupportedUrls→supportedUrls语言模型支持的 URL 声明从方法改为属性7b3ae3f95857aa 重构 supported urls 结构rawRequest并入requestv2 语言模型请求对象合并d1a1aa16f6bb89 清理 request/rawRequest移除mode/prompt type/object generation mode/logprobs简化规范面c57e248e0306157ea4132e86be6f移除 v1 providers0d06df6彻底清退旧版规范5.2 内容部件content parts全面重构2.0.0-canary.6 一次性重构了全部部件类型并沿用至今v4 的 language-model-v4-content.ts 即其后续形态text parts32831c6、file partsd0f9495并抽出LanguageModelV2File79457bd、source parts0054544文件走向 source 模式14c9410、reasoning partsd9c98f4a3f768e 重构 reasoning 支持、tool call / tool call delta parts9e9c809移除 image parts6dc848c图像统一走 file partdoGenerate 返回 content 数组3795467输出结构标准化流式规范把warnings 移入 stream-start partb6b43c7内容块id、streaming start/end 事件转发742b7be。5.3 file part 支持二进制数据含代码示例2.0.0-canary.5ad80501允许 file part 同时接受二进制与 base64内容CHANGELOG 给出了直观的前后对比// Before必须手动把二进制转成 base64 import { convertUint8ArrayToBase64 } from ai-sdk/provider-utils; const fileData new Uint8Array([0, 1, 2, 3]); const filePart { type: file, mediaType: application/pdf, data: convertUint8ArrayToBase64(fileData), // Required conversion };// After直接传 Uint8Array const fileData new Uint8Array([0, 1, 2, 3]); const filePart { type: file, mediaType: application/pdf, data: fileData, // Direct Uint8Array support };5.4 usage 信息扩展与图像 providerMetadata 示例usage 支持 reasoning tokens、cached input tokens、total token7979f7fImageModelV2增加providerMetadata9bd5ab5使experimental_generateImage能返回 OpenAI 图像模型的修订提示词const prompt Santa Claus driving a Cadillac; const { providerMetadata } await experimental_generateImage({ model: openai.image(dall-e-3), prompt, }); const revisedPrompt providerMetadata.openai.images[0]?.revisedPrompt; console.log({ prompt, revisedPrompt });注该示例源自 2.0.0-canary.13 时代的 API 形态当前版本接口以 image-model/v4 为准。5.5 v2 阶段的模型矩阵扩展语音experimental_generateSpeech8aa9e20与转录experimental_transcribea166433升级到 v2 规范7435eb5、44f4aba并支持任意媒体类型进入工具结果023ba40、raw chunk 支持e2aceaf、embed-many 尊重supportsParallelCalls与并发度a8c8bd5、provider 注册表加入转录与语音模型cb68df0等。六、早期演进1.x / 0.x 的从零到一1.0.0 及之前的版本奠定了规范层的基石CHANGELOG 记录了这些基础能力何时出现0.0.22引入ProviderV1规范26515cb错误体系TypeValidationError4bd27a9 重构0.0.10 修复isTypeValidationError、DownloadError09295e2e、additional error types6a50ac4、unknown finish reason8e780288、UnsupportedFunctionalityError增加 message 选项19a2ce7、NoImageGeneratedError3a58a2e模型能力结构化输出0.0.16、toolChoice0.0.12 f39c0dd2、stopSequences与topK设置0.0.13、responseFormat0.0.13、headers 支持0.0.11 5edc6110、PDF 输入支持1.0.11、模型生成文件1.0.12、多部分工具结果0.0.26含图像、file content parts0.0.24、provider-defined tools0.0.26、embed 与 embedMany token usage0.0.12透传能力raw response body1.0.10 e1d3d42、raw request body0.0.25 b9b0d7b、response id/model/timestamp 透出0.0.23、raw response headers0.0.2、logprobs0.0.2感谢 SamStenner 贡献1.0.0 的清理移除isXXXError方法族b469a7e与toJSON方法c0ddc240.0.1 的破坏性变更eb150a6移除设置值的缩放逻辑——使用 temperature、frequency penalty、presence penalty 时不再自动缩放需要更新 Provider 并自行调整取值。这一决策奠定了后续规范只定义语义、不替 Provider 做魔法换算的原则。七、升级与迁移要点给开发者的破坏性变更清单综合 CHANGELOG 中的 Major/Breaking 变更从旧版本升级到当前 4.0.13 时最需要关注ESM-only4.0.0 / ef992f8所有包移除 CommonJS 导出require()用户必须切换到 ESMimport语法Node.js 版本4.0.0 / 7fc6bd6最低 Node 22官方支持 22、24、26Embedding 入口重命名3.0.0 / 8d9e8adtextEmbeddingModel(id)→embeddingModel(id)旧名保留为 deprecated 别名内容类型收敛4.0.0file part 的 data 带类型标签、移除 image partimage-*工具输出类型并入file-*4.0.0-beta.12设置值不再缩放0.0.1temperature 等取值直接透传给 Provider需按各模型文档设置v2 命名体系providerMetadata→providerOptions、maxTokens→maxOutputTokens、mimeType→mediaTypekebab-case 警告4.0.0-beta.8 / 008271dopenai-compatible provider 对 kebab-case 入参发出警告应改用 camelCase。八、如何基于本仓库继续深入如果想从读 CHANGELOG升级到读实现建议按以下路径在 packages/provider 中展开入口src/index.ts 查看全部导出模块聚合接口provider/v4/provider-v4.ts 看一个 Provider 对象能提供哪些模型入口语言模型契约language-model/v4/language-model-v4.ts 与同目录下的 call options、prompt、stream part、usage 等类型文件新能力模块batchbatch/v4、filesfiles/v4、realtimerealtime-model/v4、视频异步任务video-model/v4配套实现规范层的消费者在 packages/ai高层 API 与 uploadFile/uploadSkill 助手、packages/provider-utilspostMultipartStreamToApi、deleteFromApi、createBinaryStreamResponseHandler等工具以及各供应商包如 packages/openai、packages/anthropic、packages/google、packages/gateway它们展示了同一规范在不同供应商下的落地差异。简而言之CHANGELOG 记录的是能力何时出现而 src 目录记录的是能力如何被类型化地表达。把两者对照阅读就能准确掌握 AI SDK 规范层从 v1 到 v4 的完整演化逻辑以及在升级或自研 Provider 时应当遵循的接口边界。【免费下载链接】aiThe AI Toolkit for TypeScript. From the creators of Next.js, the AI SDK is a free open-source library for building AI-powered applications and agents项目地址: https://gitcode.com/GitHub_Trending/ai/ai创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考 @ai-sdk/provider 版本演进全解读：从 Provider 规范层看 AI SDK 的多模态与异步能力升级
ai-sdk/provider 版本演进全解读从 Provider 规范层看 AI SDK 的多模态与异步能力升级【免费下载链接】aiThe AI Toolkit for TypeScript. From the creators of Next.js, the AI SDK is a free open-source library for building AI-powered applications and agents项目地址: https://gitcode.com/GitHub_Trending/ai/aiai-sdk/provider是 AI SDKThe AI Toolkit for TypeScript中定义Provider 与核心运行时之间契约的规范层包所有语言模型、嵌入模型、图像模型、语音/转录/视频模型以及批处理、文件上传等能力都必须实现这里定义的接口才能被 SDK 核心调用。本指南以该包 CHANGELOG.md 为骨架结合 packages/provider 下的源码实现完整梳理从 0.0.1 到 4.0.13 的版本演进脉络——你将掌握 v2/v3/v4 三代规范各自的能力边界、关键破坏性变更以及 batch、Realtime、视频异步生成、Provider References 等新特性的底层接口设计。一、ai-sdk/provider 在 AI SDK 中的定位从包导出入口 src/index.ts 可以看到这个包按模型类型组织成十余个独立模块language-model、embedding-model、image-model、speech-model、transcription-model、speech-translation-model、video-model、reranking-model、realtime-model、batch、files、skills、shared再加上统一的errors错误体系、providerProvider 聚合接口以及json-value等基础类型。换句话说凡是某个模型供应商能提供什么能力、以什么数据结构交互都收敛在这里。当前最新的ProviderV4聚合接口定义在 provider-v4.ts它把此前分散的模型入口统一挂在一个 Provider 对象上languageModel(modelId)/embeddingModel(modelId)/imageModel(modelId)核心三大入口modelId 会传递给 provider 工厂函数不存在的模型抛出NoSuchModelErrortranscriptionModel?/speechModel?/rerankingModel?可选能力只有支持对应模态的 Provider 才实现files?()返回FilesV4文件上传接口可直接传给uploadFileskills?()返回SkillsV4用于按 Provider 能力上传 SkillsspecificationVersion: v4标注本 Provider 实现的是哪一版规范——这正是 CHANGELOG 中反复出现的 spec v2 / v3 / v4 版本标记的运行时体现。语言模型侧由 language-model-v4.ts 定义契约specificationVersion: v4、provider如openai、modelId、supportedUrls按媒体类型声明哪些 URL 可以由模型原生读取、无需预下载以及两个核心方法doGenerate非流式与doStream流式。方法名带do前缀是刻意设计文档注释写明是为了防止用户直接误用真正的调用入口在ai包的generateText/streamText等高层 API。从 package.json 看当前版本为4.0.13type: module且exports只有 ESM 的import条件engines.node 22publishConfig.provenance: truenpm 包签名溯源。这些元数据与 CHANGELOG 4.0.0 中的两条破坏性变更完全对应移除 CommonJS 导出ESM-only与最低 Node.js 版本提升到 22支持 22/24/26。二、v4 规范批处理、异步视频与文件能力4.0.x 系列4.0.x 是当前最活跃的演进区间几乎每一版都引入一类新能力且全部落在上述源码目录中。按版本号逐项展开2.1 批处理BatchAPI 的落地与补全4.0.63469d0c首次引入 batch APIs对应源码 batch/v4 下的text-batch-v4-request.ts文本批处理请求、image-batch-v4-request.ts图像批处理请求与核心的batch-v4.ts4.0.11a4ba394支持 batch 中按请求per-request指定模型同一批次可以混合不同模型4.0.12 / 4.0.13912fb01 / 9942196连续两个 Patch 补齐batch cancel取消与 list列举API即已提交的批任务可以查询状态、中途取消4.0.8591d25b加入 batch 完成回调 Webhookexperimental_startTextBatch开始接受webhookUrlGateway provider 通过 batchcallbackUrl契约注册回调并导出类型化异步任务元数据而 Anthropic、OpenAI 直连 provider 在传入该选项时会返回不支持警告4.0.9aa45741Anthropic provider 修复了 batch 请求中保留原生消息批次计数native message batch request counts的问题并让 batch 请求支持完整的语言模型选项面。2.2 视频生成从同步生成到异步任务化视频模型是 v4 规范中演进最密集的领域源码 video-model/v4 下除了video-model-v4.ts本体还有frame-image首帧/尾帧图像、file视频输入文件、result结果等类型文件4.0.579e133c为实验性视频模型接口VideoModelV4增加异步 start/status 流程——模型可以实现doStart、doStatus、handleWebhookOption来替代或补充doGenerate对应源码video-model-v4-operation-start-result.ts、video-model-v4-operation-status-result.ts、video-model-v4-operation-webhook.ts。高层 APIexperimental_generateVideo相应接受poll轮询与webhook回调两种完成编排方式且轮询配置支持自定义延迟实现便于接入 durable workflow持久化工作流等场景4.0.7ad6a650generateVideo支持aspectRatio: adaptive。部分视频模型如 BytePlus Seedance 2.5 的首帧、首尾帧、编辑与扩展任务会从输入推导输出比例、拒绝显式的{width}:{height}因此VideoModelV3CallOptions与VideoModelV4CallOptions上的aspectRatio类型从纯数字比例扩展为${number}:${number} | adaptive这些调用不再需要类型断言支持与否因 Provider 而异4.0.10274f34视频生成增加一等公民的frameImages与inputReferences调用选项4.0.30f93c57进一步让inputReferences支持视频而不只是图像作为参考输入用于参照视频生成视频。2.3 文件接口 FilesV4 的能力扩展4.0.104.0.105190b67是文件能力的一次大版本级补强对应 files/v4 下十个文件FilesV4接口新增可选的getFileMetadata查询元数据、downloadFile流式下载、deleteFile删除三类操作并有各自独立的 call options / result 类型文件上传与下载调用统一支持abortSignal与headers上传数据新增{ type: stream }变体流式上传上传结果新增byteSize、createdAt、expiresAt字段核心的uploadFile()助手同步透传abortSignal/headersprovider-utils 侧新增postMultipartStreamToApi流式 multipart 上传具有确定性的分片顺序与失败路径流清理、deleteFromApi与createBinaryStreamResponseHandler。2.4 语音翻译与流式转录4.0.41e2f324新增实验性语音翻译模型规范Experimental_SpeechTranslationModelV4与experimental_streamTranslate支持流式语音到语音翻译对应源码 speech-translation-model/v4含六份文件4.0.25c5c0f5转录模型增加实验性流式转录支持示例实现包括 OpenAIgpt-realtime-whisper与 xAI WebSocket STT。2.5 4.0.0v7 预发布与一批架构级 Major Change4.0.0 标记了 AI SDK v7 预发布8359612 Start v7 pre-release并集中落下一批 Major Changesf7d4f01新增reasoning-file内容类型用于标记属于推理过程的文件对应源码 language-model-v4-reasoning-file.ts776b617新增custom内容类型language-model-v4-custom-content.ts为供应商自定义内容留出扩展位34bd95d支持通过 Provider References 抽象上传 Provider Skills配合 4.0.0 中uploadFile/uploadSkill可直接传 Provider 实例e311194c29a26fProvider References 抽象落地支持按 Provider 能力上传文件3887c70规范新增顶层reasoning参数并在generateText/streamText中生效9bd6512文件部件file part的 data 属性改为带类型标签同时移除 image part 类型图像统一收敛为 file part5463d0d工具结果输出的 file part 类型与顶层消息的 file part 类型对齐ef992f8所有包移除 CommonJS 导出全面 ESM-only详见下文迁移章节7fc6bd6最低 Node.js 版本提升至 22支持 22/24/26。三、Realtime 语音对话一类全新的规范模块4.0.0-canary.184.0.0-canary.18ce769dd引入了Experimental_RealtimeModelV4把语音到语音speech-to-speech实时对话提升为一等能力并在 4.0.0 中正式随 v7 预发布。其源码模块 realtime-model/v4 包含八份文件模型本体、标准化客户端事件realtime-model-v4-client-event.ts与服务端事件realtime-model-v4-server-event.ts、会话配置session-config、会话条目conversation-item、临时令牌client-secret、工具定义tool-definition与工厂realtime-factory-v4.ts。配套能力按 CHANGELOG 的记录包括OpenAI、Google、xAI 三家实时 Provider 实现openai.experimental_realtime()、google.experimental_realtime()、xai.experimental_realtime()服务端与浏览器均可使用每个 Provider 提供静态方法.getToken()用于服务端创建临时ephemeral令牌experimental_getRealtimeToolDefinitions助手为 Provider 会话生成工具定义ai-sdk/react提供experimental_useRealtimeHook返回与useChat对齐的UIMessage[]并通过onToolCall与addToolOutput支持客户端驱动的工具执行会话配置inputAudioTranscription可在 Provider 支持时展示用户语音的转写文本消息。这套设计把实时语音会话从 Provider 私有的 WebSocket 协议中抽象成规范化事件流使上层 UI 层与具体供应商解耦。四、v3 规范中间件、工具批准与模型矩阵扩张3.0.x3.0.x 对应 AI SDK 63.0.0 dee8b05 ai SDK 6 beta核心工作是shared spec v30adc679——把各模型规范共用的类型抽到 shared/v3并统一警告体系SharedV3Warninga755db5457318b 统一 warnings。几个关键点4.1 Provider 与模型规范的 v3 化ProviderV3ed329cb引入specificationVersion字段0c3b58b供运行时识别规范版本LanguageModelV38dac895工具参数从args/result演进为input/output63f9e9b 在 v2 阶段完成LanguageModelV3ToolResult[result]类型从unknown收紧为NonNullableJSONValuebb36798EmbeddingModelV30c4822d移除泛型并重命名入口8d9e8ad——从model.textEmbeddingModel(my-model-id)改为model.embeddingModel(my-model-id)旧名字以deprecated textEmbeddingModel别名保留366f50bImageModelV3522f6b8与图像编辑9061dc0、speech model v3 spec046aa3b、reranking modeld1bdadb见 reranking-model/v3embedding 调用警告53f3368与扩展 token usage3bd2689推理 token、缓存输入 token、总 token。4.2 中间件体系wrapLanguageModel / wrapEmbeddingModel / wrapImageModelwrapEmbeddingModel37c58a0带来与wrapLanguageModel相似的嵌入模型定制能力对应源码 embedding-model-middleware/v33.0.2d937c8f新增wrapImageModel与ImageModelV3Middleware把中间件模式扩展到图像模型image-model-middleware/v3。4.3 工具执行与批准Tool Execution Approval这一组变更把工具调用从模型单方决定推进到应用可审批的阶段tool execution approvale8109d3调用工具前可插入批准环节对应 language-model-v4-tool-approval-request.tsv4 中持续演进与 v3 同源类型provider-executed dynamic tools81d4308由 Provider 侧执行的动态工具以及初步的 provider executed tool results2b0caefv2.1.0-beta.4provider tool命名统一544d4e8 将 v3 provider defined tool 更名为 provider tool支持自定义名称954c356tool-specific strict mode1bd7d32严格模式可以按工具单独开启tool input examplesdce03c4工具输入示例便于模型理解调用格式flexible tool output content3794514工具输出内容支持更灵活的多种形态v4 阶段进一步把image-*工具输出类型并入file-*见 4.0.0-beta.12 ff5eba1。4.4 其他 v3 收尾raw finish reason 暴露cbf52cd模型原始结束原因透出JSONObject允许undefined值4c44a5bCallWarning修复并允许字符串作为 type10d819bv3 规范不再复用共享的 v3 类型以外的 v3 类型混用问题5c2a5a2并为 v4 预留了各模型接口拥有各自独立返回类型定义176466a。五、v2 规范命名统一与内容部件重构2.0.x / AI SDK 52.0.0 标记 AI SDK 5d5f588f是一次大规模规范化重构绝大多数改动是改名、合并、重构型 Major Change理解它们对跨版本迁移至关重要5.1 命名统一改了什么变更项变更内容providerMetadata→providerOptions所有模型规范的供应商元数据入参统一命名33f4a6amaxTokens→maxOutputTokens与输出 token语义对齐1766edemimeType→mediaType文件/转录等所有媒体类型字段统一abf9a790a87932ImageModelV1→ImageModelV2图像模型规范升级9301f86getSupportedUrls→supportedUrls语言模型支持的 URL 声明从方法改为属性7b3ae3f95857aa 重构 supported urls 结构rawRequest并入requestv2 语言模型请求对象合并d1a1aa16f6bb89 清理 request/rawRequest移除mode/prompt type/object generation mode/logprobs简化规范面c57e248e0306157ea4132e86be6f移除 v1 providers0d06df6彻底清退旧版规范5.2 内容部件content parts全面重构2.0.0-canary.6 一次性重构了全部部件类型并沿用至今v4 的 language-model-v4-content.ts 即其后续形态text parts32831c6、file partsd0f9495并抽出LanguageModelV2File79457bd、source parts0054544文件走向 source 模式14c9410、reasoning partsd9c98f4a3f768e 重构 reasoning 支持、tool call / tool call delta parts9e9c809移除 image parts6dc848c图像统一走 file partdoGenerate 返回 content 数组3795467输出结构标准化流式规范把warnings 移入 stream-start partb6b43c7内容块id、streaming start/end 事件转发742b7be。5.3 file part 支持二进制数据含代码示例2.0.0-canary.5ad80501允许 file part 同时接受二进制与 base64内容CHANGELOG 给出了直观的前后对比// Before必须手动把二进制转成 base64 import { convertUint8ArrayToBase64 } from ai-sdk/provider-utils; const fileData new Uint8Array([0, 1, 2, 3]); const filePart { type: file, mediaType: application/pdf, data: convertUint8ArrayToBase64(fileData), // Required conversion };// After直接传 Uint8Array const fileData new Uint8Array([0, 1, 2, 3]); const filePart { type: file, mediaType: application/pdf, data: fileData, // Direct Uint8Array support };5.4 usage 信息扩展与图像 providerMetadata 示例usage 支持 reasoning tokens、cached input tokens、total token7979f7fImageModelV2增加providerMetadata9bd5ab5使experimental_generateImage能返回 OpenAI 图像模型的修订提示词const prompt Santa Claus driving a Cadillac; const { providerMetadata } await experimental_generateImage({ model: openai.image(dall-e-3), prompt, }); const revisedPrompt providerMetadata.openai.images[0]?.revisedPrompt; console.log({ prompt, revisedPrompt });注该示例源自 2.0.0-canary.13 时代的 API 形态当前版本接口以 image-model/v4 为准。5.5 v2 阶段的模型矩阵扩展语音experimental_generateSpeech8aa9e20与转录experimental_transcribea166433升级到 v2 规范7435eb5、44f4aba并支持任意媒体类型进入工具结果023ba40、raw chunk 支持e2aceaf、embed-many 尊重supportsParallelCalls与并发度a8c8bd5、provider 注册表加入转录与语音模型cb68df0等。六、早期演进1.x / 0.x 的从零到一1.0.0 及之前的版本奠定了规范层的基石CHANGELOG 记录了这些基础能力何时出现0.0.22引入ProviderV1规范26515cb错误体系TypeValidationError4bd27a9 重构0.0.10 修复isTypeValidationError、DownloadError09295e2e、additional error types6a50ac4、unknown finish reason8e780288、UnsupportedFunctionalityError增加 message 选项19a2ce7、NoImageGeneratedError3a58a2e模型能力结构化输出0.0.16、toolChoice0.0.12 f39c0dd2、stopSequences与topK设置0.0.13、responseFormat0.0.13、headers 支持0.0.11 5edc6110、PDF 输入支持1.0.11、模型生成文件1.0.12、多部分工具结果0.0.26含图像、file content parts0.0.24、provider-defined tools0.0.26、embed 与 embedMany token usage0.0.12透传能力raw response body1.0.10 e1d3d42、raw request body0.0.25 b9b0d7b、response id/model/timestamp 透出0.0.23、raw response headers0.0.2、logprobs0.0.2感谢 SamStenner 贡献1.0.0 的清理移除isXXXError方法族b469a7e与toJSON方法c0ddc240.0.1 的破坏性变更eb150a6移除设置值的缩放逻辑——使用 temperature、frequency penalty、presence penalty 时不再自动缩放需要更新 Provider 并自行调整取值。这一决策奠定了后续规范只定义语义、不替 Provider 做魔法换算的原则。七、升级与迁移要点给开发者的破坏性变更清单综合 CHANGELOG 中的 Major/Breaking 变更从旧版本升级到当前 4.0.13 时最需要关注ESM-only4.0.0 / ef992f8所有包移除 CommonJS 导出require()用户必须切换到 ESMimport语法Node.js 版本4.0.0 / 7fc6bd6最低 Node 22官方支持 22、24、26Embedding 入口重命名3.0.0 / 8d9e8adtextEmbeddingModel(id)→embeddingModel(id)旧名保留为 deprecated 别名内容类型收敛4.0.0file part 的 data 带类型标签、移除 image partimage-*工具输出类型并入file-*4.0.0-beta.12设置值不再缩放0.0.1temperature 等取值直接透传给 Provider需按各模型文档设置v2 命名体系providerMetadata→providerOptions、maxTokens→maxOutputTokens、mimeType→mediaTypekebab-case 警告4.0.0-beta.8 / 008271dopenai-compatible provider 对 kebab-case 入参发出警告应改用 camelCase。八、如何基于本仓库继续深入如果想从读 CHANGELOG升级到读实现建议按以下路径在 packages/provider 中展开入口src/index.ts 查看全部导出模块聚合接口provider/v4/provider-v4.ts 看一个 Provider 对象能提供哪些模型入口语言模型契约language-model/v4/language-model-v4.ts 与同目录下的 call options、prompt、stream part、usage 等类型文件新能力模块batchbatch/v4、filesfiles/v4、realtimerealtime-model/v4、视频异步任务video-model/v4配套实现规范层的消费者在 packages/ai高层 API 与 uploadFile/uploadSkill 助手、packages/provider-utilspostMultipartStreamToApi、deleteFromApi、createBinaryStreamResponseHandler等工具以及各供应商包如 packages/openai、packages/anthropic、packages/google、packages/gateway它们展示了同一规范在不同供应商下的落地差异。简而言之CHANGELOG 记录的是能力何时出现而 src 目录记录的是能力如何被类型化地表达。把两者对照阅读就能准确掌握 AI SDK 规范层从 v1 到 v4 的完整演化逻辑以及在升级或自研 Provider 时应当遵循的接口边界。【免费下载链接】aiThe AI Toolkit for TypeScript. From the creators of Next.js, the AI SDK is a free open-source library for building AI-powered applications and agents项目地址: https://gitcode.com/GitHub_Trending/ai/ai创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考