Google GenAI 文本嵌入

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

Google GenAI 文本嵌入 API 使用密集向量表示。与倾向于将单词直接映射到数字的稀疏向量不同，密集向量旨在更好地表示文本的含义。在生成式 AI 中使用密集向量嵌入的好处是，您不必搜索直接的单词或语法匹配，而是可以更好地搜索与查询含义对齐的段落，即使这些段落没有使用相同的语言。

目前，Google GenAI SDK 仅支持文本嵌入。多模态嵌入支持正在等待中，将在 SDK 中可用时添加。

此实现提供两种认证模式

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

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

先决条件

选择以下任一身份验证方法

选项 1：Gemini Developer 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 自动配置、启动模块的工件名称发生了重大变化。请参阅 升级说明 以获取更多信息。

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 嵌入 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 实例进行身份验证。

-

嵌入自动配置的启用和禁用现在通过前缀为 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.options.model

要使用的 Google GenAI 文本嵌入模型。支持的模型包括 text-embedding-004 和 text-multilingual-embedding-002

text-embedding-004

spring.ai.google.genai.embedding.text.options.task-type

预期的下游应用程序，以帮助模型生成更高质量的嵌入。可用的任务类型：RETRIEVAL_QUERY, RETRIEVAL_DOCUMENT, SEMANTIC_SIMILARITY, CLASSIFICATION, CLUSTERING, QUESTION_ANSWERING, FACT_VERIFICATION

RETRIEVAL_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 项目，并将 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.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 嵌入 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 嵌入： - 您希望使用 API 密钥进行快速原型设计 - 您需要开发者 API 的最新嵌入功能 - 您希望灵活地在 API 密钥和 Vertex AI 模式之间切换 - 您已经在聊天中使用 Google GenAI

在以下情况使用 Vertex AI 文本嵌入： - 您拥有现有的 Vertex AI 基础设施 - 您需要多模态嵌入（目前仅在 Vertex AI 中可用） - 您的组织需要仅限 Google Cloud 的部署

© . This site is unofficial and not affiliated with VMware.