一、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 config set project <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 类示例，它使用嵌入模型生成嵌入：

@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 = "给我讲个笑话") String message) {
        EmbeddingResponse embeddingResponse = this.embeddingModel.embedForResponse(List.of(message));
        return Map.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 密钥

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"));

5.2 使用 Vertex AI

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"));

六、任务类型

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

• RETRIEVAL_QUERY：针对检索系统中的搜索查询进行优化

• RETRIEVAL_DOCUMENT：针对检索系统中的文档进行优化

• SEMANTIC_SIMILARITY：针对测量文本之间的语义相似性进行优化

• CLASSIFICATION：针对文本分类任务进行优化

• CLUSTERING：针对聚类相似文本进行优化

• QUESTION_ANSWERING：针对问答系统进行优化

• FACT_VERIFICATION：针对事实核查任务进行优化

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

// 用于索引文档
GoogleGenAiTextEmbeddingOptions docOptions = GoogleGenAiTextEmbeddingOptions.builder()
    .model("text-embedding-004")
    .taskType(TaskType.RETRIEVAL_DOCUMENT)
    .title("产品文档")  // 文档的可选标题
    .build();

// 用于搜索查询
GoogleGenAiTextEmbeddingOptions queryOptions = GoogleGenAiTextEmbeddingOptions.builder()
    .model("text-embedding-004")
    .taskType(TaskType.RETRIEVAL_QUERY)
    .build();

七、维度缩减

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

GoogleGenAiTextEmbeddingOptions options = 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

8.2 何时使用 Google GenAI 与 Vertex AI 文本嵌入

在以下情况下使用 Google GenAI 嵌入：

• 您希望通过 API 密钥进行快速原型设计

• 您需要来自开发者 API 的最新嵌入功能

• 您希望灵活地在 API 密钥和 Vertex AI 模式之间切换

• 您已经将 Google GenAI 用于聊天

在以下情况下使用 Vertex AI 文本嵌入：

• 您拥有现有的 Vertex AI 基础设施

• 您需要多模态嵌入（目前仅在 Vertex AI 中可用）

• 您的组织要求仅使用 Google Cloud 部署