From b8e31159e144ff9f8518468f49d40605f33f72ba Mon Sep 17 00:00:00 2001 From: ddobrin Date: Sun, 31 Aug 2025 14:59:16 -0400 Subject: [PATCH] Fixes #4270 Add documentation for the new Spring AI - Google GenAI integration modules Signed-off-by: ddobrin --- .../MIGRATION_GUIDE.md | 24 ++ ...iEmbeddingConnectionAutoConfiguration.java | 2 +- .../README.md | 40 +- models/spring-ai-google-genai/README.md | 6 +- .../src/main/antora/modules/ROOT/nav.adoc | 8 +- .../ROOT/pages/api/chat/comparison.adoc | 1 + .../pages/api/chat/google-genai-chat.adoc | 389 ++++++++++++++++++ .../google-genai-embeddings-text.adoc | 308 ++++++++++++++ 8 files changed, 769 insertions(+), 9 deletions(-) create mode 100644 spring-ai-docs/src/main/antora/modules/ROOT/pages/api/chat/google-genai-chat.adoc create mode 100644 spring-ai-docs/src/main/antora/modules/ROOT/pages/api/embeddings/google-genai-embeddings-text.adoc diff --git a/auto-configurations/models/spring-ai-autoconfigure-model-google-genai/MIGRATION_GUIDE.md b/auto-configurations/models/spring-ai-autoconfigure-model-google-genai/MIGRATION_GUIDE.md index 9a1a2c3d3d8..edb77bced52 100644 --- a/auto-configurations/models/spring-ai-autoconfigure-model-google-genai/MIGRATION_GUIDE.md +++ b/auto-configurations/models/spring-ai-autoconfigure-model-google-genai/MIGRATION_GUIDE.md @@ -4,6 +4,30 @@ This guide helps you migrate from the old Vertex AI-based autoconfiguration to the new Google GenAI SDK-based autoconfiguration. +## Starter Dependencies + +Spring AI provides separate starters for Google GenAI functionality: + +### Chat Functionality +```xml + + org.springframework.ai + spring-ai-starter-model-google-genai + 1.1.0-SNAPSHOT + +``` + +### Embedding Functionality +```xml + + org.springframework.ai + spring-ai-starter-model-google-genai-embedding + 1.1.0-SNAPSHOT + +``` + +**Note**: If you need both chat and embedding capabilities, include both starters in your project. The starters are designed to be used independently or together based on your requirements. + ## Key Changes ### 1. Property Namespace Changes diff --git a/auto-configurations/models/spring-ai-autoconfigure-model-google-genai/src/main/java/org/springframework/ai/model/google/genai/autoconfigure/embedding/GoogleGenAiEmbeddingConnectionAutoConfiguration.java b/auto-configurations/models/spring-ai-autoconfigure-model-google-genai/src/main/java/org/springframework/ai/model/google/genai/autoconfigure/embedding/GoogleGenAiEmbeddingConnectionAutoConfiguration.java index d68bea56c58..9694b40f4f4 100644 --- a/auto-configurations/models/spring-ai-autoconfigure-model-google-genai/src/main/java/org/springframework/ai/model/google/genai/autoconfigure/embedding/GoogleGenAiEmbeddingConnectionAutoConfiguration.java +++ b/auto-configurations/models/spring-ai-autoconfigure-model-google-genai/src/main/java/org/springframework/ai/model/google/genai/autoconfigure/embedding/GoogleGenAiEmbeddingConnectionAutoConfiguration.java @@ -39,7 +39,7 @@ * @since 1.1.0 */ @AutoConfiguration -@ConditionalOnClass(Client.class) +@ConditionalOnClass({ Client.class, GoogleGenAiEmbeddingConnectionDetails.class }) @EnableConfigurationProperties(GoogleGenAiEmbeddingConnectionProperties.class) public class GoogleGenAiEmbeddingConnectionAutoConfiguration { diff --git a/models/spring-ai-google-genai-embedding/README.md b/models/spring-ai-google-genai-embedding/README.md index 7b0c41fe9aa..3e28bb18e7c 100644 --- a/models/spring-ai-google-genai-embedding/README.md +++ b/models/spring-ai-google-genai-embedding/README.md @@ -1,5 +1,39 @@ -# Google Gen AI Embeddings module +# Google GenAI Embeddings Module -Please note that at this time the *spring-ai-google-genai-embedding* module supports only text embeddings only. +[Google GenAI Text Embeddings Documentation](https://docs.spring.io/spring-ai/reference/api/embeddings/google-genai-embeddings-text.html) -This is due to the fact that the Google GenAI SDK supports text embeddings only, with multimedia embeddings pending. \ No newline at end of file +## Overview + +The Google GenAI Embeddings module provides text embedding generation using Google's embedding models through either the Gemini Developer API or Vertex AI. + +## Current Support + +Please note that at this time the *spring-ai-google-genai-embedding* module supports **text embeddings only**. + +This is due to the fact that the Google GenAI SDK currently supports text embeddings only, with multimodal embeddings support pending. + +## Starter Dependency + +```xml + + org.springframework.ai + spring-ai-starter-model-google-genai-embedding + +``` + +## Manual Configuration + +```xml + + org.springframework.ai + spring-ai-google-genai-embedding + +``` + +## Authentication Modes + +The module supports two authentication modes: +- **Gemini Developer API**: Use an API key for quick prototyping +- **Vertex AI**: Use Google Cloud credentials for production deployments + +See the [documentation](https://docs.spring.io/spring-ai/reference/api/embeddings/google-genai-embeddings-text.html) for detailed configuration instructions. \ No newline at end of file diff --git a/models/spring-ai-google-genai/README.md b/models/spring-ai-google-genai/README.md index 39f513ede2d..914e196839b 100644 --- a/models/spring-ai-google-genai/README.md +++ b/models/spring-ai-google-genai/README.md @@ -1,10 +1,10 @@ -[VertexAI Gemini Chat](https://docs.spring.io/spring-ai/reference/api/chat/vertexai-gemini-chat.html) +[Google GenAI Chat](https://docs.spring.io/spring-ai/reference/api/chat/google-genai-chat.html) -### Starter - WIP +### Starter ```xml org.springframework.ai - spring-ai-starter-model-spring-ai-google-genai + spring-ai-starter-model-google-genai ``` diff --git a/spring-ai-docs/src/main/antora/modules/ROOT/nav.adoc b/spring-ai-docs/src/main/antora/modules/ROOT/nav.adoc index 7ae5ab6c6e7..8648ba188e4 100644 --- a/spring-ai-docs/src/main/antora/modules/ROOT/nav.adoc +++ b/spring-ai-docs/src/main/antora/modules/ROOT/nav.adoc @@ -18,8 +18,10 @@ **** xref:api/chat/azure-openai-chat.adoc[Azure OpenAI] **** xref:api/chat/deepseek-chat.adoc[DeepSeek] **** xref:api/chat/dmr-chat.adoc[Docker Model Runner] -**** xref:api/chat/google-vertexai.adoc[Google VertexAI] -***** xref:api/chat/vertexai-gemini-chat.adoc[VertexAI Gemini] +**** Google +***** xref:api/chat/google-genai-chat.adoc[Google GenAI] +***** xref:api/chat/google-vertexai.adoc[Google VertexAI] +****** xref:api/chat/vertexai-gemini-chat.adoc[VertexAI Gemini] **** xref:api/chat/groq-chat.adoc[Groq] **** xref:api/chat/huggingface.adoc[Hugging Face] **** xref:api/chat/mistralai-chat.adoc[Mistral AI] @@ -39,6 +41,8 @@ ***** xref:api/embeddings/bedrock-cohere-embedding.adoc[Cohere] ***** xref:api/embeddings/bedrock-titan-embedding.adoc[Titan] **** xref:api/embeddings/azure-openai-embeddings.adoc[Azure OpenAI] +**** Google +***** xref:api/embeddings/google-genai-embeddings-text.adoc[Google GenAI Text Embedding] **** xref:api/embeddings/mistralai-embeddings.adoc[Mistral AI] **** xref:api/embeddings/minimax-embeddings.adoc[MiniMax] **** xref:api/embeddings/oci-genai-embeddings.adoc[OCI GenAI] diff --git a/spring-ai-docs/src/main/antora/modules/ROOT/pages/api/chat/comparison.adoc b/spring-ai-docs/src/main/antora/modules/ROOT/pages/api/chat/comparison.adoc index c8edbb2544d..09ac7f30ed5 100644 --- a/spring-ai-docs/src/main/antora/modules/ROOT/pages/api/chat/comparison.adoc +++ b/spring-ai-docs/src/main/antora/modules/ROOT/pages/api/chat/comparison.adoc @@ -22,6 +22,7 @@ This table compares various Chat Models supported by Spring AI, detailing their | xref::api/chat/anthropic-chat.adoc[Anthropic Claude] | text, pdf, image ^a| image::yes.svg[width=16] ^a| image::yes.svg[width=16] ^a| image::yes.svg[width=16] ^a| image::yes.svg[width=16] ^a| image::no.svg[width=12] ^a| image::no.svg[width=12] ^a| image::no.svg[width=12] | xref::api/chat/azure-openai-chat.adoc[Azure OpenAI] | text, image ^a| image::yes.svg[width=16] ^a| image::yes.svg[width=16] ^a| image::yes.svg[width=16] ^a| image::yes.svg[width=16] ^a| image::yes.svg[width=16] ^a| image::no.svg[width=12] ^a| image::yes.svg[width=16] | xref::api/chat/deepseek-chat.adoc[DeepSeek (OpenAI-proxy)] | text ^a| image::yes.svg[width=16] ^a| image::yes.svg[width=16] ^a| image::yes.svg[width=16] ^a| image::yes.svg[width=16] ^a| image::yes.svg[width=16] ^a| image::yes.svg[width=16] ^a| image::yes.svg[width=16] +| xref::api/chat/google-genai-chat.adoc[Google GenAI] | text, pdf, image, audio, video ^a| image::yes.svg[width=16] ^a| image::yes.svg[width=16] ^a| image::yes.svg[width=16] ^a| image::yes.svg[width=16] ^a| image::yes.svg[width=16] ^a| image::no.svg[width=12] ^a| image::no.svg[width=12] | xref::api/chat/vertexai-gemini-chat.adoc[Google VertexAI Gemini] | text, pdf, image, audio, video ^a| image::yes.svg[width=16] ^a| image::yes.svg[width=16] ^a| image::yes.svg[width=16] ^a| image::yes.svg[width=16] ^a| image::yes.svg[width=16] ^a| image::no.svg[width=12] ^a| image::yes.svg[width=16] | xref::api/chat/groq-chat.adoc[Groq (OpenAI-proxy)] | text, image ^a| image::yes.svg[width=16] ^a| image::yes.svg[width=16] ^a| image::yes.svg[width=16] ^a| image::yes.svg[width=16] ^a| image::no.svg[width=12] ^a| image::no.svg[width=12] ^a| image::yes.svg[width=16] | xref::api/chat/huggingface.adoc[HuggingFace] | text ^a| image::no.svg[width=12] ^a| image::no.svg[width=12] ^a| image::no.svg[width=12] ^a| image::no.svg[width=12] ^a| image::no.svg[width=12] ^a| image::no.svg[width=12] ^a| image::no.svg[width=12] diff --git a/spring-ai-docs/src/main/antora/modules/ROOT/pages/api/chat/google-genai-chat.adoc b/spring-ai-docs/src/main/antora/modules/ROOT/pages/api/chat/google-genai-chat.adoc new file mode 100644 index 00000000000..d00cf17b576 --- /dev/null +++ b/spring-ai-docs/src/main/antora/modules/ROOT/pages/api/chat/google-genai-chat.adoc @@ -0,0 +1,389 @@ += Google GenAI Chat + +The https://ai.google.dev/gemini-api/docs[Google GenAI API] allows developers to build generative AI applications using Google's Gemini models through either the Gemini Developer API or Vertex AI. +The Google GenAI API supports multimodal prompts as input and outputs text or code. +A multimodal model is capable of processing information from multiple modalities, including images, videos, and text. For example, you can send the model a photo of a plate of cookies and ask it to give you a recipe for those cookies. + +Gemini is a family of generative AI models developed by Google DeepMind that is designed for multimodal use cases. The Gemini API gives you access to link:https://ai.google.dev/gemini-api/docs/models/gemini/2-0-flash[Gemini 2.0 Flash], link:https://ai.google.dev/gemini-api/docs/models/gemini/2-0-flash-lite[Gemini 2.0 Flash-Lite], and link:https://ai.google.dev/gemini-api/docs/models/gemini-pro[Gemini Pro] models. + +This implementation provides two authentication modes: + +- **Gemini Developer API**: Use an API key for quick prototyping and development +- **Vertex AI**: Use Google Cloud credentials for production deployments with enterprise features + +link:https://ai.google.dev/gemini-api/docs/reference[Gemini API Reference] + +== Prerequisites + +Choose one of the following authentication methods: + +=== Option 1: Gemini Developer API (API Key) + +- Obtain an API key from the https://aistudio.google.com/app/apikey[Google AI Studio] +- Set the API key as an environment variable or in your application properties + +=== Option 2: Vertex AI (Google Cloud) + +- Install the link:https://cloud.google.com/sdk/docs/install[gcloud] CLI, appropriate for your OS. +- Authenticate by running the following command. +Replace `PROJECT_ID` with your Google Cloud project ID and `ACCOUNT` with your Google Cloud username. + +[source] +---- +gcloud config set project && +gcloud auth application-default login +---- + +== Auto-configuration + +[NOTE] +==== +There has been a significant change in the Spring AI auto-configuration, starter modules' artifact names. +Please refer to the https://docs.spring.io/spring-ai/reference/upgrade-notes.html[upgrade notes] for more information. +==== + +Spring AI provides Spring Boot auto-configuration for the Google GenAI Chat Client. +To enable it add the following dependency to your project's Maven `pom.xml` or Gradle `build.gradle` build files: + +[tabs] +====== +Maven:: ++ +[source, xml] +---- + + org.springframework.ai + spring-ai-starter-model-google-genai + +---- + +Gradle:: ++ +[source,groovy] +---- +dependencies { + implementation 'org.springframework.ai:spring-ai-starter-model-google-genai' +} +---- +====== + +TIP: Refer to the xref:getting-started.adoc#dependency-management[Dependency Management] section to add the Spring AI BOM to your build file. + +=== Chat Properties + +[NOTE] +==== +Enabling and disabling of the chat auto-configurations are now configured via top level properties with the prefix `spring.ai.model.chat`. + +To enable, spring.ai.model.chat=google-genai (It is enabled by default) + +To disable, spring.ai.model.chat=none (or any value which doesn't match google-genai) + +This change is done to allow configuration of multiple models. +==== + +==== Connection Properties + +The prefix `spring.ai.google.genai` is used as the property prefix that lets you connect to Google GenAI. + +[cols="3,5,1", stripes=even] +|==== +| Property | Description | Default + +| spring.ai.model.chat | Enable Chat Model client | google-genai +| spring.ai.google.genai.api-key | API key for Gemini Developer API. When provided, the client uses the Gemini Developer API instead of Vertex AI. | - +| spring.ai.google.genai.project-id | Google Cloud Platform project ID (required for Vertex AI mode) | - +| spring.ai.google.genai.location | Google Cloud region (required for Vertex AI mode) | - +| spring.ai.google.genai.credentials-uri | URI to Google Cloud credentials. When provided it is used to create a `GoogleCredentials` instance for authentication. | - +|==== + +==== Chat Model Properties + +The prefix `spring.ai.google.genai.chat` is the property prefix that lets you configure the chat model implementation for Google GenAI Chat. + +[cols="3,5,1", stripes=even] +|==== +| Property | Description | Default + +| spring.ai.google.genai.chat.options.model | Supported https://ai.google.dev/gemini-api/docs/models[Google GenAI Chat models] to use include `gemini-2.0-flash`, `gemini-2.0-flash-lite`, `gemini-pro`, and `gemini-1.5-flash`. | gemini-2.0-flash +| spring.ai.google.genai.chat.options.response-mime-type | Output response mimetype of the generated candidate text. | `text/plain`: (default) Text output or `application/json`: JSON response. +| spring.ai.google.genai.chat.options.google-search-retrieval | Use Google search Grounding feature | `true` or `false`, default `false`. +| spring.ai.google.genai.chat.options.temperature | Controls the randomness of the output. Values can range over [0.0,1.0], inclusive. A value closer to 1.0 will produce responses that are more varied, while a value closer to 0.0 will typically result in less surprising responses from the generative. | 0.7 +| spring.ai.google.genai.chat.options.top-k | The maximum number of tokens to consider when sampling. The generative uses combined Top-k and nucleus sampling. Top-k sampling considers the set of topK most probable tokens. | - +| spring.ai.google.genai.chat.options.top-p | The maximum cumulative probability of tokens to consider when sampling. The generative uses combined Top-k and nucleus sampling. Nucleus sampling considers the smallest set of tokens whose probability sum is at least topP. | - +| spring.ai.google.genai.chat.options.candidate-count | The number of generated response messages to return. This value must be between [1, 8], inclusive. Defaults to 1. | 1 +| spring.ai.google.genai.chat.options.max-output-tokens | The maximum number of tokens to generate. | - +| spring.ai.google.genai.chat.options.frequency-penalty | Frequency penalties for reducing repetition. | - +| spring.ai.google.genai.chat.options.presence-penalty | Presence penalties for reducing repetition. | - +| spring.ai.google.genai.chat.options.thinking-budget | Thinking budget for the thinking process. | - +| spring.ai.google.genai.chat.options.tool-names | List of tools, identified by their names, to enable for function calling in a single prompt request. Tools with those names must exist in the ToolCallback registry. | - +| spring.ai.google.genai.chat.options.internal-tool-execution-enabled | If true, the tool execution should be performed, otherwise the response from the model is returned back to the user. Default is null, but if it's null, `ToolCallingChatOptions.DEFAULT_TOOL_EXECUTION_ENABLED` which is true will take into account | - +| spring.ai.google.genai.chat.options.safety-settings | List of safety settings to control safety filters, as defined by https://ai.google.dev/gemini-api/docs/safety-settings[Google GenAI Safety Settings]. Each safety setting can have a method, threshold, and category. | - + +|==== + +TIP: All properties prefixed with `spring.ai.google.genai.chat.options` can be overridden at runtime by adding a request specific <> to the `Prompt` call. + +== Runtime options [[chat-options]] + +The https://github.com/spring-projects/spring-ai/blob/main/models/spring-ai-google-genai/src/main/java/org/springframework/ai/google/genai/GoogleGenAiChatOptions.java[GoogleGenAiChatOptions.java] provides model configurations, such as the temperature, the topK, etc. + +On start-up, the default options can be configured with the `GoogleGenAiChatModel(client, options)` constructor or the `spring.ai.google.genai.chat.options.*` properties. + +At runtime, you can override the default options by adding new, request specific, options to the `Prompt` call. +For example, to override the default temperature for a specific request: + +[source,java] +---- +ChatResponse response = chatModel.call( + new Prompt( + "Generate the names of 5 famous pirates.", + GoogleGenAiChatOptions.builder() + .temperature(0.4) + .build() + )); +---- + +TIP: In addition to the model specific `GoogleGenAiChatOptions` you can use a portable link:https://github.com/spring-projects/spring-ai/blob/main/spring-ai-model/src/main/java/org/springframework/ai/chat/prompt/ChatOptions.java[ChatOptions] instance, created with the link:https://github.com/spring-projects/spring-ai/blob/main/spring-ai-model/src/main/java/org/springframework/ai/chat/prompt/DefaultChatOptionsBuilder.java[ChatOptions#builder()]. + +== Tool Calling + +The Google GenAI model supports tool calling (function calling) capabilities, allowing models to use tools during conversations. +Here's an example of how to define and use `@Tool`-based tools: + +[source,java] +---- + +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(); +---- + +You can use the java.util.function beans as tools as well: + +[source,java] +---- +@Bean +@Description("Get the weather in location. Return temperature in 36°F or 36°C format.") +public Function 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(); +---- + +Find more in xref:api/tools.adoc[Tools] documentation. + + +== Multimodal + +Multimodality refers to a model's ability to simultaneously understand and process information from various (input) sources, including `text`, `pdf`, `images`, `audio`, and other data formats. + +=== Image, Audio, Video +Google's Gemini AI models support this capability by comprehending and integrating text, code, audio, images, and video. +For more details, refer to the blog post https://blog.google/technology/ai/google-gemini-ai/#introducing-gemini[Introducing Gemini]. + +Spring AI's `Message` interface supports multimodal AI models by introducing the Media type. +This type contains data and information about media attachments in messages, using Spring's `org.springframework.util.MimeType` and a `java.lang.Object` for the raw media data. + +Below is a simple code example extracted from https://github.com/spring-projects/spring-ai/blob/main/models/spring-ai-google-genai/src/test/java/org/springframework/ai/google/genai/GoogleGenAiChatModelIT.java[GoogleGenAiChatModelIT.java], demonstrating the combination of user text with an image. + + +[source,java] +---- +byte[] data = new ClassPathResource("/vertex-test.png").getContentAsByteArray(); + +var userMessage = new UserMessage("Explain what do you see on this picture?", + List.of(new Media(MimeTypeUtils.IMAGE_PNG, this.data))); + +ChatResponse response = chatModel.call(new Prompt(List.of(this.userMessage))); +---- + +=== PDF + +Google GenAI provides support for PDF input types. +Use the `application/pdf` media type to attach a PDF file to the message: + +[source,java] +---- +var pdfData = new ClassPathResource("/spring-ai-reference-overview.pdf"); + +var userMessage = new UserMessage( + "You are a very professional document summarization specialist. Please summarize the given document.", + List.of(new Media(new MimeType("application", "pdf"), pdfData))); + +var response = this.chatModel.call(new Prompt(List.of(userMessage))); +---- + + +== Sample Controller + +https://start.spring.io/[Create] a new Spring Boot project and add the `spring-ai-starter-model-google-genai` to your pom (or gradle) dependencies. + +Add a `application.properties` file, under the `src/main/resources` directory, to enable and configure the Google GenAI chat model: + +=== Using Gemini Developer API (API Key) + +[source,application.properties] +---- +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 +---- + +=== Using Vertex AI + +[source,application.properties] +---- +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 +---- + +TIP: Replace the `project-id` with your Google Cloud Project ID and `location` is Google Cloud Region +like `us-central1`, `europe-west1`, etc... + +[NOTE] +==== +Each model has its own set of supported regions, you can find the list of supported regions in the model page. +==== + + +This will create a `GoogleGenAiChatModel` implementation that you can inject into your class. +Here is an example of a simple `@Controller` class that uses the chat model for text generations. + +[source,java] +---- +@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 generateStream(@RequestParam(value = "message", defaultValue = "Tell me a joke") String message) { + Prompt prompt = new Prompt(new UserMessage(message)); + return this.chatModel.stream(prompt); + } +} +---- + +== Manual Configuration + +The https://github.com/spring-projects/spring-ai/blob/main/models/spring-ai-google-genai/src/main/java/org/springframework/ai/google/genai/GoogleGenAiChatModel.java[GoogleGenAiChatModel] implements the `ChatModel` and uses the `com.google.genai.Client` to connect to the Google GenAI service. + +Add the `spring-ai-google-genai` dependency to your project's Maven `pom.xml` file: + +[source, xml] +---- + + org.springframework.ai + spring-ai-google-genai + +---- + +or to your Gradle `build.gradle` build file. + +[source,groovy] +---- +dependencies { + implementation 'org.springframework.ai:spring-ai-google-genai' +} +---- + +TIP: Refer to the xref:getting-started.adoc#dependency-management[Dependency Management] section to add the Spring AI BOM to your build file. + +Next, create a `GoogleGenAiChatModel` and use it for text generations: + +=== Using API Key + +[source,java] +---- +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.")); +---- + +=== Using Vertex AI + +[source,java] +---- +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.")); +---- + +The `GoogleGenAiChatOptions` provides the configuration information for the chat requests. +The `GoogleGenAiChatOptions.Builder` is fluent options builder. + +== Migration from Vertex AI Gemini + +If you're currently using the Vertex AI Gemini implementation (`spring-ai-vertex-ai-gemini`), you can migrate to Google GenAI with minimal changes: + +=== Key Differences + +1. **SDK**: Google GenAI uses the new `com.google.genai.Client` instead of `com.google.cloud.vertexai.VertexAI` +2. **Authentication**: Supports both API key and Google Cloud credentials +3. **Package Names**: Classes are in `org.springframework.ai.google.genai` instead of `org.springframework.ai.vertexai.gemini` +4. **Property Prefix**: Uses `spring.ai.google.genai` instead of `spring.ai.vertex.ai.gemini` + +=== When to Use Google GenAI vs Vertex AI Gemini + +**Use Google GenAI when:** +- You want quick prototyping with API keys +- You need the latest Gemini features from the Developer API +- You want flexibility to switch between API key and Vertex AI modes + +**Use Vertex AI Gemini when:** +- You have existing Vertex AI infrastructure +- You need specific Vertex AI enterprise features +- Your organization requires Google Cloud-only deployment + +== Low-level Java Client [[low-level-api]] + +The Google GenAI implementation is built on the new Google GenAI Java SDK, which provides a modern, streamlined API for accessing Gemini models. \ No newline at end of file diff --git a/spring-ai-docs/src/main/antora/modules/ROOT/pages/api/embeddings/google-genai-embeddings-text.adoc b/spring-ai-docs/src/main/antora/modules/ROOT/pages/api/embeddings/google-genai-embeddings-text.adoc new file mode 100644 index 00000000000..7deedd87699 --- /dev/null +++ b/spring-ai-docs/src/main/antora/modules/ROOT/pages/api/embeddings/google-genai-embeddings-text.adoc @@ -0,0 +1,308 @@ += Google GenAI Text Embeddings + +The https://ai.google.dev/gemini-api/docs/embeddings[Google GenAI Embeddings API] provides text embedding generation using Google's embedding models through either the Gemini Developer API or Vertex AI. +This document describes how to create text embeddings using the Google GenAI Text embeddings API. + +Google GenAI text embeddings API uses dense vector representations. +Unlike sparse vectors, which tend to directly map words to numbers, dense vectors are designed to better represent the meaning of a piece of text. +The benefit of using dense vector embeddings in generative AI is that instead of searching for direct word or syntax matches, you can better search for passages that align to the meaning of the query, even if the passages don't use the same language. + +[NOTE] +==== +Currently, the Google GenAI SDK supports text embeddings only. Multimodal embeddings support is pending and will be added when available in the SDK. +==== + +This implementation provides two authentication modes: + +- **Gemini Developer API**: Use an API key for quick prototyping and development +- **Vertex AI**: Use Google Cloud credentials for production deployments with enterprise features + +== Prerequisites + +Choose one of the following authentication methods: + +=== Option 1: Gemini Developer API (API Key) + +- Obtain an API key from the https://aistudio.google.com/app/apikey[Google AI Studio] +- Set the API key as an environment variable or in your application properties + +=== Option 2: Vertex AI (Google Cloud) + +- Install the link:https://cloud.google.com/sdk/docs/install[gcloud] CLI, appropriate for your OS. +- Authenticate by running the following command. +Replace `PROJECT_ID` with your Google Cloud project ID and `ACCOUNT` with your Google Cloud username. + +[source] +---- +gcloud config set project && +gcloud auth application-default login +---- + +=== Add Repositories and BOM + +Spring AI artifacts are published in Maven Central and Spring Snapshot repositories. +Refer to the xref:getting-started.adoc#artifact-repositories[Artifact Repositories] section to add these repositories to your build system. + +To help with dependency management, Spring AI provides a BOM (bill of materials) to ensure that a consistent version of Spring AI is used throughout the entire project. Refer to the xref:getting-started.adoc#dependency-management[Dependency Management] section to add the Spring AI BOM to your build system. + + +== Auto-configuration + +[NOTE] +==== +There has been a significant change in the Spring AI auto-configuration, starter modules' artifact names. +Please refer to the https://docs.spring.io/spring-ai/reference/upgrade-notes.html[upgrade notes] for more information. +==== + +Spring AI provides Spring Boot auto-configuration for the Google GenAI Embedding Model. +To enable it add the following dependency to your project's Maven `pom.xml` file: + +[source, xml] +---- + + org.springframework.ai + spring-ai-starter-model-google-genai-embedding + +---- + +or to your Gradle `build.gradle` build file. + +[source,groovy] +---- +dependencies { + implementation 'org.springframework.ai:spring-ai-starter-model-google-genai-embedding' +} +---- + +TIP: Refer to the xref:getting-started.adoc#dependency-management[Dependency Management] section to add the Spring AI BOM to your build file. + +=== Embedding Properties + +==== Connection Properties + +The prefix `spring.ai.google.genai.embedding` is used as the property prefix that lets you connect to Google GenAI Embedding API. + +[NOTE] +==== +The connection properties are shared with the Google GenAI Chat module. If you're using both chat and embeddings, you only need to configure the connection once using either `spring.ai.google.genai` prefix (for chat) or `spring.ai.google.genai.embedding` prefix (for embeddings). +==== + +[cols="3,5,1", stripes=even] +|==== +| Property | Description | Default + +| spring.ai.google.genai.embedding.api-key | API key for Gemini Developer API. When provided, the client uses the Gemini Developer API instead of Vertex AI. | - +| spring.ai.google.genai.embedding.project-id | Google Cloud Platform project ID (required for Vertex AI mode) | - +| spring.ai.google.genai.embedding.location | Google Cloud region (required for Vertex AI mode) | - +| spring.ai.google.genai.embedding.credentials-uri | URI to Google Cloud credentials. When provided it is used to create a `GoogleCredentials` instance for authentication. | - + +|==== + +[NOTE] +==== +Enabling and disabling of the embedding auto-configurations are now configured via top level properties with the prefix `spring.ai.model.embedding`. + +To enable, spring.ai.model.embedding.text=google-genai (It is enabled by default) + +To disable, spring.ai.model.embedding.text=none (or any value which doesn't match google-genai) + +This change is done to allow configuration of multiple models. +==== + +==== Text Embedding Properties + +The prefix `spring.ai.google.genai.embedding.text` is the property prefix that lets you configure the embedding model implementation for Google GenAI Text Embedding. + +[cols="3,5,1", stripes=even] +|==== +| Property | Description | Default + +| spring.ai.model.embedding.text | Enable Google GenAI Embedding API model. | google-genai +| spring.ai.google.genai.embedding.text.options.model | The https://ai.google.dev/gemini-api/docs/models/gemini#text-embedding[Google GenAI Text Embedding model] to use. Supported models include `text-embedding-004` and `text-multilingual-embedding-002` | text-embedding-004 +| spring.ai.google.genai.embedding.text.options.task-type | The intended downstream application to help the model produce better quality embeddings. Available link:https://ai.google.dev/api/embeddings#tasktype[task-types]: `RETRIEVAL_QUERY`, `RETRIEVAL_DOCUMENT`, `SEMANTIC_SIMILARITY`, `CLASSIFICATION`, `CLUSTERING`, `QUESTION_ANSWERING`, `FACT_VERIFICATION` | `RETRIEVAL_DOCUMENT` +| spring.ai.google.genai.embedding.text.options.title | Optional title, only valid with task_type=RETRIEVAL_DOCUMENT. | - +| spring.ai.google.genai.embedding.text.options.dimensions | The number of dimensions the resulting output embeddings should have. Supported for model version 004 and later. You can use this parameter to reduce the embedding size, for example, for storage optimization. | - +| spring.ai.google.genai.embedding.text.options.auto-truncate | When set to true, input text will be truncated. When set to false, an error is returned if the input text is longer than the maximum length supported by the model. | true +|==== + +== Sample Controller + +https://start.spring.io/[Create] a new Spring Boot project and add the `spring-ai-starter-model-google-genai-embedding` to your pom (or gradle) dependencies. + +Add a `application.properties` file, under the `src/main/resources` directory, to enable and configure the Google GenAI embedding model: + +=== Using Gemini Developer API (API Key) + +[source,application.properties] +---- +spring.ai.google.genai.embedding.api-key=YOUR_API_KEY +spring.ai.google.genai.embedding.text.options.model=text-embedding-004 +---- + +=== Using Vertex AI + +[source,application.properties] +---- +spring.ai.google.genai.embedding.project-id=YOUR_PROJECT_ID +spring.ai.google.genai.embedding.location=YOUR_PROJECT_LOCATION +spring.ai.google.genai.embedding.text.options.model=text-embedding-004 +---- + + +This will create a `GoogleGenAiTextEmbeddingModel` implementation that you can inject into your class. +Here is an example of a simple `@Controller` class that uses the embedding model for embeddings generations. + +[source,java] +---- +@RestController +public class EmbeddingController { + + private final EmbeddingModel embeddingModel; + + @Autowired + public EmbeddingController(EmbeddingModel embeddingModel) { + this.embeddingModel = embeddingModel; + } + + @GetMapping("/ai/embedding") + public Map embed(@RequestParam(value = "message", defaultValue = "Tell me a joke") String message) { + EmbeddingResponse embeddingResponse = this.embeddingModel.embedForResponse(List.of(message)); + return Map.of("embedding", embeddingResponse); + } +} +---- + +== Manual Configuration + +The https://github.com/spring-projects/spring-ai/blob/main/models/spring-ai-google-genai-embedding/src/main/java/org/springframework/ai/google/genai/text/GoogleGenAiTextEmbeddingModel.java[GoogleGenAiTextEmbeddingModel] implements the `EmbeddingModel`. + +Add the `spring-ai-google-genai-embedding` dependency to your project's Maven `pom.xml` file: + +[source, xml] +---- + + org.springframework.ai + spring-ai-google-genai-embedding + +---- + +or to your Gradle `build.gradle` build file. + +[source,groovy] +---- +dependencies { + implementation 'org.springframework.ai:spring-ai-google-genai-embedding' +} +---- + +TIP: Refer to the xref:getting-started.adoc#dependency-management[Dependency Management] section to add the Spring AI BOM to your build file. + +Next, create a `GoogleGenAiTextEmbeddingModel` and use it for text embeddings: + +=== Using API Key + +[source,java] +---- +GoogleGenAiEmbeddingConnectionDetails connectionDetails = + GoogleGenAiEmbeddingConnectionDetails.builder() + .apiKey(System.getenv("GOOGLE_API_KEY")) + .build(); + +GoogleGenAiTextEmbeddingOptions options = GoogleGenAiTextEmbeddingOptions.builder() + .model(GoogleGenAiTextEmbeddingOptions.DEFAULT_MODEL_NAME) + .taskType(TaskType.RETRIEVAL_DOCUMENT) + .build(); + +var embeddingModel = new GoogleGenAiTextEmbeddingModel(connectionDetails, options); + +EmbeddingResponse embeddingResponse = embeddingModel + .embedForResponse(List.of("Hello World", "World is big and salvation is near")); +---- + +=== Using Vertex AI + +[source,java] +---- +GoogleGenAiEmbeddingConnectionDetails connectionDetails = + GoogleGenAiEmbeddingConnectionDetails.builder() + .projectId(System.getenv("GOOGLE_CLOUD_PROJECT")) + .location(System.getenv("GOOGLE_CLOUD_LOCATION")) + .build(); + +GoogleGenAiTextEmbeddingOptions options = GoogleGenAiTextEmbeddingOptions.builder() + .model(GoogleGenAiTextEmbeddingOptions.DEFAULT_MODEL_NAME) + .taskType(TaskType.RETRIEVAL_DOCUMENT) + .build(); + +var embeddingModel = new GoogleGenAiTextEmbeddingModel(connectionDetails, options); + +EmbeddingResponse embeddingResponse = embeddingModel + .embedForResponse(List.of("Hello World", "World is big and salvation is near")); +---- + +== Task Types + +The Google GenAI embeddings API supports different task types to optimize embeddings for specific use cases: + +- `RETRIEVAL_QUERY`: Optimized for search queries in retrieval systems +- `RETRIEVAL_DOCUMENT`: Optimized for documents in retrieval systems +- `SEMANTIC_SIMILARITY`: Optimized for measuring semantic similarity between texts +- `CLASSIFICATION`: Optimized for text classification tasks +- `CLUSTERING`: Optimized for clustering similar texts +- `QUESTION_ANSWERING`: Optimized for question-answering systems +- `FACT_VERIFICATION`: Optimized for fact verification tasks + +Example of using different task types: + +[source,java] +---- +// For indexing documents +GoogleGenAiTextEmbeddingOptions docOptions = GoogleGenAiTextEmbeddingOptions.builder() + .model("text-embedding-004") + .taskType(TaskType.RETRIEVAL_DOCUMENT) + .title("Product Documentation") // Optional title for documents + .build(); + +// For search queries +GoogleGenAiTextEmbeddingOptions queryOptions = GoogleGenAiTextEmbeddingOptions.builder() + .model("text-embedding-004") + .taskType(TaskType.RETRIEVAL_QUERY) + .build(); +---- + +== Dimension Reduction + +For model version 004 and later, you can reduce the embedding dimensions for storage optimization: + +[source,java] +---- +GoogleGenAiTextEmbeddingOptions options = GoogleGenAiTextEmbeddingOptions.builder() + .model("text-embedding-004") + .dimensions(256) // Reduce from default 768 to 256 dimensions + .build(); +---- + +== Migration from Vertex AI Text Embeddings + +If you're currently using the Vertex AI Text Embeddings implementation (`spring-ai-vertex-ai-embedding`), you can migrate to Google GenAI with minimal changes: + +=== Key Differences + +1. **SDK**: Google GenAI uses the new `com.google.genai.Client` instead of Vertex AI SDK +2. **Authentication**: Supports both API key and Google Cloud credentials +3. **Package Names**: Classes are in `org.springframework.ai.google.genai.text` instead of `org.springframework.ai.vertexai.embedding` +4. **Property Prefix**: Uses `spring.ai.google.genai.embedding` instead of `spring.ai.vertex.ai.embedding` +5. **Connection Details**: Uses `GoogleGenAiEmbeddingConnectionDetails` instead of `VertexAiEmbeddingConnectionDetails` + +=== When to Use Google GenAI vs Vertex AI Text Embeddings + +**Use Google GenAI Embeddings when:** +- You want quick prototyping with API keys +- You need the latest embedding features from the Developer API +- You want flexibility to switch between API key and Vertex AI modes +- You're already using Google GenAI for chat + +**Use Vertex AI Text Embeddings when:** +- You have existing Vertex AI infrastructure +- You need multimodal embeddings (currently only available in Vertex AI) +- Your organization requires Google Cloud-only deployment \ No newline at end of file