Titan 嵌入模型

本站(springdoc.cn)中的内容来源于 spring.io ，原始版权归属于 spring.io。由 springdoc.cn 进行翻译，整理。可供个人学习、研究，未经许可，不得进行任何转载、商用或与之相关的行为。 商标声明：Spring 是 Pivotal Software, Inc. 在美国以及其他国家的商标。

提供 Bedrock Titan 嵌入模型。Amazon Titan 基础模型（FMs）通过全托管 API 为客户提供多种高性能的图像、多模态嵌入和文本模型选择。这些由 AWS 创建的模型基于海量数据集预训练，是支持多种用例的强大通用模型，同时遵循 AI 负责任使用原则。可直接使用或使用私有数据定制。

Bedrock Titan 嵌入模型支持文本与图像嵌入功能。
Bedrock Titan 嵌入模型不支持批量嵌入处理。

AWS Bedrock Titan 模型页面 和 Amazon Bedrock 用户指南 包含有关如何使用 AWS 托管模型的详细信息。

先决条件

请参阅 Spring AI 关于 Amazon Bedrock 的文档 来设置 API 访问权限。

添加仓库和 BOM

Spring AI 构件已发布至 Maven 中央仓库和 Spring 快照仓库。请参阅 构件仓库 章节将这些仓库添加到你的构建系统中。

为简化依赖管理，Spring AI 提供 BOM 以确保项目统一使用相同版本。请参考 “依赖管理” 章节将 Spring AI BOM 添加到你的构建系统中。

自动配置

Spring AI 自动配置及 Starter 模块的构件命名已发生重大变更，详情请参阅 升级说明 文档。

将 spring-ai-starter-model-bedrock 依赖添加到你项目的 Maven pom.xml 文件中：

<dependency>
  <groupId>org.springframework.ai</groupId>
  <artifactId>spring-ai-starter-model-bedrock</artifactId>
</dependency>

或添加到你的 Gradle build.gradle 构建文件中。

dependencies {
    implementation 'org.springframework.ai:spring-ai-starter-model-bedrock'
}
请参考 依赖管理 章节将 Spring AI BOM 添加到你的构建文件。

启用 Titan 嵌入支持

默认情况下，Titan 嵌入模型处于禁用状态。要启用它，请在你的应用配置中将 spring.ai.model.embedding 属性设置为 bedrock-titan：

spring.ai.model.embedding=bedrock-titan

或者，你可以使用 Spring 表达式语言（SpEL）引用环境变量：

# In application.yml
spring:
  ai:
    model:
      embedding: ${AI_MODEL_EMBEDDING}
# In your environment or .env file
export AI_MODEL_EMBEDDING=bedrock-titan

你也可以在启动应用时使用 Java 系统属性设置此参数：

java -Dspring.ai.model.embedding=bedrock-titan -jar your-application.jar

嵌入配置

前缀 spring.ai.bedrock.aws 是用于配置连接到 AWS Bedrock 的属性前缀。

属性 说明 默认值

spring.ai.bedrock.aws.region

AWS region

us-east-1

spring.ai.bedrock.aws.access-key

AWS access key

-

spring.ai.bedrock.aws.secret-key

AWS secret key

-

嵌入自动配置的启用与禁用现在通过顶级属性配置，前缀为 spring.ai.model.embedding。

  • 启用：spring.ai.model.embedding=bedrock-titan（默认启用）

  • 禁用：spring.ai.model.embedding=none（或任何不匹配 bedrock-titan 的值）

此变更是为了支持多模型配置。

前缀 spring.ai.bedrock.titan.embedding（定义于 BedrockTitanEmbeddingProperties 中）是用于配置 Titan 嵌入模型实现的属性前缀。

属性

说明

默认值

spring.ai.bedrock.titan.embedding.enabled （已移除且不再有效）

启用或禁用 Titan 嵌入支持功能

false

spring.ai.model.embedding

启用或禁用 Titan 嵌入支持功能

bedrock-titan

spring.ai.bedrock.titan.embedding.model

使用的模型 ID。支持的模型请参阅 TitanEmbeddingModel。

amazon.titan-embed-image-v1

支持的值为：amazon.titan-embed-image-v1、amazon.titan-embed-text-v1 和 amazon.titan-embed-text-v2:0。模型 ID 值也可在 AWS Bedroc k基础模型 ID 文档 中查询。

运行时选项

BedrockTitanEmbeddingOptions.java 提供模型配置参数（如 input-type）。初始化时，默认选项可通过 BedrockTitanEmbeddingModel(api).withInputType(type) 方法或 spring.ai.bedrock.titan.embedding.input-type 属性配置。

运行时，你可以通过向 EmbeddingRequest 调用添加新的请求特定选项来覆盖默认配置。例如，针对特定请求覆盖默认温度值：

EmbeddingResponse embeddingResponse = embeddingModel.call(
    new EmbeddingRequest(List.of("Hello World", "World is big and salvation is near"),
        BedrockTitanEmbeddingOptions.builder()
        	.withInputType(InputType.TEXT)
        .build()));

示例 Controller

创建 一个新的 Spring Boot 项目，并将 spring-ai-starter-model-bedrock 添加到你的 pom（或`gradle`）依赖中。

在 src/main/resources 目录下添加 application.properties 文件，用于启用和配置 Titan 嵌入模型：

spring.ai.bedrock.aws.region=eu-central-1
spring.ai.bedrock.aws.access-key=${AWS_ACCESS_KEY_ID}
spring.ai.bedrock.aws.secret-key=${AWS_SECRET_ACCESS_KEY}

spring.ai.model.embedding=bedrock-titan
将 regions、access-key 和 secret-key 替换为你的 AWS 凭证。

这将创建一个可注入到你类中的 EmbeddingController 实现。以下是一个简单的 @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);
    }
}

手动配置

BedrockTitanEmbeddingModel 实现了 EmbeddingModel 接口，并使用 底层 TitanEmbeddingBedrockApi 客户端 连接至 Bedrock Titan 服务。

将 spring-ai-bedrock 依赖添加到你项目的 Maven pom.xml 文件中：

<dependency>
    <groupId>org.springframework.ai</groupId>
    <artifactId>spring-ai-bedrock</artifactId>
</dependency>

或添加到你的 Gradle build.gradle 构建文件中。

dependencies {
    implementation 'org.springframework.ai:spring-ai-bedrock'
}
请参阅 依赖管理 章节将 Spring AI BOM 添加到你的构建文件中。

接下来，创建 BedrockTitanEmbeddingModel 并使用它进行文本嵌入：

var titanEmbeddingApi = new TitanEmbeddingBedrockApi(
	TitanEmbeddingModel.TITAN_EMBED_IMAGE_V1.id(), Region.US_EAST_1.id());

var embeddingModel = new BedrockTitanEmbeddingModel(this.titanEmbeddingApi);

EmbeddingResponse embeddingResponse = this.embeddingModel
	.embedForResponse(List.of("Hello World")); // NOTE titan does not support batch embedding.

底层 TitanEmbeddingBedrockApi 客户端

TitanEmbeddingBedrockApi 是基于 AWS Bedrock Titan 嵌入模型 的轻量级 Java 客户端。

以下类图展示了 TitanEmbeddingBedrockApi 接口及其核心组件：

bedrock titan embedding low level api

TitanEmbeddingBedrockApi 支持 amazon.titan-embed-image-v1 和 amazon.titan-embed-text-v1 模型，用于单个及批量嵌入计算。

以下是编程式使用该 API 的简单示例：

TitanEmbeddingBedrockApi titanEmbedApi = new TitanEmbeddingBedrockApi(
		TitanEmbeddingModel.TITAN_EMBED_TEXT_V1.id(), Region.US_EAST_1.id());

TitanEmbeddingRequest request = TitanEmbeddingRequest.builder()
	.withInputText("I like to eat apples.")
	.build();

TitanEmbeddingResponse response = this.titanEmbedApi.embedding(this.request);

要嵌入图像，需将其转换为 base64 格式：

TitanEmbeddingBedrockApi titanEmbedApi = new TitanEmbeddingBedrockApi(
		TitanEmbeddingModel.TITAN_EMBED_IMAGE_V1.id(), Region.US_EAST_1.id());

byte[] image = new DefaultResourceLoader()
	.getResource("classpath:/spring_framework.png")
	.getContentAsByteArray();


TitanEmbeddingRequest request = TitanEmbeddingRequest.builder()
	.withInputImage(Base64.getEncoder().encodeToString(this.image))
	.build();

TitanEmbeddingResponse response = this.titanEmbedApi.embedding(this.request);