Spring AI 使用 Google 生成式人工智能文本嵌入

Google 生成式人工智能嵌入 API 可通过 Gemini 开发者 API 或 Vertex AI，借助 Google 的嵌入模型生成文本嵌入向量。本文档介绍如何使用 Google 生成式人工智能文本嵌入 API 创建文本嵌入向量。

Google 生成式人工智能文本嵌入 API 采用稠密向量表示形式。与稀疏向量（通常直接将单词映射为数字）不同，稠密向量旨在更好地表示文本片段的语义。在生成式人工智能中使用稠密向量嵌入的优势在于，无需搜索精确的单词或语法匹配项，即可更精准地查找与查询语义一致的段落，即便段落使用的语言不同也可实现。

目前，Google 生成式人工智能 SDK 仅支持文本嵌入向量。多模态嵌入向量的支持功能正在开发中，将在 SDK 支持后同步添加。

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

• Gemini 开发者 API：使用 API 密钥快速完成原型开发

• Vertex AI：使用谷歌云凭证，适用于具备企业级功能的生产环境部署

前提条件

选择以下任意一种认证方式：

方式1：Gemini 开发者 API（API 密钥）

1. 从 Google AI Studio 获取 API 密钥

2. 将 API 密钥设置为环境变量，或配置在应用程序属性文件中

方式2：Vertex AI（谷歌云）

1. 安装适配你操作系统的 gcloud 命令行工具

2. 执行以下命令完成认证。将 PROJECT_ID 替换为你的谷歌云项目 ID，ACCOUNT 替换为你的谷歌云用户名

gcloud config set project&&
gcloud auth application-default login

添加仓库和物料清单

Spring AI 构件已发布至 Maven 中央仓库和 Spring 快照仓库。参考「构件仓库」章节，将这些仓库添加到你的构建系统中。

为简化依赖管理，Spring AI 提供了物料清单（BOM），确保整个项目使用一致版本的 Spring AI。参考「依赖管理」章节，将 Spring AI 物料清单添加到你的构建系统中。

自动配置

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

Spring AI 为 Google 生成式人工智能嵌入模型提供了 Spring Boot 自动配置。启用该功能需在项目的 Maven pom.xml 文件中添加以下依赖：

org.springframework.aispring-ai-starter-model-google-genai-embedding

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

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

参考「依赖管理」章节，将 Spring AI 物料清单添加到你的构建文件中。

嵌入向量配置属性

连接属性

配置前缀 spring.ai.google.genai.embedding 用于连接 Google 生成式人工智能嵌入 API。

该连接属性与 Google 生成式人工智能聊天模块共享。若你同时使用聊天和嵌入向量功能，仅需通过 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 生成式人工智能文本嵌入模型。

示例控制器

创建新的 Spring Boot 项目，并将 spring-ai-starter-model-google-genai-embedding 添加到 pom 或 Gradle 依赖中。

在 src/main/resources 目录下添加 application.properties 文件，启用并配置 Google 生成式人工智能嵌入模型：

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

spring.ai.google.genai.embedding.api-key=YOUR_API_KEY
spring.ai.google.genai.embedding.text.options.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.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 = "Tell me a joke") String message) {
        EmbeddingResponse embeddingResponse = this.embeddingModel.embedForResponse(List.of(message));
        return Map.of("embedding", embeddingResponse);
    }
}

手动配置

GoogleGenAiTextEmbeddingModel 实现了 EmbeddingModel 接口。

在项目的 Maven pom.xml 文件中添加以下依赖：

org.springframework.aispring-ai-google-genai-embedding

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

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

参考「依赖管理」章节，将 Spring AI 物料清单添加到你的构建文件中。

接下来创建 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 生成式人工智能嵌入 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 生成式人工智能：

核心差异

• SDK：Google 生成式人工智能使用全新的 com.google.genai.Client，替代 Vertex AI SDK

• 认证：同时支持 API 密钥和谷歌云凭证

• 包路径：类位于 org.springframework.ai.google.genai.text，而非 org.springframework.ai.vertexai.embedding

• 配置前缀：使用 spring.ai.google.genai.embedding，替代 spring.ai.vertex.ai.embedding

• 连接配置：使用 GoogleGenAiEmbeddingConnectionDetails，替代 VertexAiEmbeddingConnectionDetails

Google 生成式人工智能与 Vertex AI 文本嵌入选型指南

以下场景推荐使用 Google 生成式人工智能嵌入：

• 需要通过 API 密钥快速开发原型

• 需要使用开发者 API 最新的嵌入功能

• 需要灵活切换 API 密钥和 Vertex AI 模式

• 已在聊天功能中使用 Google 生成式人工智能

以下场景推荐使用 Vertex AI 文本嵌入：

• 已拥有现成的 Vertex AI 基础设施

• 需要多模态嵌入向量（目前仅 Vertex AI 支持）

• 组织要求仅部署谷歌云环境