embedding-optimization

埋め込みの最適化

RAG およびセマンティック検索システムにおける埋め込み生成を、コスト、パフォーマンス、品質の面で最適化します。

このスキルを使用するタイミング

次の場合にこのスキルを使用します：

• RAG（検索拡張生成）システムを構築する
• セマンティック検索や類似性検出を実装する
• 埋め込み API のコストを最適化する（70〜90％削減）
• より適切なチャンク分割によってドキュメント検索の品質を向上させる
• 大規模なドキュメントコーパス（数千〜数百万件のドキュメント）を処理する
• API ベースとローカルの埋め込みモデルから選択する

モデル選定フレームワーク

要件に基づいて最適な埋め込みモデルを選択します：

簡単なおすすめ：

• スタートアップ／MVP： all-MiniLM-L6-v2（ローカル、384 次元、API コストなし）
• 本番環境： text-embedding-3-small（API、1,536 次元、品質とコストのバランスが良好）
• 高品質： text-embedding-3-large（API、3,072 次元、プレミアム品質）
• 多言語対応： multilingual-e5-base（ローカル、768 次元）または Cohere embed-multilingual-v3.0

コスト比較、品質ベンチマーク、データプライバシーに関する考慮事項を含む詳細な判断フレームワークについては、references/model-selection-guide.md を参照してください。

モデル比較の概要：

モデル	種類	次元数	100 万トークンあたりのコスト	最適な用途
all-MiniLM-L6-v2	ローカル	384	$0（計算コストのみ）	大量処理、厳しい予算
BGE-base-en-v1.5	ローカル	768	$0（計算コストのみ）	品質とコストのバランス
text-embedding-3-small	API	1,536	$0.02	汎用的な本番環境
text-embedding-3-large	API	3,072	$0.13	プレミアム品質が必要な場合
embed-multilingual-v3.0	API	1,024	$0.10	100 以上の言語への対応

チャンク分割戦略

コンテンツの種類と用途に基づいてチャンク分割戦略を選択します：

コンテンツの種類 → 戦略の対応：

• ドキュメント： 再帰的（見出しを考慮）、800 文字、オーバーラップ 100
• コード： 再帰的（関数単位）、1,000 文字、オーバーラップ 100
• Q&A／FAQ： 固定サイズ、500 文字、オーバーラップ 50（正確な検索）
• 法律／技術文書： セマンティック（大きめ）、1,500 文字、オーバーラップ 200（コンテキストの保持）
• ブログ記事： セマンティック（段落単位）、1,000 文字、オーバーラップ 100
• 学術論文： 再帰的（セクションを考慮）、1,200 文字、オーバーラップ 150

詳細なチャンク分割パターン、判断ツリー、実装ガイダンスについては、references/chunking-strategies.md を参照してください。

CLI ですぐに始める：

python scripts/chunk_document.py \
  --input document.txt \
  --content-type markdown \
  --chunk-size 800 \
  --overlap 100 \
  --output chunks.jsonl

キャッシュの実装

コンテンツアドレス可能なキャッシュを使って、コストを 80〜90％削減できます。

クエリ量に応じたキャッシュアーキテクチャ：

• 月間 1 万件未満のクエリ： インメモリキャッシュ（Python の lru_cache）
• 月間 1 万〜10 万件のクエリ： Redis（高速、TTL ベースの有効期限切れ）
• 月間 10 万〜100 万件のクエリ： Redis（ホット）＋ PostgreSQL（ウォーム）
• 月間 100 万件超のクエリ： マルチティア（Redis ＋ PostgreSQL ＋ S3）

Redis を使った本番環境向けキャッシュ：

# Embed documents with caching enabled
python scripts/cached_embedder.py \
  --model text-embedding-3-small \
  --input documents.jsonl \
  --output embeddings.npy \
  --cache-backend redis \
  --cache-ttl 2592000  # 30 days

キャッシュの ROI の例：

• ドキュメントチャンク 50,000 件
• コンテンツの重複率 20％
• キャッシュなしの場合：API コスト $0.50
• キャッシュありの場合（ヒット率 60％）：API コスト $0.20
• 削減額：60％（$0.30）

次元数のトレードオフ

ストレージ、検索速度、品質のバランスを取ります：

次元数	ストレージ（ベクトル 100 万件）	検索速度（p95）	品質	用途
384	1.5 GB	10ms	良好	大規模検索
768	3 GB	15ms	高い	汎用的な RAG
1,536	6 GB	25ms	非常に高い	高品質な検索
3,072	12 GB	40ms	最高	プレミアムアプリケーション

重要なポイント： ほとんどの RAG アプリケーションでは、768 次元（ローカルの BGE-base-en-v1.5 または同等のモデル）が、品質、コスト、速度の最適なバランスを実現します。

バッチ処理の最適化

大規模な取り込みのスループットを最大化します。

OpenAI API：

• 1 リクエストあたり最大 2,048 件の入力をバッチ処理します
• レート制限を実装します（ティアに応じて 500～5,000 RPM）
• レート制限に達した場合は、バックオフを適用して並列リクエストを使用します

ローカルモデル（sentence-transformers）：

• GPU アクセラレーション（CUDA、Apple Silicon の場合は MPS）
• バッチサイズの調整（GPU メモリに応じて 32～128）
• スループットを最大化するためのマルチ GPU サポート

予想スループット：

• OpenAI API：毎分 1,000～5,000 件のテキスト（レート制限に依存）
• ローカル GPU（RTX 3090）：毎分 5,000～10,000 件のテキスト
• ローカル CPU：毎分 100～500 件のテキスト

パフォーマンスの監視

最適化に必要な主要なメトリクスを追跡します。

重要なメトリクス：

• レイテンシ： 埋め込み生成時間（p50、p95、p99）
• スループット： 1 秒／1 分あたりの埋め込み数
• コスト： API 使用状況の追跡（1K／1M トークンあたりの USD）
• キャッシュ効率： ヒット率

詳細な監視の設定、メトリクス収集のパターン、ダッシュボードについては、references/performance-monitoring.md を参照してください。

ラッパーで監視：

from scripts.performance_monitor import MonitoredEmbedder

monitored = MonitoredEmbedder(
    embedder=your_embedder,
    cost_per_1k_tokens=0.00002  # OpenAI pricing
)

embeddings = monitored.embed_batch(texts)
metrics = monitored.get_metrics()
print(f"Cache hit rate: {metrics['cache_hit_rate_pct']}%")
print(f"Total cost: ${metrics['total_cost_usd']}")

実行例

完全な実装については、examples/ ディレクトリを参照してください。

Python の例：

• examples/openai_cached.py - Redis キャッシュを使用した OpenAI の埋め込み
• examples/local_embedder.py - sentence-transformers によるローカル埋め込み
• examples/smart_chunker.py - コンテンツに応じた再帰的なチャンク分割
• examples/performance_monitor.py - パイプラインのパフォーマンス追跡
• examples/batch_processor.py - 大規模なドキュメント処理

すべての例には以下が含まれます。

• 完全な、実行可能なコード
• 依存関係のインストール手順
• エラー処理と再試行ロジック
• 設定オプション

統合ポイント

上流（このスキルの提供先）：

• ベクトルデータベース： 埋め込みは Pinecone、Weaviate、Qdrant、pgvector に渡されます
• RAG システム： 検索パイプライン向けに最適化された埋め込み
• セマンティック検索： 類似性検索用のクエリとドキュメントの埋め込み

下流（このスキルの利用元）：

• ドキュメント処理： 埋め込みの前にドキュメントをチャンク分割します
• データ取り込み： さまざまなソースからドキュメントを処理します

関連スキル：

• RAG アーキテクチャについては、building-ai-chat スキルを参照してください
• ベクトルデータベースの操作については、databases-vector スキルを参照してください
• データ取り込みパイプラインについては、ingesting-data スキルを参照してください

よく使われるパターン

パターン 1：RAG パイプライン

Document → Chunk → Embed → Store (vector DB) → Retrieve

パターン 2：セマンティック検索

Query → Embed → Search (vector DB) → Rank → Display

パターン 3：多段階検索（コスト最適化）

Query → Cheap Embedding (384d) → Initial Search →
Expensive Embedding (1,536d) → Rerank Top-K → Return

コスト削減： 高価な埋め込みを使用する単一段階方式と比べて 70% 削減

クイックリファレンスチェックリスト

モデルの選択：

• データのプライバシー要件を特定した（ローカルか API か）
• 想定されるクエリ量を計算した
• 品質要件を決定した（good／high／highest）
• 多言語サポートの必要性を確認した

チャンク分割：

• コンテンツの種類を分析した（コード、ドキュメント、法務文書など）
• 適切なチャンクサイズを選択した（500～1,500 文字）
• コンテキストの損失を防ぐためにオーバーラップを設定した（50～200 文字）
• チャンクが意味上の境界を保持していることを検証した

キャッシュ：

• コンテンツアドレス可能なハッシュを実装した
• キャッシュバックエンドを選択した（Redis、PostgreSQL）
• コンテンツの変動性に基づいて TTL を設定した
• キャッシュヒット率を監視している（目標：60% 超）

パフォーマンス：

• レイテンシ（埋め込み生成時間）を追跡している
• スループット（1 秒あたりの埋め込み数）を測定している
• コスト（API 呼び出しにかかった USD）を監視している
• 効率を最大化するためにバッチサイズを最適化している