跳到主要内容

Google VertexAI 文本嵌入

Deepseek 3.2 中英对照 Text Embedding Google VertexAI Text Embeddings

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 添加到您的构建系统中。

自动配置​

备注

Spring AI 的自动配置和 starter 模块的 artifact 名称发生了重大变化。请查阅 升级说明 获取更多信息。

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 Embedding API。

属性描述默认值
spring.ai.vertex.ai.embedding.project-idGoogle Cloud Platform 项目 ID-
spring.ai.vertex.ai.embedding.location区域-
spring.ai.vertex.ai.embedding.apiEndpointVertex AI Embedding API 端点。-
备注

嵌入自动配置的启用与禁用现在通过前缀为 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 Embedding API 模型。true
spring.ai.model.embedding.text启用 Vertex AI Embedding API 模型。vertexai
spring.ai.vertex.ai.embedding.text.options.model这是要使用的 Vertex 文本嵌入模型。text-embedding-004
spring.ai.vertex.ai.embedding.text.options.task-type预期的下游应用，以帮助模型生成更高质量的嵌入。可用的 task-types。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

示例控制器​

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

添加一个application.properties文件到src/main/resources目录下，以启用并配置 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 接口。

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

:::提示
请参考依赖管理章节，将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());