Google GenAI 文本嵌入

Google GenAI 嵌入 API 通过 Gemini Developer API 或 Vertex AI，使用 Google 的嵌入模型提供文本嵌入生成。本文档描述如何用 Google GenAI 文本嵌入 API 创建文本嵌入。

Google GenAI 文本嵌入 API 使用稠密向量表示。 与倾向于把词直接映射到数的稀疏向量不同，稠密向量旨在更好地表示一段文本的含义。 在生成式 AI 中使用稠密向量嵌入的好处是：无需寻找直接的词或语法匹配，你能更好地搜索与查询含义相符的段落，即使这些段落使用的语言不同。

NOTE

目前，Google GenAI SDK 仅支持文本嵌入。多模态嵌入支持尚未就绪，会在 SDK 提供时加入。

此实现提供两种认证模式：

• Gemini Developer API：使用 API 密钥快速做原型与开发
• Vertex AI：使用 Google Cloud 凭据进行带企业特性的生产部署

前置条件

选择以下认证方式之一：

选项一：Gemini Developer API（API 密钥）

• 从 Google AI Studio 获取一个 API 密钥
• 把 API 密钥设为环境变量或写在你的应用属性里

选项二：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 仓库中。 参见 制品仓库 一节，把这些仓库添加到你的构建系统。

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

自动配置

NOTE

Spring AI 的自动配置、starter 模块的制品名称发生了重大变更。 更多信息请参阅 升级说明。

Spring AI 为 Google GenAI 嵌入模型提供 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'
}

TIP

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

嵌入属性

连接属性

前缀 spring.ai.google.genai.embedding 用作连接 Google GenAI 嵌入 API 的属性前缀。

NOTE

连接属性与 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 实例以认证。	-

NOTE

嵌入自动配置的启用与禁用，现通过以 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 文本嵌入配置嵌入模型实现的属性前缀。

属性	描述	默认值
spring.ai.model.embedding.text	启用 Google GenAI 嵌入 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	可选标题，仅在 tasktype=RETRIEVALDOCUMENT 时有效。	-
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 密钥）

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。

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

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

TIP

参见 依赖管理 一节，把 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 嵌入 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 文本嵌入迁移

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

主要差异：

1. SDK：Google GenAI 使用新的 com.google.genai.Client 而非 Vertex AI SDK
2. 认证：同时支持 API 密钥和 Google Cloud 凭据（Vertex AI 模式）
3. 包名：类位于 org.springframework.ai.google.genai.text 而非 org.springframework.ai.vertexai.embedding
4. 属性前缀：使用 spring.ai.google.genai.embedding 而非 spring.ai.vertex.ai.embedding
5. 连接详情：使用 GoogleGenAiEmbeddingConnectionDetails 而非 VertexAiEmbeddingConnectionDetails

Google GenAI 既支持用 API 密钥快速做原型，也支持通过 Google Cloud 凭据使用 Vertex AI 进行生产部署。