Google VertexAI 文本嵌入

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 Central 和 Spring Snapshot 仓库中。 参见 制品仓库 一节，把这些仓库添加到你的构建系统。

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

自动配置

NOTE

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'
}

TIP

参见 依赖管理 一节，把 Spring AI BOM 添加到你的构建文件。

嵌入属性

前缀 spring.ai.vertex.ai.embedding 用作连接 VertexAI 嵌入 API 的属性前缀。

属性	描述	默认值
spring.ai.vertex.ai.embedding.project-id	Google Cloud Platform 项目 ID	-
spring.ai.vertex.ai.embedding.location	区域	-
spring.ai.vertex.ai.embedding.api-endpoint	Vertex AI 嵌入 API 端点。	-

NOTE

嵌入自动配置的启用与禁用，现通过以 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.model	要使用的 Vertex 文本嵌入模型	text-embedding-004
spring.ai.vertex.ai.embedding.text.task-type	预期的下游应用，以帮助模型产出更高质量的嵌入。可用的 task-types	RETRIEVAL_DOCUMENT
spring.ai.vertex.ai.embedding.text.title	可选标题，仅在 tasktype=RETRIEVALDOCUMENT 时有效。	-
spring.ai.vertex.ai.embedding.text.dimensions	所生成输出嵌入应具有的维度数。在模型版本 004 及之后受支持。你可以用此参数缩减嵌入大小，例如用于存储优化。	-
spring.ai.vertex.ai.embedding.text.auto-truncate	设为 true 时会截断输入文本。设为 false 时，如果输入文本长于模型支持的最大长度会返回错误。	true

示例控制器

创建 一个新的 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.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。

把 spring-ai-vertex-ai-embedding 依赖添加到你的项目的 Maven pom.xml 文件：

<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'
}

TIP

参见 依赖管理 一节，把 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());