Google GenAI 文本嵌入

QWen 3.8 中英对照 Google GenAI Text Embedding Google GenAI Text Embeddings

Google GenAI Embeddings API 使用 Google 的 embedding 模型，通过 Gemini Developer API 或 Vertex AI 提供文本嵌入生成服务。本文档介绍如何使用 Google GenAI Text embeddings API 创建文本嵌入。

Google GenAI 文本嵌入 API 使用稠密向量表示。与稀疏向量不同，稀疏向量通常将单词直接映射为数字，而稠密向量旨在更好地表示文本片段的含义。在生成式 AI 中使用稠密向量嵌入的优势在于，您可以更好地搜索与查询含义相符的段落，即使这些段落并未使用相同的语言，而无需寻找直接的单词或语法匹配。

备注

目前，Google GenAI SDK 仅支持文本嵌入。多模态嵌入支持待定，待 SDK 支持后可用。

该实现提供两种身份验证模式：

• Gemini 开发者 API：使用 API 密钥进行快速原型开发和测试
• Vertex AI：使用 Google Cloud 凭证进行生产环境部署，支持企业级功能

前提条件

选择以下身份验证方法之一：

选项 1：Gemini Developer API（API Key）

• 从 Google AI Studio 获取 API key

• 将 API key 设置为环境变量或在应用属性中配置

选项 2：Vertex AI (Google Cloud)

• 安装适用于您的操作系统的 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 仓库中。请参阅 Artifact Repositories 部分，将这些仓库添加到您的构建系统中。

为了方便依赖管理，Spring AI 提供了一个 BOM（物料清单），以确保在整个项目中使用一致的 Spring AI 版本。请参考 Dependency Management 部分，将 Spring AI BOM 添加到你的构建系统中。

自动配置

备注

Spring AI 的自动配置以及 starter 模块的 artifact 名称已发生重大变更。详情请参见 升级说明。

Spring AI 为 Google GenAI Embedding Model 提供 Spring Boot 自动配置。要启用它，请将以下依赖项添加到项目的 Maven pom.xml 文件中：

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

或添加到你的 Gradle build.gradle 构建文件中。

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

提示

请参见 Dependency Management 章节，以将 Spring AI BOM 添加到你的构建文件中。

嵌入属性

连接属性

前缀 spring.ai.google.genai.embedding 用作属性前缀，用于连接到 Google GenAI Embedding API。

备注

连接属性与 Google GenAI Chat 模块共享。如果同时使用聊天和嵌入，只需使用 spring.ai.google.genai 前缀（用于聊天）或 spring.ai.google.genai.embedding 前缀（用于嵌入）配置一次连接即可。

属性	描述	默认值
spring.ai.google.genai.embedding.api-key	Gemini Developer API 的 API 密钥。如果提供，客户端将使用 Gemini Developer API 而非 Vertex AI。	-
spring.ai.google.genai.embedding.project-id	Google Cloud Platform 项目 ID（Vertex AI 模式下必填）	-
spring.ai.google.genai.embedding.location	Google Cloud 区域（Vertex AI 模式下必填）	-
spring.ai.google.genai.embedding.credentials-uri	Google Cloud 凭据的 URI。如果提供，将用于创建 GoogleCredentials 实例以进行身份验证。	-

备注

嵌入（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 GenAI 文本嵌入模型实现的属性前缀。

Property	Description	Default
spring.ai.model.embedding.text	启用 Google GenAI Embedding API 模型。	google-genai
spring.ai.google.genai.embedding.text.model	要使用的 Google GenAI 文本嵌入模型。支持的模型包括 text-embedding-004 和 text-multilingual-embedding-002	text-embedding-004
spring.ai.google.genai.embedding.text.task-type	预期的下游应用程序，以帮助模型生成更高质量的嵌入。可用的 task-types：RETRIEVAL_QUERY、RETRIEVAL_DOCUMENT、SEMANTIC_SIMILARITY、CLASSIFICATION、CLUSTERING、QUESTION_ANSWERING、FACT_VERIFICATION	RETRIEVAL_DOCUMENT
spring.ai.google.genai.embedding.text.title	可选标题，仅在 task_type=RETRIEVAL_DOCUMENT 时有效。	-
spring.ai.google.genai.embedding.text.dimensions	生成的输出嵌入应具有的特征数量。支持模型版本 004 及更高版本。您可以使用此参数来减小嵌入大小，例如用于存储优化。	-
spring.ai.google.genai.embedding.text.auto-truncate	当设置为 true 时，输入文本将被截断。当设置为 false 时，如果输入文本长度超过模型支持的最大长度，则返回错误。	true

示例控制器

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

在 src/main/resources 目录下添加 application.properties 文件，以启用并配置 Google GenAI 嵌入模型：

使用 Gemini Developer API（API Key）

spring.ai.google.genai.embedding.api-key=YOUR_API_KEY
spring.ai.google.genai.embedding.text.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.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 文件中添加 spring-ai-google-genai-embedding 依赖项：

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

或添加到你的 Gradle build.gradle 构建文件中。

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

提示

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

接下来，创建一个 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 GenAI embeddings API 支持不同的任务类型，以针对特定用例优化嵌入向量：

• RETRIEVAL_QUERY: 优化用于检索系统中的查询
• RETRIEVAL_DOCUMENT: 优化用于检索系统中的文档
• SEMANTIC_SIMILARITY: 优化用于衡量文本间的语义相似度
• CLASSIFICATION: 优化用于文本分类任务
• CLUSTERING: 优化用于对相似文本进行聚类
• QUESTION_ANSWERING: 优化用于问答系统
• FACT_VERIFICATION: 优化用于事实核查任务

不同任务类型的用法示例：

// For indexing documents
GoogleGenAiTextEmbeddingOptions docOptions = GoogleGenAiTextEmbeddingOptions.builder()
    .model("text-embedding-004")
    .taskType(TaskType.RETRIEVAL_DOCUMENT)
    .title("Product Documentation")  // Optional title for documents
    .build();

// For search queries
GoogleGenAiTextEmbeddingOptions queryOptions = GoogleGenAiTextEmbeddingOptions.builder()
    .model("text-embedding-004")
    .taskType(TaskType.RETRIEVAL_QUERY)
    .build();

维度降维

对于 004 及更高版本的模型，您可以降低嵌入维度以优化存储：

GoogleGenAiTextEmbeddingOptions options = GoogleGenAiTextEmbeddingOptions.builder()
    .model("text-embedding-004")
    .dimensions(256)  // Reduce from default 768 to 256 dimensions
    .build();

从 Vertex AI Text Embeddings 迁移

如果你当前正在使用 Vertex AI 文本嵌入（spring-ai-vertex-ai-embedding）实现，你可以以最小改动迁移到 Google GenAI：

主要差异：

1. SDK：Google GenAI 使用新的 com.google.genai.Client 替代 Vertex AI SDK

2. Authentication：同时支持 API 密钥和 Google Cloud 凭证（Vertex AI 模式）

3. Package Names：类位于 org.springframework.ai.google.genai.text 包下，而非 org.springframework.ai.vertexai.embedding

4. Property Prefix：使用 spring.ai.google.genai.embedding 作为配置前缀，而非 spring.ai.vertex.ai.embedding

5. Connection Details：使用 GoogleGenAiEmbeddingConnectionDetails 替代 VertexAiEmbeddingConnectionDetails

Google GenAI 支持通过 API 密钥进行快速原型开发，以及使用 Google Cloud 凭据通过 Vertex AI 进行生产环境部署。