PGvector

このセクションでは、ドキュメントの埋め込みを保存し、類似性検索を実行するための PGvector VectorStore のセットアップについて説明します。

PGvector [GitHub] (英語) は、機械学習で生成された埋め込みの保存と検索を可能にする PostgreSQL のオープンソース拡張機能です。これは、ユーザーが正確な最近傍と近似の両方を識別できるさまざまな機能を提供します。インデックス作成やクエリなど、他の PostgreSQL 機能とシームレスに連携するように設計されています。

前提条件

まず、vector、hstore、uuid-ossp 拡張機能が有効になっている PostgreSQL インスタンスにアクセスする必要があります。

Docker Compose または Testcontainers を介して、PGvector データベースを Spring Boot 開発サービスとして実行できます。代わりに、付録のローカル Postgres/PGVector セットアップでは、Docker コンテナーを使用して DB をローカルにセットアップする方法を示します。

起動時に、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 次元をサポートします。

次に、必要に応じて、PgVectorStore によって保存された埋め込みを生成するための EmbeddingModel の API キー。

自動構成

次に、PgVectorStore Boot スターターの依存関係をプロジェクトに追加します。

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

または、Gradle build.gradle ビルドファイルに保存します。

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

ベクトルストアの実装では必要なスキーマを初期化できますが、適切なコンストラクターで initializeSchema ブール値を指定するか、application.properties ファイルで …​initialize-schema=true を設定することによってオプトインする必要があります。

これは重大な変更です。Spring AI の以前のバージョンでは、このスキーマの初期化はデフォルトで行われていました。

ベクトルストアでは、ドキュメントの埋め込みを計算するために EmbeddingModel インスタンスも必要です。利用可能な EmbeddingModel の実装のいずれかを選択できます。

例: OpenAI EmbeddingModel を使用するには、プロジェクトに次の依存関係を追加します。

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

または、Gradle build.gradle ビルドファイルに保存します。

dependencies {
    implementation 'org.springframework.ai:spring-ai-openai-spring-boot-starter'
}
Spring AI BOM をビルドファイルに追加するには、"依存関係管理" セクションを参照してください。マイルストーンやスナップショットリポジトリをビルドファイルに追加するには、リポジトリセクションを参照してください。

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
Docker Compose または Testcontainers 経由で PGvector を Spring Boot 開発サービスとして実行する場合、URL、ユーザー名、パスワードは Spring Boot によって自動的に構成されるため、構成する必要はありません。
デフォルト値と構成オプションについては、構成パラメーターのリストを確認してください。

これで、アプリケーションで PgVectorStore をオートワイヤーして使用できるようになります。

@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 = vectorStore.similaritySearch(SearchRequest.query("Spring").withTopK(5));

構成プロパティ

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.schema-validation=true を設定してスキーマ検証を有効にすることを検討してください。これにより、名前の正確性が保証され、SQL インジェクション攻撃のリスクが軽減されます。

メタデータのフィルタリング

PgVector ストアでは、汎用の移植可能なメタデータフィルターを利用できます。

例: 次のいずれかのテキスト式言語を使用できます。

vectorStore.similaritySearch(
    SearchRequest.defaults()
    .withQuery("The World")
    .withTopK(TOP_K)
    .withSimilarityThreshold(SIMILARITY_THRESHOLD)
    .withFilterExpression("author in ['john', 'jill'] && article_type == 'blog'"));

または、Filter.Expression DSL を使用してプログラム的に次のようにします。

FilterExpressionBuilder b = new FilterExpressionBuilder();

vectorStore.similaritySearch(SearchRequest.defaults()
    .withQuery("The World")
    .withTopK(TOP_K)
    .withSimilarityThreshold(SIMILARITY_THRESHOLD)
    .withFilterExpression(b.and(
        b.in("author","john", "jill"),
        b.eq("article_type", "blog")).build()));
これらのフィルター式は、同等の PgVector フィルターに変換されます。

手動構成

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 new PgVectorStore(jdbcTemplate, embeddingModel);
}

Postgres と PGVector DB をローカルで実行する 

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