此版本仍在开发中,尚未被视为稳定版。为了获取最新的快照版本,请使用Spring AI 1.1.3spring-doc.cadn.net.cn

谷歌GenAI聊天

Google GenAI API谷歌生成式AI API允许开发者通过Gemini开发者API或Vertex AI使用Google的Gemini模型来构建生成式AI应用。 谷歌生成式AI API支持多模态提示作为输入,并输出文本或代码。 多模态模型能够处理来自多种模态的信息,包括图像、视频和文本。例如,您可以向模型发送一张饼干的照片,并要求它提供该饼干的制作Recipes。spring-doc.cadn.net.cn

Gemini是Google DeepMind开发的一系列生成式AI模型,旨在应对多模态应用场景。Gemini API为您提供访问权限,包括Gemini 2.0 Flash-Lite,所有Gemini Pro模型,直至最新的Gemini 3 Prospring-doc.cadn.net.cn

此实现提供了两种认证模式:spring-doc.cadn.net.cn

前提条件

请选择以下认证方法之一:spring-doc.cadn.net.cn

选项 1:Gemini 开发者 API(API 密钥)

选项 2:Vertex AI(谷歌云)

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

自动配置

There has been a significant change in the Spring AI auto-configuration, starter modules' artifact names. Please refer to the 升级说明以获取更多信息。spring-doc.cadn.net.cn

Spring AI 为 Google GenAI 聊天客户端提供了 Spring Boot 自动配置功能。 要启用该功能,请在项目的 Maven pom.xml 或 Gradle build.gradle 构建文件中添加以下依赖项:spring-doc.cadn.net.cn

<dependency>
    <groupId>org.springframework.ai</groupId>
    <artifactId>spring-ai-starter-model-google-genai</artifactId>
</dependency>
dependencies {
    implementation 'org.springframework.ai:spring-ai-starter-model-google-genai'
}
参考以下依赖管理部分,添加Spring AI BOM到你的构建文件中。

聊天属性

启用和禁用聊天自动配置现在通过顶级属性使用前缀 spring.ai.model.chat 配置完成。spring-doc.cadn.net.cn

要启用,请设置 spring.ai.model.chat=google-genai (默认情况下已启用)spring-doc.cadn.net.cn

要禁用,请设置 spring.ai.model.chat=none(或任何不匹配google-genai的值)spring-doc.cadn.net.cn

这种修改是为了允许配置多个模型。spring-doc.cadn.net.cn

连接属性

前缀 spring.ai.google.genai 用于作为属性前缀,以便您连接到Google GenAI。spring-doc.cadn.net.cn

属性 描述 默认

spring.ai.model.chatspring-doc.cadn.net.cn

启用聊天模型客户端spring-doc.cadn.net.cn

google-genaispring-doc.cadn.net.cn

spring.ai.google.genai.api-keyspring-doc.cadn.net.cn

Gemini 开发者 API 的 API 密钥。当提供此密钥时,客户端将使用 Gemini 开发者 API 而非 Vertex AI。spring-doc.cadn.net.cn

-spring-doc.cadn.net.cn

spring.ai.google.genai.project-idspring-doc.cadn.net.cn

Google Cloud Platform 项目ID(Vertex AI模式必需)spring-doc.cadn.net.cn

-spring-doc.cadn.net.cn

spring.ai.google.genai.locationspring-doc.cadn.net.cn

Google Cloud 区域(Vertex AI 模式必需)spring-doc.cadn.net.cn

-spring-doc.cadn.net.cn

spring.ai.google.genai.credentials-urispring-doc.cadn.net.cn

通往Google Cloud凭证的URI。当提供时,它用于创建一个GoogleCredentials实例以进行身份验证。spring-doc.cadn.net.cn

-spring-doc.cadn.net.cn

聊天模型属性

前缀spring.ai.google.genai.chat是属性前缀,用于配置Google GenAI Chat的聊天模型实现。spring-doc.cadn.net.cn

属性 描述 默认

spring.ai.google.genai.chat.options.modelspring-doc.cadn.net.cn

支持使用的Google GenAI 聊天模型包括 gemini-2.0-flash, gemini-2.0-flash-lite, gemini-pro, 和 gemini-1.5-flashspring-doc.cadn.net.cn

gemini-2.0-flashspring-doc.cadn.net.cn

spring.ai.google.genai.chat.options.response-mime-typespring-doc.cadn.net.cn

生成候选文本的响应MIME类型。spring-doc.cadn.net.cn

text/plain: (默认) 文本输出或 application/json: JSON 响应.spring-doc.cadn.net.cn

spring.ai.google.genai.chat.options.google-search-retrievalspring-doc.cadn.net.cn

使用 Google 搜索接地功能spring-doc.cadn.net.cn

truefalse,默认为 false.spring-doc.cadn.net.cn

spring.ai.google.genai.chat.options.temperaturespring-doc.cadn.net.cn

控制输出的随机性。值范围为 [0.0,1.0],包括两端。接近 1.0 的值将产生更多样化的响应,而接近 0.0 的值通常会导致生成的响应较为不那么出人意料。spring-doc.cadn.net.cn

0.7spring-doc.cadn.net.cn

spring.ai.google.genai.chat.options.top-kspring-doc.cadn.net.cn

在采样时要考虑的最大Tokens数量。生成器使用了结合了Top-k和 nucleus的采样方法。Top-k采样考虑了概率最高的topK个Tokens集合。spring-doc.cadn.net.cn

-spring-doc.cadn.net.cn

spring.ai.google.genai.chat.options.top-pspring-doc.cadn.net.cn

在采样时考虑的Tokens最大累积概率。生成过程结合使用了Top-k和核(nucleus)采样。核采样会考虑概率总和至少为topP的最小子集的Tokens。spring-doc.cadn.net.cn

-spring-doc.cadn.net.cn

spring.ai.google.genai.chat.options.candidate-countspring-doc.cadn.net.cn

生成的响应消息数量。此值必须在[1, 8]之间(包含边界)。默认值为1。spring-doc.cadn.net.cn

1spring-doc.cadn.net.cn

spring.ai.google.genai.chat.options.max-output-tokensspring-doc.cadn.net.cn

生成的最大Tokens数量。spring-doc.cadn.net.cn

-spring-doc.cadn.net.cn

spring.ai.google.genai.chat.options.frequency-penaltyspring-doc.cadn.net.cn

减少重复的频率惩罚。spring-doc.cadn.net.cn

-spring-doc.cadn.net.cn

spring.ai.google.genai.chat.options.presence-penaltyspring-doc.cadn.net.cn

减少重复的惩罚系数。spring-doc.cadn.net.cn

-spring-doc.cadn.net.cn

spring.ai.google.genai.chat.options.thinking-budgetspring-doc.cadn.net.cn

为思考过程考虑预算。参见思维配置spring-doc.cadn.net.cn

-spring-doc.cadn.net.cn

spring.ai.google.genai.chat.options.thinking-levelspring-doc.cadn.net.cn

模型应生成的思考Tokens级别。有效值:LOWHIGHTHINKING_LEVEL_UNSPECIFIED。参见思考配置spring-doc.cadn.net.cn

-spring-doc.cadn.net.cn

spring.ai.google.genai.chat.options.include-thoughtsspring-doc.cadn.net.cn

为函数调用启用思维签名。Gemini 3 Pro 必需此设置,以避免在内部工具执行循环中出现验证错误。参见思维签名spring-doc.cadn.net.cn

falsespring-doc.cadn.net.cn

spring.ai.google.genai.chat.options.tool-namesspring-doc.cadn.net.cn

用于在单个提示请求中启用函数调用的工具列表,这些工具通过它们的名称来识别。具有这些名称的工具必须存在于ToolCallback注册表中。spring-doc.cadn.net.cn

-spring-doc.cadn.net.cn

spring.ai.google.genai.chat.options.tool-callbacksspring-doc.cadn.net.cn

向ChatModel注册的工具回调。spring-doc.cadn.net.cn

-spring-doc.cadn.net.cn

spring.ai.google.genai.chat.options.internal-tool-execution-enabledspring-doc.cadn.net.cn

如果为真,则应执行工具,否则将模型的响应返回给用户。默认值为null,但如果为null,ToolCallingChatOptions.DEFAULT_TOOL_EXECUTION_ENABLED(表示真)将被考虑spring-doc.cadn.net.cn

-spring-doc.cadn.net.cn

spring.ai.google.genai.chat.options.safety-settingsspring-doc.cadn.net.cn

安全设置列表,用于控制安全过滤器,由Google GenAI 安全设置定义。每个安全设置可以包含一个方法、阈值和类别。spring-doc.cadn.net.cn

-spring-doc.cadn.net.cn

spring.ai.google.genai.chat.options.cached-content-namespring-doc.cadn.net.cn

本次请求使用的缓存内容的名称。当与use-cached-content=true一起设置时,缓存内容将用作上下文。参见缓存内容spring-doc.cadn.net.cn

-spring-doc.cadn.net.cn

spring.ai.google.genai.chat.options.use-cached-contentspring-doc.cadn.net.cn

是否使用可用的缓存内容。当设置为true且cached-content-name被设置时,系统将使用缓存的内容。spring-doc.cadn.net.cn

falsespring-doc.cadn.net.cn

spring.ai.google.genai.chat.options.auto-cache-thresholdspring-doc.cadn.net.cn

自动缓存超过此Tokens阈值的提示。当设置时,大于此值的提示将被自动缓存以供重用。设为null以禁用自动缓存。spring-doc.cadn.net.cn

-spring-doc.cadn.net.cn

spring.ai.google.genai.chat.options.auto-cache-ttlspring-doc.cadn.net.cn

自动缓存内容的有效期(持续时间),采用ISO-8601格式表示(例如,PT1H代表1小时)。此设置在启用自动缓存时使用。spring-doc.cadn.net.cn

PT1Hspring-doc.cadn.net.cn

spring.ai.google.genai.chat.enable-cached-contentspring-doc.cadn.net.cn

为管理缓存内容,启用GoogleGenAiCachedContentService bean。spring-doc.cadn.net.cn

truespring-doc.cadn.net.cn

所有以spring.ai.google.genai.chat.options为前缀的属性都可以通过向Prompt调用中添加特定于请求的运行时选项在运行时覆盖。

运行时选项

GoogleGenAiChatOptions.java 文件提供了模型配置选项,如温度、topK等参数。spring-doc.cadn.net.cn

On start-up, the default options can be configured with the GoogleGenAiChatModel(client, options) constructor or the spring.ai.google.genai.chat.options.* properties.spring-doc.cadn.net.cn

在运行时,您可以通过向Prompt调用添加新的、针对请求的选项来覆盖默认设置。 例如,要为特定请求覆盖默认温度:spring-doc.cadn.net.cn

ChatResponse response = chatModel.call(
    new Prompt(
        "Generate the names of 5 famous pirates.",
        GoogleGenAiChatOptions.builder()
            .temperature(0.4)
        .build()
    ));
除了模型特定的GoogleGenAiChatOptions之外,您还可以使用可移植的ChatOptions实例,通过ChatOptions#builder()方法创建。

工具调用

Google GenAI 模型支持工具调用(函数调用)功能,使得模型在对话过程中能够使用工具。 以下是如何定义和使用基于@Tool的工具的示例:spring-doc.cadn.net.cn

public class WeatherService {

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

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

您也可以将 java.util.function 包中的 beans 用作工具:spring-doc.cadn.net.cn

@Bean
@Description("Get the weather in location. Return temperature in 36°F or 36°C format.")
public Function<Request, Response> weatherFunction() {
    return new MockWeatherService();
}

String response = ChatClient.create(this.chatModel)
        .prompt("What's the weather like in Boston?")
        .toolNames("weatherFunction")
        .inputType(Request.class)
        .call()
        .content();

工具文档中查找更多信息。spring-doc.cadn.net.cn

思考配置

Gemini模型支持一种“思考”能力,使得模型在生成响应前能够进行更深层次的推理。这通过思维深度参数控制,其中包括三个相关选项:浅层思考中层思考深层思考spring-doc.cadn.net.cn

思维层级

选项 thinkingLevel 用于控制模型生成的推理Tokens深度。此功能适用于支持思考的模型(例如,Gemini 3 Pro 预览版)。spring-doc.cadn.net.cn

描述

LOWspring-doc.cadn.net.cn

极简思维。适用于追求速度胜于深度分析的简单查询。spring-doc.cadn.net.cn

HIGHspring-doc.cadn.net.cn

深入思考。适用于需要深度分析和逐步推理的复杂问题。spring-doc.cadn.net.cn

THINKING_LEVEL_UNSPECIFIEDspring-doc.cadn.net.cn

模型使用其默认行为。spring-doc.cadn.net.cn

通过属性进行配置

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

基于编程的配置

import org.springframework.ai.google.genai.common.GoogleGenAiThinkingLevel;

ChatResponse response = chatModel.call(
    new Prompt(
        "Explain the theory of relativity in simple terms.",
        GoogleGenAiChatOptions.builder()
            .model("gemini-3-pro-preview")
            .thinkingLevel(GoogleGenAiThinkingLevel.HIGH)
            .build()
    ));

思考预算

thinkingBudget 选项为思考过程设定了一个Tokens预算:spring-doc.cadn.net.cn

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

选项兼容性

thinkingLevelthinkingBudget 是互斥的。 您不能在同一个请求中同时使用两者 - 这样做将导致API错误。spring-doc.cadn.net.cn

您可以将 includeThoughtsthinkingLevelthinkingBudget (但不能同时)结合使用:spring-doc.cadn.net.cn

// For Gemini 3 Pro: use thinkingLevel + includeThoughts
ChatResponse response = chatModel.call(
    new Prompt(
        "Analyze this complex scenario.",
        GoogleGenAiChatOptions.builder()
            .model("gemini-3-pro-preview")
            .thinkingLevel(GoogleGenAiThinkingLevel.HIGH)
            .includeThoughts(true)
            .build()
    ));

// For Gemini 2.5: use thinkingBudget + includeThoughts
ChatResponse response = chatModel.call(
    new Prompt(
        "Analyze this complex scenario.",
        GoogleGenAiChatOptions.builder()
            .model("gemini-2.5-pro")
            .thinkingBudget(8192)
            .includeThoughts(true)
            .build()
    ));

模型支持

思考型配置选项是特定于模型的:spring-doc.cadn.net.cn

模型 thinkingLevel thinkingBudget 注意事项

双子座3 Pro(预览版)spring-doc.cadn.net.cn

支持的spring-doc.cadn.net.cn

仅向后兼容spring-doc.cadn.net.cn

使用 thinkingLevel。无法禁用思考功能。需要全局端点。spring-doc.cadn.net.cn

双子星2.5 专业版spring-doc.cadn.net.cn

不支持spring-doc.cadn.net.cn

支持的spring-doc.cadn.net.cn

使用 thinkingBudget。设置为 0 以禁用,-1 为动态。spring-doc.cadn.net.cn

双子座2.5闪存spring-doc.cadn.net.cn

不支持spring-doc.cadn.net.cn

支持的spring-doc.cadn.net.cn

使用 thinkingBudget。设置为 0 以禁用,-1 为动态。spring-doc.cadn.net.cn

双子座2.5 Flash-Litespring-doc.cadn.net.cn

不支持spring-doc.cadn.net.cn

支持的spring-doc.cadn.net.cn

默认情况下禁用思考。设置为thinkingBudget以启用。spring-doc.cadn.net.cn

双子座2.0闪存spring-doc.cadn.net.cn

不支持spring-doc.cadn.net.cn

不支持spring-doc.cadn.net.cn

思考未提供。spring-doc.cadn.net.cn

启用思维功能会增加Tokens使用量和API成本。请根据查询的复杂程度适当使用。

思想签名

Gemini 3 Pro 引入了思想签名,这是在函数调用期间保留模型推理上下文的不透明字节数组。当includeThoughts被启用时,模型会返回思想签名,这些签名必须在内部工具执行循环的同一回合中传回。spring-doc.cadn.net.cn

当思维签名至关重要时

重要提示:思想签名验证仅适用于当前回合——特别是在模型进行函数调用(包括并行和顺序)的内部工具执行循环中。API对对话历史中的前几回合的思想签名进行验证。spring-doc.cadn.net.cn

对于Gemini 2.5 Pro及更早型号,思想签名是可选的,且API较为宽容。spring-doc.cadn.net.cn

配置

使用配置属性启用思维签名:spring-doc.cadn.net.cn

spring.ai.google.genai.chat.options.model=gemini-3-pro-preview
spring.ai.google.genai.chat.options.include-thoughts=true

或者在运行时以编程方式:spring-doc.cadn.net.cn

ChatResponse response = chatModel.call(
    new Prompt(
        "Your question here",
        GoogleGenAiChatOptions.builder()
            .model("gemini-3-pro-preview")
            .includeThoughts(true)
            .toolCallbacks(callbacks)
            .build()
    ));

自动处理

Spring AI 在内部工具执行循环期间自动处理思想签名。当internalToolExecutionEnabled为真(默认情况下),Spring AI会:spring-doc.cadn.net.cn

  1. 从模型响应中提取思想特征spring-doc.cadn.net.cn

  2. 将它们附着到正确的 functionCall 部分上,当发送函数响应时spring-doc.cadn.net.cn

  3. 在单个执行周期内(包括并行和顺序)正确传播它们spring-doc.cadn.net.cn

您无需手动管理思维签名 - Spring AI会确保它们根据API规范正确地附加到functionCall部分。spring-doc.cadn.net.cn

通过函数调用的示例

@Bean
@Description("Get the weather in a location")
public Function<WeatherRequest, WeatherResponse> weatherFunction() {
    return new WeatherService();
}

// Enable includeThoughts for Gemini 3 Pro with function calling
String response = ChatClient.create(this.chatModel)
        .prompt("What's the weather like in Boston?")
        .options(GoogleGenAiChatOptions.builder()
            .model("gemini-3-pro-preview")
            .includeThoughts(true)
            .build())
        .toolNames("weatherFunction")
        .call()
        .content();

手动工具执行模式

如果将internalToolExecutionEnabled=false设置为手动控制工具执行循环,那么在使用Gemini 3 Pro并设置为includeThoughts=true时,必须自行处理思维签名。spring-doc.cadn.net.cn

手动工具执行带有思维签名的要求:spring-doc.cadn.net.cn

  1. 从响应元数据中提取思维特征签名:spring-doc.cadn.net.cn

    AssistantMessage assistantMessage = response.getResult().getOutput();
    Map<String, Object> metadata = assistantMessage.getMetadata();
    List<byte[]> thoughtSignatures = (List<byte[]>) metadata.get("thoughtSignatures");
  2. 在发送函数响应时,请将原始的AssistantMessage及其元数据完整地包含在您的消息历史中。Spring AI会自动将思考签名附到正确的functionCall部分上。spring-doc.cadn.net.cn

  3. 对于Gemini 3 Pro,如果在当前回合中未能保留思维特征,将导致API返回HTTP 400错误。spring-doc.cadn.net.cn

仅当前轮次的函数调用需要思考签名。当开始新的一轮对话(完成一轮函数调用后),你无需保留上一轮的签名信息。
启用includeThoughts会增加Tokens使用量,因为思考过程会被纳入响应中。这会影响API成本,但提供了更好的推理透明度。

多模态

多模态是指模型同时理解和处理来自多种(输入)源信息的能力,包括textpdfimagesaudio等其他数据格式。spring-doc.cadn.net.cn

图像、音频、视频

Google的Gemini人工智能模型通过理解并整合文本、代码、音频、图像和视频支持此功能。 了解更多详情,请参阅博客文章Gemini介绍spring-doc.cadn.net.cn

Spring AI的Message接口通过引入媒体类型来支持多模态AI模型。 此类型包含消息中媒体附件的数据和信息,使用Spring的org.springframework.util.MimeType及一个java.lang.Object来存储原始媒体数据。spring-doc.cadn.net.cn

以下是来自GoogleGenAiChatModelIT.java的简单代码示例,展示了用户文本与图像的结合。spring-doc.cadn.net.cn

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

var userMessage = UserMessage.builder()
			.text("Explain what do you see o this picture?")
			.media(List.of(new Media(MimeTypeUtils.IMAGE_PNG, data)))
			.build();

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

PDF

Google GenAI 支持PDF输入类型。 使用application/pdf媒体类型将PDF文件附加到消息中:spring-doc.cadn.net.cn

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

var userMessage = UserMessage.builder()
			.text("You are a very professional document summarization specialist. Please summarize the given document.")
			.media(List.of(new Media(new MimeType("application", "pdf"), pdfData)))
			.build();

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

缓存内容

Google GenAI的上下文缓存功能允许您缓存大量内容(如长文档、代码仓库或媒体),并在多个请求中重用,显著降低API成本并提高对相同内容重复查询的响应速度。spring-doc.cadn.net.cn

优势

缓存需求

使用缓存内容服务

Spring AI 为程序化缓存管理提供 GoogleGenAiCachedContentService。当使用 Spring Boot 自动配置时,该服务会自动配置。spring-doc.cadn.net.cn

创建缓存内容

@Autowired
private GoogleGenAiCachedContentService cachedContentService;

// Create cached content with a large document
String largeDocument = "... your large context here (>32k tokens) ...";

CachedContentRequest request = CachedContentRequest.builder()
    .model("gemini-2.0-flash")
    .contents(List.of(
        Content.builder()
            .role("user")
            .parts(List.of(Part.fromText(largeDocument)))
            .build()
    ))
    .displayName("My Large Document Cache")
    .ttl(Duration.ofHours(1))
    .build();

GoogleGenAiCachedContent cachedContent = cachedContentService.create(request);
String cacheName = cachedContent.getName(); // Save this for reuse

在聊天请求中使用缓存内容

一旦创建了缓存内容,您可以在聊天请求中引用它:spring-doc.cadn.net.cn

ChatResponse response = chatModel.call(
    new Prompt(
        "Summarize the key points from the document",
        GoogleGenAiChatOptions.builder()
            .useCachedContent(true)
            .cachedContentName(cacheName) // Use the cached content name
            .build()
    ));

或者通过配置属性:spring-doc.cadn.net.cn

spring.ai.google.genai.chat.options.use-cached-content=true
spring.ai.google.genai.chat.options.cached-content-name=cachedContent/your-cache-name

管理缓存内容

GoogleGenAiCachedContentService 提供了全面的缓存管理功能:spring-doc.cadn.net.cn

// Retrieve cached content
GoogleGenAiCachedContent content = cachedContentService.get(cacheName);

// Update cache TTL
CachedContentUpdateRequest updateRequest = CachedContentUpdateRequest.builder()
    .ttl(Duration.ofHours(2))
    .build();
GoogleGenAiCachedContent updated = cachedContentService.update(cacheName, updateRequest);

// List all cached content
List<GoogleGenAiCachedContent> allCaches = cachedContentService.listAll();

// Delete cached content
boolean deleted = cachedContentService.delete(cacheName);

// Extend cache TTL
GoogleGenAiCachedContent extended = cachedContentService.extendTtl(cacheName, Duration.ofMinutes(30));

// Cleanup expired caches
int removedCount = cachedContentService.cleanupExpired();

异步操作

所有操作都有异步版本:spring-doc.cadn.net.cn

CompletableFuture<GoogleGenAiCachedContent> futureCache =
    cachedContentService.createAsync(request);

CompletableFuture<GoogleGenAiCachedContent> futureGet =
    cachedContentService.getAsync(cacheName);

CompletableFuture<Boolean> futureDelete =
    cachedContentService.deleteAsync(cacheName);

自动缓存

Spring AI 可以在大型提示超过指定Tokens阈值时自动缓存这些提示:spring-doc.cadn.net.cn

# Automatically cache prompts larger than 100,000 tokens
spring.ai.google.genai.chat.options.auto-cache-threshold=100000
# Set auto-cache TTL to 1 hour
spring.ai.google.genai.chat.options.auto-cache-ttl=PT1H

或者以编程方式:spring-doc.cadn.net.cn

ChatResponse response = chatModel.call(
    new Prompt(
        largePrompt,
        GoogleGenAiChatOptions.builder()
            .autoCacheThreshold(100000)
            .autoCacheTtl(Duration.ofHours(1))
            .build()
    ));
自动缓存对于一次性处理大量上下文非常有用。但对于相同上下文的重复使用,手动创建和引用缓存内容更为高效。

监控缓存使用情况

缓存内容包括可通过服务访问的使用元数据。spring-doc.cadn.net.cn

GoogleGenAiCachedContent content = cachedContentService.get(cacheName);

// Check if cache is expired
boolean expired = content.isExpired();

// Get remaining TTL
Duration remaining = content.getRemainingTtl();

// Get usage metadata
CachedContentUsageMetadata metadata = content.getUsageMetadata();
if (metadata != null) {
    System.out.println("Total tokens: " + metadata.totalTokenCount().orElse(0));
}

最佳实践

  1. 缓存生命周期: 根据您的使用场景设置适当的TTL。对于频繁变化的内容使用较短的TTL,对于静态内容使用较长的TTL。spring-doc.cadn.net.cn

  2. 缓存命名: 使用描述性的显示名称轻松识别缓存内容。spring-doc.cadn.net.cn

  3. 清理: 定期清理过期缓存以保持组织性。spring-doc.cadn.net.cn

  4. Tokens阈值: 仅缓存超过最小阈值(32,768个Tokens)的内容。spring-doc.cadn.net.cn

  5. 成本优化: 在多次请求中重用缓存内容,以最大化成本节约。spring-doc.cadn.net.cn

配置示例

完整配置示例:spring-doc.cadn.net.cn

# Enable cached content service (enabled by default)
spring.ai.google.genai.chat.enable-cached-content=true

# Use a specific cached content
spring.ai.google.genai.chat.options.use-cached-content=true
spring.ai.google.genai.chat.options.cached-content-name=cachedContent/my-cache-123

# Auto-caching configuration
spring.ai.google.genai.chat.options.auto-cache-threshold=50000
spring.ai.google.genai.chat.options.auto-cache-ttl=PT30M

示例控制器

创建一个新的Spring Boot项目,并将spring-boot-starter-web添加到您的pom(或gradle)依赖中。spring-doc.cadn.net.cn

src/main/resources目录下添加一个application.properties文件,以启用并配置Google GenAI聊天模型:spring-doc.cadn.net.cn

使用Gemini开发者API(API密钥)

spring.ai.google.genai.api-key=YOUR_API_KEY
spring.ai.google.genai.chat.options.model=gemini-2.0-flash
spring.ai.google.genai.chat.options.temperature=0.5

使用Vertex AI

spring.ai.google.genai.project-id=PROJECT_ID
spring.ai.google.genai.location=LOCATION
spring.ai.google.genai.chat.options.model=gemini-2.0-flash
spring.ai.google.genai.chat.options.temperature=0.5
project-id 替换为您的Google Cloud项目ID,而 location 代表Google Cloud区域 如 us-central1, europe-west1, 等……

每个模型都有其支持的区域集,您可以在模型页面上找到支持区域的列表。spring-doc.cadn.net.cn

这将创建一个GoogleGenAiChatModel实现,您可以将其注入到您的类中。 以下是一个使用聊天模型进行文本生成的简单@Controller类的例子。spring-doc.cadn.net.cn

@RestController
public class ChatController {

    private final GoogleGenAiChatModel chatModel;

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

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

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

手动配置

GoogleGenAiChatModel 实现了 ChatModel 并使用 com.google.genai.Client 连接到Google GenAI服务。spring-doc.cadn.net.cn

spring-ai-google-genai 依赖添加到您项目的 Maven pom.xml 文件中:spring-doc.cadn.net.cn

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

或者添加到您的Gradle 构建脚本文件中。spring-doc.cadn.net.cn

dependencies {
    implementation 'org.springframework.ai:spring-ai-google-genai'
}
参考以下依赖管理部分,添加Spring AI BOM到你的构建文件中。

接下来,创建一个GoogleGenAiChatModel并用它来生成文本:spring-doc.cadn.net.cn

使用API密钥

Client genAiClient = Client.builder()
    .apiKey(System.getenv("GOOGLE_API_KEY"))
    .build();

var chatModel = new GoogleGenAiChatModel(genAiClient,
    GoogleGenAiChatOptions.builder()
        .model(ChatModel.GEMINI_2_0_FLASH)
        .temperature(0.4)
    .build());

ChatResponse response = this.chatModel.call(
    new Prompt("Generate the names of 5 famous pirates."));

使用Vertex AI

Client genAiClient = Client.builder()
    .project(System.getenv("GOOGLE_CLOUD_PROJECT"))
    .location(System.getenv("GOOGLE_CLOUD_LOCATION"))
    .vertexAI(true)
    .build();

var chatModel = new GoogleGenAiChatModel(genAiClient,
    GoogleGenAiChatOptions.builder()
        .model(ChatModel.GEMINI_2_0_FLASH)
        .temperature(0.4)
    .build());

ChatResponse response = this.chatModel.call(
    new Prompt("Generate the names of 5 famous pirates."));

数字GoogleGenAiChatOptions为聊天请求提供了配置信息。 数字GoogleGenAiChatOptions.Builder是流利选项构建器。spring-doc.cadn.net.cn

从Vertex AI Gemini迁移

如果您当前正在使用Vertex AI Gemini实现(spring-ai-vertex-ai-gemini),您可以进行最小更改迁移到Google GenAI:spring-doc.cadn.net.cn

主要区别

  1. SDK: Google GenAI 现使用新版本 com.google.genai.Client 而非 com.google.cloud.vertexai.VertexAIspring-doc.cadn.net.cn

  2. 认证方式: 同时支持API密钥和Google Cloud凭证spring-doc.cadn.net.cn

  3. 包名称: 类位于 org.springframework.ai.google.genai 而不是 org.springframework.ai.vertexai.geminispring-doc.cadn.net.cn

  4. 属性前缀: 使用 spring.ai.google.genai 代替 spring.ai.vertex.ai.geminispring-doc.cadn.net.cn

何时使用Google GenAI与Vertex AI Gemini进行比较

使用Google GenAI的场景包括: - 需要快速原型设计并使用API密钥 - 需要从开发者API获取最新的Gemini特性 - 希望在API密钥与Vertex AI模式之间灵活切换spring-doc.cadn.net.cn

使用Vertex AI Gemini的情况包括: - 您已有Vertex AI基础设施 - 您需要特定的Vertex AI企业功能 - 您的组织要求仅部署在Google Cloud上spring-doc.cadn.net.cn

Java底层客户端

Google GenAI 的实现是基于全新的 Google GenAI Java SDK 构建的,该 SDK 为访问 Gemini 模型提供了一个现代化、简化的 API。spring-doc.cadn.net.cn