vector-db

vector-db

目的

このスキルを使うと、高次元ベクトルの保存、インデックス作成、クエリ実行のためのベクトルデータベースを管理し、類似検索や埋め込みなどのタスクにおける AI/ML ワークフローを最適化できます。

使用するタイミング

レコメンデーションエンジンの構築、NLP におけるセマンティック検索、画像検索システムなど、高速なベクトル類似検索が必要な AI/ML アプリケーションでこのスキルを使用します。ブルートフォース比較を避けるため、モデル（BERT など）から生成された埋め込みなど、大規模なベクトルデータを扱う際に適用します。

主な機能

• ベクトルをメタデータとともに保存し、インデックスを使って効率的な近傍探索を実行します。
• 類似度計算のため、コサイン距離、ユークリッド距離、内積などの距離指標に対応します。
• 最大 2048 次元のベクトルを扱い、数百万件までスケールできます。
• 埋め込みモデルと連携し、リアルタイムのベクトル生成とクエリに対応します。

使用パターン

簡単な操作には CLI から、コードでは API 呼び出しを通じてこのスキルを実行します。使用前に、必ず環境変数 $VECTOR_DB_API_KEY を設定して認証してください。CLI ではコマンドの先頭に vector-db を付け、複雑な設定には JSON 設定ファイル（例：{ "dimension": 768, "metric": "cosine" } を記述した config.json）を使用します。コードでは、レスポンスのエラーチェックを確実に行いながら、API エンドポイントに HTTP リクエストを送信します。基本的な流れは、まずインデックスを作成し、次にベクトルを挿入し、最後にクエリを実行します。

主なコマンド/API

CLI ツール vector-db または https://api.openclaw.com/vector-db/v1 の API を使用します。認証には、ヘッダーに $VECTOR_DB_API_KEY が必要です。

• CLI コマンド：インデックスを作成
  vector-db create index --name myindex --dimension 768 --metric cosine --file config.json
  新しいインデックスを初期化します。config.json でシャードなどの追加オプションを指定してください。

• CLI コマンド：ベクトルを挿入
  vector-db insert --index myindex --vectors "[0.1, 0.2, 0.3]" --id vec1
  ベクトルは JSON 配列形式で指定する必要があります。複数のベクトルを挿入するには、--batch フラグを使用します。

• API エンドポイント：ベクトルをクエリ
  POST https://api.openclaw.com/vector-db/v1/indexes/myindex/query
  本文：{ "vector": [0.1, 0.2, 0.3], "top_k": 5 }
  レスポンス：最近傍の配列を含む JSON。

• API エンドポイント：インデックスを削除
  DELETE https://api.openclaw.com/vector-db/v1/indexes/myindex
  ヘッダーに Authorization: Bearer $VECTOR_DB_API_KEY を含めます。

設定形式：CLI 操作では、{ "index_name": "myindex", "vector_size": 768, "distance": "cosine" } のような JSON ファイルを使用します。

統合に関する注意事項

モデルからベクトルをエクスポートし、このスキルで保存することで、AI/ML ツールと統合します。環境変数または .env ファイルに $VECTOR_DB_API_KEY を設定してください。Python との統合には、requests ライブラリを使用します。

import requests  
headers = {'Authorization': f'Bearer {os.environ.get("VECTOR_DB_API_KEY")}' }  
response = requests.post('https://api.openclaw.com/vector-db/v1/indexes/myindex/insert', json={'vectors': [[0.1, 0.2]]}, headers=headers)  

API のベース URL がデプロイ環境と一致していることを確認してください。リトライを追加して、レート制限に対処します。aimlops でクラスタリングする場合は、共有 ID を使って連携します（例：ワークフローでスキル ID "vector-db" を使用します）。

エラー処理

よくあるエラーには、$VECTOR_DB_API_KEY の未設定による認証失敗（HTTP 401）、無効なベクトル次元（インデックスとの不一致など）、ネットワークの問題があります。対処方法は次のとおりです。

• 401 エラーを確認し、ユーザーに $VECTOR_DB_API_KEY の設定を促します。
• 無効な入力については、コードで try-except を使用します。

  try:  
      response = requests.post(url, json=data)  
      response.raise_for_status()  
  except requests.exceptions.HTTPError as e:  
      print(f"Error: {e} - Check vector dimensions.")  
  

• CLI エラーは "Error: Invalid metric specified" と表示されます。コマンドのフラグを確認して修正してください。リクエストを送信する前に、必ず入力を検証します。

具体的な使用例

1. 例：シンプルな検索エンジンの構築
   まず、インデックスを作成します：vector-db create index --name searchindex --dimension 512。
   埋め込みを挿入します：vector-db insert --index searchindex --vectors '[[0.5, 0.6], [0.7, 0.8]]' --ids 'doc1,doc2'。
   類似度を検索します：API で /indexes/searchindex/query に、本文 { "vector": [0.5, 0.6], "top_k": 3 } を指定して POST します。
   このパターンは NLP に最適です。たとえば、埋め込みに基づいて類似文書を検索できます。

2. 例：ML パイプラインでの画像の類似検索
   モデルで画像の埋め込みを生成し、保存します：vector-db insert --index imageindex --vectors '[[0.1, 0.2, 0.3]]' --metadata '{"url": "image1.jpg"}'。
   類似画像を検索します：CLI で vector-db query --index imageindex --vector [0.1, 0.2, 0.3] --top_k 5 を実行します。
   結果を取得してメタデータでフィルタリングするようコードに組み込むと、レコメンデーションシステムに役立ちます。

グラフの関係

• クラスター aimlops に接続されています（例：データ処理スキルとデータパイプラインを共有します）。
• 次のものと関連しています：埋め込み生成スキル（ベクトルの作成用）とクエリ最適化ツール（検索の強化用）。
• 次のものと連携します：ML モデル統合のための ai スキル、およびトレーニングデータ保存のための ml スキル。