ベクトル アップサート

エンドツーエンド パイプライン: データセット → エンベディング → ベクトル DB アップサート。

実行するタイミング

• ユーザーがデータに対してセマンティック検索を行いたい場合。
• database-guide がベクトル バックエンドを推奨した場合。
• 既存のエンベディングを更新する必要がある場合。

サポートされているバックエンド

• Pinecone（マネージド クラウド）。
• Qdrant（セルフホスト型またはクラウド）。
• Weaviate（セルフホスト型またはクラウド）。
• Milvus / Zilliz。
• pgvector（Postgres 拡張）。
• ChromaDB（ローカル / 組み込み）。

手順

1. ソースを特定する — データセット パス、およびエンベディングする列を特定します。
2. エンベディング モデルを選択します:
   • ローカル（API コストなし）: sentence-transformers（例: all-MiniLM-L6-v2、BAAI/bge-small-en-v1.5）またはタスク チューニング済みモデル。
   • ホステッド: OpenAI text-embedding-3-small / -large、Cohere、Voyage、Jina、ラッパー経由の Anthropic 互換。
   • ユーザーがホステッド品質を希望しない限り、小さなローカル モデルをデフォルトとします。選択をデータ辞書に記録します。
3. 必要に応じてチャンク化します:
   • 長いテキスト（選択したモデルのトークン予算を超える）を検出します。
   • 文の境界でチャンク化し、オーバーラップさせます（デフォルト 400 トークン、50 オーバーラップ）。ユーザーに確認します。
   • ダウンストリームの検索が再集約できるように、chunk_id と parent_row_id を追跡します。
4. メタデータを添付します — すべてのベクトルはフィルタリング用ペイロード メタデータを保有します。ユーザーに含める列を尋ねます（小さく保つこと。ベクトル DB は大きなブロブの保存場所ではありません）。
5. ターゲットを設定します:
   • 既存設定: $CLAUDE_USER_DATA/Claude-Data-Wrangler/config.json の vector_profiles で保存済みバックエンドを確認します。
   • 新しい設定: バックエンド、エンドポイント/URL、インデックス/コレクション名、API キー参照（環境変数 / 1Password / プロンプト — プレーンテキストは厳禁）を尋ねます。
   • 選択したモデルの正しいベクトル次元および距離メトリック（デフォルトはコサイン）を使用して、インデックス/コレクションを作成します。
6. バッチでエンベディングします（デフォルト 1 バッチあたり 64 行）。レート制限と一時的なエラーに対して再試行します。
7. 決定的 ID（parent_row_id + chunk_id のハッシュ）でアップサートします。これにより、再実行時は冪等になります。
8. 検証します — 既知のIDをフェッチバックしてみます。サンプル クエリを実行し、結果の妥当性を確認します。
9. レポートを作成します — エンベディング数、アップサート数、バックエンド インデックス統計、およびサンプル検索結果を報告します。
10. データ辞書を更新します。エンベディング モデル、次元、チャンク パラメータ、ターゲット インデックス名を含めます。

設定ファイルの構造

$CLAUDE_USER_DATA/Claude-Data-Wrangler/config.json:

{
  "vector_profiles": {
    "pinecone-prod": {
      "backend": "pinecone",
      "index": "knowledge-base",
      "namespace": "documents",
      "api_key_ref": {"type": "op", "reference": "op://Private/Pinecone/api_key"}
    },
    "local-qdrant": {
      "backend": "qdrant",
      "url": "http://localhost:6333",
      "collection": "documents"
    }
  },
  "embedding_defaults": {
    "model": "BAAI/bge-small-en-v1.5",
    "dimension": 384,
    "metric": "cosine"
  }
}

依存関係

pip install pandas sentence-transformers  # local embedding
# per backend
pip install pinecone-client
pip install qdrant-client
pip install weaviate-client
pip install pymilvus
pip install psycopg[binary]  # for pgvector
pip install chromadb

エッジ ケース

• 次元のミスマッチ — 設定済みインデックスの次元が選択したモデルと異なる場合、アップサートを拒否し、モデルの切り替えまたは新しいインデックスの作成をお勧めします。ベクトルを自動的に再形成しないでください。
• ホステッド エンベディングのレート制限 — バックオフでバッチ処理します。大規模なデータセットについては事前にコストを見積もり、ユーザーに確認します。
• 冪等性と更新 — 決定的 ID は、同じデータに対して再実行すると上書きされます。ユーザーが履歴を保持したい場合、別の「バージョン管理済み」インデックスまたはメタデータに version フィールドを含めることをお勧めします。
• 多言語コンテンツ — 多言語モデル（paraphrase-multilingual-mpnet-base-v2、multilingual-e5-large）を選択します。英語以外のコンテンツを英語専用モデルで暗黙的にエンベディングしないでください。
• エンベディング済みテキスト内の PII — 最初に pii-flag を実行します。エンベディングはトレーニング隣接情報をリークする可能性があり、事後的な修正が困難です。