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-onlytype: 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接口可以看到完整的配置面配置项默认值说明baseURLhttps://generativelanguage.googleapis.com/v1betaAPI 前缀可用于代理服务器源码中通过withoutTrailingSlash自动去除尾部斜杠apiKey环境变量GOOGLE_GENERATIVE_AI_API_KEY通过x-goog-api-key请求头发送见 google-provider.tsheaders无自定义请求头与默认头合并fetch全局 fetch自定义 fetch 实现可用于拦截请求或测试generateId内置generateId每个请求生成唯一 IDwebSocket全局 WebSocket自定义 WebSocket 实现供 Live/Realtime 类接口使用需带 header 支持的运行时namegoogle.generative-ai自定义 Provider 名称影响providerOptions键名与遥测归属其中name字段对应 CHANGELOG 3.0.0 中 Support for custom provider name in google and anthropic providerscommit 1742445。自定义 name 会改变 providerOptions 的命名空间这一点在涉及多 Provider 混用或 gateway 场景时尤其重要。三、模型能力演进从 Gemini 2.0 到 Gemini 3.8CHANGELOG 中最直观的线索是模型 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-flashLatest 别名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-20264.0.0 中加入Embeddinggemini-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/Flashcommit 8e6b69d、2.1.0-beta.11 支持最新 Gemini 模型 IDcommit 9a728c8、3.0.0 加入gemini-3-pro-preview与gemini-3-pro-image-previewcommit 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 capabilitiescommit f126649意味着对于未知模型 IDProvider 会按最新能力集进行功能推断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 使用lazySchemazodSchema定义了 Provider 选项的运行时校验该懒加载机制对应 CHANGELOG 3.0.0 中 lazy schema loadingimport 时间从 22.3ms 降至 19.5ms。核心参数参数类型/枚举说明responseModalities[TEXT,IMAGE]响应模态配合gemini-2.5-flash-image等图像生成模型使用thinkingConfig.thinkingBudgetnumber思考预算token 数thinkingConfig.includeThoughtsboolean是否包含思考过程thinkingConfig.thinkingLevelminimal/low/medium/highGemini 3 思考级别见 CHANGELOG 3.0.0 commit 9be07c8cachedContentcachedContents/{id}使用缓存内容作为上下文0.0.27 加入structuredOutputsboolean默认 true结构化输出开关当 JSON Schema 包含 Google 所用 OpenAPI 版本不支持的要素时可关闭0.0.44 可禁用safetySettings数组按categoryHATE_SPEECH、DANGEROUS_CONTENT 等 6 类thresholdBLOCK_LOW_AND_ABOVE至OFF配置安全阈值0.0.18 加入2.0.0 允许OFFthreshold同上枚举独立展开的简化阈值4.0.11 将其展开为 safetySettingsaudioTimestampboolean音频文件时间戳理解1.0.11 加入labels记录账单标签仅 Vertex AI 可用mediaResolutionLOW/MEDIUM/HIGH媒体分辨率2.1.0-beta.6 加入imageConfig.aspectRatio1:1、16:9等 14 种图像纵横比3.0.0 commit 09ba2ddimageConfig.imageSize1K/2K/4K/512图像尺寸3.0.0 commit fff8d59imageConfig.personGenerationALLOW_ALL 等人物生成控制Vertex 专属4.0.17 透传4.2 安全与重试CHANGELOG 中多次强化安全与鲁棒性Prototype pollution 防护4.0.7commit c6f5e62同步解析 JSON 时防原型污染4.0.0commit 5878b40修复流式 tool args 的原型污染URL 校验4.0.14commit 4be62c1为getFromApi增加validateUrl标志拒绝私有/回环地址并逐跳校验重定向4.0.52commit 7de3612对 Provider 返回的标识符进行编码后再用于带凭据的后续请求同源凭据保护4.0.0commit aeda373与 4.0.14 的credentialedOrigin/trustedOrigin机制确保 API Key 只发送给同源 URL防止凭据外泄相关设计可参考 contributing/secure-url-handling.md错误归一化4.0.52commit 35841f5将流式中途的错误事件统一为公开的StreamProviderError实例并保留 provider 的 type/code/status/retry/raw payload 元数据空结果重试4.0.65commit 45099da对未分类的空图片结果进行重试并保留重试次数统计同时将 Google 与 Google Vertex 的 prompt blocks 标记为终态。4.3 推理与 thoughtSignature围绕 Gemini 3 思考模型CHANGELOG 有大量专门的修复记录3.0.0commit 8370068在工具执行过程中保留thoughtSignature3.0.0commit 218bba1使用动态providerOptionsName检索 thoughtSignature修复 google-vertex 多轮工具调用时报 function call is missing a thought_signature 的问题3.0.0commit cfca634修复 Vertex 无参数流式工具调用单 chunk 形如{ functionCall: { name: X } }被丢弃的问题该问题会导致下一轮 400 错误4.0.0commit a8d70b6对无签名的 Gemini 3 工具调用回放自动注入skip_thought_signature_validator4.0.22commit 5e5453c避免对合法无签名 Gemini 3 并行函数调用注入 skip 校验器及产生缺失 thought-signature 警告。这些修复的核心在于Gemini 3 思考模型的函数调用需要携带thought_signature才能在下一轮被接受Provider 需要精确地在 unary 与 streaming 两条路径上传播该元数据。五、Batch API批量推理的完整生命周期Batch 能力是 4.x 版本的重点演进方向其实现位于 google-batch.ts4.0.51commit e7fc90eexperimental_startTextBatch支持 Gemini Batch API4.0.60commit e07b577Batch 支持工具调用tool calling4.0.63commit 048ce06Batch 开始结果暴露上传的输入文件providerMetadata.provider.inputFileId/inputFileExpiresAt并支持inputFileExpiresAfterProvider 选项4.0.65commit a4ba394Batch 支持按请求选择模型per-request models4.0.67commit ab6e9f9Batch 支持取消与列表batch cancellation and listing4.0.52commit 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.0commit b04e23e首次支持 Gemini Interactions API4.0.0commit 7f04802支持托管智能体managed agents通过/v1beta/agents创建的用户自定义智能体4.0.0commit db394ab支持通过 AbortSignal 取消长时间运行的 Interactions 智能体并处理间歇流4.0.4commit dc1eb8d支持 Interactions 视频输出将输出块解析为文件 partbuffered 与 streaming并通过providerMetadata.google.outputTokensByModality暴露按模态的输出 token 明细4.0.6commit d20f0dcVertex 侧新增vertex.interactions()面向 location-scoped 的.../locations/{region}/interactions资源支持gemini-omni-flash-preview这类视频输出模型GoogleInteractionsLanguageModel从ai-sdk/google/internal导出供 Provider 复用4.0.16commit 662ddfcInteractions 智能体请求支持内置工具包括file_search4.0.63commit 18ad19c支持智能体视频处理agentic video processing4.0.59commit ca29e9b支持 Gemini Interactions 中的视频响应格式4.0.0commit ebbb0f2修复 Interactions 无状态模式下的图像一致性4.0.0commit 4e825f3适配上游 5 月 26 日的破坏性变更4.0.0commit bdb9ea1移除过时的Api-Revision头。从 google-provider.ts 看google.interactions()接受三种输入模型 ID 字符串、{ agent: name }已知 Gemini 智能体预设、{ managedAgent: name }用户自定义智能体。七、Realtime 与语音能力Live API 与 TTS/STT7.1 Realtime语音到语音4.0.0commit ce769dd为ai-sdk/provider引入Experimental_RealtimeModelV4规范Google 实现了google.experimental_realtime()支持服务端与浏览器双端.getToken()静态方法用于服务端创建短期 token见 google-provider.ts 中experimentalRealtimeFactory.getToken调用doCreateClientSecretexperimental_getRealtimeToolDefinitions生成会话工具定义experimental_useRealtimeai-sdk/react返回与useChat对齐的UIMessage[]支持onToolCall与addToolOutput客户端驱动工具执行inputAudioTranscription会话配置可显示转写后的用户音频消息。4.0.22commit 66b7151修复了 Gemini Live 生命周期事件的保留问题。实现位于 realtime/ 目录模型 ID 类型为Experimental_GoogleRealtimeModelId。7.2 语音生成与转写语音生成TTS4.0.0commit b563707为 Google 加入 Gemini TTSspeech模型支持google.speech(modelId)创建SpeechModelV4gemini-2.5-flash-preview-tts、gemini-2.5-pro-preview-tts、gemini-3.1-flash-tts-preview等模型 ID 出现在类型中转写STT4.0.8commit 5c5c0f5引入实验性流式转写4.0.54commit 1f7835c加入 Gemini 3.5 Transcribeunary 转写gemini-3.5-transcribe经 generateContent支持语言检测、说话人分离、词级时间戳、自定义词汇与流式转写gemini-3.5-transcribe-live经 Live API WebSocket支持VERBATIM/SMART两种格式化模式语音翻译4.0.26commit c49380c加入实验性流式语音翻译google.translation(gemini-3.5-live-translate-preview)Gemini Live API WebSocket4.0.0commit 947cdab为其补充 Provider 选项4.0.37commit bbd9b31将*TranslationModel重命名为*SpeechTranslationModel。八、图像、视频与嵌入生成式多模态矩阵8.1 图像生成ImageModelV42.0.0commit 8af9e03引入 Imagen 3 图像模型3.0.26commit 4c27179允许 Gemini 图像模型用于generateImage3.0.0commit 9061dc0支持图像编辑4.0.0commit 6190649移除过时的 Google 图像模型Imagen 集成随 API 停服移除commit f607a124.0.0commit b71c0d7generateImage支持 Google 搜索 grounding3.0.32/3.0.33/3.0.38 持续补充gemini-3.1-flash-image-preview的宽高比、尺寸与图像 thought signature 支持4.0.0commit 6a26901fileData支持 embedding 模型4.0.0commit ab43029embedding Provider 选项支持多模态内容 part4.0.0commit 82288b0gemini-embedding-2-preview与embedMany多模态嵌入修复4.0.7commit bd8d172修复 embedding batch 大小以遵守 Gemini API 单批 100 请求的限制2.0.0commit 6a16dcfembed()改用单条 embedding 端点batch 端点 150 RPM、单条端点 1500 RPM避免embed()走 batch 触发限流。8.2 视频生成Experimental_VideoModelV43.0.20commit 53f6731引入实验性视频生成3.0.22commit 7168375支持全局 Provider 视频模型解析4.0.3commit 0274f34加入第一等公民的frameImages与inputReferences视频生成选项4.0.11commit 0f93c57inputReferences支持视频不仅图片参考输入4.0.32commit 79e133c为视频模型加入异步 start/status 流程VideoModelV4可实现doStart/doStatus/handleWebhookOptionexperimental_generateVideo支持poll与webhook选项轮询延迟可用自定义实现以适配持久化工作流。实现上图像模型见 google-image-model.ts、视频模型见 google-video-model.ts模型 ID 联合类型分别定义在 google-image-settings.ts 与 google-video-settings.ts。九、Provider 内置工具google.toolsgoogle-tools.ts 导出了googleTools对象这是一组Provider 定义工具与普通 function tool 的区别在于它们由 Provider 原生实现、名称固定工具固定名称适用场景googleSearchgoogle_search实时网络内容搜索原 google_search_retrieval 实现3.0.39 更换为 image searchenterpriseWebSearchenterprise_web_search合规导向的网络索引金融/医疗/公共部门不记录客户数据支持 VPC 服务控制仅 Vertex AI、Gemini 2.0googleMapsgoogle_mapsGoogle Maps 数据 grounding3.0.0 commit 32a6c13 加入urlContexturl_context访问实时网页内容2.0.0 commit 2e06f14 加入fileSearchfile_search基于 File Search store 的 RAG3.0.0 commit 2825757 加入参数含fileSearchStoreNames、metadataFilter、topKcodeExecutioncode_execution生成并运行 Python 代码2.0.0 commit 78e7fa9 加入4.0.64 commit 63533eb 修正其名称映射vertexRagStorevertex_rag_store对 Vertex RAG Store 执行 RAG 搜索3.0.0 commit 0b92881 加入CHANGELOG 中的相关修复还包括1.1.21 加入动态检索dynamic retrieval、3.0.0commit 8ee8edc为gemini-3-pro-preview准备搜索工具、3.0.6commit 2043612修复使用 Google Provider 工具时的结构化输出解析、3.0.0commit e300a3b修复fileSearch()的 Zod 校验新 API 返回fileSearchStore而非uriextractSources()同时兼容两种格式、4.0.0commit 01fa606支持 Gemini 3 上内置工具与函数调用组合使用。十、文件与多模态消息处理10.1 文件 URL 支持矩阵google-provider.ts 定义了受支持的 URL 白名单Google Files URLhttps://generativelanguage.googleapis.com/v1beta/files/...与自定义 baseURL 下的/files/路径4.0.57 修复自定义 baseURL 时无法识别 Google Files URL 的问题YouTube URLyoutube.com/watch?v与youtu.be短链2.0.1 加入外部 HTTPS 媒体 URLsupportsExternalFileUrls()判定模型 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.0commit 18c1970为 Google function response 加入多模态工具结果支持output.type content的工具结果会将媒体 part 映射进functionResponse.partsimage-data、file-data、base64data:URL但远程 HTTP(S) URL 不支持4.0.11commit 17d66c5修复旧工具结果路径上文件数据以 inline data 而非 JSON 文本发送的问题4.0.0commit 2edd14e正确标记 reasoning 文件并修复相关多轮错误4.0.0commit f7d4f01增加reasoning-file文件类型4.0.63commit 048ce06为文件上传暴露byteSize、createdAt、expiresAt等字段uploadFile()也转发abortSignal/headers4.0.61commit 5190b67扩展FilesV4接口getFileMetadata、downloadFile流式、deleteFile、{ type: stream }上传变体并新增postMultipartStreamToApi、deleteFromApi、createBinaryStreamResponseHandler工具函数。十一、metadata 与可观测性2.0.0commit 19a4336暴露 Google 返回的原始usageMetadata到providerMetadata2.0.0commit 3bd2689扩展 token usage按模态输出 token 明细commit a05109d4.0.0commit 045d2e8修复流式响应中serviceTier始终为 null 的问题流式响应的 serviceTier 在usageMetadata.serviceTier中每个 chunk 都携带而非x-gemini-service-tier响应头仅非流式响应有值——该字段会出现在providerMetadata.google.serviceTier3.0.0commit 0cfae4cVertex 支持trafficType于 provider usageMetadata4.0.0commit 4dac142新增finishMessage字段3.0.0commit 0c3b58b为 ProviderV3 增加specificationVersion3.0.0commit 1cad0abuser-agent 头中加入 Provider 版本实现见 google-provider.ts 的withUserAgentSuffix(..., ai-sdk/google/${VERSION})4.0.55commit 56d492f将无候选的 prompt 级安全拦截content-filter结果与 prompt feedback 元数据一起作为结果暴露4.0.56commit 3ad9da9在原始 usage 结果中保留完整的 Google Generative Language usage 元数据。十二、破坏性变更与升级注意事项12.1 v74.0.0主要破坏性变更从 CHANGELOG 4.0.0 的 Major Changes 中可提取ESM-onlycommit ef992f8移除所有包的 CommonJS 导出require()消费者必须改用 ESMimportNode.js 22commit 7fc6bd6支持版本为 22、24、26类型命名统一commit a3757d7移除无意义的GenerativeAI后缀如GoogleGenerativeAIProvider→GoogleProvider旧名称通过 deprecated 别名继续可用commit 04e9009 同样说明被重命名的导出符号保留旧别名从 index.ts 可以看到GoogleGenerativeAIProvider、GoogleGenerativeAIProviderSettings、createGoogleGenerativeAI等均标记为 deprecated 别名顶层 reasoning 参数commit 3887c70generateText/streamText新增顶层reasoning参数provider references 与按 Provider 上传文件commit c29a26fProvider 定义的 file part 类型统一commit 9bd6512file part 的 data 属性带类型标记并移除 image part 类型image-*工具输出类型并入file-*类型commit ff5eba1。12.2 早期版本破坏性变更1.0.0AI SDK 4移除baseUrl选项统一为baseURL0.0.1 时已自动去尾部斜杠、移除topK模型设置、移除 facade2.0.0AI SDK 5providerOptions 化改造commit 7378473、Provider 定义工具化commit 2e06f14、embed()走单条端点3.0.0AI SDK 6ProviderV3/LanguageModelV3/EmbeddingModelV3textEmbeddingModel→embeddingModel保留 deprecated 别名、ImageModelV3、thinking_level选项、lazy schema 加载。12.3 功能移除记录4.0.49commit f607a12随 API 停服移除 Imagen 模型集成3.0.35commit 64a8fae移除废弃模型 ID3.0.21 移除gemini-2.5-flash-image-preview1.1.9 移除 Gemini API 已不再返回的 reasoning 文本。十三、测试与验证该包在 packages/google/src 内置了完整的测试套件可参考验证本文所述行为google-provider.test.ts 与 google-provider.test-d.tsProvider 工厂与类型测试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.tsconvert-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 testnode edge 两套 vitest 配置见 package.json。十四、总结与选型建议回看 CHANGELOG 的整体脉络ai-sdk/google的能力矩阵可以归纳为文本/推理Gemini 2.x/3.x 全系模型含 thinkingConfig、thoughtSignature 多轮一致性、结构化输出批量Batch API 覆盖文本与图像支持工具调用、按请求选模型、取消/列表/文件生命周期智能体Interactions API模型 ID、agent 预设、managedAgent 三种入口支持内置工具与视频输出语音Realtime 会话、TTSspeech、STTtranscription 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创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考