alicloud-ai-search-milvus

Category: provider

PyMilvus を使用した AliCloud Milvus（Serverless）

このスキルでは、標準の PyMilvus API を使用して AliCloud Milvus に接続し、ベクトル検索を実行します。

前提条件

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

python3 -m venv .venv
. .venv/bin/activate
python -m pip install --upgrade pymilvus

• 環境変数で接続情報を指定します。
  • MILVUS_URI（例：http://<host>:19530）
  • MILVUS_TOKEN（<username>:<password>）
  • MILVUS_DB（デフォルト：default）

クイックスタート（Python）

import os
from pymilvus import MilvusClient

client = MilvusClient(
    uri=os.getenv("MILVUS_URI"),
    token=os.getenv("MILVUS_TOKEN"),
    db_name=os.getenv("MILVUS_DB", "default"),
)

# 1) Create a collection
client.create_collection(
    collection_name="docs",
    dimension=768,
)

# 2) Insert data
items = [
    {"id": 1, "vector": [0.01] * 768, "source": "kb", "chunk": 0},
    {"id": 2, "vector": [0.02] * 768, "source": "kb", "chunk": 1},
]
client.insert(collection_name="docs", data=items)

# 3) Search
query_vectors = [[0.01] * 768]
res = client.search(
    collection_name="docs",
    data=query_vectors,
    limit=5,
    filter='source == "kb" and chunk >= 0',
    output_fields=["source", "chunk"],
)
print(res)

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

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

環境変数：

• MILVUS_URI
• MILVUS_TOKEN
• MILVUS_DB（任意）
• MILVUS_COLLECTION（任意）
• MILVUS_DIMENSION（任意）

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

Claude Code/Codex 向けの注意事項

• 挿入処理は非同期です。新しく挿入したデータを検索する前に、数秒待ってください。
• ベクトルの dimension を、使用する埋め込みモデルに合わせてください。
• フィルターを使用して、テナントのスコープやデータセットのパーティションを適用してください。

エラー処理

• 認証エラー：MILVUS_TOKEN とインスタンスの権限を確認してください。
• 次元の不一致：すべてのベクトルがコレクションの次元と一致していることを確認してください。
• ネットワークエラー：インスタンスの VPC／パブリックアクセス設定を確認してください。

検証

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

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

出力と証跡

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

ワークフロー

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

参考資料

• AliCloud Milvus 向け PyMilvus MilvusClient の例

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