qdrant

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

概要

Qdrant は、セマンティック検索と類似性検索に対応した、AI ネイティブのベクトルデータベースです。このスキルでは、Spring Boot と LangChain4j の統合に重点を置き、Qdrant を Java アプリケーションに統合するためのパターンを紹介します。

使用する場面

• 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）はデバッグ専用としてください。
• コレクションを再作成するとすべてのデータが削除されます。本番環境ではバックアップ戦略を実装してください。