このバージョンはまだ開発中であり、まだ安定しているとは見なされていません。最新の安定バージョンについては、Spring AI 2.0.1 を使用してください!

Milvus

Milvus (英語) は、データサイエンスと機械学習のフィールドで大きな注目を集めているオープンソースのベクトルデータベースです。その際立った機能の 1 つは、ベクトルのインデックス作成とクエリの強力なサポートにあります。Milvus は、検索プロセスを高速化するために最先端のアルゴリズムを採用しており、大規模なデータセットを処理する場合でも、同様のベクトルを非常に効率的に取得できます。

前提条件

依存関係

Spring AI の自動構成およびスターターモジュールのアーティファクト名に大幅な変更がありました。詳細については、アップグレードノートを参照してください。

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

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

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

dependencies {
    implementation 'org.springframework.ai:spring-ai-starter-vector-store-milvus'
}
Spring AI BOM をビルドファイルに追加するには、依存関係管理セクションを参照してください。Maven Central リポジトリおよび / または Snapshot リポジトリをビルドファイルに追加するには、アーティファクトリポジトリセクションを参照してください。

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

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

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

MilvusVectorStore に接続して構成するには、インスタンスのアクセスの詳細を指定する必要があります。シンプルな構成は、Spring Boot の application.yml 経由で提供できます。

spring:
	ai:
		vectorstore:
			milvus:
				client:
					host: "localhost"
					port: 19530
					username: "root"
					password: "milvus"
				databaseName: "default"
				collectionName: "vector_store"
				embeddingDimension: 1536
				indexType: IVF_FLAT
				metricType: COSINE
デフォルト値と構成オプションについては、構成パラメーターのリストを確認してください。

これで、Milvus ベクトルストアをアプリケーションに自動接続して使用できるようになりました。

@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 Milvus Vector Store
vectorStore.add(documents);

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

手動構成

Spring Boot 自動構成を使用する代わりに、MilvusVectorStore を手動で構成できます。次の依存関係をプロジェクトに追加するには、次の手順を実行します。

<dependency>
	<groupId>org.springframework.ai</groupId>
	<artifactId>spring-ai-milvus-store</artifactId>
</dependency>
依存関係管理のセクションを参照して、Spring AI の部品表をビルドファイルに追加してください。

アプリケーションで MilvusVectorStore を構成するには、次のセットアップを使用できます。

	@Bean
	public VectorStore vectorStore(MilvusServiceClient milvusClient, EmbeddingModel embeddingModel) {
		return MilvusVectorStore.builder(milvusClient, embeddingModel)
				.collectionName("test_vector_store")
				.databaseName("default")
				.indexType(IndexType.IVF_FLAT)
				.metricType(MetricType.COSINE)
				.batchingStrategy(new TokenCountBatchingStrategy())
				.initializeSchema(true)
				.build();
	}

	@Bean
	public MilvusServiceClient milvusClient() {
		return new MilvusServiceClient(ConnectParam.newBuilder()
			.withAuthorization("minioadmin", "minioadmin")
			.withUri(milvusContainer.getEndpoint())
			.build());
	}

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

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

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

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());
これらのフィルター式は、同等の Milvus フィルターに変換されます。
検索結果からメタデータを読み込む際、数値は Gson を使用して逆直列化されます。整数値は Long 型、小数値は Double 型として返されます。整数メタデータフィールドを直接 Double 型にキャストするコードは、代わりに Long 型または上位型である Number 型を使用するように更新する必要があります。

MilvusSearchRequest の使用

MilvusSearchRequest は SearchRequest を継承し、ネイティブ式や検索パラメーター JSON などの Milvus 固有の検索パラメーターを使用できるようにします。

MilvusSearchRequest request = MilvusSearchRequest.milvusBuilder()
    .query("sample query")
    .topK(5)
    .similarityThreshold(0.7)
    .nativeExpression("metadata[\"age\"] > 30") // Overrides filterExpression if both are set
    .filterExpression("age <= 30") // Ignored if nativeExpression is set
    .searchParamsJson("{\"nprobe\":128}")
    .build();
List results = vectorStore.similaritySearch(request);

これにより、Milvus 固有の検索機能を使用する際の柔軟性が向上します。

MilvusSearchRequest における nativeExpression と searchParamsJson の重要性

これら 2 つのパラメーターは、Milvus 検索の精度を高め、最適なクエリパフォーマンスを保証します。

nativeExpression: Milvus のネイティブフィルタリング式を使用して追加のフィルタリング機能を有効にします。Milvus フィルタリング (英語)

例:

MilvusSearchRequest request = MilvusSearchRequest.milvusBuilder()
    .query("sample query")
    .topK(5)
    .nativeExpression("metadata['category'] == 'science'")
    .build();

searchParamsJson: IVF_FLAT、Milvus' デフォルトインデックスを使用する場合の検索動作の調整に不可欠です。Milvus ベクトルインデックス (英語)

デフォルトでは、正確な結果を得るには、IVF_FLAT に nprobe を設定する必要があります。指定しない場合、nprobe はデフォルトで 1 に設定され、再現率が低下したり、検索結果がゼロになったりする可能性があります。

例:

MilvusSearchRequest request = MilvusSearchRequest.milvusBuilder()
    .query("sample query")
    .topK(5)
    .searchParamsJson("{\"nprobe\":128}")
    .build();

nativeExpression を使用すると高度なフィルタリングが保証され、searchParamsJson を使用すると、デフォルトの nprobe 値が低いために発生する効果のない検索が防止されます。

Milvus VectorStore のプロパティ

Spring Boot 構成で次のプロパティを使用して、Milvus ベクトルストアをカスタマイズできます。

プロパティ 説明 デフォルト値

spring.ai.vectorstore.milvus.database-name

使用する Milvus データベースの名前。

default

spring.ai.vectorstore.milvus.collection-name

Milvus ベクトルを格納するコレクション名

vector_store

spring.ai.vectorstore.milvus.partition-name

既存の Milvus パーティション名。挿入、削除、検索操作の範囲を指定するために使用されます。設定されていない場合、または空白の場合は、Milvus のデフォルト動作が使用されます。

-

spring.ai.vectorstore.milvus.initialize-schema

Milvus のバックエンドを初期化するかどうか

false

spring.ai.vectorstore.milvus.embedding-dimension

Milvus コレクションに格納されるベクトルの次元。

1536

spring.ai.vectorstore.milvus.index-type

Milvus コレクション用に作成されるインデックスの型。

IVF_FLAT

spring.ai.vectorstore.milvus.metric-type

Milvus コレクションに使用するメトリクス型。

COSINE

spring.ai.vectorstore.milvus.index-parameters

Milvus コレクションに使用されるインデックスパラメーター。

{"nlist":1024}

spring.ai.vectorstore.milvus.id-field-name

コレクションの ID フィールド名

doc_id

spring.ai.vectorstore.milvus.auto-id

ID フィールドに自動 ID が使用されているかどうかを示すブールフラグ

false

spring.ai.vectorstore.milvus.content-field-name

コレクションのコンテンツフィールド名

コンテンツ

spring.ai.vectorstore.milvus.metadata-field-name

コレクションのメタデータフィールド名

メタデータ

spring.ai.vectorstore.milvus.embedding-field-name

コレクションの埋め込みフィールド名

埋め込み

spring.ai.vectorstore.milvus.client.host

ホストの名前またはアドレス。

localhost

spring.ai.vectorstore.milvus.client.port

接続ポート。

19530

spring.ai.vectorstore.milvus.client.uri

Milvus インスタンスの URI

-

spring.ai.vectorstore.milvus.client.token

識別および認証の目的でキーとして機能するトークン。

-

spring.ai.vectorstore.milvus.client.connect-timeout-ms

クライアントチャネルの接続タイムアウト値。タイムアウト値はゼロより大きくなければなりません。

10000

spring.ai.vectorstore.milvus.client.keep-alive-time-ms

クライアントチャネルのキープアライブ時間の値。キープアライブ値はゼロより大きくなければなりません。

55000

spring.ai.vectorstore.milvus.client.keep-alive-timeout-ms

クライアントチャネルのキープアライブタイムアウト値。タイムアウト値はゼロより大きくなければなりません。

20000

spring.ai.vectorstore.milvus.client.rpc-deadline-ms

サーバーからの応答を待つ期限。期限を設定すると、ネットワークの変動によって高速 RPC が失敗した場合、クライアントは待機します。期限の値はゼロ以上である必要があります。

0

spring.ai.vectorstore.milvus.client.client-key-path

TLS 双方向認証の client.key パスは、"secure" が true の場合にのみ有効になります。

-

spring.ai.vectorstore.milvus.client.client-pem-path

TLS 双方向認証の client.pem パスは、"secure" が true の場合にのみ有効になります。

-

spring.ai.vectorstore.milvus.client.ca-pem-path

TLS 双方向認証の ca.pem パスは、"secure" が true の場合にのみ有効になります

-

spring.ai.vectorstore.milvus.client.server-pem-path

TLS 一方向認証用の server.pem パス。"secure" が true の場合にのみ有効です。

-

spring.ai.vectorstore.milvus.client.server-name

SSL ホスト名チェックのターゲット名オーバーライドを設定します。"secure" が True の場合にのみ有効になります。注: この値は grpc.ssl_target_name_override に渡されます

-

spring.ai.vectorstore.milvus.client.secure

この接続の認証を保護します。TLS を有効にするには True に設定します。

false

spring.ai.vectorstore.milvus.client.idle-timeout-ms

クライアントチャネルのアイドルタイムアウト値。タイムアウト値はゼロより大きくなければなりません。

24 時間

spring.ai.vectorstore.milvus.client.username

この接続のユーザー名とパスワード。

ルート

spring.ai.vectorstore.milvus.client.password

この接続のパスワード。

ミルバス

Milvus ストアを開始します

src/test/resources/ フォルダー内から次を実行します。

docker-compose up

環境をきれいにするには:

docker-compose down; rm -Rf ./volumes

次に、http://localhost:19530 または管理用のベクトルストアに接続します。http://localhost:9001 (user: minioadmin、パス: minioadmin)

トラブルシューティング

Docker がリソースについて文句を言う場合は、次のコマンドを実行します。

docker system prune --all --force --volumes

ネイティブクライアントへのアクセス

Milvus ベクトルストアの実装は、getNativeClient() メソッドを通じて、基盤となるネイティブ Milvus クライアント (MilvusServiceClient) へのアクセスを提供します。

MilvusVectorStore vectorStore = context.getBean(MilvusVectorStore.class);
Optional<MilvusServiceClient> nativeClient = vectorStore.getNativeClient();

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

ネイティブクライアントを使用すると、VectorStore インターフェースでは公開されない可能性のある Milvus 固有の機能と操作にアクセスできます。