跳到主要内容

快速开始

本指南介绍如何快速创建 Zilliz Cloud 集群并进行 CRUD 操作。

安装 SDK​

Zilliz Cloud 兼容各类型的 Milvus SDK 和 RESTful API。您可以直接调用 RESTful API 或安装以下任意 SDK：

创建集群​

您可以通过 RESTful API 或 Zilliz Cloud 控制台创建集群。

以下代码示例展示如何通过 RESTful API 创建一个 Free 集群。

curl --request POST \
    --url "https://api.cloud.zilliz.com.cn/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 创建一个 Serverless 集群。

curl --request POST \
    --url "https://api.cloud.zilliz.com.cn/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.cn/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."
#     }
# }
📘说明

在创建 Dedicated 集群之前，请先添加支付方式。

要获取云区域、API 密钥和项目 ID，请参阅Zilliz Cloud 控制台。有关如何创建集群，请参阅创建集群。

集群启动后，系统将提示您一次性下载集群凭证，请将凭证保存在安全位置，以便后续连接集群时使用。

另外，您也可以创建 API 密钥，用以连接集群，无需使用集群凭证。

连接 Zilliz Cloud 集群Milvus​

获取集群凭证或 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 
)
📘说明

由于编程语言的差异，使用 Java 或 Node.js 时，需将代码置于主函数内。

创建 collection​

在 Zilliz Cloud， 您需要将向量数据存储到 collection 中。同一个 collection 中的向量数据具有相同的维度和相似度测量指标。您可以通过以下几种方式创建 collection。

快速创建​

要快速创建 collection，您只需指定 collection 名称和向量维度。

# 2. Create a collection in quick setup mode
client.create_collection(
    collection_name="quick_setup",
    dimension=5
)

在以上配置中：

  • 主键和向量字段均采用默认名称（即 id 和 vector）；

  • 默认采用 COSINE 度量类型；

  • 主键字段仅接受整数型，且不会自动递增；

  • 保留 JSON 字段 $meta 将用于存储未在 schema 中定义的其他字段和字段值。

自定义创建​

自定义 collection 的 schema 时，您可以详细定义每个字段的属性，如字段名称、数据类型和其他属性。 通过自定义创建方式，您可以自由定制 schema 和索引参数。

# 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
)

通过以上代码，您可以自由定义 collection 的各项属性，包括 schema 和索引参数等。

  • Schema

    Schema 决定了 collection 的结构。除了上述代码添加的预定义字段外，您还可以启用或禁用以下功能：

    • Auto ID

      是否自动递增 collection 的主键值。

    • Dynamic Field

      是否使用保留 JSON 字段 $meta 来存储在 schema 中未定义的字段和字段值。

    有关更多信息，请参阅Schema。

  • 索引参数

    索引参数将定义 Zilliz Cloud 如何处理 collection 中的数据。您可以为字段设置特定的索引类型和度量类型。

    • 向量字段可以选择 AUTOINDEX 作为索引类型，并采用 COSINE、L2或 IP 作为度量类型（metric_type）。

    • 标量字段，如主键字段，整数型使用 TRIE，字符串类型使用 STL_SORT。

    有关更多信息，请参阅 AUTOINDEX。

📘说明

通过上述代码创建的 collection 将自动加载（load）。如需管理非自动加载的 collection，请参阅管理 Collection (SDK)。

通过 RESTful API 创建的 collection 会自动完成加载（load）。

插入数据​

无论采用何种方式创建，collection 都将被索引并加载（load）完毕。准备就绪后，可以开始插入示例数据。

# 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]
# }

假设您已通过快速创建的方式完成了 collection 创建。通过以上代码：

  • 插入的数据为字典列表，每个字典代表一条数据记录，即 entity。

  • 每个字典包含一个名为 color 的非 schema 定义字段。

  • 每个字典包含与预定义和动态字段相对应的键值。

📘说明

通过 RESTful API 创建的 collection 启用了 AutoID，因此插入数据时应跳过主键字段。

增加数据量​

如果您希望仅基于已插入的 10 个 entity 进行 search 或 query，则可以跳过此步骤。为帮助您更深入了解 Zilliz Cloud 集群或 的搜索性能，可使用以下代码片段向 collection 中随机添加更多 entity。

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)
📘说明

每次调用插入RESTful API，最多可批量插入 100 个 entity。

您可以基于一条或多条向量 embedding 执行相似性搜索（search）。

📘说明

插入操作是异步的，立即进行搜索可能得到空结果集。建议插入数据后稍等几秒钟。

query_vectors变量是一个列表，包含代表 5 维向量 embedding 的浮点数子列表。

# 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": {}
#         }
#     ]
# ]

输出结果是一个列表，内含三个字典型的子列表，字典中包含返回 entity ID 和距离。

您也可以在 query_vectors 中添加多个向量 embedding 进行 bulk-vector search。

# 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": {}
#         }
#     ]
# ]

输出为一个列表，包括两个各含三个字典的子列表，每个字典展示返回 entity 的 ID 和距离。

  • Schema 中已定义的字段

    您可以在搜索请求中加入 filter 过滤并指定输出字段，以优化搜索结果。

    # 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": {}
    #         }
    #     ]
    # ]

    输出结果为列表形式，内含三个字典类型的子列表。每个字典代表一个 entity，包括其 ID、相似距离和指定的输出字段。

  • Schema 中未定义的字段

    您可在过滤表达式（filter）中加入动态字段（dynamic field）。以下代码示例中，color 是未在 schema 中定义的字段，可以通过 $meta 魔术字段的来访问，如 $meta["color"]，或像其他 schema 中已定义字段那样直接使用，如 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"
    #             }
    #         }
    #     ]
    # ]

标量查询（query）​

不同于向量相似性搜索（search），scalar query 是指基于过滤表达式的标量过滤检索。

  • 过滤查询 schema 中已定义的字段

    # 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
    #     }
    # ]

  • 过滤查询 schema 中未定义的字段

    # 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
    #     }
    # ]

Get entity​

若已知 entity ID，可通过以下示例代码获取（get）entity 信息：

# 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 接口。

删除 entity​

您可以通过 ID 或过滤表达式删除 entity。

  • 通过 ID 删除 entity

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

    print(res)

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

  • 通过过滤表达式删除 entity

    # 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 接口暂不支持过滤表达式。

删除 collection​

本指南完成后，您可以如下操作来删除 collection：

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

client.drop_collection(
    collection_name="customized_setup"
)

总结​

  • 有两种方法可以创建 collection：快速创建仅需要您指定 collection 名称和向量维度；自定义创建则允许您定制 collection 的各项配置。

  • 插入数据可能需要些时间，因此建议在插入数据后等待几秒钟再进行相似性搜索。

  • 过滤表达式同时适用于搜索（search）和查询（query）请求，但在查询（query）请求时必须使用。