|
此版本仍在开发中，尚未被视为稳定版。如需最新的快照版本，请使用 Spring AI 1.1.3！ |
Google GenAI 文本嵌入
Google GenAI Embeddings API 通过 Gemini 开发者 API 或 Vertex AI，利用 Google 的嵌入模型提供文本嵌入生成功能。 本文档描述了如何使用 Google GenAI 文本嵌入 API 创建文本嵌入。
Google GenAI 文本嵌入 API 使用稠密向量表示。 与倾向于直接将单词映射为数字的稀疏向量不同，稠密向量旨在更好地表示一段文本的含义。 在生成式人工智能中使用稠密向量嵌入的好处是，您可以搜索与查询含义相符的段落，而不仅仅是搜索直接的单词或语法匹配，即使这些段落使用的语言不同。
|
目前，Google GenAI SDK 仅支持文本嵌入。多模态嵌入支持尚在筹备中，将在 SDK 可用时添加。 |
此实现提供了两种认证模式：
-
Gemini 开发者 API: 使用 API 密钥进行快速原型制作和开发
-
Vertex AI: 使用Google Cloud凭据进行生产部署，具备企业级功能
前置条件
请选择以下之一的身份验证方法：
选项 1: 吉明尼开发人员 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>Auto-configuration
|
Spring AI自动配置和starter模块的artifact名称有了重大变化。 请参阅升级说明获取更多信息。 |
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 聊天模块共享。如果您同时使用聊天和嵌入功能，只需配置一次连接，使用 |
| <property> </property> | <description> </description> | 默认 |
|---|---|---|
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 文本嵌入的嵌入模型实现。
| <property> </property> | <description> </description> | 默认 |
|---|---|---|
spring.ai.model.embedding.text |
启用 Google GenAI Embedding 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项目，并在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 嵌入 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