Qdrant ベクトルデータベース統合

概要

Qdrant は AI ネイティブなベクトルデータベースで、セマンティック検索と類似度検索に使用されます。このスキルは Qdrant を Java アプリケーションと統合するためのパターンを提供し、Spring Boot と LangChain4j の統合に焦点を当てています。

使用する場合

• Spring Boot アプリケーションでセマンティック検索または推奨システムを実装する場合
• Java と LangChain4j を使用した RAG パイプライン
• AI/ML アプリケーション向けのベクトルデータベース統合
• フィルタリングされたクエリを使用した高性能な類似度検索

実装手順

1. Docker で Qdrant をデプロイ

docker run -p 6333:6333 -p 6334:6334 \
    -v "$(pwd)/qdrant_storage:/qdrant/storage:z" \
    qdrant/qdrant

アクセス: REST API は http://localhost:6333、gRPC は http://localhost:6334 です。

2. 依存関係を追加

Maven:

<dependency>
    <groupId>io.qdrant</groupId>
    <artifactId>client</artifactId>
    <version>1.15.0</version>
</dependency>

Gradle:

implementation 'io.qdrant:client:1.15.0'

3. クライアントを初期化

QdrantClient client = new QdrantClient(
    QdrantGrpcClient.newBuilder("localhost").build());

API キー付きのプロダクション環境の場合:

QdrantClient client = new QdrantClient(
    QdrantGrpcClient.newBuilder("localhost", 6334, false)
        .withApiKey("YOUR_API_KEY")
        .build());

4. コレクションを作成

client.createCollectionAsync("search-collection",
    VectorParams.newBuilder()
        .setDistance(Distance.Cosine)
        .setSize(384)
        .build()
).get();

検証: client.getCollectionAsync("search-collection").get() を実行してコレクションが作成されたことを確認します。

5. ベクトルをアップサート

List<PointStruct> points = List.of(
    PointStruct.newBuilder()
        .setId(id(1))
        .setVectors(vectors(0.05f, 0.61f, 0.76f, 0.74f))
        .putAllPayload(Map.of("title", value("Spring Boot Documentation")))
        .build()
);
client.upsertAsync("search-collection", points).get();

検証: client.upsertAsync(...).get() が例外をスローせずに完了することを確認します。

6. ベクトルを検索

List<ScoredPoint> results = client.queryAsync(
    QueryPoints.newBuilder()
        .setCollectionName("search-collection")
        .setLimit(5)
        .setQuery(nearest(0.2f, 0.1f, 0.9f, 0.7f))
        .build()
).get();

フィルタリングされた検索:

List<ScoredPoint> results = client.searchAsync(
    SearchPoints.newBuilder()
        .setCollectionName("search-collection")
        .addAllVector(List.of(0.62f, 0.12f, 0.53f, 0.12f))
        .setFilter(Filter.newBuilder()
            .addMust(range("category", Range.newBuilder().setEq("docs").build()))
            .build())
        .setLimit(5)
        .build()).get();

LangChain4j 統合

RAG パイプラインの場合は、LangChain4j の高水準抽象化を使用してください:

EmbeddingStore<TextSegment> embeddingStore = QdrantEmbeddingStore.builder()
    .collectionName("rag-collection")
    .host("localhost")
    .port(6334)
    .apiKey("YOUR_API_KEY")
    .build();

LangChain4j を使用した Spring Boot 設定:

@Bean
public EmbeddingStore<TextSegment> embeddingStore() {
    return QdrantEmbeddingStore.builder()
        .collectionName("rag-collection")
        .host(host)
        .port(port)
        .build();
}

@Bean
public EmbeddingModel embeddingModel() {
    return new AllMiniLmL6V2EmbeddingModel();
}

Spring Boot 統合

設定を通じてクライアントをインジェクト:

@Configuration
public class QdrantConfig {
    @Value("${qdrant.host:localhost}")
    private String host;

    @Value("${qdrant.port:6334}")
    private int port;

    @Bean
    public QdrantClient qdrantClient() {
        return new QdrantClient(
            QdrantGrpcClient.newBuilder(host, port, false).build());
    }
}

例

REST 検索エンドポイント

@RestController
@RequestMapping("/api/search")
public class SearchController {
    private final VectorSearchService searchService;

    public SearchController(VectorSearchService searchService) {
        this.searchService = searchService;
    }

    @GetMapping
    public List<ScoredPoint> search(@RequestParam String query) {
        List<Float> queryVector = embeddingModel.embed(query).content().vectorAsList();
        return searchService.search("documents", queryVector);
    }
}

ベストプラクティス

• 距離メトリック: 正規化されたテキスト埋め込みの場合はコサイン距離、正規化されていない場合はユークリッド距離を使用してください。
• バッチアップサート: 個別のポイント挿入よりもバッチ操作を使用してください。
• 接続プーリング: 高スループットのプロダクションワークロードの場合は接続プーリングを設定してください。
• エラーハンドリング: 非同期操作を try/catch で包み、ExecutionException/InterruptedException に対応してください。
• API キー: 環境変数または Spring 設定に保存し、ハードコードしないでください。

高度なパターン

マルチテナントストレージ

public void upsertForTenant(String tenantId, List<PointStruct> points) {
    String collectionName = "tenant_" + tenantId + "_documents";
    client.upsertAsync(collectionName, points).get();
}

プロダクション向け Docker Compose

services:
  qdrant:
    image: qdrant/qdrant:v1.7.0
    ports:
      - "6333:6333"
      - "6334:6334"
    volumes:
      - qdrant_storage:/qdrant/storage

リファレンス

• Qdrant API リファレンス — 完全なクライアント API ドキュメント
• 完全な Spring Boot の例 — 完全なアプリケーション実装
• Qdrant ドキュメント
• LangChain4j ドキュメント

制約と警告

• ベクトル次元は埋め込みモデルと正確に一致する必要があります。次元が一致しないとアップサートエラーが発生します。
• 入力検証: 取り込み前にすべてのドキュメント内容をサニタイズしてください。信頼されていないペイロードはプロンプトインジェクション攻撃を含む可能性があります。
• コンテンツフィルタリング: 取得したドキュメントを LLM に渡す前にコンテンツフィルタリングを適用してください。
• 大規模なコレクションは受け入れ可能な検索パフォーマンスのために適切なインデックスが必要です。
• プロダクション環境では gRPC API (ポート 6334) を使用してください。REST API (ポート 6333) はデバッグのみに使用してください。
• コレクションの再作成はすべてのデータを削除します。プロダクション環境ではバックアップ戦略を実装してください。