Spring AI / Models Embedding / Models / Google GenAI Text Embedding

Google GenAI 文本嵌入
Google GenAI 嵌入 API 通过 Gemini Developer API 或 Vertex AI 使用 Google 的嵌入模型生成文本嵌入。本文档介绍如何使用 Google GenAI 文本嵌入 API 创建文本嵌入。

Google GenAI 文本嵌入 API 使用稠密向量表示。与倾向于直接将单词映射为数字的稀疏向量不同，稠密向量旨在更好地表示一段文本的含义。在生成式 AI 中使用稠密向量嵌入的好处在于，您可以更好地搜索与查询含义对齐的段落，即使这些段落未使用相同的语言，而不是直接搜索单词或语法匹配。

目前，Google GenAI SDK 仅支持文本嵌入。多模态嵌入支持尚待完善，将在 SDK 支持后添加。

此实现提供两种身份验证模式：

• Gemini Developer API：使用 API 密钥进行快速原型设计和开发
• Vertex AI：使用 Google Cloud 凭证进行生产部署，并享有企业级功能

先决条件
选择以下身份验证方法之一：

选项 1：Gemini Developer API（API 密钥）

• 从 Google AI Studio 获取 API 密钥
• 将 API 密钥设置为环境变量或在应用程序属性中设置

选项 2：Vertex AI（Google Cloud）

• 根据您的操作系统安装 gcloud CLI。
• 通过运行以下命令进行身份验证。将PROJECT_ID替换为您的 Google Cloud 项目 ID，将ACCOUNT替换为您的 Google Cloud 用户名。

  gcloud configsetproject<PROJECT_ID>&&gcloud auth application-default login<ACCOUNT>

添加仓库和 BOM
Spring AI 工件发布在 Maven Central 和 Spring Snapshot 仓库中。请参阅工件仓库部分，将这些仓库添加到您的构建系统中。

为了帮助管理依赖项，Spring AI 提供了一个 BOM（物料清单），以确保在整个项目中使用一致版本的 Spring AI。请参阅依赖管理部分，将 Spring AI BOM 添加到您的构建系统中。

自动配置
Spring AI 自动配置的启动器模块的工件名称发生了重大变化。更多信息请参阅升级说明。

Spring AI 为 Google GenAI 嵌入模型提供了 Spring Boot 自动配置。要启用它，请将以下依赖项添加到您项目的 Mavenpom.xml文件中：

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

或添加到您的 Gradlebuild.gradle构建文件中。

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

请参阅依赖管理部分，将 Spring AI BOM 添加到您的构建文件中。

嵌入属性

连接属性
前缀spring.ai.google.genai.embedding用作连接 Google GenAI 嵌入 API 的属性前缀。

连接属性与 Google GenAI 聊天模块共享。如果您同时使用聊天和嵌入功能，只需使用spring.ai.google.genai前缀（用于聊天）或spring.ai.google.genai.embedding前缀（用于嵌入）配置连接一次即可。

嵌入自动配置的启用和禁用现在通过前缀为spring.ai.model.embedding的顶层属性进行配置。

• 启用：spring.ai.model.embedding.text=google-genai（默认启用）
• 禁用：spring.ai.model.embedding.text=none（或任何不匹配google-genai的值）

此更改是为了允许配置多个模型。

文本嵌入属性
前缀spring.ai.google.genai.embedding.text是用于配置 Google GenAI 文本嵌入的嵌入模型实现的属性前缀。

示例控制器
创建一个新的 Spring Boot 项目，并将spring-ai-starter-model-google-genai-embedding添加到您的pom（或 gradle）依赖项中。

在src/main/resources目录下添加一个application.properties文件，以启用和配置 Google GenAI 嵌入模型：

使用 Gemini Developer API（API 密钥）

spring.ai.google.genai.embedding.api-key=YOUR_API_KEY spring.ai.google.genai.embedding.text.model=text-embedding-004

使用 Vertex AI

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.model=text-embedding-004

这将创建一个您可以注入到您的类中的GoogleGenAiTextEmbeddingModel实现。以下是一个简单的@Controller类示例，它使用嵌入模型生成嵌入。

@RestControllerpublicclassEmbeddingController{privatefinalEmbeddingModelembeddingModel;@AutowiredpublicEmbeddingController(EmbeddingModelembeddingModel){this.embeddingModel=embeddingModel;}@GetMapping("/ai/embedding")publicMapembed(@RequestParam(value="message",defaultValue="Tell me a joke")Stringmessage){EmbeddingResponseembeddingResponse=this.embeddingModel.embedForResponse(List.of(message));returnMap.of("embedding",embeddingResponse);}}

手动配置
GoogleGenAiTextEmbeddingModel实现了EmbeddingModel。

将spring-ai-google-genai-embedding依赖项添加到您项目的 Mavenpom.xml文件中：

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

或添加到您的 Gradlebuild.gradle构建文件中。

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

请参阅依赖管理部分，将 Spring AI BOM 添加到您的构建文件中。

接下来，创建一个GoogleGenAiTextEmbeddingModel并将其用于文本嵌入：

使用 API 密钥

GoogleGenAiEmbeddingConnectionDetailsconnectionDetails=GoogleGenAiEmbeddingConnectionDetails.builder().apiKey(System.getenv("GOOGLE_API_KEY")).build();GoogleGenAiTextEmbeddingOptionsoptions=GoogleGenAiTextEmbeddingOptions.builder().model(GoogleGenAiTextEmbeddingOptions.DEFAULT_MODEL_NAME).taskType(TaskType.RETRIEVAL_DOCUMENT).build();varembeddingModel=newGoogleGenAiTextEmbeddingModel(connectionDetails,options);EmbeddingResponseembeddingResponse=embeddingModel.embedForResponse(List.of("Hello World","World is big and salvation is near"));

使用 Vertex AI

GoogleGenAiEmbeddingConnectionDetailsconnectionDetails=GoogleGenAiEmbeddingConnectionDetails.builder().projectId(System.getenv("GOOGLE_CLOUD_PROJECT")).location(System.getenv("GOOGLE_CLOUD_LOCATION")).build();GoogleGenAiTextEmbeddingOptionsoptions=GoogleGenAiTextEmbeddingOptions.builder().model(GoogleGenAiTextEmbeddingOptions.DEFAULT_MODEL_NAME).taskType(TaskType.RETRIEVAL_DOCUMENT).build();varembeddingModel=newGoogleGenAiTextEmbeddingModel(connectionDetails,options);EmbeddingResponseembeddingResponse=embeddingModel.embedForResponse(List.of("Hello World","World is big and salvation is near"));

任务类型
Google GenAI 嵌入 API 支持不同的任务类型，以针对特定用例优化嵌入：

• RETRIEVAL_QUERY：针对检索系统中的搜索查询进行优化
• RETRIEVAL_DOCUMENT：针对检索系统中的文档进行优化
• SEMANTIC_SIMILARITY：针对测量文本之间的语义相似性进行优化
• CLASSIFICATION：针对文本分类任务进行优化
• CLUSTERING：针对聚类相似文本进行优化
• QUESTION_ANSWERING：针对问答系统进行优化
• FACT_VERIFICATION：针对事实核查任务进行优化

不同任务类型的使用示例：

// 用于索引文档GoogleGenAiTextEmbeddingOptionsdocOptions=GoogleGenAiTextEmbeddingOptions.builder().model("text-embedding-004").taskType(TaskType.RETRIEVAL_DOCUMENT).title("Product Documentation")// 文档的可选标题.build();// 用于搜索查询GoogleGenAiTextEmbeddingOptionsqueryOptions=GoogleGenAiTextEmbeddingOptions.builder().model("text-embedding-004").taskType(TaskType.RETRIEVAL_QUERY).build();

维度缩减
对于 004 及更高版本的模型，您可以减少嵌入维度以进行存储优化：

GoogleGenAiTextEmbeddingOptionsoptions=GoogleGenAiTextEmbeddingOptions.builder().model("text-embedding-004").dimensions(256)// 从默认的 768 维减少到 256 维.build();

从 Vertex AI 文本嵌入迁移
如果您当前使用的是 Vertex AI 文本嵌入实现（spring-ai-vertex-ai-embedding），您可以迁移到 Google GenAI，只需进行少量更改：

主要区别：

• SDK：Google GenAI 使用新的com.google.genai.Client而不是 Vertex AI SDK
• 身份验证：支持 API 密钥和 Google Cloud 凭证（Vertex AI 模式）
• 包名：类位于org.springframework.ai.google.genai.text而不是org.springframework.ai.vertexai.embedding
• 属性前缀：使用spring.ai.google.genai.embedding而不是spring.ai.vertex.ai.embedding
• 连接详情：使用GoogleGenAiEmbeddingConnectionDetails而不是VertexAiEmbeddingConnectionDetails

Google GenAI 通过 Google Cloud 凭证，既支持使用 API 密钥进行快速原型设计，也支持使用 Vertex AI 进行生产部署。