跳到主要内容

Milvus

Milvus はオープンソースのベクトルデータベースです。LangChain4j は、これを EmbeddingStore として使用し、埋め込みを永続化して類似度検索を実行できます。

2 つの Milvus モジュール​

現在、Milvus 連携モジュールは 2 つ あります。これらは独立しており、併用できます。

モジュールMilvus Java SDK クライアント API機能ステータス
langchain4j-milvusMilvusServiceClient(v1 API)密ベクトル検索レガシー。古い v1 クライアント API をベースに構築されています。
langchain4j-milvus-v2MilvusClientV2(v2 API)密 + 疎 + ハイブリッド 検索(組み込み BM25 を含む)現行。新規プロジェクトに推奨されます。
暫定的な命名 — LangChain4j 2.0 で変更されます

-v2 サフィックスは、Milvus Java SDK の MilvusClientV2 API を指しており、このモジュールや Milvus サーバーのバージョンを指すものではありません。これは暫定的なものです。

LangChain4j 2.0 では、レガシーの langchain4j-milvus モジュールは 削除 され、langchain4j-milvus-v2 は langchain4j-milvus に名称変更 されます(Maven アーティファクト、...milvus.v2 パッケージ、MilvusV2* クラス名のすべてから v2 が外れます)。

langchain4j-milvus-v2 を今採用する場合、2.0 へアップグレードする際に Maven の 座標、import、クラス名の更新が必要になることに注意してください。移行ガイドは 2.0 のリリースとともに提供されます。

新規プロジェクトでは langchain4j-milvus-v2 を使用してください。


langchain4j-milvus-v2(推奨)​

Milvus Java SDK の MilvusClientV2 API をベースに構築されています。密ベクトル検索、疎ベクトル検索、ハイブリッド (密 + 疎)検索をサポートします。Milvus の組み込み BM25 全文疎ベクトルも含まれます。

Maven 依存関係​

<dependency>
<groupId>dev.langchain4j</groupId>
<artifactId>langchain4j-milvus-v2</artifactId>
<version>1.23.0-beta33</version>
</dependency>

API​

  • MilvusV2EmbeddingStore

基本的な使い方 — 密ベクトル検索​

これは標準的な EmbeddingStore の使い方です。検索モードのデフォルトは VECTOR(密のみ)です。

MilvusV2EmbeddingStore store = MilvusV2EmbeddingStore.builder()
.uri("http://localhost:19530") // or .host("localhost").port(19530)
.collectionName("my_collection")
.dimension(384) // required when a new collection is created
.build();

store.add(embedding, textSegment);

EmbeddingSearchResult<TextSegment> result = store.search(
EmbeddingSearchRequest.builder()
.queryEmbedding(queryEmbedding)
.maxResults(5)
.build());

ハイブリッド検索(密 + 疎)​

ハイブリッド検索は、密ベクトル検索と疎ベクトル検索を組み合わせ、結果をリランカー (デフォルトは Reciprocal Rank Fusion)でマージします。searchMode(HYBRID) で有効にします。

疎ベクトルの生成方法は sparseMode で選択でき、2 通りあります:

  • BM25(デフォルト) — Milvus がテキストから疎ベクトルを自動的に計算します。テキストを渡すだけです。
  • CUSTOM — 疎ベクトルを自分で用意します(例:BGE-M3 モデルから)。

オプション A — 組み込み BM25(テキスト → 疎ベクトル、Milvus が計算)​

MilvusV2EmbeddingStore store = MilvusV2EmbeddingStore.builder()
.uri("http://localhost:19530")
.collectionName("bm25_collection")
.dimension(384)
.searchMode(MilvusV2EmbeddingStore.SearchMode.HYBRID)
.sparseMode(MilvusV2EmbeddingStore.MilvusSparseMode.BM25) // default
.build();

// Insert: only dense embeddings are needed; Milvus builds the BM25 sparse index from the text.
store.addAll(ids, denseEmbeddings, textSegments);

// Search: provide the dense query embedding and the query text (used for BM25).
MilvusV2EmbeddingSearchRequest request = MilvusV2EmbeddingSearchRequest.milvusBuilder()
.queryEmbedding(queryDenseEmbedding)
.query("full-text keywords here")
.maxResults(10)
.build();

EmbeddingSearchResult<TextSegment> result = store.search(request);

オプション B — カスタム疎ベクトル(例:BGE-M3)​

MilvusV2EmbeddingStore store = MilvusV2EmbeddingStore.builder()
.uri("http://localhost:19530")
.collectionName("hybrid_collection")
.dimension(384)
.searchMode(MilvusV2EmbeddingStore.SearchMode.HYBRID)
.sparseMode(MilvusV2EmbeddingStore.MilvusSparseMode.CUSTOM) // you provide sparse vectors
.build();

// Insert both dense and sparse embeddings.
List<SparseEmbedding> sparseEmbeddings = List.of(
new SparseEmbedding(new long[]{1L, 42L, 300L}, new float[]{0.8f, 0.5f, 0.3f}),
new SparseEmbedding(new long[]{7L, 99L}, new float[]{0.6f, 0.4f}));
store.addAllHybrid(ids, denseEmbeddings, sparseEmbeddings, textSegments);

// Search with a dense query embedding and a sparse query embedding.
MilvusV2EmbeddingSearchRequest request = MilvusV2EmbeddingSearchRequest.milvusBuilder()
.queryEmbedding(queryDenseEmbedding)
.sparseEmbedding(querySparseEmbedding)
.maxResults(10)
.build();

EmbeddingSearchResult<TextSegment> result = store.search(request);
备注

検索モードは コレクションスキーマ のプロパティであり、ストア(およびコレクション)の作成時に一度だけ設定されます。 HYBRID コレクションには密ベクトルフィールドと疎ベクトルフィールドの両方があり、VECTOR コレクションには 密フィールドのみがあります。 両者は互換性がなく、モードを切り替えるには新しいコレクションが必要です。

Zilliz Cloud への接続​

MilvusV2EmbeddingStore store = MilvusV2EmbeddingStore.builder()
.uri("https://xxx.api.gcp-us-west1.zillizcloud.com")
.token("your-api-key")
.collectionName("my_collection")
.dimension(384)
.build();

.milvusClient(client) を使って、独自の MilvusClientV2 インスタンスを渡すこともできます。

互換性​

  • Milvus Server 2.5.x 以降 を推奨します(BM25 全文検索には 2.5 以上、ハイブリッド検索には 2.4 以上が必要です)。
  • 統合テストは、Milvus 2.6 および 3.x に対して毎晩実行されています。
  • ストアは作成時に Milvus サーバーのバージョンを一度だけ読み取ります。Milvus サーバーを新しいメジャーバージョンにアップグレードした後は、アプリケーションを再起動してください。
  • Java 17 以上

langchain4j-milvus(レガシー)​

Milvus Java SDK の古い MilvusServiceClient(v1)API をベースに構築されています。密ベクトル検索のみをサポートします。LangChain4j 2.0 で削除される予定です (上記の注記を参照)。新規プロジェクトでは langchain4j-milvus-v2 を優先してください。

Maven 依存関係​

<dependency>
<groupId>dev.langchain4j</groupId>
<artifactId>langchain4j-milvus</artifactId>
<version>1.23.0-beta33</version>
</dependency>

API​

  • MilvusEmbeddingStore

作成方法​

MilvusEmbeddingStore を作成する方法は 2 つあります:

  1. ホスト、ポート、認証情報から、ストアが内部で MilvusServiceClient を作成する方法:
MilvusEmbeddingStore store = MilvusEmbeddingStore.builder()
.host("localhost") // Host for Milvus instance
.port(19530) // Port for Milvus instance
.collectionName("example_collection") // Name of the collection
.dimension(128) // Dimension of vectors
.indexType(IndexType.FLAT) // Index type
.metricType(MetricType.COSINE) // Metric type
.username("username") // Username for Milvus
.password("password") // Password for Milvus
.consistencyLevel(ConsistencyLevelEnum.EVENTUALLY) // Consistency level
.autoFlushOnInsert(true) // Auto flush after insert
.idFieldName("id") // ID field name
.textFieldName("text") // Text field name
.metadataFieldName("metadata") // Metadata field name
.vectorFieldName("vector") // Vector field name
.build();
  1. 既存の MilvusServiceClient を渡す方法:
// Set up a custom MilvusServiceClient
MilvusServiceClient customMilvusClient = new MilvusServiceClient(
ConnectParam.newBuilder()
.withHost("localhost")
.withPort(19530)
.build()
);

// Use the custom client in the builder
MilvusEmbeddingStore store = MilvusEmbeddingStore.builder()
.milvusClient(customMilvusClient) // Use an existing Milvus client
.collectionName("example_collection") // Name of the collection
.dimension(128) // Dimension of vectors
.indexType(IndexType.FLAT) // Index type
.metricType(MetricType.COSINE) // Metric type
.consistencyLevel(ConsistencyLevelEnum.EVENTUALLY) // Consistency level
.autoFlushOnInsert(true) // Auto flush after insert
.idFieldName("id") // ID field name
.textFieldName("text") // Text field name
.metadataFieldName("metadata") // Metadata field name
.vectorFieldName("vector") // Vector field name
.build();

互換性​

  • ストアは作成時に Milvus サーバーのバージョンを一度だけ読み取ります。Milvus サーバーを新しいメジャーバージョンにアップグレードした後は、アプリケーションを再起動してください。

例​