Spring AI 迁移指南：从 Vertex AI 自动配置迁移到 Google GenAI 自动配置

Spring AI 迁移指南：从 Vertex AI 自动配置迁移到 Google GenAI 自动配置

【免费下载链接】spring-aiAn Application Framework for AI Engineering项目地址: https://gitcode.com/GitHub_Trending/spr/spring-ai

导读

本文是 Spring AI 仓库中 MIGRATION_GUIDE.md 的完整展开版，面向已经或准备使用 Google Gemini 模型的 Spring AI 开发者。文章围绕"旧 Vertex AI 自动配置 → 新 Google GenAI 自动配置"这一主线，系统讲解新 starter 的引入方式、spring.ai.google.genai.*新属性命名空间、两种认证模式（Vertex AI 模式与 Gemini Developer API 模式）的选择逻辑、Bean 名与类名的变更对照，以及可落地的分步迁移清单。读完本文，你将能够把基于spring.ai.vertex.ai.*的旧工程平滑升级到基于官方 GenAI SDK（com.google.genai.Client）的新自动配置模块，并正确配置 Chat、Embedding 能力。

说明：本文所引用的属性、类名、Bean 名与代码路径均来自当前仓库快照（自动配置模块版本为 2.0.2-SNAPSHOT，属性类注解标注since 1.1.0）。仓库为只读，本文只介绍查看、配置与运行方式。

背景：为什么需要迁移

Spring AI 的 Google Gemini 支持早期建立在 Vertex AI Java SDK（com.google.cloud.vertexai）之上，对应的自动配置属性前缀为spring.ai.vertex.ai.*。随着 Google 推出新一代官方 GenAI SDK（入口类为com.google.genai.Client），Spring AI 将 Google 相关能力迁移到了新的spring-ai-google-genai系列模块（位于 models/spring-ai-google-genai，包名为org.springframework.ai.google.genai.*），并随之重写了自动配置。

新自动配置模块位于 spring-ai-autoconfigure-model-google-genai，其pom.xml直接依赖：

• spring-ai-google-genai（Chat 核心，含GoogleGenAiChatModel）
• spring-ai-google-genai-embedding（文本嵌入）
• spring-ai-google-genai-image（图像生成）
• 以及spring-ai-autoconfigure-model-tool、spring-ai-autoconfigure-retry、chat/embedding/image 三个 observation 自动配置模块

因此，迁移的本质是：替换依赖坐标 → 替换属性前缀与结构 → 替换 Bean 名与类名 → 按需切换认证模式。

一、引入新的 Starter 依赖

1. Chat 能力

<dependency> <groupId>org.springframework.ai</groupId> <artifactId>spring-ai-starter-model-google-genai</artifactId> <version>1.1.0-SNAPSHOT</version> </dependency>

2. Embedding 能力

<dependency> <groupId>org.springframework.ai</groupId> <artifactId>spring-ai-starter-model-google-genai-embedding</artifactId> <version>1.1.0-SNAPSHOT</version> </dependency>

注意：Chat 与 Embedding 两个 starter 相互独立，可单独使用，也可同时引入以满足完整需求。如果项目同时使用对话与向量检索（如 RAG 场景），两个依赖都需要声明。仓库中两个 starter 的pom.xml均位于 starters 目录下（spring-ai-starter-model-google-genai/pom.xml与spring-ai-starter-model-google-genai-embedding/pom.xml），它们最终会传递引入上述自动配置模块。

二、属性命名空间变更（核心变化）

旧属性（Vertex AI 自动配置）

spring.ai.vertex.ai.gemini.project-id=my-project spring.ai.vertex.ai.gemini.location=us-central1 spring.ai.vertex.ai.gemini.chat.options.model=gemini-pro spring.ai.vertex.ai.embedding.text.options.model=textembedding-gecko

新属性（Google GenAI 自动配置）

# 方式一：Vertex AI 模式 spring.ai.google.genai.project-id=my-project spring.ai.google.genai.location=us-central1 spring.ai.google.genai.chat.model=gemini-2.0-flash # 方式二：Gemini Developer API 模式（新增！） spring.ai.google.genai.api-key=your-api-key spring.ai.google.genai.chat.model=gemini-2.0-flash # Embedding 属性 spring.ai.google.genai.embedding.project-id=my-project spring.ai.google.genai.embedding.location=us-central1 spring.ai.google.genai.embedding.text.options.model=text-embedding-004

源码印证与两点关键差异

从源码看，新属性前缀由两个@ConfigurationProperties类定义：

• GoogleGenAiConnectionProperties.java：CONFIG_PREFIX = "spring.ai.google.genai"，字段包括apiKey、projectId、location、credentialsUri（可选的 Google Cloud 凭据 Resource）以及vertexAi（是否强制使用 Vertex AI 模式）。
• GoogleGenAiChatProperties.java：CONFIG_PREFIX = "spring.ai.google.genai.chat"，字段包括model、temperature、topP、topK、candidateCount、maxOutputTokens、stopSequences、responseMimeType、responseSchema、frequencyPenalty、presencePenalty、thinkingBudget、includeThoughts、thinkingLevel、includeExtendedUsageMetadata、缓存相关（cachedContentName、useCachedContent、autoCacheThreshold、autoCacheTtl）、googleSearchRetrieval、includeServerSideToolInvocations、safetySettings、labels、serviceTier与toolChoice。

对比旧版可发现两点结构差异：

1. 前缀整体替换：spring.ai.vertex.ai.gemini.*→spring.ai.google.genai.*，Embedding 侧spring.ai.vertex.ai.embedding.*→spring.ai.google.genai.embedding.*。
2. options.model层级扁平化：旧 Chat 属性是spring.ai.vertex.ai.gemini.chat.options.model，新版为spring.ai.google.genai.chat.model（去掉了中间的options层级）。从 2.0.0 起，GoogleGenAiChatProperties与GoogleGenAiTextEmbeddingProperties内部遗留的options嵌套均被标记为@Deprecated（@DeprecatedConfigurationProperty指向扁平化后的新属性），老写法仍可暂时解析但已被废弃，迁移时应直接使用新结构。

完整 Chat 属性参考（可选配置项）

结合 GoogleGenAiChatProperties.java 的toOptions()方法，以下属性均可配置，且最终会被组装进GoogleGenAiChatOptions：

spring.ai.google.genai.chat.model=gemini-2.0-flash spring.ai.google.genai.chat.temperature=0.7 spring.ai.google.genai.chat.top-p=0.9 spring.ai.google.genai.chat.top-k=40 spring.ai.google.genai.chat.candidate-count=1 spring.ai.google.genai.chat.max-output-tokens=2048 spring.ai.google.genai.chat.stop-sequences=a,b spring.ai.google.genai.chat.response-mime-type=application/json spring.ai.google.genai.chat.frequency-penalty=0.0 spring.ai.google.genai.chat.presence-penalty=0.0 spring.ai.google.genai.chat.thinking-budget=1024 spring.ai.google.genai.chat.thinking-level=LOW spring.ai.google.genai.chat.include-thoughts=true spring.ai.google.genai.chat.include-extended-usage-metadata=true spring.ai.google.genai.chat.google-search-retrieval=false spring.ai.google.genai.chat.include-server-side-tool-invocations=false spring.ai.google.genai.chat.cached-content-name= spring.ai.google.genai.chat.use-cached-content=true spring.ai.google.genai.chat.auto-cache-threshold=3 spring.ai.google.genai.chat.service-tier=DEFAULT

Embedding 侧（GoogleGenAiTextEmbeddingProperties.java）还支持task-type、dimensions、title三个可选参数，例如：

spring.ai.google.genai.embedding.text.model=text-embedding-004 spring.ai.google.genai.embedding.text.task-type=RETRIEVAL_DOCUMENT spring.ai.google.genai.embedding.text.dimensions=768

三、认证模式：Vertex AI 与 Gemini Developer API

新自动配置最大的能力增量是同时支持两种认证模式：

• Vertex AI 模式：沿用 Google Cloud 凭据体系，需要project-id+location（可选credentials-uri指向服务账号 JSON 凭据文件），适合企业内已有 GCP 资源与 IAM 权限体系的场景。
• Gemini Developer API 模式（新增）：只需一个 API Key（spring.ai.google.genai.api-key），无需项目与区域，适合个人开发者与快速原型验证。

模式选择的底层逻辑

从 GoogleGenAiChatAutoConfiguration.java 的googleGenAiClientBean 可以看出完整的判定规则：

1. 同时配置了 API Key 与 Vertex AI 配置（project-id + location）时：
   • 若显式设置spring.ai.google.genai.vertex-ai=true，强制走 Vertex AI，API Key 被忽略并记录 info 日志；
   • 否则默认走 Gemini Developer API（API Key），并输出 warn 日志提示可通过vertex-ai=true切换。
2. 只设置vertex-ai=true但缺少 project-id 或 location：直接抛出IllegalStateException（fail-fast 校验），提示 "Vertex AI mode requires both 'project-id' and 'location'"。
3. 仅设置 API Key：走 Gemini Developer API。
4. 未设置vertex-ai但配置了 project-id + location：自动推断为 Vertex AI 模式。
5. 两者都未配置：抛出IllegalStateException，提示需提供api-key或project-id+location。

Vertex AI 模式下，configureVertexAi会调用builder.project(...).location(...).vertexAI(true)，若提供了credentials-uri，则通过GoogleCredentials.fromStream加载自定义凭据（GoogleGenAiChatAutoConfiguration.java#L113-L124）。

迁移提示：若旧工程使用 API Key 认证，迁移后需删除project-id与location（Chat 场景下 API Key 模式不再需要它们）；若继续使用 Vertex AI，则保留并改为新前缀。

四、环境变量

环境变量在迁移中用于覆盖或兜底属性配置，旧写法不变：

export GOOGLE_CLOUD_PROJECT=my-project export GOOGLE_CLOUD_LOCATION=us-central1

新增的可选写法（对应 Gemini Developer API 模式）：

export GOOGLE_API_KEY=your-api-key

五、Bean 名变更

如果代码中按名称自动装配 Bean（如@Qualifier、getBean("vertexAi")），需要同步更新为：

其中googleGenAiClient与googleGenAiChatModel由 GoogleGenAiChatAutoConfiguration.java 定义（@ConditionalOnMissingBean，可被用户自定义 Bean 覆盖），googleGenAiTextEmbedding由 GoogleGenAiTextEmbeddingAutoConfiguration.java 定义。若业务代码中依赖旧 Bean 名，迁移时必须全局替换。

六、类名与包名变更

如果代码直接 import 相关类，按下表替换：

com.google.genai.Client由自动配置以googleGenAiClientBean 暴露，GoogleGenAiChatModel通过Client.builder()构建，再注入ToolCallingManager、RetryTemplate、ObservationRegistry等（见上述自动配置类），因此只要替换 import 与构造方式即可继续使用 Spring AI 统一的ChatModel/EmbeddingModel抽象 API。

七、移除的功能

迁移后需要注意两个不再存在或暂不支持的配置：

1. transport属性不再需要：旧 Vertex AI 自动配置中用于指定底层传输方式的transport配置已移除，新 SDK 自动处理连接细节，删除对应配置即可。
2. 多模态 Embedding 自动配置已被移除：旧版的多模态 Embedding 自动配置在新 SDK 中暂不支持（等待新 SDK 提供能力），原使用多模态嵌入的项目需评估替代方案。

八、分步迁移清单

按以下顺序执行，可最小化迁移风险：

1. 更新应用属性：
   • 将spring.ai.vertex.ai.*全局替换为spring.ai.google.genai.*；
   • Chat 侧去掉options层级（chat.options.model→chat.model）；
   • 删除任何transport配置。
2. 切换认证方式：
   • 使用 API Key：设置spring.ai.google.genai.api-key，Chat 场景下删除project-id与location；
   • 使用 Vertex AI：保留project-id与location，如需自定义凭据可配置credentials-uri。
3. 更新自定义配置与 Bean 引用：按上文表格替换 Bean 名（googleGenAiClient、googleGenAiChatModel、googleGenAiTextEmbedding）与 import 类名（com.google.genai.Client、org.springframework.ai.google.genai.*）。
4. 全面测试：重点验证 Chat 调用、Embedding 维度、工具调用（仓库测试中已有FunctionCallWithFunctionBeanIT、FunctionCallWithFunctionWrapperIT、FunctionCallWithPromptFunctionIT等集成测试用例，位于 auto-configurations/models/spring-ai-autoconfigure-model-google-genai/src/test 下，可作参考）以及流式输出是否正常。

九、向后兼容性说明

旧的 Vertex AI 自动配置模块在当前仓库中仍然可用，但已被标记为废弃（deprecated）。官方建议尽快迁移到新的 Google GenAI 模块，以获得官方 GenAI SDK 的持续更新、Gemini Developer API（API Key）支持以及更完整的模型能力（如 thinking、缓存内容、服务层级等）。若你仍依赖旧模块，请留意后续版本中的移除计划，并安排迁移窗口。

参考资源（仓库内）

• 迁移指南原文：auto-configurations/models/spring-ai-autoconfigure-model-google-genai/MIGRATION_GUIDE.md
• 自动配置模块 pom：auto-configurations/models/spring-ai-autoconfigure-model-google-genai/pom.xml
• Chat 自动配置与连接属性：GoogleGenAiChatAutoConfiguration.java、GoogleGenAiConnectionProperties.java
• Chat 模型属性：GoogleGenAiChatProperties.java
• Embedding 自动配置与属性：GoogleGenAiTextEmbeddingAutoConfiguration.java、GoogleGenAiTextEmbeddingProperties.java
• 模型实现模块：models/spring-ai-google-genai
• Starter 坐标：starters/spring-ai-starter-model-google-genai/pom.xml、starters/spring-ai-starter-model-google-genai-embedding/pom.xml

【免费下载链接】spring-aiAn Application Framework for AI Engineering项目地址: https://gitcode.com/GitHub_Trending/spr/spring-ai