Spring AI 使用谷歌 Vertex AI 文本嵌入模型

Vertex AI 支持两种类型的嵌入模型：文本嵌入模型和多模态嵌入模型。本文档介绍如何使用 Vertex AI 文本嵌入 API 创建文本嵌入。

Vertex AI 文本嵌入 API 采用稠密向量表示形式。与稀疏向量（直接将单词映射为数值）不同，稠密向量旨在更好地表示文本的语义含义。在生成式 AI 中使用稠密向量嵌入的优势在于：无需搜索精确的单词或语法匹配项，而是可以精准查找与查询语义匹配的文本片段，即便这些片段使用的语言不同。

前提条件

根据你的操作系统安装对应的 gcloud 命令行工具。

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

gcloud config set project <PROJECT_ID> &&
gcloud auth application-default login <ACCOUNT>

添加仓库和物料清单（BOM）

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

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

自动配置

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

Spring AI 为 Vertex AI 嵌入模型提供了 Spring Boot 自动配置。如需启用该功能，请在项目的 Maven pom.xml 文件中添加以下依赖：

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

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

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

参考依赖管理章节，将 Spring AI BOM 添加到你的构建文件中。

嵌入模型属性

以 spring.ai.vertex.ai.embedding 为前缀的属性，用于配置与 Vertex AI 嵌入 API 的连接。

嵌入模型自动配置的启用与禁用，现在通过以 spring.ai.model.embedding 为前缀的顶级属性进行配置。

启用配置：spring.ai.model.embedding.text=vertexai（默认已启用）

禁用配置：spring.ai.model.embedding.text=none（或任何不等于 vertexai 的值）

该变更用于支持多模型配置。

以 spring.ai.vertex.ai.embedding.text 为前缀的属性，用于配置 Vertex AI 文本嵌入的 EmbeddingModel 实现类。

示例控制器

创建一个新的 Spring Boot 项目，并将 spring-ai-starter-model-vertex-ai-embedding 添加到你的 Maven（或 Gradle）依赖中。

在 src/main/resources 目录下添加 application.properties 文件，启用并配置 Vertex AI 聊天模型：

spring.ai.vertex.ai.embedding.project-id=<YOUR_PROJECT_ID>
spring.ai.vertex.ai.embedding.location=<YOUR_PROJECT_LOCATION>
spring.ai.vertex.ai.embedding.text.options.model=text-embedding-004

配置完成后会创建 VertexAiTextEmbeddingModel 实现类，你可以将其注入到自定义类中。以下是一个使用嵌入模型生成嵌入向量的简单 @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);
    }
}

手动配置

VertexAiTextEmbeddingModel 实现了 EmbeddingModel 接口。

在项目的 Maven pom.xml 文件中添加 spring-ai-vertex-ai-embedding 依赖：

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

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

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

参考依赖管理章节，将 Spring AI BOM 添加到你的构建文件中。

接下来，创建 VertexAiTextEmbeddingModel 实例并用于生成文本嵌入：

VertexAiEmbeddingConnectionDetails connectionDetails =
    VertexAiEmbeddingConnectionDetails.builder()
        .projectId(System.getenv(<VERTEX_AI_GEMINI_PROJECT_ID>))
        .location(System.getenv(<VERTEX_AI_GEMINI_LOCATION>))
        .build();

VertexAiTextEmbeddingOptions options = VertexAiTextEmbeddingOptions.builder()
    .model(VertexAiTextEmbeddingOptions.DEFAULT_MODEL_NAME)
    .build();

var embeddingModel = new VertexAiTextEmbeddingModel(this.connectionDetails, this.options);

EmbeddingResponse embeddingResponse = this.embeddingModel
	.embedForResponse(List.of("Hello World", "World is big and salvation is near"));

从谷歌服务账号加载凭证

若要通过编程方式从服务账号 JSON 文件加载 GoogleCredentials，可使用以下代码：

GoogleCredentials credentials = GoogleCredentials.fromStream(<INPUT_STREAM_TO_CREDENTIALS_JSON>)
        .createScoped("https://www.googleapis.com/auth/cloud-platform");
credentials.refreshIfExpired();

VertexAiEmbeddingConnectionDetails connectionDetails =
    VertexAiEmbeddingConnectionDetails.builder()
        .projectId(System.getenv(<VERTEX_AI_GEMINI_PROJECT_ID>))
        .location(System.getenv(<VERTEX_AI_GEMINI_LOCATION>))
        .apiEndpoint(endpoint)
        .predictionServiceSettings(
            PredictionServiceSettings.newBuilder()
                .setEndpoint(endpoint)
                .setCredentialsProvider(FixedCredentialsProvider.create(credentials))
                .build());