using-vector-databases

AI アプリケーション向けベクトルデータベース

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

次の機能を実装するときに、このスキルを使用します。

• AI チャットボット向けの RAG（検索拡張生成） システム
• セマンティック検索 機能（キーワードだけでなく、意味に基づく検索）
• 類似性に基づく レコメンデーションシステム
• マルチモーダル AI（テキスト、画像、音声を横断する統合検索）
• ドキュメントの類似性 と重複排除
• プライベートなナレッジベースを対象とした 質問応答

すばやく判断するためのフレームワーク

1. ベクトルデータベースの選択

START: Choosing a Vector Database

EXISTING INFRASTRUCTURE?
├─ Using PostgreSQL already?
│  └─ pgvector (<10M vectors, tight budget)
│      See: references/pgvector.md
│
└─ No existing vector database?
   │
   ├─ OPERATIONAL PREFERENCE?
   │  │
   │  ├─ Zero-ops managed only
   │  │  └─ Pinecone (fully managed, excellent DX)
   │  │      See: references/pinecone.md
   │  │
   │  └─ Flexible (self-hosted or managed)
   │     │
   │     ├─ SCALE: <100M vectors + complex filtering ⭐
   │     │  └─ Qdrant (RECOMMENDED)
   │     │      • Best metadata filtering
   │     │      • Built-in hybrid search (BM25 + Vector)
   │     │      • Self-host: Docker/K8s
   │     │      • Managed: Qdrant Cloud
   │     │      See: references/qdrant.md
   │     │
   │     ├─ SCALE: >100M vectors + GPU acceleration
   │     │  └─ Milvus / Zilliz Cloud
   │     │      See: references/milvus.md
   │     │
   │     ├─ Embedded / No server
   │     │  └─ LanceDB (serverless, edge deployment)
   │     │
   │     └─ Local prototyping
   │        └─ Chroma (simple API, in-memory)

2. 埋め込みモデルの選択

REQUIREMENTS?

├─ Best quality (cost no object)
│  └─ Voyage AI voyage-3 (1024d)
│      • 9.74% better than OpenAI on MTEB
│      • ~$0.12/1M tokens
│      See: references/embedding-strategies.md
│
├─ Enterprise reliability
│  └─ OpenAI text-embedding-3-large (3072d)
│      • Industry standard
│      • ~$0.13/1M tokens
│      • Maturity shortening: reduce to 256/512/1024d
│
├─ Cost-optimized
│  └─ OpenAI text-embedding-3-small (1536d)
│      • ~$0.02/1M tokens (6x cheaper)
│      • 90-95% of large model performance
│
├─ Multilingual (100+ languages)
│  └─ Cohere embed-v3 (1024d)
│      • ~$0.10/1M tokens
│
└─ Self-hosted / Privacy-critical
   ├─ English: nomic-embed-text-v1.5 (768d, Apache 2.0)
   ├─ Multilingual: BAAI/bge-m3 (1024d, MIT)
   └─ Long docs: jina-embeddings-v2 (768d, 8K context)

基本概念

ドキュメントのチャンク分割戦略

ほとんどの RAG システムで推奨されるデフォルト値：

• チャンクサイズ： 512 トークン（文字数ではありません）
• オーバーラップ： 50 トークン（10% の重複）

この数値が適切な理由：

• 512 トークンはコンテキストと精度のバランスを取ります
  • 小さすぎる場合（128～256）：概念が分断され、コンテキストが失われます
  • 大きすぎる場合（1024～2048）：関連性が薄まり、LLM のトークンを無駄に消費します
• 50 トークンのオーバーラップにより、文が文脈の途中で分割されるのを防ぎます

コンテンツの種類に応じた高度な戦略については、references/chunking-patterns.md を参照してください。

ハイブリッド検索（ベクトル＋キーワード）

ハイブリッド検索 ＝ ベクトル類似度 ＋ BM25 キーワードマッチング

User Query: "OAuth refresh token implementation"
           │
    ┌──────┴──────┐
    │             │
Vector Search   Keyword Search
(Semantic)      (BM25)
    │             │
Top 20 docs   Top 20 docs
    │             │
    └──────┬──────┘
           │
   Reciprocal Rank Fusion
   (Merge + Re-rank)
           │
    Final Top 5 Results

ハイブリッド検索が重要な理由：

• ベクトル検索は意味的な内容を捉えます（「OAuth refresh」≈「token renewal」）
• キーワード検索は完全一致を保証します（リテラルの「refresh_token」）
• 組み合わせることで、最適な検索品質が得られます

実装の詳細については、references/hybrid-search.md を参照してください。

はじめに

Python＋Qdrant の例

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

# 1. Initialize client
client = QdrantClient("localhost", port=6333)

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

# 3. Insert documents with embeddings
points = [
    PointStruct(
        id=idx,
        vector=embedding,  # From OpenAI/Voyage/etc
        payload={
            "text": chunk_text,
            "source": "docs/api.md",
            "section": "Authentication"
        }
    )
    for idx, (embedding, chunk_text) in enumerate(chunks)
]
client.upsert(collection_name="documents", points=points)

# 4. Search with metadata filtering
results = client.search(
    collection_name="documents",
    query_vector=query_embedding,
    limit=5,
    query_filter={
        "must": [
            {"key": "section", "match": {"value": "Authentication"}}
        ]
    }
)

完全な例については、examples/qdrant-python/ を参照してください。

TypeScript＋Qdrant の例

import { QdrantClient } from '@qdrant/js-client-rest';

const client = new QdrantClient({ url: 'http://localhost:6333' });

// Create collection
await client.createCollection('documents', {
  vectors: { size: 1024, distance: 'Cosine' }
});

// Insert documents
await client.upsert('documents', {
  points: chunks.map((chunk, idx) => ({
    id: idx,
    vector: chunk.embedding,
    payload: {
      text: chunk.text,
      source: chunk.source
    }
  }))
});

// Search
const results = await client.search('documents', {
  vector: queryEmbedding,
  limit: 5,
  filter: {
    must: [
      { key: 'source', match: { value: 'docs/api.md' } }
    ]
  }
});

完全な例については、examples/typescript-rag/ を参照してください。

RAG パイプラインのアーキテクチャ

パイプラインを構成するすべての要素

1. INGESTION
   ├─ Document Loading (PDF, web, code, Office)
   ├─ Text Extraction & Cleaning
   ├─ Chunking (semantic, recursive, code-aware)
   └─ Embedding Generation (batch, rate-limited)

2. INDEXING
   ├─ Vector Store Insertion (batch upsert)
   ├─ Index Configuration (HNSW, distance metric)
   └─ Keyword Index (BM25 for hybrid search)

3. RETRIEVAL (Query Time)
   ├─ Query Processing (expansion, embedding)
   ├─ Hybrid Search (vector + keyword)
   ├─ Filtering & Post-Processing (metadata, MMR)
   └─ Re-Ranking (cross-encoder, LLM-based)

4. GENERATION
   ├─ Context Construction (format chunks, citations)
   ├─ Prompt Engineering (system + context + query)
   ├─ LLM Inference (streaming, temperature tuning)
   └─ Response Post-Processing (citations, validation)

5. EVALUATION (Production Critical)
   ├─ Retrieval Metrics (precision, recall, relevancy)
   ├─ Generation Metrics (faithfulness, correctness)
   └─ System Metrics (latency, cost, satisfaction)

本番環境の RAG に不可欠なメタデータ

フィルタリングと関連性の確保に不可欠です：

metadata = {
    # SOURCE TRACKING
    "source": "docs/api-reference.md",
    "source_type": "documentation",  # code, docs, logs, chat
    "last_updated": "2025-12-01T12:00:00Z",

    # HIERARCHICAL CONTEXT
    "section": "Authentication",
    "subsection": "OAuth 2.1",
    "heading_hierarchy": ["API Reference", "Authentication", "OAuth 2.1"],

    # CONTENT CLASSIFICATION
    "content_type": "code_example",  # prose, code, table, list
    "programming_language": "python",

    # FILTERING DIMENSIONS
    "product_version": "v2.0",
    "audience": "enterprise",  # free, pro, enterprise

    # RETRIEVAL HINTS
    "chunk_index": 3,
    "total_chunks": 12,
    "has_code": True
}

メタデータが重要な理由：

• ベクトル検索の前にフィルタリングできるため、検索対象を絞り込めます
• 対象を絞った検索によって関連性が向上します
• マルチテナントシステムに対応できます（ユーザー／組織でフィルタリング）
• バージョン管理されたドキュメントに対応できます（製品バージョンでフィルタリング）

RAGAS による評価

自動評価には scripts/evaluate_rag.py を使用します：

from ragas import evaluate
from ragas.metrics import (
    faithfulness,       # Answer grounded in context
    answer_relevancy,   # Answer addresses query
    context_recall,     # Retrieved docs cover ground truth
    context_precision   # Retrieved docs are relevant
)

# Test dataset
test_data = {
    "question": ["How do I refresh OAuth tokens?"],
    "answer": ["Use /token with refresh_token grant..."],
    "contexts": [["OAuth refresh documentation..."]],
    "ground_truth": ["POST to /token with grant_type=refresh_token"]
}

# Evaluate
results = evaluate(test_data, metrics=[
    faithfulness,
    answer_relevancy,
    context_recall,
    context_precision
])

# Production targets:
# faithfulness: >0.90 (minimal hallucination)
# answer_relevancy: >0.85 (addresses user query)
# context_recall: >0.80 (sufficient context retrieved)
# context_precision: >0.75 (minimal noise)

パフォーマンスの最適化

埋め込みの生成

• バッチ処理： 1 バッチあたり 100～500 チャンク
• キャッシュ： コンテンツハッシュをキーに埋め込みをキャッシュします
• レート制限： API プロバイダーの制限を守ります（指数バックオフ）

ベクトル検索

• インデックスの種類： ほとんどの場合、HNSW（Hierarchical Navigable Small World）を使用します
• 距離指標： 正規化された埋め込みにはコサイン距離を使用します
• 事前フィルタリング： ベクトル検索の前にメタデータフィルターを適用します
• 結果の多様性： MMR（最大限界関連性）を使用して冗長性を減らします

コストの最適化

• 埋め込みモデル： 予算に制約がある場合は text-embedding-3-small を検討します
• 次元の削減： matryoshka shortening（3072d → 1024d）を使用します
• キャッシュ： 繰り返しのクエリに対してセマンティックキャッシュを実装します
• バッチ操作： 挿入／更新をまとめて効率化します

よくあるワークフロー

1. RAG チャットボットの構築

• ベクトルデータベース：Qdrant（セルフホストまたはクラウド）
• 埋め込み：OpenAI text-embedding-3-large
• チャンク分割：512 トークン、オーバーラップ 50、セマンティックスプリッター
• 検索：ハイブリッド（ベクトル＋BM25）
• 統合：ai-chat スキルを使用したフロントエンド

完全な実装については、examples/qdrant-python/ を参照してください。

2. セマンティック検索エンジン

• ベクトルデータベース：Qdrant または Pinecone
• 埋め込み：Voyage AI voyage-3（最高品質）
• チャンク分割：コンテンツの種類に応じて設定します（chunking-patterns.md を参照）
• 検索：再ランキングを組み合わせたハイブリッド検索
• フィルタリング：メタデータ（日付、カテゴリなど）で事前に絞り込みます

3. コード検索

• ベクトルデータベース：Qdrant
• 埋め込み：OpenAI text-embedding-3-large
• チャンク分割：AST ベース（関数／クラスの境界）
• メタデータ：言語、ファイルパス、インポート
• 検索：言語フィルタリングを組み合わせたハイブリッド検索

コードに特化した実装については、examples/qdrant-python/ を参照してください。

他のスキルとの統合

フロントエンドのスキル

• ai-chat：ベクターデータベースでチャットインターフェースの背後にあるRAGパイプラインを実現
• search-filter：キーワード検索をセマンティック検索に置き換え
• data-viz：埋め込み空間と類似度スコアを可視化

バックエンドのスキル

• databases-relational：pgvector拡張機能を使用したハイブリッドなアプローチ
• api-patterns：REST/GraphQL経由でセマンティック検索を公開
• observability：埋め込み品質と検索指標を監視

多言語サポート

Python（主要）

• クライアント：qdrant-client
• フレームワーク：LangChain、LlamaIndex
• 参照：examples/qdrant-python/

Rust

• クライアント：qdrant-client（Context7にコードスニペット1,549件）
• フレームワーク：パフォーマンスが重要なシステム向けの生のRust
• 参照：examples/rust-axum-vector/

TypeScript

• クライアント：@qdrant/js-client-rest
• フレームワーク：LangChain.js、Next.jsとの統合
• 参照：examples/typescript-rag/

Go

• クライアント：qdrant-go
• ユースケース：高性能なマイクロサービス

トラブルシューティング

検索品質が低い場合

1. チャンク分割の戦略を確認します（大きすぎる／小さすぎる？）
2. メタデータフィルタリングを確認します（厳しすぎる？）
3. ベクトルのみの検索ではなく、ハイブリッド検索を試します
4. 再ランキングの段階を実装します
5. RAGASの指標を使用して評価します

パフォーマンスが遅い場合

1. HNSWインデックスを使用します（Flatではなく）
2. ベクトル検索の前にメタデータで事前フィルタリングします
3. ベクトルの次元数を減らします（成熟度の短縮）
4. バッチ処理（挿入、検索）を行います
5. GPUアクセラレーションを検討します（Milvus）

コストが高い場合

1. text-embedding-3-smallに切り替えます
2. セマンティックキャッシュを実装します
3. チャンクの重複を減らします
4. セルフホスト可能な埋め込み（nomic、bge-m3）を使用します
5. 埋め込み生成をバッチ処理します

Qdrant Context7ドキュメント

主なリソース： /llmstxt/qdrant_tech_llms-full_txt

• 信頼スコア： 高
• コードスニペット： 10,154件
• 品質スコア： 83.1

Context7経由でアクセス：

resolve-library-id({ libraryName: "Qdrant" })
get-library-docs({
  context7CompatibleLibraryID: "/llmstxt/qdrant_tech_llms-full_txt",
  topic: "hybrid search collections python",
  mode: "code"
})

追加リソース

リファレンスドキュメント

• references/qdrant.md - Qdrantの包括的なガイド
• references/pgvector.md - PostgreSQL pgvector拡張機能
• references/milvus.md - 数十億規模に対応するMilvus/Zilliz
• references/embedding-strategies.md - 埋め込みモデルの比較
• references/chunking-patterns.md - 高度なチャンク分割手法

コード例

• examples/qdrant-python/ - FastAPI + QdrantのRAGパイプライン
• examples/pgvector-prisma/ - PostgreSQL + Prismaの統合
• examples/typescript-rag/ - Honoを使用したTypeScriptのRAG

自動化スクリプト

• scripts/generate_embeddings.py - 埋め込みをバッチ生成
• scripts/benchmark_similarity.py - パフォーマンスをベンチマーク
• scripts/evaluate_rag.py - RAGASベースの評価

---

次のステップ：

1. 規模とインフラストラクチャに基づいてベクターデータベースを選択します
2. 品質とコストのトレードオフに基づいて埋め込みモデルを選択します
3. コンテンツの種類に適したチャンク分割戦略を実装します
4. 本番環境で求められる品質を実現するため、ハイブリッド検索を設定します
5. RAGASの指標を使用して評価します
6. パフォーマンスとコストを最適化します