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

クイックスタート

このガイドでは、Zilliz Cloudクラスタを設定し、CRUD操作を数分で実行する方法について説明します。

SDKをインストールする​

Zilliz CloudはMilvus SDKとすべてのRESTful APIエンドポイントをサポートしています。RESTful APIを直接使用するか、以下のSDKのいずれかを選択して開始することができます。

クラスタの作成​

RESTful APIエンドポイントまたはZilliz Cloudコンソールを使用して、任意のサブスクリプションプランでクラスタを作成できます。

以下は、RESTful APIを使用して無料クラスタを作成する方法を示しています。

curl --request POST \
    --url "https://api.cloud.zilliz.com/v2/clusters/createFree" \
    --header "Authorization: Bearer ${API_KEY}" \
    --header "Accept: application/json" \
    --header "Content-Type: application/json" \
    --data-raw '{
        "clusterName": "Free-01",
        "projectId": "proj-xxxxxxxxxxxxxxxxxxxxxx",
        "regionId": "gcp-us-west1"
    }'
    
# {
#     "code": 0,
#     "data": {
#         "clusterId": "inxx-xxxxxxxxxxxxxxx",
#         "username": "db_xxxxxxxx",
#         "password": "*************",
#         "prompt": "successfully submitted, cluster is being created. You can access data about the creation progress and status of your cluster by DescribeCluster API. Once the cluster status is RUNNING, you may access your vector database using the SDK with the admin account and the initial password you specified."
#     }
# }

以下は、RESTful APIを使用してサーバーレスクラスターを作成する方法を示しています。

curl --request POST \
    --url "https://api.cloud.zilliz.com/v2/clusters/createServerless" \
    --header "Authorization: Bearer ${API_KEY}" \
    --header "Accept: application/json" \
    --header "Content-Type: application/json" \
    --data-raw '{
        "clusterName": "Serverless-05",
        "projectId": "proj-xxxxxxxxxxxxxxxxxxxxxxx",
        "regionId": "gcp-us-west1"
    }'
    
# {
#     "code": 0,
#     "data": {
#         "clusterId": "inxx-xxxxxxxxxxxxxxx",
#         "username": "db_xxxxxxxx",
#         "password": "*************",
#         "prompt": "successfully submitted, cluster is being created. You can access data about the creation progress and status of your cluster by DescribeCluster API. Once the cluster status is RUNNING, you may access your vector database using the SDK with the admin account and the initial password you specified."
#     }
# }

以下は、RESTful APIを使用してクラスターを作成する方法を示しています。

curl --request POST \
    --url "https://api.cloud.zilliz.com/v2/clusters/createDedicated" \
    --header "Authorization: Bearer ${API_KEY}" \
    --header "Accept: application/json" \
    --header "Content-Type: application/json" \
    --data-raw '{
        "clusterName": "Cluster-05",
        "projectId": "proj-xxxxxxxxxxxxxxxxxxxxxx",
        "regionId": "aws-us-west-2",
        "plan": "Standard",
        "cuType": "Performance-optimized",
        "cuSize": 1
    }'
    
# {
#     "code": 0,
#     "data": {
#         "clusterId": "inxx-xxxxxxxxxxxxxxx",
#         "username": "db_admin",
#         "password": "*************",
#         "prompt": "successfully submitted, cluster is being created. You can access data about the creation progress and status of your cluster by DescribeCluster API. Once the cluster status is RUNNING, you may access your vector database using the SDK with the admin account and the initial password you specified."
#     }
# }
📘ノート

専用クラスタを作成する前に、支払い方法を追加する必要があります。

Zilliz Cloudコンソールで、クラウドリージョン、APIキー、プロジェクトIDを確認できます。Zilliz Cloudコンソールで無料クラスタを作成する場合は、クラスタ作成を参照してください。

クラスタが実行されると、一度だけクラスタ資格情報を求められます。安全な場所にダウンロードして保存してください。後でクラスタに接続するために必要になります。

接続先Zilliz Cloudクラスタ​

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

from pymilvus import MilvusClient, DataType

CLUSTER_ENDPOINT = "YOUR_CLUSTER_ENDPOINT"
TOKEN = "YOUR_CLUSTER_TOKEN"

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

言語の違いにより、main関数にコードを含める必要があります。JavaまたはNode. jsでコーディングする場合は。

コレクションを作成​

Zilliz Cloud上では、ベクトル埋め込みをコレクションに保存する必要があります。コレクションに保存されたすべてのベクトル埋め込みは、類似性を測定するための同じ次元と距離メトリックを共有します。コレクションを作成する方法は、以下のいずれかです。

クイックセットアップ​

クイックセットアップモードでコレクションを設定するには、コレクション名とコレクションのベクトル場の次元を設定するだけです。

# 2. Create a collection in quick setup mode
client.create_collection(
    collection_name="quick_setup",
    dimension=5 # The dimensionality should be an integer greater than 1.
)

上記の設定では、

  • プライマリフィールドとベクトルフィールドは、デフォルトの名前(idとvector)を使用します。

  • メトリックタイプもデフォルト値(COSINE)に設定されます。

  • プライマリフィールドは整数を受け入れ、自動的に増加しません。

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

📘ノート

RESTful APIを使用して作成されたコレクションは、最低32次元のベクトルフィールドをサポートしています。

カスタマイズされたセットアップ​

コレクションスキーマを自分で定義するには、カスタマイズされたセットアップを使用します。この方法で、コレクション内の各フィールドの属性を定義できます。これには、名前、データ型、および特定のフィールドの追加属性が含まれます。

# 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="customized_setup",
    schema=schema,
    index_params=index_params
)

上記のセットアップでは、スキーマやインデックスパラメーターなど、コレクションの作成時にさまざまな側面を定義する柔軟性があります。

  • スキーマ

    スキーマはコレクションの構造を定義します。上記で示したように、事前に定義されたフィールドを追加して属性を設定する以外は、有効化と無効化のオプションがあります。

    • オートID

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

    • ダイナミックフィールド

      予約済みのJSONフィールド**$meta**を使用して、スキーマ定義されていないフィールドとその値を保存するかどうか。

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

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

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

    • ベクトル場では、インデックスタイプとしてAUTOINDEXを使用し、メトリックタイプとしてCOSINE、L 2、またはIPを使用できます。

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

    インデックスタイプの詳細については、AUTOINDEXのAUTOINDEXの説明参照してください。

📘ノート

前のコードスニペットで作成されたコレクションは自動的にロードされます。自動的にロードされるコレクションを作成したくない場合は、コレクションを作成するを参照してください。

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="quick_setup",
    data=data
)

print(res)

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

提供されたコードは、クイックセットアップの方法でコレクションを作成したことを前提としています。上記のコードに示すように、

  • 挿入するデータは辞書のリストに整理され、各辞書はエンティティと呼ばれるデータレコードを表します。

  • 各ディクショナリには、colorという名前のスキーマ定義されていないフィールドが含まれています。

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

📘ノート

RESTful API対応のAutoIDを使用して作成されたコレクションは、挿入するデータのプライマリフィールドをスキップする必要があります。

より多くのデータを挿入​

後で挿入された10個のエンティティで検索したい場合は、このセクションを安全にスキップできます。Zilliz Cloudクラスターの検索パフォーマンスについて詳しく知るには、以下のコードスニペットを使用して、ランダムに生成されたエンティティをコレクションに追加することをお勧めします。

import time

# 5. Insert more data into the collection
# 5.1. Prepare data

colors = ["green", "blue", "yellow", "red", "black", "white", "purple", "pink", "orange", "brown", "grey"]
data = [ {
    "id": i, 
    "vector": [ random.uniform(-1, 1) for _ in range(5) ], 
    "color": f"{random.choice(colors)}_{str(random.randint(1000, 9999))}" 
} for i in range(1000) ]

# 5.2. Insert data
res = client.insert(
    collection_name="quick_setup",
    data=data[10:]
)

print(res)

# Output
#
# {
#     "insert_count": 990
# }

# Wait for a while
time.sleep(5)
📘ノート

Insert RESTful APIを呼び出すたびに、最大100個のエンティティをバッチに挿入できます。

1つ以上のベクトル埋め込みに基づいて類似検索を実行できます。

📘ノート

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

変数query_vectorの値は、浮動小数点数のサブリストを含むリストです。このサブリストは、5次元のベクトル埋め込みを表します。

# 6.1. Prepare query vectors
query_vectors = [
    [0.041732933, 0.013779674, -0.027564144, -0.013061441, 0.009748648]
]

# 6.2. Start search
res = client.search(
    collection_name="quick_setup",     # target collection
    data=query_vectors,                # query vectors
    limit=3,                           # number of returned entities
)

print(res)

# Output
#
# [
#     [
#         {
#             "id": 551,
#             "distance": 0.08821295201778412,
#             "entity": {}
#         },
#         {
#             "id": 296,
#             "distance": 0.0800950899720192,
#             "entity": {}
#         },
#         {
#             "id": 43,
#             "distance": 0.07794742286205292,
#             "entity": {}
#         }
#     ]
# ]

出力は、IDと距離を持つ返されたエンティティを表す3つの辞書のサブリストを含むリストです。

複数のベクトル埋め込みをquery_vector変数に含めて、バッチ類似検索を実行することもできます。

# 7. Search with multiple vectors
# 7.1. Prepare query vectors
query_vectors = [
    [0.041732933, 0.013779674, -0.027564144, -0.013061441, 0.009748648],
    [0.0039737443, 0.003020432, -0.0006188639, 0.03913546, -0.00089768134]
]

# 7.2. Start search
res = client.search(
    collection_name="quick_setup",
    data=query_vectors,
    limit=3,
)

print(res)

# Output
#
# [
#     [
#         {
#             "id": 551,
#             "distance": 0.08821295201778412,
#             "entity": {}
#         },
#         {
#             "id": 296,
#             "distance": 0.0800950899720192,
#             "entity": {}
#         },
#         {
#             "id": 43,
#             "distance": 0.07794742286205292,
#             "entity": {}
#         }
#     ],
#     [
#         {
#             "id": 730,
#             "distance": 0.04431751370429993,
#             "entity": {}
#         },
#         {
#             "id": 333,
#             "distance": 0.04231833666563034,
#             "entity": {}
#         },
#         {
#             "id": 232,
#             "distance": 0.04221535101532936,
#             "entity": {}
#         }
#     ]
# ]

出力は2つのサブリストのリストであり、それぞれに3つの辞書が含まれ、返されたエンティティをIDと距離で表します。

フィルターされた検索​

  • スキーマ定義フィールド

    検索要求にフィルターを含め、特定の出力フィールドを指定することで、検索結果を強化することもできます。

    # 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="quick_setup",
        data=query_vectors,
        filter="500 < id < 800",
        limit=3
    )

    print(res)

    # Output
    #
    # [
    #     [
    #         {
    #             "id": 551,
    #             "distance": 0.08821295201778412,
    #             "entity": {}
    #         },
    #         {
    #             "id": 760,
    #             "distance": 0.07432225346565247,
    #             "entity": {}
    #         },
    #         {
    #             "id": 539,
    #             "distance": 0.07279646396636963,
    #             "entity": {}
    #         }
    #     ]
    # ]

    出力は、ID、距離、指定された出力フィールドを持つ検索されたエンティティを表す3つの辞書のサブリストを含むリストである必要があります。

  • スキーマ定義されていないフィールド

    フィルター式に動的フィールドを含めることもできます。次のコードスニペットでは、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="quick_setup",
        data=query_vectors,
        filter='$meta["color"] like "red%"',
        limit=3,
        output_fields=["color"]
    )

    print(res)

    # Output
    #
    # [
    #     [
    #         {
    #             "id": 263,
    #             "distance": 0.0744686871767044,
    #             "entity": {
    #                 "color": "red_9369"
    #             }
    #         },
    #         {
    #             "id": 381,
    #             "distance": 0.06509696692228317,
    #             "entity": {
    #                 "color": "red_9315"
    #             }
    #         },
    #         {
    #             "id": 360,
    #             "distance": 0.057343415915966034,
    #             "entity": {
    #                 "color": "red_6066"
    #             }
    #         }
    #     ]
    # ]

スカラークエリ​

ベクトル類似検索とは異なり、クエリはフィルタ式に基づくスカラーフィルタリングによってベクトルを取得します。

  • スキーマ定義フィールドを使用したフィルター

    # 10. Query with a filter expression using a schema-defined field
    res = client.query(
        collection_name="quick_setup",
        filter="10 < id < 15",
        output_fields=["color"]
    )

    print(res)

    # Output
    #
    # [
    #     {
    #         "color": "yellow_4104",
    #         "id": 11
    #     },
    #     {
    #         "color": "blue_7278",
    #         "id": 12
    #     },
    #     {
    #         "color": "orange_7136",
    #         "id": 13
    #     },
    #     {
    #         "color": "pink_7776",
    #         "id": 14
    #     }
    # ]

  • スキーマ定義されていないフィールドを使用したフィルター。

    # 11. Query with a filter expression using a custom field
    res = client.query(
        collection_name="quick_setup",
        filter='$meta["color"] like "brown_8%"',
        output_fields=["color"],
        limit=5
    )

    print(res)

    # Output
    #
    # [
    #     {
    #         "color": "brown_8454",
    #         "id": 17
    #     },
    #     {
    #         "color": "brown_8390",
    #         "id": 35
    #     },
    #     {
    #         "color": "brown_8442",
    #         "id": 309
    #     },
    #     {
    #         "color": "brown_8429",
    #         "id": 468
    #     },
    #     {
    #         "color": "brown_8020",
    #         "id": 472
    #     }
    # ]

エンティティを取得​

取得するエンティティのIDがわかっている場合は、次のようにIDからエンティティを取得できます。

# 12. Get entities by IDs
res = client.get(
    collection_name="quick_setup",
    ids=[1,2,3],
    output_fields=["vector"]
)

print(res)

# Output
#
# [
#     {
#         "vector": [
#             0.19886813,
#             0.060235605,
#             0.6976963,
#             0.26144746,
#             0.8387295
#         ],
#         "id": 1
#     },
#     {
#         "vector": [
#             0.43742132,
#             -0.55975026,
#             0.6457888,
#             0.7894059,
#             0.20785794
#         ],
#         "id": 2
#     },
#     {
#         "vector": [
#             0.3172005,
#             0.97190446,
#             -0.36981148,
#             -0.48608947,
#             0.9579189
#         ],
#         "id": 3
#     }
# ]
📘ノート

現在、RESTful APIはgetエンドポイントを提供していません。

エンティティの削除​

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

  • IDでエンティティを削除します。

    # 13. Delete entities by IDs
    res = client.delete(
        collection_name="quick_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="quick_setup",
        filter="id in [5,6,7,8,9]"
    )

    print(res)

    # Output
    #
    # {
    #     "delete_count": 5
    # }
    📘ノート

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

コレクションを削除する​

無料プランでは、クラスタ内で最大2つのコレクションを使用できます。このガイドを完了したら、次のようにコレクションを削除できます。

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

client.drop_collection(
    collection_name="customized_setup"
)

まとめ​

  • コレクションを作成するには2つの方法があります。1つ目はクイックセットアップで、ベクトル場の名前と次元を提供するだけで済みます。2つ目はカスタマイズされたセットアップで、コレクションのほぼすべての側面をカスタマイズできます。

  • データの挿入過程は完了するまでに時間がかかる場合があります。データを挿入した後、類似検索を行う前に数秒間待つことをお勧めします。

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