PGvector

Deepseek 3.2 中英对照 PGvector

本节将指导您设置PGvector VectorStore，用于存储文档嵌入并执行相似性搜索。

PGvector 是一个为 PostgreSQL 设计的开源扩展，支持存储和检索机器学习生成的嵌入向量。它提供多种功能，让用户既能进行精确最近邻搜索，也能进行近似最近邻搜索。该扩展旨在与 PostgreSQL 的其他特性（包括索引和查询）无缝协作。

前提条件

首先，你需要访问一个启用了 vector、hstore 和 uuid-ossp 扩展的 PostgreSQL 实例。

:::提示
你可以通过Docker Compose或Testcontainers以 Spring Boot 开发服务的形式运行 PGvector 数据库。或者，设置本地 Postgres/PGVector附录展示了如何使用 Docker 容器在本地设置数据库。
:::

当启用明确的模式初始化功能启动时，PgVectorStore将尝试安装所需的数据库扩展，并在不存在的情况下创建带有索引的必需vector_store表。

或者，你也可以手动完成，操作如下：

CREATE EXTENSION IF NOT EXISTS vector;
CREATE EXTENSION IF NOT EXISTS hstore;
CREATE EXTENSION IF NOT EXISTS "uuid-ossp";

CREATE TABLE IF NOT EXISTS vector_store (
	id uuid DEFAULT uuid_generate_v4() PRIMARY KEY,
	content text,
	metadata json,
	embedding vector(1536) // 1536 is the default embedding dimension
);

CREATE INDEX ON vector_store USING HNSW (embedding vector_cosine_ops);

:::提示
如果你使用的是不同的维度，请将 1536 替换为实际的嵌入维度。PGvector 的 HNSW 索引最多支持 2000 维。
:::

接下来，如果需要的话，还需要一个 EmbeddingModel 的 API 密钥，用于生成由 PgVectorStore 存储的嵌入向量。

自动配置

备注

Spring AI 的自动配置和 starter 模块的 artifact 名称发生了重大变化。更多信息请参阅 升级说明。

然后向你的项目中添加 PgVectorStore 启动器依赖：

<dependency>
	<groupId>org.springframework.ai</groupId>
	<artifactId>spring-ai-starter-vector-store-pgvector</artifactId>
</dependency>

或将其添加到您的Gradle build.gradle 构建文件中。

dependencies {
    implementation 'org.springframework.ai:spring-ai-starter-vector-store-pgvector'
}

向量存储实现可以为您初始化所需的模式，但您必须通过在适当的构造函数中指定 initializeSchema 布尔值，或在 application.properties 文件中设置 …​initialize-schema=true 来选择启用此功能。

:::注意
这是一个破坏性变更！在 Spring AI 的早期版本中，默认会自动执行此模式初始化。
:::

向量存储还需要一个 EmbeddingModel 实例来计算文档的嵌入向量。你可以从现有的 嵌入模型实现 中选择一个。

例如，要使用 OpenAI EmbeddingModel，请将以下依赖项添加到你的项目中：

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

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

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

提示

请参考 依赖管理 部分，将 Spring AI BOM 添加到您的构建文件中。参考 制品仓库 部分，将 Maven Central 和/或 Snapshot 仓库添加到您的构建文件中。

要连接和配置 PgVectorStore，你需要提供实例的访问详情。可以通过 Spring Boot 的 application.yml 文件提供一个简单的配置。

spring:
  datasource:
    url: jdbc:postgresql://localhost:5432/postgres
    username: postgres
    password: postgres
  ai:
	vectorstore:
	  pgvector:
		index-type: HNSW
		distance-type: COSINE_DISTANCE
		dimensions: 1536
		max-document-batch-size: 10000 # Optional: Maximum number of documents per batch

提示

如果您通过 Docker Compose 或 Testcontainers 将 PGvector 作为 Spring Boot 开发服务运行，则无需配置 URL、用户名和密码，因为 Spring Boot 会自动配置这些信息。

提示

请查阅配置参数列表以了解默认值和配置选项。

现在你可以在你的应用程序中自动连接 VectorStore 并使用它

@Autowired VectorStore vectorStore;

// ...

List<Document> documents = List.of(
    new Document("Spring AI rocks!! Spring AI rocks!! Spring AI rocks!! Spring AI rocks!! Spring AI rocks!!", Map.of("meta1", "meta1")),
    new Document("The World is Big and Salvation Lurks Around the Corner"),
    new Document("You walk forward facing the past and you turn back toward the future.", Map.of("meta2", "meta2")));

// Add the documents to PGVector
vectorStore.add(documents);

// Retrieve documents similar to a query
List<Document> results = this.vectorStore.similaritySearch(SearchRequest.builder().query("Spring").topK(5).build());

配置属性

您可以在 Spring Boot 配置中使用以下属性来自定义 PGVector 向量存储。

属性	描述	默认值
spring.ai.vectorstore.pgvector.index-type	最近邻搜索索引类型。选项为 NONE - 精确最近邻搜索，IVFFlat - 索引将向量划分为列表，然后搜索最接近查询向量的那些列表的子集。与 HNSW 相比，其构建时间更快，内存使用更少，但查询性能较低（在速度-召回率权衡方面）。HNSW - 创建多层图。与 IVFFlat 相比，其构建时间更慢，内存使用更多，但查询性能更好（在速度-召回率权衡方面）。它没有像 IVFFlat 那样的训练步骤，因此可以在表没有任何数据的情况下创建索引。	HNSW
spring.ai.vectorstore.pgvector.distance-type	搜索距离类型。默认为 COSINE_DISTANCE。但如果向量已归一化到长度 1，则可以使用 EUCLIDEAN_DISTANCE 或 NEGATIVE_INNER_PRODUCT 以获得最佳性能。	COSINE_DISTANCE
spring.ai.vectorstore.pgvector.dimensions	嵌入维度。如果未显式指定，PgVectorStore 将从提供的 EmbeddingModel 检索维度。维度在创建表时设置到嵌入列上。如果更改维度，您也必须重新创建 vector_store 表。	-
spring.ai.vectorstore.pgvector.remove-existing-vector-store-table	在启动时删除现有的 vector_store 表。	false
spring.ai.vectorstore.pgvector.initialize-schema	是否初始化所需的模式	false
spring.ai.vectorstore.pgvector.schema-name	向量存储模式名称	public
spring.ai.vectorstore.pgvector.table-name	向量存储表名称	vector_store
spring.ai.vectorstore.pgvector.schema-validation	启用模式和表名验证，以确保它们是有效且现有的对象。	false
spring.ai.vectorstore.pgvector.max-document-batch-size	单个批次中要处理的最大文档数。	10000

:::提示
如果您配置了自定义模式（schema）和/或表名，建议通过设置 spring.ai.vectorstore.pgvector.schema-validation=true 来启用模式验证。这可以确保名称的正确性，并降低 SQL 注入攻击的风险。
:::

元数据过滤

你可以利用通用的、可移植的元数据过滤器与 PgVector 存储一起使用。

例如，您可以使用文本表达式语言：

vectorStore.similaritySearch(
    SearchRequest.builder()
    .query("The World")
    .topK(TOP_K)
    .similarityThreshold(SIMILARITY_THRESHOLD)
    .filterExpression("author in ['john', 'jill'] && article_type == 'blog'").build());

或者通过 Filter.Expression DSL 以编程方式实现：

FilterExpressionBuilder b = new FilterExpressionBuilder();

vectorStore.similaritySearch(SearchRequest.builder()
    .query("The World")
    .topK(TOP_K)
    .similarityThreshold(SIMILARITY_THRESHOLD)
    .filterExpression(b.and(
        b.in("author","john", "jill"),
        b.eq("article_type", "blog")).build()).build());

备注

这些筛选表达式会被转换为 PostgreSQL JSON 路径表达式，以实现高效的元数据过滤。

手动配置

若不使用 Spring Boot 的自动配置，你也可以手动配置 PgVectorStore。为此，你需要将 PostgreSQL 连接和 JdbcTemplate 的自动配置依赖添加到你的项目中：

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

<dependency>
	<groupId>org.postgresql</groupId>
	<artifactId>postgresql</artifactId>
	<scope>runtime</scope>
</dependency>

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

提示

请参考 依赖管理 章节，将 Spring AI BOM 添加到您的构建文件中。

要在您的应用程序中配置 PgVector，可以使用以下设置：

@Bean
public VectorStore vectorStore(JdbcTemplate jdbcTemplate, EmbeddingModel embeddingModel) {
    return PgVectorStore.builder(jdbcTemplate, embeddingModel)
        .dimensions(1536)                    // Optional: defaults to model dimensions or 1536
        .distanceType(COSINE_DISTANCE)       // Optional: defaults to COSINE_DISTANCE
        .indexType(HNSW)                     // Optional: defaults to HNSW
        .initializeSchema(true)              // Optional: defaults to false
        .schemaName("public")                // Optional: defaults to "public"
        .vectorTableName("vector_store")     // Optional: defaults to "vector_store"
        .maxDocumentBatchSize(10000)         // Optional: defaults to 10000
        .build();
}

本地运行 Postgres 和 PGVector 数据库

docker run -it --rm --name postgres -p 5432:5432 -e POSTGRES_USER=postgres -e POSTGRES_PASSWORD=postgres pgvector/pgvector

你可以像这样连接到此服务器：

psql -U postgres -h localhost -p 5432

访问原生客户端

PGVector存储实现通过getNativeClient()方法提供了对底层原生JDBC客户端（JdbcTemplate）的访问：

PgVectorStore vectorStore = context.getBean(PgVectorStore.class);
Optional<JdbcTemplate> nativeClient = vectorStore.getNativeClient();

if (nativeClient.isPresent()) {
    JdbcTemplate jdbc = nativeClient.get();
    // Use the native client for PostgreSQL-specific operations
}

原生客户端让你能够访问可能未通过VectorStore接口暴露的PostgreSQL特有功能与操作。