跳到主要内容
版本：Cloud 开发指南

快速开始

本指南演示如何使用 Zilliz Cloud 集群高效执行语义检索的相关操作。

如下步骤假设您已经创建了 Zilliz Cloud 集群，获取了可以访问该集群的 API Key 或鉴权凭据，并安装了相关 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 
)

创建 collection​

在 Zilliz Cloud， 您需要将向量数据存储到 collection 中。同一个 collection 中的向量数据具有相同的维度和相似度测量指标。

在创建 collection 时，您需要详细定义每个字段的属性，如字段名称、数据类型和其他属性。另外，您还可以选择为需要加速检索的字段创建索引。其中，向量字段必须创建索引。

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

通过以上代码，您可以自由定义 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。

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

插入数据​

在准备好 collection 后，您可以参考如下示例向其中插入数据。

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

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

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

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

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

📘说明

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

  • 插入数据为异步操作。在插入数据后立即进行检索，检索结果可能为空。建议您在插入数据后等待一段时间。

您可以基于一条或多条向量 embedding 执行相似性搜索（search）。您还可以在搜索请求中携带过滤条件来增强搜索结果。

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

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

您还可以在过滤表达式（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="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"
#             }
#         }
#     ]
# ]

删除 entity​

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

  • Delete entities by IDs.

    # 13. Delete entities by IDs
    res = client.delete(
        collection_name="custom_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="custom_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="custom_setup"
)

client.drop_collection(
    collection_name="customized_setup"
)

总结​

  • 在创建 collection 前，您需要为 collection 定义 schema，和各字段的相关配置。

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

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

后续操作​