谷歌GenAI文本嵌入

Google GenAI 嵌入式API谷歌GenAI嵌入式API通过Gemini开发者API或Vertex AI提供使用谷歌嵌入式模型的文本嵌入生成服务。 本文档介绍如何使用Google GenAI文本嵌入式API创建文本嵌入。spring-doc.cadn.net.cn

Google GenAI 文本嵌入API使用密集向量表示。 与倾向于直接将单词映射到数字的稀疏向量不同，密集向量旨在更好地表达文本的意义。 在生成式AI中使用密集向量嵌入的好处是，您可以不仅仅搜索直接的单词或语法匹配，还能更好地查找与查询意义相符的段落，即使这些段落使用的语言不同。spring-doc.cadn.net.cn

目前，Google GenAI SDK仅支持文本嵌入。多模态嵌入的支持正在计划中，将在SDK可用时添加。spring-doc.cadn.net.cn

此实现提供了两种认证模式：spring-doc.cadn.net.cn

前提条件

请选择以下认证方法之一：spring-doc.cadn.net.cn

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

选项 2：Vertex AI（谷歌云）

gcloud config set project <PROJECT_ID> &&
gcloud auth application-default login <ACCOUNT>

添加仓库和BOM

Spring AI 工件发布在 Maven Central 和 Spring Snapshot 仓库中。 请参阅 工件仓库 部分，以将这些仓库添加到您的构建系统。spring-doc.cadn.net.cn

为了帮助管理依赖，Spring AI 提供了一个 BOM（物料清单），以确保在整个项目中使用一致的 Spring AI 版本。请参阅 依赖管理 部分，将 Spring AI BOM 添加到您的构建系统。spring-doc.cadn.net.cn

自动配置

There has been a significant change in the Spring AI auto-configuration, starter modules' artifact names. Please refer to the 升级说明以获取更多信息。spring-doc.cadn.net.cn

Spring AI 为 Google GenAI 嵌入模型提供了 Spring Boot 自动配置功能。要启用它，请在项目的 Maven pom.xml 文件中添加以下依赖项：spring-doc.cadn.net.cn

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

或者添加到您的Gradle 构建脚本文件中。spring-doc.cadn.net.cn

dependencies {
    implementation 'org.springframework.ai:spring-ai-starter-model-google-genai-embedding'
}
参考以下依赖管理部分，添加Spring AI BOM到你的构建文件中。

嵌入属性

连接属性

前缀 spring.ai.google.genai.embedding 用于作为属性前缀，以便您连接到Google GenAI嵌入式API。spring-doc.cadn.net.cn

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

spring.ai.google.genai.embedding.api-keyspring-doc.cadn.net.cn

Gemini 开发者 API 的 API 密钥。当提供此密钥时，客户端将使用 Gemini 开发者 API 而非 Vertex AI。spring-doc.cadn.net.cn

-spring-doc.cadn.net.cn

spring.ai.google.genai.embedding.project-idspring-doc.cadn.net.cn

Google Cloud Platform 项目ID（Vertex AI模式必需）spring-doc.cadn.net.cn

-spring-doc.cadn.net.cn

spring.ai.google.genai.embedding.locationspring-doc.cadn.net.cn

Google Cloud 区域（Vertex AI 模式必需）spring-doc.cadn.net.cn

-spring-doc.cadn.net.cn

spring.ai.google.genai.embedding.credentials-urispring-doc.cadn.net.cn

通往Google Cloud凭证的URI。当提供时，它用于创建一个GoogleCredentials实例以进行身份验证。spring-doc.cadn.net.cn

-spring-doc.cadn.net.cn

启用和禁用嵌入式自动配置现在通过带有前缀 spring.ai.model.embedding 的顶级属性进行配置。spring-doc.cadn.net.cn

要启用，请设置 spring.ai.model.embedding.text=google-genai （默认情况下已启用）spring-doc.cadn.net.cn

要禁用，请设置 spring.ai.model.embedding.text=none（或任何不匹配google-genai的值）。spring-doc.cadn.net.cn

这种修改是为了允许配置多个模型。spring-doc.cadn.net.cn

文本嵌入属性

前缀spring.ai.google.genai.embedding.text是属性前缀，允许您为Google GenAI文本嵌入配置嵌入模型实现。spring-doc.cadn.net.cn

属性 描述 默认

spring.ai.model.embedding.textspring-doc.cadn.net.cn

启用 Google GenAI 嵌入 API 模型。spring-doc.cadn.net.cn

google-genaispring-doc.cadn.net.cn

spring.ai.google.genai.embedding.text.options.modelspring-doc.cadn.net.cn

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

text-embedding-004spring-doc.cadn.net.cn

spring.ai.google.genai.embedding.text.options.task-typespring-doc.cadn.net.cn

用于帮助模型生成更高质量嵌入的预期下游应用。可用的task-types: RETRIEVAL_QUERY, RETRIEVAL_DOCUMENT, SEMANTIC_SIMILARITY, CLASSIFICATION, CLUSTERING, QUESTION_ANSWERING, FACT_VERIFICATIONspring-doc.cadn.net.cn

RETRIEVAL_DOCUMENTspring-doc.cadn.net.cn

spring.ai.google.genai.embedding.text.options.titlespring-doc.cadn.net.cn

可选标题，仅在 task_type=RETRIEVAL_DOCUMENT 时有效。spring-doc.cadn.net.cn

-spring-doc.cadn.net.cn

spring.ai.google.genai.embedding.text.options.dimensionsspring-doc.cadn.net.cn

生成的输出嵌入应具有的维度数量。此功能支持模型版本004及以后。您可以使用此参数减小嵌入尺寸，例如，为了进行存储优化。spring-doc.cadn.net.cn

-spring-doc.cadn.net.cn

spring.ai.google.genai.embedding.text.options.auto-truncatespring-doc.cadn.net.cn

当设置为true时，输入文本将被截断。当设置为false时，如果输入文本超过模型支持的最大长度，则返回错误。spring-doc.cadn.net.cn

truespring-doc.cadn.net.cn

示例控制器

创建一个新的Spring Boot项目，并将spring-boot-starter-web添加到您的pom（或gradle）依赖中。spring-doc.cadn.net.cn

在src/main/resources目录下添加一个application.properties文件，以启用并配置Google GenAI嵌入模型：spring-doc.cadn.net.cn

使用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类的例子。spring-doc.cadn.net.cn

@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-doc.cadn.net.cn

将 spring-ai-google-genai-embedding 依赖添加到您项目的 Maven pom.xml 文件中：spring-doc.cadn.net.cn

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

或者添加到您的Gradle 构建脚本文件中。spring-doc.cadn.net.cn

dependencies {
    implementation 'org.springframework.ai:spring-ai-google-genai-embedding'
}
参考以下依赖管理部分，添加Spring AI BOM到你的构建文件中。

接下来，创建一个GoogleGenAiTextEmbeddingModel并将其用于文本嵌入：spring-doc.cadn.net.cn

使用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支持不同的任务类型，以便为特定用例优化嵌入：spring-doc.cadn.net.cn

使用不同任务类型的例子：spring-doc.cadn.net.cn

// 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版本及以后的模型，您可以减少嵌入维度以优化存储。spring-doc.cadn.net.cn

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:spring-doc.cadn.net.cn

主要区别

  1. SDK: Google GenAI 现使用新版本 com.google.genai.Client 代替 Vertex AI SDKspring-doc.cadn.net.cn

  2. 认证方式: 同时支持API密钥和Google Cloud凭证spring-doc.cadn.net.cn

  3. 包名称: 类位于 org.springframework.ai.google.genai.text 而不是 org.springframework.ai.vertexai.embeddingspring-doc.cadn.net.cn

  4. 属性前缀: 使用 spring.ai.google.genai.embedding 代替 spring.ai.vertex.ai.embeddingspring-doc.cadn.net.cn

  5. 连接详情: 使用 GoogleGenAiEmbeddingConnectionDetails 代替 VertexAiEmbeddingConnectionDetailsspring-doc.cadn.net.cn

何时使用Google GenAI与Vertex AI文本嵌入

使用Google GenAI嵌入技术的场景包括： - 需要快速原型设计并使用API密钥 - 需要从开发者API获取最新的嵌入功能 - 希望在API密钥与Vertex AI模式之间灵活切换 - 已在使用Google GenAI进行聊天功能spring-doc.cadn.net.cn

使用Vertex AI文本嵌入的场景包括： - 您已拥有Vertex AI基础设施 - 您需要多模态嵌入（目前仅在Vertex AI中可用） - 您的组织要求仅部署在Google Cloud上spring-doc.cadn.net.cn