AI SDK Google Provider 演进全览：从 Gemini 模型接入到 Batch、Interactions 与 Realtime 的能力图谱

AI SDK Google Provider 演进全览：从 Gemini 模型接入到 Batch、Interactions 与 Realtime 的能力图谱

【免费下载链接】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 SDK 仓库中 packages/google/CHANGELOG.md 为骨架，系统梳理@ai-sdk/google从 0.0.1 到 4.0.67 的关键演进路径：包括 Gemini 模型族的接入与迭代、Batch 批量推理、Interactions API、Realtime 语音、图片/视频/语音/嵌入等全模态能力，以及 ESM-only、Node 版本基线等破坏性变更。读完本文，你将理解该 Provider 当前的能力边界、各 API 的适用场景、常见配置参数与安全设计，并能在自己的 TypeScript 项目中正确选用与升级。

一、文档定位：为什么 CHANGELOG 是一份能力地图

@ai-sdk/google的 CHANGELOG 记录了该包自 2024 年初（0.0.1）到当前（4.0.67）的每一次发布。与普通变更记录不同，这份文档几乎完整映射了 Google Provider 的功能演进：每次 "feat" 都代表一项新能力的落地，每次 "fix" 都揭示了一个真实的实现细节或协议兼容性坑点，每次 "Major" 都标记了升级时必须关注的破坏性变化。以它为主体，配合 源码目录 中的实现文件，可以还原出完整的 Provider 能力地图。

从 package.json 可以看到当前包版本 4.0.67、ESM-only（"type": "module"）、要求 Node.js >= 22、以 Apache-2.0 协议发布，主入口为dist/index.js，类型入口为dist/index.d.ts。这些元数据本身就是理解 CHANGELOG 中各种变更的背景。

二、快速上手：Provider 实例与基础用法

2.1 安装与 Provider 实例

在 README.md 中给出的安装方式为：

npm i @ai-sdk/google

从 google-provider.ts 可以看到，包默认导出一个预配置的google实例，也支持通过createGoogle()自定义：

import { google } from '@ai-sdk/google'; import { generateText } from 'ai'; const { text } = await generateText({ model: google('gemini-2.5-pro'), prompt: 'Write a vegetarian lasagna recipe for 4 people.', });

Provider 的函数签名google(modelId)等价于google.chat(modelId)，返回LanguageModelV4（见 google-provider.ts）。此外还保留了generativeAI()等旧别名（标记为 deprecated）。

2.2 核心配置项（GoogleProviderSettings）

从 google-provider.ts 的GoogleProviderSettings接口可以看到完整的配置面：

其中name字段对应 CHANGELOG 3.0.0 中 "Support for custom provider name in google and anthropic providers"（commit 1742445）。自定义 name 会改变 providerOptions 的命名空间，这一点在涉及多 Provider 混用或 gateway 场景时尤其重要。

三、模型能力演进：从 Gemini 2.0 到 Gemini 3.8

CHANGELOG 中最直观的线索是模型 ID 的持续扩充。当前 google-language-model-options.ts 中的GoogleModelId联合类型按 Stable / Latest / Experimental 分组，包含：

• Stable 模型：gemini-2.0-flash、gemini-2.0-flash-lite、gemini-2.5-pro、gemini-2.5-flash、gemini-2.5-flash-lite、gemini-2.5-flash-image，以及gemini-3-pro-preview、gemini-3-flash-preview、gemini-3.1-pro-preview、gemini-3.1-flash-lite-preview、gemini-3.5-flash、gemini-3.5-flash-lite、gemini-3.6-flash、gemini-3.7-flash、gemini-3.8-flash；
• Latest 别名：gemini-pro-latest、gemini-flash-latest、gemini-flash-lite-latest；
• 深度研究模型：deep-research-pro-preview-12-2025、deep-research-max-preview-04-2026、deep-research-preview-04-2026（4.0.0 中加入）；
• Embedding：gemini-embedding-2、gemini-embedding-2-preview、gemini-embedding-001等；
• 实验性模型：nano-banana-pro-preview、aqa与 Gemma 系列（gemma-3-1b-it至gemma-3-27b-it）。

CHANGELOG 中可追踪的模型节点包括：0.0.14 加入gemini-1.5-flash-latest、1.1.23 加入gemma-3模型 ID、1.2.3 加入gemini-2.5-pro-exp-03-25、2.0.0 引入 Gemini 2.5 Pro/Flash（commit 8e6b69d）、2.1.0-beta.11 支持最新 Gemini 模型 ID（commit 9a728c8）、3.0.0 加入gemini-3-pro-preview与gemini-3-pro-image-preview（commit 33d9327）、3.0.21 移除已停服的gemini-2.5-flash-image-preview、3.0.35 清理废弃模型 ID、3.0.37 加入gemini-3.1-flash-lite-preview、4.0.21 加入gemini-3.6-flash与gemini-3.5-flash-lite、4.0.44 加入gemini-3.7-flash、4.0.63 加入gemini-3.8-flash。

值得注意的实现细节：4.0.23 的 "default unknown Gemini model IDs to the newest supported capabilities"（commit f126649）意味着对于未知模型 ID，Provider 会按最新能力集进行功能推断；4.0.46 与 4.0.45 将 Gemini Flash 3.7 及之后版本的最低推理级别（reasoning level）收敛为low。这说明 Provider 会针对不同模型动态调整请求参数，模型 ID 的选择会影响实际请求体。

四、模型选项详解：Thinking、Safety、结构化输出等

4.1 GoogleLanguageModelOptions 全参数

google-language-model-options.ts 使用lazySchema+zodSchema定义了 Provider 选项的运行时校验（该懒加载机制对应 CHANGELOG 3.0.0 中 "lazy schema loading"，import 时间从 22.3ms 降至 19.5ms）。核心参数：

4.2 安全与重试

CHANGELOG 中多次强化安全与鲁棒性：

• Prototype pollution 防护：4.0.7（commit c6f5e62）同步解析 JSON 时防原型污染；4.0.0（commit 5878b40）修复流式 tool args 的原型污染；
• URL 校验：4.0.14（commit 4be62c1）为getFromApi增加validateUrl标志，拒绝私有/回环地址，并逐跳校验重定向；4.0.52（commit 7de3612）对 Provider 返回的标识符进行编码后再用于带凭据的后续请求；
• 同源凭据保护：4.0.0（commit aeda373）与 4.0.14 的credentialedOrigin/trustedOrigin机制确保 API Key 只发送给同源 URL，防止凭据外泄；相关设计可参考 contributing/secure-url-handling.md；
• 错误归一化：4.0.52（commit 35841f5）将流式中途的错误事件统一为公开的StreamProviderError实例，并保留 provider 的 type/code/status/retry/raw payload 元数据；
• 空结果重试：4.0.65（commit 45099da）对未分类的空图片结果进行重试并保留重试次数统计，同时将 Google 与 Google Vertex 的 prompt blocks 标记为终态。

4.3 推理与 thoughtSignature

围绕 Gemini 3 思考模型，CHANGELOG 有大量专门的修复记录：

• 3.0.0（commit 8370068）在工具执行过程中保留thoughtSignature；
• 3.0.0（commit 218bba1）使用动态providerOptionsName检索 thoughtSignature，修复 google-vertex 多轮工具调用时报 "function call is missing a thought_signature" 的问题；
• 3.0.0（commit cfca634）修复 Vertex 无参数流式工具调用（单 chunk 形如{ functionCall: { name: 'X' } }）被丢弃的问题，该问题会导致下一轮 400 错误；
• 4.0.0（commit a8d70b6）对无签名的 Gemini 3 工具调用回放自动注入skip_thought_signature_validator；
• 4.0.22（commit 5e5453c）避免对合法无签名 Gemini 3 并行函数调用注入 skip 校验器及产生缺失 thought-signature 警告。

这些修复的核心在于：Gemini 3 思考模型的函数调用需要携带thought_signature才能在下一轮被接受，Provider 需要精确地在 unary 与 streaming 两条路径上传播该元数据。

五、Batch API：批量推理的完整生命周期

Batch 能力是 4.x 版本的重点演进方向，其实现位于 google-batch.ts：

• 4.0.51（commit e7fc90e）：experimental_startTextBatch支持 Gemini Batch API；
• 4.0.60（commit e07b577）：Batch 支持工具调用（tool calling）；
• 4.0.63（commit 048ce06）：Batch 开始结果暴露上传的输入文件（providerMetadata.<provider>.inputFileId/inputFileExpiresAt），并支持inputFileExpiresAfterProvider 选项；
• 4.0.65（commit a4ba394）：Batch 支持按请求选择模型（per-request models）；
• 4.0.67（commit ab6e9f9）：Batch 支持取消与列表（batch cancellation and listing）；
• 4.0.52（commit a9782e1）：对齐各 Provider 的批量结果解析、请求计数与生命周期行为。

Provider 上通过google.experimental_batch()创建 Batch 实例（见 google-provider.ts）。Batch 内部复用 language model 的 baseURL、headers、fetch 配置，并且由于批量提示词转换发生在模型可用之前，其支持的 URL 仅包含所有批量模型共有的部分（getSupportedUrls(undefined, false)，即不包含外部 URL）。

六、Interactions API：智能体与多模态输出

Interactions API 是 Google 面向智能体（agent）场景的新接口，目标是POST /v1beta/interactions，实现在 interactions/ 目录下。CHANGELOG 中的演进：

• 4.0.0（commit b04e23e）：首次支持 Gemini Interactions API；4.0.0（commit 7f04802）支持托管智能体（managed agents，通过/v1beta/agents创建的用户自定义智能体）；4.0.0（commit db394ab）支持通过 AbortSignal 取消长时间运行的 Interactions 智能体并处理间歇流；
• 4.0.4（commit dc1eb8d）：支持 Interactions 视频输出，将输出块解析为文件 part（buffered 与 streaming），并通过providerMetadata.google.outputTokensByModality暴露按模态的输出 token 明细；
• 4.0.6（commit d20f0dc）：Vertex 侧新增vertex.interactions()，面向 location-scoped 的.../locations/{region}/interactions资源，支持gemini-omni-flash-preview这类视频输出模型；GoogleInteractionsLanguageModel从@ai-sdk/google/internal导出供 Provider 复用；
• 4.0.16（commit 662ddfc）：Interactions 智能体请求支持内置工具（包括file_search）；
• 4.0.63（commit 18ad19c）：支持智能体视频处理（agentic video processing）；
• 4.0.59（commit ca29e9b）：支持 Gemini Interactions 中的视频响应格式；
• 4.0.0（commit ebbb0f2）：修复 Interactions 无状态模式下的图像一致性；4.0.0（commit 4e825f3）适配上游 5 月 26 日的破坏性变更；4.0.0（commit bdb9ea1）移除过时的Api-Revision头。

从 google-provider.ts 看，google.interactions()接受三种输入：模型 ID 字符串、{ agent: <name> }（已知 Gemini 智能体预设）、{ managedAgent: <name> }（用户自定义智能体）。

七、Realtime 与语音能力：Live API 与 TTS/STT

7.1 Realtime（语音到语音）

4.0.0（commit ce769dd）为@ai-sdk/provider引入Experimental_RealtimeModelV4规范，Google 实现了google.experimental_realtime()，支持服务端与浏览器双端：

• .getToken()静态方法用于服务端创建短期 token（见 google-provider.ts 中experimentalRealtimeFactory.getToken，调用doCreateClientSecret）；
• experimental_getRealtimeToolDefinitions生成会话工具定义；
• experimental_useRealtime（@ai-sdk/react）返回与useChat对齐的UIMessage[]，支持onToolCall与addToolOutput客户端驱动工具执行；
• inputAudioTranscription会话配置可显示转写后的用户音频消息。

4.0.22（commit 66b7151）修复了 Gemini Live 生命周期事件的保留问题。实现位于 realtime/ 目录，模型 ID 类型为Experimental_GoogleRealtimeModelId。

7.2 语音生成与转写

• 语音生成（TTS）：4.0.0（commit b563707）为 Google 加入 Gemini TTS（speech）模型支持，google.speech(modelId)创建SpeechModelV4；gemini-2.5-flash-preview-tts、gemini-2.5-pro-preview-tts、gemini-3.1-flash-tts-preview等模型 ID 出现在类型中；
• 转写（STT）：4.0.8（commit 5c5c0f5）引入实验性流式转写；4.0.54（commit 1f7835c）加入 Gemini 3.5 Transcribe：unary 转写gemini-3.5-transcribe（经 generateContent，支持语言检测、说话人分离、词级时间戳、自定义词汇）与流式转写gemini-3.5-transcribe-live（经 Live API WebSocket，支持VERBATIM/SMART两种格式化模式）；
• 语音翻译：4.0.26（commit c49380c）加入实验性流式语音翻译google.translation('gemini-3.5-live-translate-preview')（Gemini Live API WebSocket）；4.0.0（commit 947cdab）为其补充 Provider 选项；4.0.37（commit bbd9b31）将*TranslationModel重命名为*SpeechTranslationModel。

八、图像、视频与嵌入：生成式多模态矩阵

8.1 图像生成（ImageModelV4）

• 2.0.0（commit 8af9e03）引入 Imagen 3 图像模型；3.0.26（commit 4c27179）允许 Gemini 图像模型用于generateImage；3.0.0（commit 9061dc0）支持图像编辑；
• 4.0.0（commit 6190649）移除过时的 Google 图像模型（Imagen 集成随 API 停服移除，commit f607a12）；4.0.0（commit b71c0d7）generateImage支持 Google 搜索 grounding；
• 3.0.32/3.0.33/3.0.38 持续补充gemini-3.1-flash-image-preview的宽高比、尺寸与图像 thought signature 支持；
• 4.0.0（commit 6a26901）fileData支持 embedding 模型；4.0.0（commit ab43029）embedding Provider 选项支持多模态内容 part；4.0.0（commit 82288b0）gemini-embedding-2-preview与embedMany多模态嵌入修复；
• 4.0.7（commit bd8d172）修复 embedding batch 大小以遵守 Gemini API 单批 100 请求的限制；
• 2.0.0（commit 6a16dcf）embed()改用单条 embedding 端点（batch 端点 150 RPM、单条端点 1500 RPM），避免embed()走 batch 触发限流。

8.2 视频生成（Experimental_VideoModelV4）

• 3.0.20（commit 53f6731）引入实验性视频生成；3.0.22（commit 7168375）支持全局 Provider 视频模型解析；
• 4.0.3（commit 0274f34）加入第一等公民的frameImages与inputReferences视频生成选项；4.0.11（commit 0f93c57）inputReferences支持视频（不仅图片）参考输入；
• 4.0.32（commit 79e133c）为视频模型加入异步 start/status 流程：VideoModelV4可实现doStart/doStatus/handleWebhookOption，experimental_generateVideo支持poll与webhook选项，轮询延迟可用自定义实现以适配持久化工作流。

实现上，图像模型见 google-image-model.ts、视频模型见 google-video-model.ts，模型 ID 联合类型分别定义在 google-image-settings.ts 与 google-video-settings.ts。

九、Provider 内置工具（google.tools）

google-tools.ts 导出了googleTools对象，这是一组"Provider 定义工具"，与普通 function tool 的区别在于它们由 Provider 原生实现、名称固定：

CHANGELOG 中的相关修复还包括：1.1.21 加入动态检索（dynamic retrieval）、3.0.0（commit 8ee8edc）为gemini-3-pro-preview准备搜索工具、3.0.6（commit 2043612）修复使用 Google Provider 工具时的结构化输出解析、3.0.0（commit e300a3b）修复fileSearch()的 Zod 校验（新 API 返回fileSearchStore而非uri，extractSources()同时兼容两种格式）、4.0.0（commit 01fa606）支持 Gemini 3 上内置工具与函数调用组合使用。

十、文件与多模态消息处理

10.1 文件 URL 支持矩阵

google-provider.ts 定义了受支持的 URL 白名单：

• Google Files URL（https://generativelanguage.googleapis.com/v1beta/files/...）与自定义 baseURL 下的/files/路径（4.0.57 修复自定义 baseURL 时无法识别 Google Files URL 的问题）；
• YouTube URL（youtube.com/watch?v=与youtu.be短链，2.0.1 加入）；
• 外部 HTTPS 媒体 URL：supportsExternalFileUrls()判定模型 ID 含gemini-且非gemini-2.0时才允许，覆盖 text/html、application/pdf、image/jpeg、video/mp4 等 21 种 MIME 类型（4.0.9 起文档化的 Gemini 外部 HTTPS 文件 URL 直接透传而不再下载）。

10.2 多模态工具结果

• 4.0.0（commit 18c1970）为 Google function response 加入多模态工具结果支持：output.type = 'content'的工具结果会将媒体 part 映射进functionResponse.parts（image-data、file-data、base64data:URL），但远程 HTTP(S) URL 不支持；
• 4.0.11（commit 17d66c5）修复旧工具结果路径上文件数据以 inline data 而非 JSON 文本发送的问题；
• 4.0.0（commit 2edd14e）正确标记 reasoning 文件并修复相关多轮错误；4.0.0（commit f7d4f01）增加reasoning-file文件类型；
• 4.0.63（commit 048ce06）为文件上传暴露byteSize、createdAt、expiresAt等字段，uploadFile()也转发abortSignal/headers；
• 4.0.61（commit 5190b67）扩展FilesV4接口：getFileMetadata、downloadFile（流式）、deleteFile、{ type: 'stream' }上传变体，并新增postMultipartStreamToApi、deleteFromApi、createBinaryStreamResponseHandler工具函数。

十一、metadata 与可观测性

• 2.0.0（commit 19a4336）暴露 Google 返回的原始usageMetadata到providerMetadata；
• 2.0.0（commit 3bd2689）扩展 token usage（按模态输出 token 明细，commit a05109d）；
• 4.0.0（commit 045d2e8）修复流式响应中serviceTier始终为 null 的问题：流式响应的 serviceTier 在usageMetadata.serviceTier中（每个 chunk 都携带），而非x-gemini-service-tier响应头（仅非流式响应有值）——该字段会出现在providerMetadata.google.serviceTier；
• 3.0.0（commit 0cfae4c）Vertex 支持trafficType于 provider usageMetadata；4.0.0（commit 4dac142）新增finishMessage字段；
• 3.0.0（commit 0c3b58b）为 ProviderV3 增加specificationVersion；
• 3.0.0（commit 1cad0ab）user-agent 头中加入 Provider 版本（实现见 google-provider.ts 的withUserAgentSuffix(..., 'ai-sdk/google/${VERSION}')）；
• 4.0.55（commit 56d492f）将无候选的 prompt 级安全拦截（content-filter）结果与 prompt feedback 元数据一起作为结果暴露；
• 4.0.56（commit 3ad9da9）在原始 usage 结果中保留完整的 Google Generative Language usage 元数据。

十二、破坏性变更与升级注意事项

12.1 v7（4.0.0）主要破坏性变更

从 CHANGELOG 4.0.0 的 Major Changes 中可提取：

1. ESM-only（commit ef992f8）：移除所有包的 CommonJS 导出，require()消费者必须改用 ESMimport；
2. Node.js >= 22（commit 7fc6bd6）：支持版本为 22、24、26；
3. 类型命名统一（commit a3757d7）：移除无意义的GenerativeAI后缀（如GoogleGenerativeAIProvider→GoogleProvider），旧名称通过 deprecated 别名继续可用（commit 04e9009 同样说明被重命名的导出符号保留旧别名）；从 index.ts 可以看到GoogleGenerativeAIProvider、GoogleGenerativeAIProviderSettings、createGoogleGenerativeAI等均标记为 deprecated 别名；
4. 顶层 reasoning 参数（commit 3887c70）：generateText/streamText新增顶层reasoning参数；
5. provider references 与按 Provider 上传文件（commit c29a26f）；
6. Provider 定义的 file part 类型统一（commit 9bd6512）：file part 的 data 属性带类型标记并移除 image part 类型；image-*工具输出类型并入file-*类型（commit ff5eba1）。

12.2 早期版本破坏性变更

• 1.0.0（AI SDK 4）：移除baseUrl选项（统一为baseURL，0.0.1 时已自动去尾部斜杠）、移除topK模型设置、移除 facade；
• 2.0.0（AI SDK 5）：providerOptions 化改造（commit 7378473）、Provider 定义工具化（commit 2e06f14）、embed()走单条端点；
• 3.0.0（AI SDK 6）：ProviderV3/LanguageModelV3/EmbeddingModelV3（textEmbeddingModel→embeddingModel，保留 deprecated 别名）、ImageModelV3、thinking_level选项、lazy schema 加载。

12.3 功能移除记录

• 4.0.49（commit f607a12）随 API 停服移除 Imagen 模型集成；
• 3.0.35（commit 64a8fae）移除废弃模型 ID；3.0.21 移除gemini-2.5-flash-image-preview；
• 1.1.9 移除 Gemini API 已不再返回的 reasoning 文本。

十三、测试与验证

该包在 packages/google/src 内置了完整的测试套件，可参考验证本文所述行为：

• google-provider.test.ts 与 google-provider.test-d.ts：Provider 工厂与类型测试；
• google-language-model.test.ts、google-batch.test.ts、google-embedding-model.test.ts、google-image-model.test.ts、google-video-model.test.ts、google-speech-model.test.ts；
• convert-to-google-messages.test.ts 与 convert-json-schema-to-openapi-schema.test.ts：消息转换与 JSON Schema → OpenAPI Schema 转换；
• google-files.test.ts 与 google-supported-file-url.test.ts：文件 URL 白名单验证；
• google-error.test.ts：错误归一化。

包级测试命令为pnpm test（node + edge 两套 vitest 配置），见 package.json。

十四、总结与选型建议

回看 CHANGELOG 的整体脉络，@ai-sdk/google的能力矩阵可以归纳为：

• 文本/推理：Gemini 2.x/3.x 全系模型，含 thinkingConfig、thoughtSignature 多轮一致性、结构化输出；
• 批量：Batch API 覆盖文本与图像，支持工具调用、按请求选模型、取消/列表/文件生命周期；
• 智能体：Interactions API（模型 ID、agent 预设、managedAgent 三种入口），支持内置工具与视频输出；
• 语音：Realtime 会话、TTS（speech）、STT（transcription unary/live）、流式语音翻译（speech-translation）；
• 生成：图像（Gemini image / 编辑 / 搜索 grounding）、视频（poll/webhook 异步流程）；
• 检索增强：googleSearch、enterpriseWebSearch、googleMaps、urlContext、fileSearch、codeExecution、vertexRagStore 七种 Provider 内置工具。

升级时重点核对三条基线：Node.js >= 22、ESM-only 导入、GoogleProvider系列命名。若需要对接 Vertex AI，则使用同仓库的@ai-sdk/google-vertex包（位于 packages/google-vertex），其与 google 包共享大量实现（thoughtSignature 双向兼容、serviceTier PayGo 等，见 CHANGELOG 相关条目），并在 packages/google-vertex/CHANGELOG.md 中追踪自身演进。

【免费下载链接】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