milvus

Milvus ベクトルデータベーススキル

pymilvus SDK を使用し、Python コードから Milvus ベクトルデータベースを直接操作します。接続、スキーマ設計、コレクション管理、ベクトルの CRUD、検索、ハイブリッド検索、全文検索、インデックス、パーティション、データベース、RBAC といったライフサイクル全体を網羅します。

使用する場面

ユーザーが次のことを希望する場合に、このスキルを使用します。

• Milvus インスタンス（ローカル、スタンドアロン、クラスター、または Milvus Lite）に接続する
• カスタムスキーマでコレクションを作成する
• ベクトルを挿入、アップサート、検索、クエリ、取得、または削除する
• 再ランキングを使用してハイブリッド検索を実行する
• 全文検索（BM25）を実行する
• インデックス、パーティション、データベースを管理する
• ユーザー、ロール、アクセス制御（RBAC）を設定する
• Milvus を使用して RAG パイプライン、セマンティック検索、またはレコメンデーションシステムを構築する
• 検索／クエリイテレーターで大規模な結果セットを反復処理する

要件

• Python 3.8+
• pymilvus（pip install pymilvus）
• 起動中の Milvus インスタンス、または開発用の Milvus Lite（組み込み型、ファイルベース）

機能の概要

領域	できること
接続	Milvus Lite、Standalone、Cluster、または Zilliz Cloud に接続
コレクション	作成（クイック作成またはカスタムスキーマ）、一覧表示、説明、削除、名前変更、切り詰め、ロード、解放
ベクトル	挿入、アップサート、検索、ハイブリッド検索、クエリ、取得、削除
全文検索	スパースベクトルを使用した BM25 ベースのキーワード検索
イテレーター	大規模なデータセットに対するページ分割検索とクエリ
インデックス	作成（AUTOINDEX、HNSW、IVF_FLAT など）、一覧表示、説明、削除
パーティション	作成、一覧表示、ロード、解放、削除
データベース	作成、一覧表示、切り替え、削除
RBAC	ユーザー、ロール、権限の管理

---

接続

重要：接続コードを書く前に、必ずユーザーに接続情報を確認してください。 次の内容を確認します。

1. デプロイタイプ — Milvus Lite（ローカルファイル）、Standalone／Cluster（セルフホスト）、または Zilliz Cloud（マネージド）ですか？
2. URI — セルフホストの場合：ホストとポート（例：http://localhost:19530）。Zilliz Cloud の場合：エンドポイント URL。
3. 認証 — 必要に応じて、トークン、API キー、またはユーザー名／パスワード。
4. データベース名 — デフォルトのデータベースを使用しない場合。

接続パラメーターを推測したり、コードに直接記述したりしないでください。 開発用のローカル／組み込みモードをユーザーが明示的に希望した場合に限り、Milvus Lite（uri="./milvus.db"）を使用します。

from pymilvus import MilvusClient

# Milvus Lite (embedded, file-based — great for dev/test)
client = MilvusClient(uri="./milvus.db")

# Standalone / Cluster Milvus (ask user for actual host:port and credentials)
client = MilvusClient(uri="<USER_URI>", token="<USER_TOKEN>")

# Zilliz Cloud (ask user for endpoint and API key)
client = MilvusClient(uri="<USER_ZILLIZ_ENDPOINT>", token="<USER_API_KEY>")

パラメーター：

パラメーター	型	説明
uri	str	Milvus Lite の場合は "./file.db"、サーバーの場合は "http://host:19530"
token	str	API キー、または "username:password"
user	str	ユーザー名（token の代わりに指定）
password	str	パスワード（token の代わりに指定）
db_name	str	対象のデータベース（デフォルト："default"）
timeout	float	操作のタイムアウト時間（秒）

非同期クライアント

from pymilvus import AsyncMilvusClient

async with AsyncMilvusClient(uri="<USER_URI>") as client:
    results = await client.search(collection_name="my_collection", data=[query_vector], limit=10)

---

コレクション管理

クイック作成（スキーマの自動設定＋インデックスの自動作成＋自動ロード）

client.create_collection(
    collection_name="my_collection",
    dimension=768,
    metric_type="COSINE"  # Optional: "COSINE" (default), "L2", "IP"
)

これにより、id フィールド（INT64、主キー、auto_id）、vector フィールド（FLOAT_VECTOR）、AUTOINDEX が自動的に作成され、コレクションが自動的にロードされます。

カスタムスキーマで作成

from pymilvus import DataType

schema = client.create_schema(auto_id=False, enable_dynamic_field=True)
schema.add_field("id", DataType.INT64, is_primary=True)
schema.add_field("text", DataType.VARCHAR, max_length=512)
schema.add_field("embedding", DataType.FLOAT_VECTOR, dim=768)

index_params = client.prepare_index_params()
index_params.add_index(field_name="embedding", index_type="AUTOINDEX", metric_type="COSINE")

client.create_collection(collection_name="my_collection", schema=schema, index_params=index_params)

データ型、add_field のパラメーター、コレクション操作の全一覧については、references/collection.md を参照してください。

その他のコレクション操作

client.list_collections()
client.describe_collection(collection_name="my_collection")
client.has_collection(collection_name="my_collection")
client.rename_collection(old_name="old", new_name="new")
client.drop_collection(collection_name="my_collection")
client.truncate_collection(collection_name="my_collection")
client.load_collection(collection_name="my_collection")
client.release_collection(collection_name="my_collection")
client.get_load_state(collection_name="my_collection")
client.get_collection_stats(collection_name="my_collection")

• クイック作成はプロトタイピングに最適です。本番環境ではカスタムスキーマを使用してください。
• 検索またはクエリを実行する前に、コレクションをロードする必要があります。
• スキーマで定義されていないフィールドの挿入を許可するには、enable_dynamic_field=True を使用します。

---

ベクトル操作

ハイブリッド検索、全文検索、イテレーター、フィルター構文、詳細な例については、references/vector.md を参照してください。

挿入／アップサート

# Vectors must come from an embedding model — never use fake/placeholder vectors
from pymilvus import model

embedding_fn = model.dense.SentenceTransformerEmbeddingFunction(model_name="all-MiniLM-L6-v2")

docs = ["AI advances in 2024", "ML basics for beginners"]
vectors = embedding_fn.encode_documents(docs)

data = [
    {"id": 1, "text": docs[0], "embedding": vectors[0]},
    {"id": 2, "text": docs[1], "embedding": vectors[1]},
]
client.insert(collection_name="my_collection", data=data)
client.upsert(collection_name="my_collection", data=data)

検索（ベクトル類似性）

# Use the same embedding model to encode the query
query_vectors = embedding_fn.encode_queries(["What is artificial intelligence?"])

results = client.search(
    collection_name="my_collection",
    data=query_vectors,
    anns_field="embedding",
    limit=10,
    output_fields=["text", "id"],
    filter='age > 20 and status == "active"',
    search_params={"metric_type": "COSINE", "params": {"nprobe": 10}}
)

クエリ／取得／削除

# Query by filter
client.query(collection_name="my_collection", filter='id in [1, 2, 3]', output_fields=["text"], limit=100)

# Get by primary key
client.get(collection_name="my_collection", ids=[1, 2, 3], output_fields=["text"])

# Delete
client.delete(collection_name="my_collection", ids=[1, 2, 3])
client.delete(collection_name="my_collection", filter='status == "obsolete"')

• 偽のベクトルやプレースホルダーのベクトルは絶対に使用しないでください（例：[0.1, 0.2, ...]）。必ず埋め込みモデルからベクトルを生成してください。
• 組み込みの埋め込み関数には pip install "pymilvus[model]" を使用するか、任意の埋め込みモデル（OpenAI、Cohere など）を使用してください。
• 検索時のベクトルの次元は、コレクションのスキーマと完全に一致させてください。
• クエリの埋め込みモデルは、保存済みのベクトルの生成に使用したモデルと同じものである必要があります。
• 大量のデータを挿入する場合は、データをチャンクに分割してください（例：1 バッチあたり 1000 行）。
• 大量の検索結果にはイテレーターを使用してください。references/vector.md を参照してください。

---

インデックス管理

インデックスの種類、メトリックの種類、パラメーターについては、references/index.md を参照してください。

index_params = client.prepare_index_params()
index_params.add_index(
    field_name="embedding",
    index_type="HNSW",
    metric_type="COSINE",
    params={"M": 16, "efConstruction": 256}
)
client.create_index(collection_name="my_collection", index_params=index_params)

client.list_indexes(collection_name="my_collection")
client.describe_index(collection_name="my_collection", index_name="my_index")
client.drop_index(collection_name="my_collection", index_name="my_index")

• ほとんどのユースケースでは、AUTOINDEX を推奨します。
• コレクションをロードする前に、インデックスが必要です。

---

その他の機能

機能	リファレンス
パーティション管理	references/partition.md
データベース管理	references/database.md
ユーザーとロールの管理（RBAC）	references/user-role.md
一般的なパターン（RAG、セマンティック検索）	references/patterns.md

---

一般的なガイダンス

• 接続コードを書く前に、必ずユーザーに接続の詳細（URI、トークン／認証情報）を確認してください。接続パラメーターを推測したり、コードにハードコードしたりしないでください。
• 偽のベクトルやプレースホルダーのベクトルは絶対に生成しないでください。 埋め込みモデルを使って、実際のベクトルを生成してください。組み込みの埋め込み関数には pip install "pymilvus[model]" を提案してください。
• 素早くプロトタイプを作成する場合は、Milvus Lite（uri="./file.db"）を使用してください。サーバーは不要ですが、ユーザーがローカル／組み込みモードを明示的に要求した場合に限ります。
• 検索／クエリを実行する前に、コレクションをメモリにロードする必要があります。
• 検索データのベクトルの次元は、コレクションのスキーマと完全に一致させる必要があります。
• クエリの埋め込みモデルは、保存済みのベクトルの生成に使用したモデルと同じものである必要があります。
• 破壊的な操作（コレクションの削除、データベースの削除、ベクトルの削除）を行う前に、必ずユーザーに確認してください。
• スキーマが変更される可能性がある場合は、enable_dynamic_field=True を使用してください。
• ユーザーから特定のパフォーマンス要件が提示されない限り、AUTOINDEX を優先してください。
• コレクションを削除せずにすべてのデータを消去するには、truncate_collection を使用してください。
• 大規模なデータセットでは、制限値を増やすのではなく、イテレーター（search_iterator、query_iterator）を使用してください。