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 凭证进行生产部署并享有企业级功能先决条件选择以下身份验证方法之一选项 1Gemini Developer APIAPI 密钥从 Google AI Studio 获取 API 密钥将 API 密钥设置为环境变量或在应用程序属性中设置选项 2Vertex AIGoogle Cloud根据您的操作系统安装 gcloud CLI。通过运行以下命令进行身份验证。将PROJECT_ID替换为您的 Google Cloud 项目 ID将ACCOUNT替换为您的 Google Cloud 用户名。gcloud configsetprojectPROJECT_IDgcloud auth application-default loginACCOUNT添加仓库和 BOMSpring AI 工件发布在 Maven Central 和 Spring Snapshot 仓库中。请参阅工件仓库部分将这些仓库添加到您的构建系统中。为了帮助管理依赖项Spring AI 提供了一个 BOM物料清单以确保在整个项目中使用一致版本的 Spring AI。请参阅依赖管理部分将 Spring AI BOM 添加到您的构建系统中。自动配置Spring AI 自动配置的启动器模块的工件名称发生了重大变化。更多信息请参阅升级说明。Spring AI 为 Google GenAI 嵌入模型提供了 Spring Boot 自动配置。要启用它请将以下依赖项添加到您项目的 Mavenpom.xml文件中dependencygroupIdorg.springframework.ai/groupIdartifactIdspring-ai-starter-model-google-genai-embedding/artifactId/dependency或添加到您的 Gradlebuild.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 聊天模块共享。如果您同时使用聊天和嵌入功能只需使用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 项目 IDVertex 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.textgoogle-genai默认启用禁用spring.ai.model.embedding.textnone或任何不匹配google-genai的值此更改是为了允许配置多个模型。文本嵌入属性前缀spring.ai.google.genai.embedding.text是用于配置 Google GenAI 文本嵌入的嵌入模型实现的属性前缀。属性描述默认值spring.ai.model.embedding.text启用 Google GenAI 嵌入 API 模型。google-genaispring.ai.google.genai.embedding.text.model要使用的 Google GenAI 文本嵌入模型。支持的模型包括text-embedding-004和text-multilingual-embedding-002text-embedding-004spring.ai.google.genai.embedding.text.task-type预期的下游应用程序以帮助模型生成更高质量的嵌入。可用的任务类型RETRIEVAL_QUERYRETRIEVAL_DOCUMENTSEMANTIC_SIMILARITYCLASSIFICATIONCLUSTERINGQUESTION_ANSWERINGFACT_VERIFICATIONRETRIEVAL_DOCUMENTspring.ai.google.genai.embedding.text.title可选标题仅当task_typeRETRIEVAL_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 APIAPI 密钥spring.ai.google.genai.embedding.api-keyYOUR_API_KEY spring.ai.google.genai.embedding.text.modeltext-embedding-004使用 Vertex AIspring.ai.google.genai.embedding.project-idYOUR_PROJECT_ID spring.ai.google.genai.embedding.locationYOUR_PROJECT_LOCATION spring.ai.google.genai.embedding.text.modeltext-embedding-004这将创建一个您可以注入到您的类中的GoogleGenAiTextEmbeddingModel实现。以下是一个简单的Controller类示例它使用嵌入模型生成嵌入。RestControllerpublicclassEmbeddingController{privatefinalEmbeddingModelembeddingModel;AutowiredpublicEmbeddingController(EmbeddingModelembeddingModel){this.embeddingModelembeddingModel;}GetMapping(/ai/embedding)publicMapembed(RequestParam(valuemessage,defaultValueTell me a joke)Stringmessage){EmbeddingResponseembeddingResponsethis.embeddingModel.embedForResponse(List.of(message));returnMap.of(embedding,embeddingResponse);}}手动配置GoogleGenAiTextEmbeddingModel实现了EmbeddingModel。将spring-ai-google-genai-embedding依赖项添加到您项目的 Mavenpom.xml文件中dependencygroupIdorg.springframework.ai/groupIdartifactIdspring-ai-google-genai-embedding/artifactId/dependency或添加到您的 Gradlebuild.gradle构建文件中。dependencies { implementation org.springframework.ai:spring-ai-google-genai-embedding }请参阅依赖管理部分将 Spring AI BOM 添加到您的构建文件中。接下来创建一个GoogleGenAiTextEmbeddingModel并将其用于文本嵌入使用 API 密钥GoogleGenAiEmbeddingConnectionDetailsconnectionDetailsGoogleGenAiEmbeddingConnectionDetails.builder().apiKey(System.getenv(GOOGLE_API_KEY)).build();GoogleGenAiTextEmbeddingOptionsoptionsGoogleGenAiTextEmbeddingOptions.builder().model(GoogleGenAiTextEmbeddingOptions.DEFAULT_MODEL_NAME).taskType(TaskType.RETRIEVAL_DOCUMENT).build();varembeddingModelnewGoogleGenAiTextEmbeddingModel(connectionDetails,options);EmbeddingResponseembeddingResponseembeddingModel.embedForResponse(List.of(Hello World,World is big and salvation is near));使用 Vertex AIGoogleGenAiEmbeddingConnectionDetailsconnectionDetailsGoogleGenAiEmbeddingConnectionDetails.builder().projectId(System.getenv(GOOGLE_CLOUD_PROJECT)).location(System.getenv(GOOGLE_CLOUD_LOCATION)).build();GoogleGenAiTextEmbeddingOptionsoptionsGoogleGenAiTextEmbeddingOptions.builder().model(GoogleGenAiTextEmbeddingOptions.DEFAULT_MODEL_NAME).taskType(TaskType.RETRIEVAL_DOCUMENT).build();varembeddingModelnewGoogleGenAiTextEmbeddingModel(connectionDetails,options);EmbeddingResponseembeddingResponseembeddingModel.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针对事实核查任务进行优化不同任务类型的使用示例// 用于索引文档GoogleGenAiTextEmbeddingOptionsdocOptionsGoogleGenAiTextEmbeddingOptions.builder().model(text-embedding-004).taskType(TaskType.RETRIEVAL_DOCUMENT).title(Product Documentation)// 文档的可选标题.build();// 用于搜索查询GoogleGenAiTextEmbeddingOptionsqueryOptionsGoogleGenAiTextEmbeddingOptions.builder().model(text-embedding-004).taskType(TaskType.RETRIEVAL_QUERY).build();维度缩减对于 004 及更高版本的模型您可以减少嵌入维度以进行存储优化GoogleGenAiTextEmbeddingOptionsoptionsGoogleGenAiTextEmbeddingOptions.builder().model(text-embedding-004).dimensions(256)// 从默认的 768 维减少到 256 维.build();从 Vertex AI 文本嵌入迁移如果您当前使用的是 Vertex AI 文本嵌入实现spring-ai-vertex-ai-embedding您可以迁移到 Google GenAI只需进行少量更改主要区别SDKGoogle GenAI 使用新的com.google.genai.Client而不是 Vertex AI SDK身份验证支持 API 密钥和 Google Cloud 凭证Vertex AI 模式包名类位于org.springframework.ai.google.genai.text而不是org.springframework.ai.vertexai.embedding属性前缀使用spring.ai.google.genai.embedding而不是spring.ai.vertex.ai.embedding连接详情使用GoogleGenAiEmbeddingConnectionDetails而不是VertexAiEmbeddingConnectionDetailsGoogle GenAI 通过 Google Cloud 凭证既支持使用 API 密钥进行快速原型设计也支持使用 Vertex AI 进行生产部署。