qdrant-vector-search

Qdrant - ベクトル類似検索エンジン

本番環境の RAG とセマンティック検索向けに Rust で記述された高性能ベクトルデータベースです。

Qdrant を使う場面

次のような場合に Qdrant を使用します：

• 低レイテンシが求められる本番環境の RAG システムを構築する
• ハイブリッド検索（ベクトル＋メタデータフィルタリング）が必要である
• シャーディング／レプリケーションによる水平スケーリングが必要である
• データを完全に管理できるオンプレミスのデプロイを希望する
• レコードごとに複数のベクトル（密ベクトル＋疎ベクトル）を保存する必要がある
• リアルタイムのレコメンデーションシステムを構築する

主な機能：

• Rust による実装：メモリ安全で高性能
• 豊富なフィルタリング：検索中に任意のペイロードフィールドでフィルタリング
• 複数のベクトル：ポイントごとに密ベクトル、疎ベクトル、複数の密ベクトルに対応
• 量子化：メモリ効率を高めるスカラー、プロダクト、バイナリ量子化
• 分散構成：Raft コンセンサス、シャーディング、レプリケーション
• REST＋gRPC：両 API で全機能に対応

代わりに次の選択肢を使用します：

• Chroma：より簡単なセットアップ、組み込み用途
• FAISS：最大限の処理速度、研究／バッチ処理
• Pinecone：完全マネージド、運用作業を避けたい場合
• Weaviate：GraphQL を優先する場合、組み込みベクトライザー

クイックスタート

インストール

# Python client
pip install qdrant-client

# Docker (recommended for development)
docker run -p 6333:6333 -p 6334:6334 qdrant/qdrant

# Docker with persistent storage
docker run -p 6333:6333 -p 6334:6334 \
    -v $(pwd)/qdrant_storage:/qdrant/storage \
    qdrant/qdrant

基本的な使い方

from qdrant_client import QdrantClient
from qdrant_client.models import Distance, VectorParams, PointStruct

# Connect to Qdrant
client = QdrantClient(host="localhost", port=6333)

# Create collection
client.create_collection(
    collection_name="documents",
    vectors_config=VectorParams(size=384, distance=Distance.COSINE)
)

# Insert vectors with payload
client.upsert(
    collection_name="documents",
    points=[
        PointStruct(
            id=1,
            vector=[0.1, 0.2, ...],  # 384-dim vector
            payload={"title": "Doc 1", "category": "tech"}
        ),
        PointStruct(
            id=2,
            vector=[0.3, 0.4, ...],
            payload={"title": "Doc 2", "category": "science"}
        )
    ]
)

# Search with filtering
results = client.search(
    collection_name="documents",
    query_vector=[0.15, 0.25, ...],
    query_filter={
        "must": [{"key": "category", "match": {"value": "tech"}}]
    },
    limit=10
)

for point in results:
    print(f"ID: {point.id}, Score: {point.score}, Payload: {point.payload}")

主な概念

ポイント - 基本データ単位

from qdrant_client.models import PointStruct

# Point = ID + Vector(s) + Payload
point = PointStruct(
    id=123,                              # Integer or UUID string
    vector=[0.1, 0.2, 0.3, ...],        # Dense vector
    payload={                            # Arbitrary JSON metadata
        "title": "Document title",
        "category": "tech",
        "timestamp": 1699900000,
        "tags": ["python", "ml"]
    }
)

# Batch upsert (recommended)
client.upsert(
    collection_name="documents",
    points=[point1, point2, point3],
    wait=True  # Wait for indexing
)

コレクション - ベクトルコンテナー

from qdrant_client.models import VectorParams, Distance, HnswConfigDiff

# Create with HNSW configuration
client.create_collection(
    collection_name="documents",
    vectors_config=VectorParams(
        size=384,                        # Vector dimensions
        distance=Distance.COSINE         # COSINE, EUCLID, DOT, MANHATTAN
    ),
    hnsw_config=HnswConfigDiff(
        m=16,                            # Connections per node (default 16)
        ef_construct=100,                # Build-time accuracy (default 100)
        full_scan_threshold=10000        # Switch to brute force below this
    ),
    on_disk_payload=True                 # Store payload on disk
)

# Collection info
info = client.get_collection("documents")
print(f"Points: {info.points_count}, Vectors: {info.vectors_count}")

距離メトリクス

メトリクス	用途	範囲
COSINE	テキスト埋め込み、正規化されたベクトル	0 ～ 2
EUCLID	空間データ、画像特徴量	0 ～ ∞
DOT	レコメンデーション、正規化されていないベクトル	-∞ ～ ∞
MANHATTAN	疎な特徴量、離散データ	0 ～ ∞

検索操作

基本検索

# Simple nearest neighbor search
results = client.search(
    collection_name="documents",
    query_vector=[0.1, 0.2, ...],
    limit=10,
    with_payload=True,
    with_vectors=False  # Don't return vectors (faster)
)

フィルター付き検索

from qdrant_client.models import Filter, FieldCondition, MatchValue, Range

# Complex filtering
results = client.search(
    collection_name="documents",
    query_vector=query_embedding,
    query_filter=Filter(
        must=[
            FieldCondition(key="category", match=MatchValue(value="tech")),
            FieldCondition(key="timestamp", range=Range(gte=1699000000))
        ],
        must_not=[
            FieldCondition(key="status", match=MatchValue(value="archived"))
        ]
    ),
    limit=10
)

# Shorthand filter syntax
results = client.search(
    collection_name="documents",
    query_vector=query_embedding,
    query_filter={
        "must": [
            {"key": "category", "match": {"value": "tech"}},
            {"key": "price", "range": {"gte": 10, "lte": 100}}
        ]
    },
    limit=10
)

バッチ検索

from qdrant_client.models import SearchRequest

# Multiple queries in one request
results = client.search_batch(
    collection_name="documents",
    requests=[
        SearchRequest(vector=[0.1, ...], limit=5),
        SearchRequest(vector=[0.2, ...], limit=5, filter={"must": [...]}),
        SearchRequest(vector=[0.3, ...], limit=10)
    ]
)

RAG 連携

詳細、コード例、パラメータ表については、references/rag-integration.md を参照してください。この手順が該当する場合に読みます。

マルチベクトルのサポート

名前付きベクトル（異なる埋め込みモデル）

from qdrant_client.models import VectorParams, Distance

# Collection with multiple vector types
client.create_collection(
    collection_name="hybrid_search",
    vectors_config={
        "dense": VectorParams(size=384, distance=Distance.COSINE),
        "sparse": VectorParams(size=30000, distance=Distance.DOT)
    }
)

# Insert with named vectors
client.upsert(
    collection_name="hybrid_search",
    points=[
        PointStruct(
            id=1,
            vector={
                "dense": dense_embedding,
                "sparse": sparse_embedding
            },
            payload={"text": "document text"}
        )
    ]
)

# Search specific vector
results = client.search(
    collection_name="hybrid_search",
    query_vector=("dense", query_dense),  # Specify which vector
    limit=10
)

疎ベクトル（BM25、SPLADE）

from qdrant_client.models import SparseVectorParams, SparseIndexParams, SparseVector

# Collection with sparse vectors
client.create_collection(
    collection_name="sparse_search",
    vectors_config={},
    sparse_vectors_config={"text": SparseVectorParams(index=SparseIndexParams(on_disk=False))}
)

# Insert sparse vector
client.upsert(
    collection_name="sparse_search",
    points=[PointStruct(id=1, vector={"text": SparseVector(indices=[1, 5, 100], values=[0.5, 0.8, 0.2])}, payload={"text": "document"})]
)

量子化（メモリ最適化）

from qdrant_client.models import ScalarQuantization, ScalarQuantizationConfig, ScalarType

# Scalar quantization (4x memory reduction)
client.create_collection(
    collection_name="quantized",
    vectors_config=VectorParams(size=384, distance=Distance.COSINE),
    quantization_config=ScalarQuantization(
        scalar=ScalarQuantizationConfig(
            type=ScalarType.INT8,
            quantile=0.99,        # Clip outliers
            always_ram=True      # Keep quantized in RAM
        )
    )
)

# Search with rescoring
results = client.search(
    collection_name="quantized",
    query_vector=query,
    search_params={"quantization": {"rescore": True}},  # Rescore top results
    limit=10
)

ペイロードのインデックス作成

from qdrant_client.models import PayloadSchemaType

# Create payload index for faster filtering
client.create_payload_index(
    collection_name="documents",
    field_name="category",
    field_schema=PayloadSchemaType.KEYWORD
)

client.create_payload_index(
    collection_name="documents",
    field_name="timestamp",
    field_schema=PayloadSchemaType.INTEGER
)

# Index types: KEYWORD, INTEGER, FLOAT, GEO, TEXT (full-text), BOOL

本番環境へのデプロイ

Qdrant Cloud

from qdrant_client import QdrantClient

# Connect to Qdrant Cloud
client = QdrantClient(
    url="https://your-cluster.cloud.qdrant.io",
    api_key="your-api-key"
)

パフォーマンスの調整

# Optimize for search speed (higher recall)
client.update_collection(
    collection_name="documents",
    hnsw_config=HnswConfigDiff(ef_construct=200, m=32)
)

# Optimize for indexing speed (bulk loads)
client.update_collection(
    collection_name="documents",
    optimizer_config={"indexing_threshold": 20000}
)

ベストプラクティス

1. バッチ操作 - 効率化のため、バッチの upsert／検索を使用します
2. ペイロードのインデックス作成 - フィルターで使用するフィールドにインデックスを作成します
3. 量子化 - 大規模なコレクション（ベクトル数が 100 万件超）では有効にします
4. シャーディング - ベクトル数が 1,000 万件を超えるコレクションで使用します
5. ディスク上のストレージ - 大きなペイロードでは on_disk_payload を有効にします
6. コネクションプーリング - クライアントインスタンスを再利用します

よくある問題

フィルター付き検索が遅い場合：

# Create payload index for filtered fields
client.create_payload_index(
    collection_name="docs",
    field_name="category",
    field_schema=PayloadSchemaType.KEYWORD
)

メモリ不足の場合：

# Enable quantization and on-disk storage
client.create_collection(
    collection_name="large_collection",
    vectors_config=VectorParams(size=384, distance=Distance.COSINE),
    quantization_config=ScalarQuantization(...),
    on_disk_payload=True
)

接続に関する問題：

# Use timeout and retry
client = QdrantClient(
    host="localhost",
    port=6333,
    timeout=30,
    prefer_grpc=True  # gRPC for better performance
)

参考資料

• 高度な使い方 - 分散モード、ハイブリッド検索、レコメンデーション
• トラブルシューティング - よくある問題、デバッグ、パフォーマンスの調整

リソース

• GitHub: https://github.com/qdrant/qdrant
• ドキュメント: https://qdrant.tech/documentation/
• Python クライアント: https://github.com/qdrant/qdrant-client
• クラウド: https://cloud.qdrant.io
• バージョン: 1.12.0+
• ライセンス: Apache 2.0

エージェントの作業手順

1. 環境を確認します。 コーパス、埋め込みモデル、ベクトルストアのバージョン、およびインデックスの保存先を確認します。
2. 入力を明確にします。 データまたはユーザーから、形式、識別子、パラメーターを確認します。結果に影響する値を推測せず、確認してください。
3. まず小規模に実行します。 小さなサブセットにインデックスを作成し、既知の質問と該当箇所のペアを使って検索をテストします。
4. 上記の手順と参考情報を使って、タスク全体を実行します。
5. 結果を検証します。 ラベル付きデータセットで recall@k を測定し、回答が検索された箇所のみを引用していることを確認します。
6. 報告します。 実行した内容（バージョン、コマンド、パラメーター）、確認した内容、未確定の事項を明記します。

このような場合	対応
検索結果に無関係なチャンクが含まれる	生成器を変更する前に、チャンク分割を見直す、BM25／ハイブリッド検索を追加する、または再ランキングを行います。
これらの手順に記載された関数、フラグ、エンドポイントがインストール済みバージョンに存在しない	インストール済みバージョンのドキュメント（help()、--help、公式ドキュメント）を確認して適切に対応し、ユーザーに伝えます。API を決して捏造しないでください。
必須の入力、識別子、パラメーターが曖昧	ユーザーに確認するか、実行前に仮定を明示します。

インテグリティに関するルール

• 結果、パラメーター、識別子、引用、統計を決して捏造しないでください。実行または検証できない場合は、その旨を明確に伝えてください。
• 回答は検索されたテキストに基づく必要があります。コーパスに回答が含まれていない場合は、その旨を伝えてください。
• ここに記載されたバージョン固有の詳細は古くなっている可能性があるため、インストール済みバージョンの公式ドキュメントで確認してください。
• 費用が発生する操作、共有 GPU やクラウドのクォータを消費する操作、個人データや患者データに触れる操作、または取り消せない操作を行う前に、ユーザーに確認してください。

関連スキル

• pinecone：管理型のサーバーレスベクトルデータベースである Pinecone を、Python クライアントおよび LangChain、LlamaIndex の統合を通じて使用する方法を説明します。
• faiss：密ベクトルの効率的な類似検索とクラスタリングを行うための Facebook のライブラリです。
• chroma：AI アプリケーション向けのオープンソース埋め込みデータベースです。