grepai-storage-qdrant

Qdrant を使用した GrepAI ストレージ

このスキルでは、高性能なベクトル検索を実現するために、GrepAI のストレージバックエンドとして Qdrant を使用する方法を説明します。

このスキルを使用する場面

• 可能な限り高速な検索パフォーマンスが必要な場合
• 非常に大規模なコードベース（50K 以上のファイル）を扱う場合
• すでに Qdrant インフラストラクチャを使用している場合
• 高度なベクトル検索機能を利用したい場合

Qdrant とは？

Qdrant は、次の機能を提供する、ベクトル検索専用に構築されたベクトルデータベースです。

• ⚡ 非常に高速なベクトル類似検索
• 📏 優れたスケーラビリティ
• 🔧 高度なフィルタリング機能
• 🐳 簡単な Docker デプロイ

前提条件

1. Qdrant サーバーが稼働していること
2. Qdrant へのネットワークアクセスがあること

メリット

メリット	説明
⚡ パフォーマンス	最速のベクトル検索
📏 スケーラビリティ	数百万のベクトルを処理
🔍 高度な機能	フィルタリング、ペイロード、シャーディング
🐳 簡単なデプロイ	Docker 対応
☁️ クラウドオプション	Qdrant Cloud を利用可能

Qdrant のセットアップ

オプション 1：Docker（推奨）

# Run Qdrant with persistent storage
docker run -d \
  --name grepai-qdrant \
  -p 6333:6333 \
  -p 6334:6334 \
  -v qdrant_storage:/qdrant/storage \
  qdrant/qdrant

ポート：

• 6333：REST API
• 6334：gRPC API（GrepAI が使用）

オプション 2：Docker Compose

# docker-compose.yml
version: '3.8'
services:
  qdrant:
    image: qdrant/qdrant
    ports:
      - "6333:6333"
      - "6334:6334"
    volumes:
      - qdrant_storage:/qdrant/storage
    environment:
      - QDRANT__SERVICE__GRPC_PORT=6334

volumes:
  qdrant_storage:

docker-compose up -d

オプション 3：Qdrant Cloud

1. cloud.qdrant.io でサインアップします
2. クラスターを作成します
3. エンドポイントと API キーを取得します

設定

基本設定（ローカル）

# .grepai/config.yaml
store:
  backend: qdrant
  qdrant:
    endpoint: localhost
    port: 6334

TLS を使用する場合（本番環境）

store:
  backend: qdrant
  qdrant:
    endpoint: qdrant.company.com
    port: 6334
    use_tls: true

API キーを使用する場合（Qdrant Cloud）

store:
  backend: qdrant
  qdrant:
    endpoint: your-cluster.aws.cloud.qdrant.io
    port: 6334
    use_tls: true
    api_key: ${QDRANT_API_KEY}

環境変数を設定します：

export QDRANT_API_KEY="your-api-key"

設定オプション

オプション	デフォルト	説明
endpoint	localhost	Qdrant サーバーのホスト名
port	6334	gRPC ポート
use_tls	false	TLS 暗号化を有効にする
api_key	なし	認証キー

セットアップの確認

Qdrant が稼働していることを確認する

# REST API health check
curl http://localhost:6333/health

# Expected: {"status":"ok"}

コレクションを確認する（インデックス作成後）

# List collections
curl http://localhost:6333/collections

# Get collection info
curl http://localhost:6333/collections/grepai

GrepAI から確認する

grepai status

# Should show Qdrant backend info

Qdrant ダッシュボード

http://localhost:6333/dashboard でウェブダッシュボードにアクセスできます。

• コレクションを表示する
• ベクトルを参照する
• クエリを実行する
• パフォーマンスを監視する

パフォーマンス特性

検索レイテンシ

コードベースのサイズ	ベクトル数	検索時間
小規模（1K ファイル）	5,000	<10ms
中規模（10K ファイル）	50,000	<20ms
大規模（100K ファイル）	500,000	<50ms

メモリ使用量

Qdrant は高速検索のため、ベクトルをメモリに読み込みます。

ベクトル数	次元数	メモリ
10,000	768	~60 MB
100,000	768	~600 MB
1,000,000	768	~6 GB

高度な設定

Qdrant サーバーの設定

config/production.yaml を作成します。

storage:
  storage_path: /qdrant/storage

service:
  grpc_port: 6334
  http_port: 6333
  max_request_size_mb: 32

optimizers:
  memmap_threshold_kb: 200000
  indexing_threshold_kb: 50000

Docker にマウントします：

docker run -d \
  -v ./config:/qdrant/config \
  -v qdrant_storage:/qdrant/storage \
  qdrant/qdrant

コレクション設定

GrepAI は grepai という名前のコレクションを次の設定で作成します。

• ベクトルサイズ：埋め込みの次元数に一致
• 距離：コサイン類似度
• 大規模データセット向けのディスク上ストレージ

クラスタリング（上級）

非常に大規模なデプロイでは、Qdrant は分散モードをサポートしています。

# qdrant config
cluster:
  enabled: true
  p2p:
    port: 6335

バックアップと復元

スナップショットの作成

# Create snapshot via REST API
curl -X POST 'http://localhost:6333/collections/grepai/snapshots'

スナップショットの復元

# Restore from snapshot
curl -X PUT 'http://localhost:6333/collections/grepai/snapshots/recover' \
  -H 'Content-Type: application/json' \
  -d '{"location": "/path/to/snapshot"}'

GOB からの移行

1. Qdrant を起動します：

docker run -d --name qdrant -p 6333:6333 -p 6334:6334 qdrant/qdrant

2. 設定を更新します：

store:
  backend: qdrant
  qdrant:
    endpoint: localhost
    port: 6334

3. 古いインデックスを削除します：

rm .grepai/index.gob

4. インデックスを再作成します：

grepai watch

PostgreSQL からの移行

1. Qdrant を起動します
2. Qdrant を使用するように設定を更新します
3. インデックスを再作成します（埋め込みを再生成する必要があります）

よくある問題

❌ 問題： 接続が拒否される
✅ 解決策： Qdrant が稼働していることを確認します：

docker ps | grep qdrant
docker start grepai-qdrant

❌ 問題： gRPC 接続に失敗する
✅ 解決策： ポート 6334 が公開されていることを確認します：

docker run -p 6334:6334 ...

❌ 問題： 認証に失敗する
✅ 解決策： API キーを確認します：

echo $QDRANT_API_KEY

❌ 問題： メモリ不足
✅ 解決策：

• Qdrant の設定でディスク上ストレージを有効にする
• Docker のメモリ上限を引き上げる
• マネージドスケーリングには Qdrant Cloud を使用する

❌ 問題： 初回のインデックス作成が遅い
✅ 解決策： これは正常です。Qdrant はバックグラウンドで最適化を行います。インデックス作成の完了後は検索が高速になります。

Qdrant と PostgreSQL の比較

機能	Qdrant	PostgreSQL
検索速度	⚡⚡⚡	⚡⚡
セットアップの複雑さ	簡単（Docker）	中程度
SQL クエリ	❌	✅
スケーラビリティ	優れている	良好
メモリ効率	優れている	良好
チームの習熟度	低い	高い

推奨事項： 大規模なコードベースや最大限のパフォーマンスが必要な場合は、Qdrant を使用してください。SQL との連携が必要な場合や、チームが PostgreSQL に慣れている場合は、PostgreSQL を使用してください。

ベストプラクティス

1. 永続ボリュームを使用する： /qdrant/storage をマウントします
2. 本番環境では TLS を有効にする： use_tls: true を設定します
3. API キーを保護する： 環境変数を使用します
4. メモリを監視する： ベクトル検索はメモリを大量に消費します
5. 定期的にスナップショットを作成する： 大きな変更の前にバックアップします

出力形式

Qdrant のストレージ状態：

✅ Qdrant Storage Configured

   Backend: Qdrant
   Endpoint: localhost:6334
   TLS: disabled
   Collection: grepai

   Contents:
   - Files: 5,000
   - Vectors: 25,000
   - Dimensions: 768

   Performance:
   - Connection: OK
   - Indexed: Yes
   - Search latency: ~15ms