alicloud-ai-search-dashvector

カテゴリ：プロバイダー

DashVector ベクトル検索

DashVector を使用してコレクションを管理し、オプションのフィルターとスパースベクトルを使ってベクトル類似検索を実行します。

前提条件

• SDK をインストールします（PEP 668 の制限を回避するため、venv の使用を推奨します）。

python3 -m venv .venv
. .venv/bin/activate
python -m pip install dashvector

• 環境変数で認証情報とエンドポイントを指定します。
  • DASHVECTOR_API_KEY
  • DASHVECTOR_ENDPOINT（クラスターのエンドポイント）

正規化された操作

コレクションの作成

• name（str）
• dimension（int）
• metric（str：cosine | dotproduct | euclidean）
• fields_schema（フィールド型を指定する任意の dict）

ドキュメントのアップサート

• {id, vector, fields} のリスト、またはタプル形式の docs
• sparse_vector とマルチベクトルコレクションに対応しています

ドキュメントのクエリ

• vector または id（どちらか一方が必須です。両方が空の場合、フィルターのみが適用されます）
• topk（int）
• filter（SQL 形式の where 句）
• output_fields（フィールド名のリスト）
• include_vector（bool）

クイックスタート（Python SDK）

import os
import dashvector
from dashvector import Doc

client = dashvector.Client(
    api_key=os.getenv("DASHVECTOR_API_KEY"),
    endpoint=os.getenv("DASHVECTOR_ENDPOINT"),
)

# 1) Create a collection
ret = client.create(
    name="docs",
    dimension=768,
    metric="cosine",
    fields_schema={"title": str, "source": str, "chunk": int},
)
assert ret

# 2) Upsert docs
collection = client.get(name="docs")
ret = collection.upsert(
    [
        Doc(id="1", vector=[0.01] * 768, fields={"title": "Intro", "source": "kb", "chunk": 0}),
        Doc(id="2", vector=[0.02] * 768, fields={"title": "FAQ", "source": "kb", "chunk": 1}),
    ]
)
assert ret

# 3) Query
ret = collection.query(
    vector=[0.01] * 768,
    topk=5,
    filter="source = 'kb' AND chunk >= 0",
    output_fields=["title", "source", "chunk"],
    include_vector=False,
)
for doc in ret:
    print(doc.id, doc.fields)

スクリプトのクイックスタート

python skills/ai/search/alicloud-ai-search-dashvector/scripts/quickstart.py

環境変数：

• DASHVECTOR_API_KEY
• DASHVECTOR_ENDPOINT
• DASHVECTOR_COLLECTION（任意）
• DASHVECTOR_DIMENSION（任意）

任意の引数：--collection、--dimension、--topk、--filter。

Claude Code/Codex 向けの注意事項

• 冪等な取り込みには upsert を使用してください。
• dimension を埋め込みモデルの出力サイズに合わせてください。
• テナントまたはデータセットの範囲を適用するには、フィルターを使用してください。
• スパースベクトルを使用する場合は、アップサート時またはクエリ時に sparse_vector={token_id: weight, ...} を渡してください。

エラー処理

• 401/403：DASHVECTOR_API_KEY が無効です
• 400：コレクションのスキーマが無効、または次元が一致しません
• 429/5xx：指数バックオフで再試行してください

検証

mkdir -p output/alicloud-ai-search-dashvector
for f in skills/ai/search/alicloud-ai-search-dashvector/scripts/*.py; do
  python3 -m py_compile "$f"
done
echo "py_compile_ok" > output/alicloud-ai-search-dashvector/validate.txt

合格条件：コマンドが 0 で終了し、output/alicloud-ai-search-dashvector/validate.txt が生成されること。

出力と証跡

• 成果物、コマンド出力、API レスポンスの概要を output/alicloud-ai-search-dashvector/ に保存します。
• 再現性を確保するため、証跡ファイルに主要なパラメーター（リージョン／リソース ID／時間範囲）を記載します。

ワークフロー

1. ユーザーの意図、リージョン、識別子、および操作が読み取り専用か変更を伴うかを確認します。
2. 接続と権限を検証するため、最初に最小限の読み取り専用クエリを 1 つ実行します。
3. 明示的なパラメーターと限定された範囲を指定して、対象の操作を実行します。
4. 結果を検証し、出力ファイルと証跡ファイルを保存します。

参考資料

• DashVector Python SDK：Client.create、Collection.upsert、Collection.query

• ソース一覧：references/sources.md