Google VertexAI 文本嵌入模型

本站(springdoc.cn)中的内容来源于 spring.io ，原始版权归属于 spring.io。由 springdoc.cn 进行翻译，整理。可供个人学习、研究，未经许可，不得进行任何转载、商用或与之相关的行为。 商标声明：Spring 是 Pivotal Software, Inc. 在美国以及其他国家的商标。

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

Vertex AI 文本嵌入 API 采用密集向量表示。与直接映射单词到数字的稀疏向量不同，密集向量能更好地捕捉文本的语义。其优势在于：生成式 AI 应用中，无需精确匹配单词或语法，即可检索语义相关的文本段落（即使语言不同）。

先决条件

  • 安装适用于你操作系统的 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 中央仓库和 Spring 快照仓库。请参阅 “Artifact 仓库” 章节将这些仓库添加到你的构建系统中。

为简化依赖管理，Spring AI 提供 BOM (物料清单) 以确保项目统一使用相同版本。请参考 “依赖管理” 章节将 Spring AI BOM 添加到你的构建系统。

自动配置

Spring AI 自动配置及 starter 模块的构件命名已发生重大变更，详情请参阅 升级说明文档。

Spring AI 为 VertexAI 嵌入模型提供 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 是用于连接 VertexAI 嵌入 API 的属性前缀。

属性 说明 默认值

spring.ai.vertex.ai.embedding.project-id

Google Cloud Platform project ID

-

spring.ai.vertex.ai.embedding.location

Region

-

spring.ai.vertex.ai.embedding.apiEndpoint

Vertex AI Embedding API endpoint.

-

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

  • 启用：spring.ai.model.embedding.text=vertexai（默认启用）

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

此变更为支持多模型配置。

前缀 spring.ai.vertex.ai.embedding.text 是用于配置 VertexAI 文本嵌入模型实现的属性前缀。

属性 说明 默认值

spring.ai.vertex.ai.embedding.text.enabled （已移除且不再有效）

启用 Vertex AI 嵌入 API 模型。

true

spring.ai.model.embedding.text

启用 Vertex AI 嵌入 API 模型。

vertexai

spring.ai.vertex.ai.embedding.text.options.model

要使用的 Vertex 文本嵌入模型。

text-embedding-004

spring.ai.vertex.ai.embedding.text.options.task-type

下游应用任务类型（帮助模型生成更高质量的嵌入）。可选 任务类型。

RETRIEVAL_DOCUMENT

spring.ai.vertex.ai.embedding.text.options.title

可选，标题（仅当 task_type=RETRIEVAL_DOCUMENT 时有效）。

-

spring.ai.vertex.ai.embedding.text.options.dimensions

输出嵌入向量的维度数（仅模型版本 004 及以上支持）。可通过此参数减小嵌入尺寸（例如用于存储优化）。

-

spring.ai.vertex.ai.embedding.text.options.auto-truncate

设为 true 时自动截断输入文本；设为 false 时若输入超长将返回错误。

true

示例 Controller

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

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

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

从 Google 服务账号加载凭证

要通过编程方式从服务账号 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());