メインコンテンツまでスキップ
バージョン: User Guides (Cloud)

クイックスタート

このガイドでは、Zilliz Cloud クラスターを使用して、高性能なセマンティック検索に関連する操作を実行する方法を説明します。

以下の手順は、すでにクラスターを作成済みで、API キーまたはクラスター認証情報を取得済みであり、お好みの SDK をインストール済みであることを前提としています。

接続の設定​

クラスター認証情報または API キーを取得したら、それを使用してクラスターに接続できます。

from pymilvus import MilvusClient, DataType

CLUSTER_ENDPOINT = "YOUR_CLUSTER_ENDPOINT"
TOKEN = "YOUR_CLUSTER_TOKEN" 
# A valid token could be either
# - An API key, or 
# - A colon-joined cluster username and password, as in `user:pass`

# 1. Set up a Milvus client
client = MilvusClient(
    uri=CLUSTER_ENDPOINT,
    token=TOKEN 
)

Create Collection​

Zilliz Cloud では、ベクトル埋め込みをコレクション内に保存する必要があります。1つのコレクションに保存されるすべてのベクトル埋め込みは、同じ次元数と類似性測定のための距離メトリックを共有します。

コレクションを作成するには、そのコレクション内の各フィールドの属性（名前、データ型、および特定のフィールドに必要な追加属性）を定義する必要があります。さらに、検索パフォーマンスを高速化する必要のあるフィールドに対してインデックスを作成する必要があります。ベクトルフィールドにはインデックスが必須であることに注意してください。

# 3. Create a collection in customized setup mode

# 3.1. Create schema
schema = MilvusClient.create_schema(
    auto_id=False,
    enable_dynamic_field=True,
)

# 3.2. Add fields to schema
schema.add_field(field_name="my_id", datatype=DataType.INT64, is_primary=True)
schema.add_field(field_name="my_vector", datatype=DataType.FLOAT_VECTOR, dim=5)

# 3.3. Prepare index parameters
index_params = client.prepare_index_params()

# 3.4. Add indexes
index_params.add_index(
    field_name="my_id"
)

index_params.add_index(
    field_name="my_vector", 
    index_type="AUTOINDEX",
    metric_type="IP"
)

# 3.5. Create a collection
client.create_collection(
    collection_name="custom_setup",
    schema=schema,
    index_params=index_params
)

上記の設定では、コレクション作成時にそのスキーマやインデックスパラメータなど、コレクションのさまざまな側面を定義しています。

  • スキーマ

    スキーマはコレクションの構造を定義します。上記で示したように、事前定義済みフィールドを追加し、それらの属性を設定することに加えて、以下のオプションを有効または無効にできます。

    • 自動ID (自動ID)

      プライマリフィールドを自動的にインクリメントするかどうか。

    • 動的フィールド (Dynamic Field)

      スキーマで定義されていないフィールドとその値を格納するために、予約済みのJSONフィールド $meta を使用するかどうか。

    スキーマの詳細については、Schema Explained を参照してください。

  • インデックスパラメータ

    インデックスパラメータは、Zilliz Cloudがコレクション内のデータをどのように整理するかを決定します。フィールドごとに特定のインデックスを割り当てるために、メトリックタイプ および インデックスタイプ を設定できます。

    • ベクトルフィールドの場合、インデックスタイプとして AUTOINDEX を使用でき、metric_type には COSINE、L2、または IP を指定できます。

    • スカラーフィールド（プライマリフィールドを含む）の場合、Zilliz Cloudは整数には TRIE を、文字列には STL_SORT を使用します。

    インデックスタイプに関する詳細情報は、AUTOINDEX Explained を参照してください。

📘Notes

  • 前述のコードスニペットで作成されたコレクションは、自動的にロードされます。自動ロードされないコレクションを作成したい場合は、インデックスパラメータの設定をスキップしてください。詳細については、Create Collection を参照してください。

  • RESTful APIを使用して作成されたコレクションは、常に自動的にロードされます。

データの挿入​

コレクションの準備ができたら、次のようにしてデータを追加できます。

# 4. Insert data into the collection
# 4.1. Prepare data
data=[
    {"id": 0, "vector": [0.3580376395471989, -0.6023495712049978, 0.18414012509913835, -0.26286205330961354, 0.9029438446296592], "color": "pink_8682"},
    {"id": 1, "vector": [0.19886812562848388, 0.06023560599112088, 0.6976963061752597, 0.2614474506242501, 0.838729485096104], "color": "red_7025"},
    {"id": 2, "vector": [0.43742130801983836, -0.5597502546264526, 0.6457887650909682, 0.7894058910881185, 0.20785793220625592], "color": "orange_6781"},
    {"id": 3, "vector": [0.3172005263489739, 0.9719044792798428, -0.36981146090600725, -0.4860894583077995, 0.95791889146345], "color": "pink_9298"},
    {"id": 4, "vector": [0.4452349528804562, -0.8757026943054742, 0.8220779437047674, 0.46406290649483184, 0.30337481143159106], "color": "red_4794"},
    {"id": 5, "vector": [0.985825131989184, -0.8144651566660419, 0.6299267002202009, 0.1206906911183383, -0.1446277761879955], "color": "yellow_4222"},
    {"id": 6, "vector": [0.8371977790571115, -0.015764369584852833, -0.31062937026679327, -0.562666951622192, -0.8984947637863987], "color": "red_9392"},
    {"id": 7, "vector": [-0.33445148015177995, -0.2567135004164067, 0.8987539745369246, 0.9402995886420709, 0.5378064918413052], "color": "grey_8510"},
    {"id": 8, "vector": [0.39524717779832685, 0.4000257286739164, -0.5890507376891594, -0.8650502298996872, -0.6140360785406336], "color": "white_9381"},
    {"id": 9, "vector": [0.5718280481994695, 0.24070317428066512, -0.3737913482606834, -0.06726932177492717, -0.6980531615588608], "color": "purple_4976"}
]

# 4.2. Insert data
res = client.insert(
    collection_name="custom_setup",
    data=data
)

print(res)

# Output
#
# {
#     "insert_count": 10,
#     "ids": [0, 1, 2, 3, 4, 5, 6, 7, 8, 9]
# }

上記のコードに示されているように、

  • 挿入するデータは辞書のリスト形式で構成され、各辞書が1つのデータレコード（エンティティ）を表します。

  • 各辞書には、スキーマで定義されていない color という名前のフィールドが含まれています。

  • 各辞書には、事前に定義されたフィールドおよび動的フィールドに対応するキーが含まれています。

📘Notes

  • RESTful API を使用して作成されたコレクションでは AutoID が有効になっているため、挿入するデータに主キー（primary field）を含めない必要があります。

  • 挿入操作は非同期で実行されるため、データ挿入直後に検索を行うと結果が空になる可能性があります。これを回避するには、数秒間待機することをお勧めします。

1つまたは複数のベクトル埋め込みに基づいて類似性検索を実行できます。また、検索リクエストにフィルタリング条件を含めることで、類似性検索の結果をさらに強化できます。

# 8. Search with a filter expression using schema-defined fields
# 1 Prepare query vectors
query_vectors = [
    [0.041732933, 0.013779674, -0.027564144, -0.013061441, 0.009748648]
]

# 2. Start search
res = client.search(
    collection_name="custom_setup",
    data=query_vectors,
    filter="4 < id < 8",
    limit=3
)

print(res)

# Output
#
# [
#     [
#         {
#             "id": 5,
#             "distance": 0.08821295201778412,
#             "entity": {}
#         },
#         {
#             "id": 6,
#             "distance": 0.07432225346565247,
#             "entity": {}
#         },
#         {
#             "id": 7,
#             "distance": 0.07279646396636963,
#             "entity": {}
#         }
#     ]
# ]

出力は、検索されたエンティティを表す3つの辞書からなるサブリストであり、各辞書にはそのID、距離、および指定された出力フィールドが含まれます。

フィルター式に動的フィールドを含めることもできます。以下のコードスニペットでは、color はスキーマで定義されていないフィールドです。このようなフィールドは、マジックフィールド $meta のキーとして $meta["color"] のように記述するか、スキーマ定義済みフィールドと同様に color のように直接使用できます。

# 9. Search with a filter expression using custom fields
# 9.1.Prepare query vectors
query_vectors = [
    [0.041732933, 0.013779674, -0.027564144, -0.013061441, 0.009748648]
]

# 9.2.Start search
res = client.search(
    collection_name="custom_setup",
    data=query_vectors,
    filter='$meta["color"] like "red%"',
    limit=3,
    output_fields=["color"]
)

print(res)

# Output
#
# [
#     [
#         {
#             "id": 5,
#             "distance": 0.08821295201778412,
#             "entity": {
#                 "color": "yellow_4222"
#             }
#         },
#         {
#             "id": 6,
#             "distance": 0.07432225346565247,
#             "entity": {
#                 "color": "red_9392"
#             }
#         },
#         {
#             "id": 7,
#             "distance": 0.07279646396636963,
#             "entity": {
#                 "color": "grey_8510"
#             }
#         }
#     ]
# ]

エンティティの削除​

Zilliz Cloud では、ID およびフィルターによるエンティティの削除が可能です。

  • ID によるエンティティの削除

    # 13. Delete entities by IDs
    res = client.delete(
        collection_name="custom_setup",
        ids=[0,1,2,3,4]
    )

    print(res)

    # Output
    #
    # {
    #     "delete_count": 5
    # }

  • フィルターによるエンティティの削除

    # 14. Delete entities by a filter expression
    res = client.delete(
        collection_name="custom_setup",
        filter="id in [5,6,7,8,9]"
    )

    print(res)

    # Output
    #
    # {
    #     "delete_count": 5
    # }
    📘Notes

    現在、RESTful API の delete エンドポイントはフィルターをサポートしていません。

Drop the collection​

このガイドの手順が完了したら、以下のようにコレクションを削除できます。

# 15. Drop collection
client.drop_collection(
    collection_name="custom_setup"
)

client.drop_collection(
    collection_name="customized_setup"
)

再確認​

  • コレクションを作成する前に、スキーマを作成し、コレクション内のフィールドを定義する必要があります。

  • データ挿入プロセスが完了するまでに時間がかかる場合があります。データ挿入後、類似性検索を実行する前に数秒待機することを推奨します。

  • フィルター式は検索リクエストとクエリリクエストの両方で使用できますが、クエリリクエストでは必須です。

次のステップ​

このクイックスタートガイドを確認した後は、以下のトピックを参照してください：