PostgresML 嵌入模型

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

Spring AI 支持 PostgresML 文本嵌入模型。

嵌入是文本的数字表示。它们用于将单词和句子表示为向量，即数字数组。嵌入模型可以通过使用距离度量比较数字向量的相似度来查找相似的文本片段，也可以用作其他机器学习模型的输入特征，因为大多数算法都无法直接使用文本。

PostgresML 支持使用多种预训练大语言模型（LLMs）生成文本嵌入向量。可通过 Hugging Face 浏览所有可用模型以选择最佳方案。

添加仓库和 BOM

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

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

自动配置

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

Spring AI 为 Azure PostgresML 嵌入模型提供 Spring Boot 自动配置。启用该功能需在项目的 Maven pom.xml 文件中添加以下依赖：

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

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

dependencies {
    implementation 'org.springframework.ai:spring-ai-starter-model-postgresml-embedding'
}

请参考 “依赖管理” 章节将 Spring AI BOM 添加到你的构建文件。

使用 spring.ai.postgresml.embedding.options.* 属性配置 PostgresMlEmbeddingModel。相关链接：

嵌入配置

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

启用：spring.ai.model.embedding=postgresml（默认启用）
禁用：spring.ai.model.embedding=none（或任何不匹配 postgresml 的值）

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

前缀 spring.ai.postgresml.embedding 是用于配置 PostgresML 嵌入模型（EmbeddingModel）实现的属性前缀。

属性

说明

默认值

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

启用 PostgresML 嵌入模型。.

true

spring.ai.model.embedding

启用 PostgresML 嵌入模型。

postgresml

spring.ai.postgresml.embedding.create-extension

执行 SQL 命令 CREATE EXTENSION IF NOT EXISTS pgml 以启用该扩展。

false

spring.ai.postgresml.embedding.options.transformer

用于嵌入的 Hugging Face 转换器模型。

distilbert-base-uncased

spring.ai.postgresml.embedding.options.kwargs

转换器特定选项。

empty map

spring.ai.postgresml.embedding.options.vectorType

用于嵌入的 PostgresML 向量类型。支持两种选项：PG_ARRAY 和 PG_VECTOR。

PG_ARRAY

spring.ai.postgresml.embedding.options.metadataMode

文档元数据聚合模式。

EMBED

所有以 spring.ai.postgresml.embedding.options 为前缀的属性，均可通过在 EmbeddingRequest 调用中添加请求特定的运行时选项进行覆盖。

运行时选项

使用 PostgresMlEmbeddingOptions.java 配置 PostgresMlEmbeddingModel 的选项，例如使用的模型等。

初始化时可通过 PostgresMlEmbeddingModel 构造函数传入 PostgresMlEmbeddingOptions 配置所有嵌入请求的默认选项。运行时通过在 EmbeddingRequest 中添加 PostgresMlEmbeddingOptions 覆盖默认配置。

例如，针对特定请求覆盖默认模型名称：

EmbeddingResponse embeddingResponse = embeddingModel.call(
    new EmbeddingRequest(List.of("Hello World", "World is big and salvation is near"),
            PostgresMlEmbeddingOptions.builder()
                .transformer("intfloat/e5-small")
                .vectorType(VectorType.PG_ARRAY)
                .kwargs(Map.of("device", "gpu"))
                .build()));

示例 Controller

这将创建一个可注入到类中的 EmbeddingModel 实现。以下是一个简单的 @Controller 类示例，该类使用 EmbeddingModel 实现：

spring.ai.postgresml.embedding.options.transformer=distilbert-base-uncased
spring.ai.postgresml.embedding.options.vectorType=PG_ARRAY
spring.ai.postgresml.embedding.options.metadataMode=EMBED
spring.ai.postgresml.embedding.options.kwargs.device=cpu

@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);
    }
}

手动配置

若不使用 Spring Boot 自动配置，可手动创建 PostgresMlEmbeddingModel。为此需在项目的 Maven pom.xml 文件中添加 spring-ai-postgresml 依赖：

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

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

dependencies {
    implementation 'org.springframework.ai:spring-ai-postgresml'
}

请参考 “依赖管理” 章节将 Spring AI BOM 添加到你的构建文件。

接下来，创建 PostgresMlEmbeddingModel 实例并使用它计算两个输入文本之间的相似度：

var jdbcTemplate = new JdbcTemplate(dataSource); // your posgresml data source

PostgresMlEmbeddingModel embeddingModel = new PostgresMlEmbeddingModel(this.jdbcTemplate,
        PostgresMlEmbeddingOptions.builder()
            .transformer("distilbert-base-uncased") // huggingface transformer model name.
            .vectorType(VectorType.PG_VECTOR) //vector type in PostgreSQL.
            .kwargs(Map.of("device", "cpu")) // optional arguments.
            .metadataMode(MetadataMode.EMBED) // Document metadata mode.
            .build());

embeddingModel.afterPropertiesSet(); // initialize the jdbc template and database.

EmbeddingResponse embeddingResponse = this.embeddingModel
	.embedForResponse(List.of("Hello World", "World is big and salvation is near"));

手动创建时，必须在设置属性后、使用客户端前调用 afterPropertiesSet() 方法。更推荐（且便捷）的方式是将 PostgresMlEmbeddingModel 声明为 @Bean，如此便无需手动调用 afterPropertiesSet()：

@Bean
public EmbeddingModel embeddingModel(JdbcTemplate jdbcTemplate) {
    return new PostgresMlEmbeddingModel(jdbcTemplate,
        PostgresMlEmbeddingOptions.builder()
             ....
            .build());
}