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 config set project <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 自动配置。要启用它，请将以下依赖项添加到您项目的 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 添加到您的构建文件中。

嵌入属性

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

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

属性	描述	默认值
spring.ai.google.genai.embedding.api-key	Gemini Developer API 的 API 密钥。提供时，客户端将使用 Gemini Developer API 而非 Vertex AI。	-
spring.ai.google.genai.embedding.project-id	Google Cloud Platform 项目 ID（Vertex AI 模式必需）	-
spring.ai.google.genai.embedding.location	Google Cloud 区域（Vertex AI 模式必需）	-
spring.ai.google.genai.embedding.credentials-uri	Google Cloud 凭证的 URI。提供时，它将用于创建 GoogleCredentials 实例进行身份验证。	-

嵌入自动配置的启用和禁用现在通过前缀为 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.ai.model.embedding.text	启用 Google GenAI 嵌入 API 模型。	google-genai
spring.ai.google.genai.embedding.text.model	要使用的 Google GenAI 文本嵌入模型。支持的模型包括 text-embedding-004 和 text-multilingual-embedding-002	text-embedding-004
spring.ai.google.genai.embedding.text.task-type	预期的下游应用程序，以帮助模型生成更高质量的嵌入。可用的任务类型：RETRIEVAL_QUERY， RETRIEVAL_DOCUMENT， SEMANTIC_SIMILARITY， CLASSIFICATION， CLUSTERING， QUESTION_ANSWERING， FACT_VERIFICATION	RETRIEVAL_DOCUMENT
spring.ai.google.genai.embedding.text.title	可选标题，仅当 task_type=RETRIEVAL_DOCUMENT 时有效。	-
spring.ai.google.genai.embedding.text.dimensions	结果输出嵌入应具有的维度数。适用于 004 及更高版本的模型。您可以使用此参数减小嵌入大小，例如，用于存储优化。	-
spring.ai.google.genai.embedding.text.auto-truncate	设置为 true 时，输入文本将被截断。设置为 false 时，如果输入文本长于模型支持的最大长度，则返回错误。	true

示例控制器
创建一个新的 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 类示例，它使用嵌入模型生成嵌入。

@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);
    }
}

手动配置
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 并将其用于文本嵌入：

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

使用 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("Product Documentation")  // 文档的可选标题
    .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，只需进行少量更改：

主要区别：

• 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 进行生产部署。