35_Spring AI 干货笔记之 Google GenAI 文本嵌入-育师

一、Google GenAI 文本嵌入

Google GenAI 嵌入 API 通过 Gemini 开发者 API 或 Vertex AI 使用 Google 的嵌入模型提供文本嵌入生成功能。本文档介绍如何使用 Google GenAI 文本嵌入 API 创建文本嵌入。

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

目前，Google GenAI SDK 仅支持文本嵌入。多模态嵌入支持正在开发中，将在 SDK 可用时添加。

此实现提供两种认证模式：

Gemini 开发者 API：使用 API 密钥进行快速原型设计和开发
Vertex AI：使用 Google Cloud 凭据进行具有企业功能的生产部署

二、先决条件

选择以下一种认证方法：

2.1 选项 1：Gemini 开发者 API（API 密钥）

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

2.2 选项 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>
```

2.3 添加仓库和 BOM

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

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

三、自动配置

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

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

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

或添加到您的 Gradle build.gradle 构建文件中：

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

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

3.1 嵌入属性

3.1.1 连接属性

前缀 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 不匹配的值）
进行此更改是为了允许配置多个模型。

3.1.2 文本嵌入属性

前缀 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 嵌入模型：

4.1 使用 Gemini 开发者 API（API 密钥）

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

4.2 使用 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.options.model=text-embedding-004

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

@RestControllerpublicclassEmbeddingController{privatefinalEmbeddingModelembeddingModel;@AutowiredpublicEmbeddingController(EmbeddingModelembeddingModel){this.embeddingModel=embeddingModel;}@GetMapping("/ai/embedding")publicMapembed(@RequestParam(value="message",defaultValue="给我讲个笑话")Stringmessage){EmbeddingResponseembeddingResponse=this.embeddingModel.embedForResponse(List.of(message));returnMap.of("embedding",embeddingResponse);}}

五、手动配置

GoogleGenAiTextEmbeddingModel 实现了 EmbeddingModel。

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

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

或添加到您的 Gradle build.gradle 构建文件中：

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

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

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

5.1 使用 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"));

5.2 使用 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("产品文档")// 文档的可选标题.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：

8.1 主要差异

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