跳到主要内容

Google GenAI 文本嵌入

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

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

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

备注

目前，Google GenAI SDK 仅支持文本嵌入。多模态嵌入支持待定，将在 SDK 中提供此功能时添加。

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

  • Gemini Developer API：使用 API 密钥进行快速原型设计和开发

  • Vertex AI：使用 Google Cloud 凭据进行具有企业功能的生产部署

前提条件​

请从以下身份验证方法中选择一种：

选项 1：Gemini 开发者 API（API 密钥）​

  • 从 Google AI Studio 获取一个 API 密钥

  • 将 API 密钥设置为环境变量或配置到你的应用程序属性中

选项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仓库中。请参阅工件仓库章节，将这些仓库添加到您的构建系统中。

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

自动配置​

备注

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

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

嵌入属性​

连接属性​

前缀 spring.ai.google.genai.embedding 作为属性前缀，允许你连接到 Google GenAI Embedding API。

备注

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

属性描述默认值
spring.ai.google.genai.embedding.api-keyGemini Developer API 的 API 密钥。当提供此值时，客户端将使用 Gemini Developer API 而非 Vertex AI。-
spring.ai.google.genai.embedding.project-idGoogle Cloud Platform 项目 ID（Vertex AI 模式下必需）-
spring.ai.google.genai.embedding.locationGoogle Cloud 区域（Vertex AI 模式下必需）-
spring.ai.google.genai.embedding.credentials-uriGoogle Cloud 凭据的 URI。当提供此值时，将用于创建用于身份验证的 GoogleCredentials 实例。-
备注

现在，嵌入自动配置的启用和禁用通过顶级属性进行配置，这些属性以 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 Embedding API 模型。google-genai
spring.ai.google.genai.embedding.text.options.model使用的 Google GenAI 文本嵌入模型。支持的模型包括 text-embedding-004 和 text-multilingual-embedding-002text-embedding-004
spring.ai.google.genai.embedding.text.options.task-type预期的下游应用程序，以帮助模型生成更高质量的嵌入。可用的 task-types: RETRIEVAL_QUERY, RETRIEVAL_DOCUMENT, SEMANTIC_SIMILARITY, CLASSIFICATION, CLUSTERING, QUESTION_ANSWERING, FACT_VERIFICATIONRETRIEVAL_DOCUMENT
spring.ai.google.genai.embedding.text.options.title可选的标题，仅当 task_type=RETRIEVAL_DOCUMENT 时有效。-
spring.ai.google.genai.embedding.text.options.dimensions生成输出嵌入应具有的维度数。模型版本 004 及更高版本支持此参数。您可以使用此参数来减小嵌入大小，例如用于存储优化。-
spring.ai.google.genai.embedding.text.options.auto-truncate设置为 true 时，输入文本将被截断。设置为 false 时，如果输入文本超过模型支持的最大长度，将返回错误。true

示例控制器​

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

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

使用 Gemini 开发者 API（API 密钥）​

spring.ai.google.genai.embedding.api-key=YOUR_API_KEY
spring.ai.google.genai.embedding.text.options.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.options.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'
}

:::提示
请参考依赖管理部分，将 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 文本嵌入迁移​

如果你当前正在使用 Vertex AI 文本嵌入实现（spring-ai-vertex-ai-embedding），只需进行少量更改即可迁移到 Google GenAI：

关键区别​

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

  2. 认证：支持 API 密钥和 Google Cloud 凭证

  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 与 Vertex AI 文本嵌入​

在以下情况下使用 Google GenAI Embeddings： - 您希望通过 API 密钥快速进行原型设计 - 您需要开发者 API 提供的最新嵌入功能 - 您希望在 API 密钥和 Vertex AI 模式之间灵活切换 - 您已在聊天功能中使用 Google GenAI

在以下情况下使用 Vertex AI 文本嵌入模型：

  • 您已有现成的 Vertex AI 基础设施
  • 您需要多模态嵌入（目前仅 Vertex AI 提供此功能）
  • 您的组织要求仅部署在 Google Cloud 上