PostgresML Embeddings

Spring AI 支持 PostgresML 文本嵌入模型。 嵌入是文本的数字表示。它们用于将单词和句子表示为向量，即数字数组。嵌入可用于通过使用距离度量比较数字向量相似性来查找相似的文本，或者它们可以用作其他机器学习模型的输入特征，因为大多数算法不能直接使用文本。 在 PostgresML 内，许多经过预先训练的 LLM 可用于从文本中生成嵌入。您可浏览所有可用的 models 来在 Hugging Face 上找到最佳解决方案。

Add Repositories and BOM

Spring AI 工件发布在 Spring Milestone 和 Snapshot 存储库中。有关将这些存储库添加到你的构建系统的说明，请参阅 Repositories 部分。

为了帮助进行依赖项管理，Spring AI 提供了一个 BOM（物料清单）以确保在整个项目中使用一致版本的 Spring AI。有关将 Spring AI BOM 添加到你的构建系统的说明，请参阅 Dependency Management 部分。

Auto-configuration

Spring AI 为 Azure PostgresML Embedding 客户端提供 Spring Boot 自动配置。要启用它，请将以下依赖项添加到项目的 Maven pom.xml 文件：

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

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

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

  1. 参见 Dependency Management 部分，将 Spring AI BOM 添加到你的构建文件中。

使用 spring.ai.postgresml.embedding.options.* 属性配置你的 PostgresMlEmbeddingClient。链接

Embedding Properties

前缀 spring.ai.postgresml.embedding 是配置 PostgresML 嵌入的 EmbeddingClient 实现的属性前缀。

Property

Description

Default

spring.ai.postgresml.embedding.enabled

Enable PostgresML embedding client.

true

spring.ai.postgresml.embedding.options.transformer

用于嵌入的 Huggingface transformer 模型。

distilbert-base-uncased

spring.ai.postgresml.embedding.options.kwargs

Additional transformer specific options.

empty map

spring.ai.postgresml.embedding.options.vectorType

要用于嵌入的 PostgresML 矢量类型。支持两个选项：PG_ARRAY 和 PG_VECTOR。

PG_ARRAY

spring.ai.postgresml.embedding.options.metadataMode

Document metadata aggregation mode

EMBED

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

EmbeddingOptions

使用 PostgresMlEmbeddingOptions.java 使用选项（例如，使用该模型等）来配置 PostgresMlEmbeddingClient。

在启动时，你可以将 PostgresMlEmbeddingOptions 传递给 PostgresMlEmbeddingClient 构造函数，以配置用于所有嵌入请求的默认选项。

在运行时，可以使用 EmbeddingRequest 中的 PostgresMlEmbeddingOptions 覆盖默认选项。

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

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

Sample Controller (Auto-configuration)

这将创建一个 EmbeddingClient 实现，你可以将其注入到你的类中。这里有一个简单的 @Controller 类的示例，它使用 EmbeddingClient 实现。

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 EmbeddingClient embeddingClient;

    @Autowired
    public EmbeddingController(EmbeddingClient embeddingClient) {
        this.embeddingClient = embeddingClient;
    }

    @GetMapping("/ai/embedding")
    public Map embed(@RequestParam(value = "message", defaultValue = "Tell me a joke") String message) {
        EmbeddingResponse embeddingResponse = this.embeddingClient.embedForResponse(List.of(message));
        return Map.of("embedding", embeddingResponse);
    }
}

Manual configuration

除了使用 Spring Boot 自动配置，你还可以手动创建 PostgresMlEmbeddingClient。为此，将 spring-ai-postgresml 依赖项添加到项目的 Maven pom.xml 文件：

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

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

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

  1. 参见 Dependency Management 部分，将 Spring AI BOM 添加到你的构建文件中。

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

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

PostgresMlEmbeddingClient embeddingClient = new PostgresMlEmbeddingClient(this.jdbcTemplate,
        PostgresMlEmbeddingOptions.builder()
            .withTransformer("distilbert-base-uncased") // huggingface transformer model name.
            .withVectorType(VectorType.PG_VECTOR) //vector type in PostgreSQL.
            .withKwargs(Map.of("device", "cpu")) // optional arguments.
            .withMetadataMode(MetadataMode.EMBED) // Document metadata mode.
            .build());

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

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

手动创建时，必须在设置属性并使用客户端之前调用 afterPropertiesSet()。更方便（也是更推荐的）方式是将 PostgresMlEmbeddingClient 创建为 @Bean。那么您不必手动调用 afterPropertiesSet()：

 
@Bean
public EmbeddingClient embeddingClient(JdbcTemplate jdbcTemplate) {
    return new PostgresMlEmbeddingClient(jdbcTemplate,
        PostgresMlEmbeddingOptions.builder()
             ....
            .build());
}