|
此版本仍在开发中，尚未被视为稳定版。为了获取最新的快照版本，请使用Spring AI 1.1.3！ |
谷歌GenAI文本嵌入
Google GenAI 嵌入式API谷歌GenAI嵌入式API通过Gemini开发者API或Vertex AI提供使用谷歌嵌入式模型的文本嵌入生成服务。 本文档介绍如何使用Google GenAI文本嵌入式API创建文本嵌入。
Google GenAI 文本嵌入API使用密集向量表示。 与倾向于直接将单词映射到数字的稀疏向量不同，密集向量旨在更好地表达文本的意义。 在生成式AI中使用密集向量嵌入的好处是，您可以不仅仅搜索直接的单词或语法匹配，还能更好地查找与查询意义相符的段落，即使这些段落使用的语言不同。
|
目前，Google GenAI SDK仅支持文本嵌入。多模态嵌入的支持正在计划中，将在SDK可用时添加。 |
此实现提供了两种认证模式：
-
双子星开发者API: 使用API密钥进行快速原型设计和开发
-
Vertex AI: 使用 Google Cloud 凭证进行具备企业功能的生产部署
前提条件
请选择以下认证方法之一：
选项 1：Gemini 开发者 API（API 密钥）
-
从Google AI Studio获取API密钥
-
将API密钥设置为环境变量或在您的应用程序属性中设置
选项 2：Vertex AI（谷歌云）
-
安装适合您操作系统的gcloud命令行工具。
-
通过运行以下命令进行身份验证。 将
PROJECT_ID替换为您的Google Cloud项目ID，将ACCOUNT替换为您的Google Cloud用户名。
gcloud config set project <PROJECT_ID> &&
gcloud auth application-default login <ACCOUNT>自动配置
|
There has been a significant change in the Spring AI auto-configuration, starter modules' artifact names. Please refer to the 升级说明以获取更多信息。 |
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 构建脚本文件中。
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.embedding.api-key |
Gemini 开发者 API 的 API 密钥。当提供此密钥时，客户端将使用 Gemini 开发者 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。当提供时，它用于创建一个 |
- |
|
启用和禁用嵌入式自动配置现在通过带有前缀 要启用，请设置 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 |
spring.ai.google.genai.embedding.text.options.task-type |
用于帮助模型生成更高质量嵌入的预期下游应用。可用的 |
|
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-boot-starter-web添加到您的pom（或gradle）依赖中。
在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 构建脚本文件中。
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:
主要区别
-
SDK: Google GenAI 现使用新版本
com.google.genai.Client代替 Vertex AI SDK -
认证方式: 同时支持API密钥和Google Cloud凭证
-
包名称: 类位于
org.springframework.ai.google.genai.text而不是org.springframework.ai.vertexai.embedding -
属性前缀: 使用
spring.ai.google.genai.embedding代替spring.ai.vertex.ai.embedding -
连接详情: 使用
GoogleGenAiEmbeddingConnectionDetails代替VertexAiEmbeddingConnectionDetails
何时使用Google GenAI与Vertex AI文本嵌入
使用Google GenAI嵌入技术的场景包括： - 需要快速原型设计并使用API密钥 - 需要从开发者API获取最新的嵌入功能 - 希望在API密钥与Vertex AI模式之间灵活切换 - 已在使用Google GenAI进行聊天功能
使用Vertex AI文本嵌入的场景包括： - 您已拥有Vertex AI基础设施 - 您需要多模态嵌入（目前仅在Vertex AI中可用） - 您的组织要求仅部署在Google Cloud上