接入 Google Gemini 与 Vertex AI

15.1 Gemini 是什么

Gemini 是 Google DeepMind 开发的生成式 AI 模型家族。它天生支持多模态，能同时理解文本、图片、音频和视频。你可以发一张饼干照片，让它写出配方。

Gemini 的模型按能力和成本分档：Flash 系列轻快便宜，适合日常任务；Pro 系列能力强，适合复杂问题。常见模型名有 gemini-2.5-flash、gemini-2.5-pro、gemini-2.5-flash-lite，以及更新的 gemini-3.1-pro-preview、gemini-3.5-flash。

Spring AI 对 Google 的集成统一放在 spring-ai-google-genai 模块里。这个模块支持两种认证方式，用途完全不同。

15.2 两种接入方式

对比项	Gemini Developer API	Vertex AI
认证方式	API Key	Google Cloud 凭证
获取成本	到 Google AI Studio 免费申请	需要 GCP 项目
适用场景	快速原型、个人开发	生产部署、企业级
配置属性	spring.ai.google.genai.api-key	project-id + location

两条路用的都是同一套 Gemini 模型，只是入口不同。API Key 方式最简单，五分钟就能跑起来。Vertex AI 走 Google Cloud，有配额管理、审计等企业能力，但要先有云账号。

15.3 准备工作

用 API Key 方式，只需要一个密钥。打开 Google AI Studio，创建 API Key 即可。

用 Vertex AI 方式，需要先安装 gcloud CLI，然后执行两条命令认证：

gcloud config set project <PROJECT_ID>
gcloud auth application-default login <ACCOUNT>

把 PROJECT_ID 换成你的 GCP 项目 ID，ACCOUNT 换成你的 Google 账号。认证完成后，在配置里填项目 ID 和区域。

区域有讲究。每个模型支持的区域不同，具体以官方模型页面的区域列表为准。选模型前先查清楚，避免调用时报区域不可用。

15.4 添加依赖

在 Maven 的 pom.xml 中加入 starter：

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

Gradle 写法：

dependencies {
    implementation 'org.springframework.ai:spring-ai-starter-model-google-genai'
}

别忘了在 dependencyManagement 里引入 spring-ai-bom，版本用 2.0.0。这是前面章节反复强调的惯例，后面不再重复。

15.5 最小配置与首次对话

在 application.properties 里配置连接信息和模型参数：

# API Key 方式（Gemini Developer API）
spring.ai.google.genai.api-key=YOUR_API_KEY
spring.ai.google.genai.chat.model=gemini-2.5-flash
spring.ai.google.genai.chat.temperature=0.5

Vertex AI 方式则把前三行换成：

# Vertex AI 方式（Google Cloud）
spring.ai.google.genai.project-id=PROJECT_ID
spring.ai.google.genai.location=us-central1
spring.ai.google.genai.chat.model=gemini-2.5-flash

启动后 Spring Boot 自动装配 GoogleGenAiChatModel。推荐直接用 ChatClient 调用，代码和别的厂商完全一致：

@RestController
public class ChatController {

    private final ChatClient chatClient;

    public ChatController(ChatClient.Builder builder) {
        this.chatClient = builder.build();
    }

    @GetMapping("/ai/generate")
    public Map<String, String> generate(@RequestParam(defaultValue = "讲个笑话") String message) {
        return Map.of("generation", chatClient.prompt(message).call().content());
    }

    @GetMapping("/ai/generateStream")
    public Flux<String> generateStream(@RequestParam(defaultValue = "讲个笑话") String message) {
        return chatClient.prompt(message).stream().content();
    }
}

依赖注入 ChatClient.Builder，而不是具体的 GoogleGenAiChatModel。这样以后换厂商，业务代码不用动。

15.6 运行时覆盖参数

模型参数可以在每次请求时单独覆盖。用 GoogleGenAiChatOptions 的 builder：

ChatResponse response = chatModel.call(
    new Prompt("列出 5 个中国省会城市",
        GoogleGenAiChatOptions.builder()
            .model("gemini-2.5-flash")
            .temperature(0.4)
            .build()));

常用参数有 temperature（随机性）、top-k / top-p（采样策略）、max-output-tokens（输出上限）、candidate-count（返回候选数，1 到 8）。所有 spring.ai.google.genai.chat.* 属性都能在运行时被覆盖。

15.7 多模态：图片与 PDF

Gemini 的强项是多模态。Spring AI 用 Media 类型把图片、音频、视频挂到消息上。下面这个例子同时发送文本和一张图片：

byte[] data = new ClassPathResource("/vertex-test.png").getContentAsByteArray();

UserMessage userMessage = UserMessage.builder()
    .text("这张图里有什么？")
    .media(List.of(new Media(MimeTypeUtils.IMAGE_PNG, data)))
    .build();

ChatResponse response = chatModel.call(new Prompt(List.of(userMessage)));

PDF 也支持，媒体类型用 application/pdf：

Resource pdfData = new ClassPathResource("/spring-ai-reference-overview.pdf");

UserMessage userMessage = UserMessage.builder()
    .text("请总结这份文档")
    .media(List.of(new Media(new MimeType("application", "pdf"), pdfData)))
    .build();

ChatResponse response = chatModel.call(new Prompt(List.of(userMessage)));

用 ChatClient 写更简洁：

String response = chatClient.prompt()
    .user(u -> u.text("这张图里有什么？")
        .media(MimeTypeUtils.IMAGE_PNG, new ClassPathResource("/test.png")))
    .call()
    .content();

15.8 直接注入模型与流式响应

业务代码推荐用 ChatClient，但有些场景需要直接操作模型对象。可以注入 GoogleGenAiChatModel，它实现了 ChatModel 和 StreamingChatModel：

@RestController
public class ChatController {

    private final GoogleGenAiChatModel chatModel;

    public ChatController(GoogleGenAiChatModel chatModel) {
        this.chatModel = chatModel;
    }

    @GetMapping("/ai/generate")
    public Map<String, String> generate(@RequestParam(defaultValue = "Tell me a joke") String message) {
        return Map.of("generation", chatModel.call(message));
    }

    @GetMapping("/ai/generateStream")
    public Flux<ChatResponse> generateStream(@RequestParam(defaultValue = "Tell me a joke") String message) {
        return chatModel.stream(new Prompt(new UserMessage(message)));
    }
}

call 返回完整响应，stream 返回 Flux<ChatResponse>。流式适合长回答，用户能边看边等。

15.9 工具调用

GoogleGenAiChatModel 自己不会执行工具。工具循环交给 ChatClient 的 ToolCallingAdvisor 管理，它在检测到工具调用时自动处理。定义一个 @Tool 方法即可：

public class WeatherService {

    @Tool(description = "Get the weather in location")
    public String weatherByLocation(@ToolParam(description = "City or state name") String location) {
        return "20 degrees";
    }
}

String response = ChatClient.create(chatModel)
    .prompt("What's the weather like in Boston?")
    .tools(new WeatherService())
    .call()
    .content();

也可以注册 ToolCallback Bean 再传入。这套用法和 OpenAI、Mistral 完全一致，属于 Spring AI 的统一抽象。

15.10 联网搜索与上下文缓存

Gemini 支持服务端联网搜索，也就是 Grounding。开启后，模型遇到时效性问题会自己上网查：

spring.ai.google.genai.chat.google-search-retrieval=true
spring.ai.google.genai.chat.include-server-side-tool-invocations=true

第二个属性把服务端的搜索调用和结果写进响应元数据，方便观察模型搜了什么。注意它只支持 API Key 方式，Vertex AI 不支持。

上下文缓存是省钱利器。长文档反复提问时，把内容缓存起来，缓存 token 的价格只有常规输入的十分之一到四分之一。缓存最小 32768 token，默认有效期 1 小时：

# 超过 10 万 token 的提示词自动缓存
spring.ai.google.genai.chat.auto-cache-threshold=100000
spring.ai.google.genai.chat.auto-cache-ttl=PT1H

缓存内容超过 32768 token 才划算，小提示词别开。缓存管理也可以编程式操作，注入 GoogleGenAiCachedContentService 后能创建、查询、续期、删除缓存条目，还带异步版本。重复使用同一份长上下文时，手动建缓存比自动缓存更可控。

安全过滤也值得配。safety-settings 属性按类别和阈值设置安全过滤器，控制模型对敏感内容的处理强度。默认值对多数应用够用，涉及未成年人内容或医疗场景时再收紧。

15.11 思考（Thinking）配置

Gemini 2.5 之后支持”思考”能力，模型在回答前先推理。Spring AI 提供两个配置项，注意它们互斥：

• thinking-budget：思考的 token 预算。0 表示关闭，正数表示上限。适用于 Gemini 2.5 系列。
• thinking-level：思考深度（LOW / HIGH 等）。适用于 Gemini 3.x 系列。

两个参数不能同时用，混用会报 API 错误。模型兼容性也分两拨：Gemini 2.5 系列只用 budget，Gemini 3 系列只用 level，而且 3 Pro 只认 LOW 和 HIGH，传 MINIMAL 会抛异常。

spring.ai.google.genai.chat.model=gemini-3.1-pro-preview
spring.ai.google.genai.chat.thinking-level=HIGH

Gemini 2.5 的写法是：

ChatResponse response = chatModel.call(
    new Prompt("Solve this complex math problem step by step.",
        GoogleGenAiChatOptions.builder()
            .model("gemini-2.5-pro")
            .thinkingBudget(8192)
            .build()));

15.12 从旧版 Vertex AI Gemini 迁移

Spring AI 2.0 移除了 spring-ai-vertex-ai-gemini 模块，统一到 google-genai。迁移时注意四处变化：

• SDK：从 com.google.cloud.vertexai.VertexAI 换成 com.google.genai.Client
• 包名：org.springframework.ai.vertexai.gemini 换成 org.springframework.ai.google.genai
• 配置前缀：spring.ai.vertex.ai.gemini 换成 spring.ai.google.genai
• 依赖：spring-ai-starter-model-vertex-ai-gemini 换成 spring-ai-starter-model-google-genai

换依赖、改前缀、改 import，三步就能迁完。API Key 和 Vertex AI 两种认证在同一个模块里共存，不用再为两种方式各引一个依赖。

15.13 常见问题

报错 400 说 region 不支持。 模型和区域绑定，gemini-3.1-pro-preview 只在 global 端点可用。设置 spring.ai.google.genai.location=global 再试。

工具调用时 Gemini 3 Pro 报校验错误。 3 Pro 要求开启 thought signature：spring.ai.google.genai.chat.include-thoughts=true。用 ChatClient 时 Spring AI 自动处理签名，手动循环时要把原始 AssistantMessage 原样留在历史里。

API Key 和 Vertex AI 都配了会怎样。 配了 api-key 就走 Developer API，project-id 被忽略。想切 Vertex AI，把 api-key 去掉。

想换账号。 聊天和嵌入模块共享连接配置，只配一次 spring.ai.google.genai.* 即可，两边都生效。

响应想直接要 JSON。 设置 spring.ai.google.genai.chat.response-mime-type=application/json，模型会按 JSON 格式输出，适合配合结构化解析。

15.14 小结

本节完成了 Gemini 的接入。核心是分清 API Key 与 Vertex AI 两种认证，记住 spring.ai.google.genai 前缀。多模态和工具调用用的都是 Spring AI 统一抽象，和别的厂商没有区别。下一节讲 Azure OpenAI，配置思路会换成”端点 + 部署名”的组合。