跳到主要内容

管理 Collection (SDK)

本指南将介绍如何通过各种语言的 SDK 创建和管理 Collection。Zilliz Cloud Web 控制台操作更简单直观，但使用 SDK 可提供更多灵活性。

前提条件​

概述​

在 Zilliz Cloud 中您通过 Collection 来存储 Embedding 向量。同一个 Collection 中的所有 Embedding 向量维度相同，且使用同样的相似性类型来计算向量距离和相似性。

Zilliz Cloud Collection 支持动态列（即支持插入未在 Schema 中预先定义的字段数据） 和自动生成的主键列。

为了满足不同的用户需求，Zilliz Cloud 提供两种创建 Collection 的方式——快速创建 Collection 和自定义 Collection Schema 和索引参数。

此外，您还可以通过 SDK 查看、加载、释放、删除 Collection。

创建 Collection​

您可以通过以下任意一种方式创建 Collection：

  • 快速创建

    您只需要设置 Collection 名称和向量维度即可快速完成 Collection 创建。更多详情，请参考快速创建。

  • 定制化创建

    您可以自定义 Schema 和索引参数。更多详情，请参考定制化创建。

快速创建​

Zilliz Cloud 提供快速创建 Collection 的方式。您只需定义以下三个参数：

  • 创建的 Collection 的名称

  • 向量数据的维度

  • 用于计算向量距离的相似度类型

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 
)

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

res = client.get_load_state(
    collection_name="quick_setup"
)

print(res)

# Output
#
# {
#     "state": "<LoadState: Loaded>"
# }

上述代码生成的 Collection 仅包含 2 个字段：id (主键字段) 和 vector (向量字段)。auto_id 和 enable_dynamic_field 功能已默认开启。

  • auto_id

    开启后，系统会自动为插入数据分配自增主键。因此，您无需在插入数据时额外提供主键。

  • enable_dynamic_field

    开启后，插入数据中除 id 和 vector 以外的字段都将被视作为动态列。这些字段将以键值对的形式存储在 $meta 字段中。动态列功能开启后，您可以在插入数据时包含未在 Schema 中预先定义的额外字段。

以上创建的 Collection 会自动创建索引和加载，可立即向 Collection 中插入数据。

定制化创建​

除了使用快速创建以外，您还可以自定义 Collection 的 Schema 和索引参数。

步骤 1: 设置 Schema​

Schema 用于定义 Collection 结构。您可以在设置 Schema 时选择是否开启动态列 enable_dynamic_field、添加预定义的字段、设置每个字段的属性。如需了解 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)

在上述代码中，enable_dynamic_field 设置为 True，主键列也开启了 auto_id。此外，上述代码还添加了一个维度为 768 的 vector 字段和 4 个标量字段。

步骤 2: 设置索引参数​

索引参数规定了Zilliz Cloud 如何组织 Collection 中的数据。您可以通过调整 metric_type 和 index_type 这两个参数来选择合适的相似度类型和索引类型。在 Zilliz Cloud 中，我们使用推荐使用 AUTOINDEX 作为index_type。对于向量字段，您可以按需灵活选择 COSINE、 L2、 IP 作为 metric_type。更多关于索引类型详情，请参考 AUTOINDEX。

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

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

index_params.add_index(
    field_name="my_vector", 
    index_type="IVF_FLAT",
    metric_type="IP",
    params={ "nlist": 128 }
)

上述代码展示了如何为向量字段和标量字段设置索引参数。向量字段需要同时设置 index_type 和 metric_type。标量字段仅需设置 index_type。我们建议您为向量字段和在过滤时常用的标量字段创建索引。

步骤 3：创建 Collection​

您可以选择分开创建 Collection 和索引文件，或在 Collection 创建的同时创建和加载索引文件。

  • 创建 Collection 并同时加载索引

    # 3.5. Create a collection with the index loaded simultaneously
    client.create_collection(
        collection_name="customized_setup_1",
        schema=schema,
        index_params=index_params
    )

    time.sleep(5)

    res = client.get_load_state(
        collection_name="customized_setup_1"
    )

    print(res)

    # Output
    #
    # {
    #     "state": "<LoadState: Loaded>"
    # }

    以上创建的 Collection 已自动加载。如需了解如何手动加载或释放 Collection，请参考加载和释放 Collection。

  • 分开创建 Collection 和索引文件

    # 3.6. Create a collection and index it separately
    client.create_collection(
        collection_name="customized_setup_2",
        schema=schema,
    )

    res = client.get_load_state(
        collection_name="customized_setup_2"
    )

    print(res)

    # Output
    #
    # {
    #     "state": "<LoadState: NotLoad>"
    # }

    以上创建的 Collection 未自动加载。您可以通过以下命令为上述 Collection 创建索引。分开创建的 Collection 和索引将不会自动加载。如需了解如何加载 Collection，请参考加载和释放 Collection。

    # 3.6 Create index
    client.create_index(
        collection_name="customized_setup_2",
        index_params=index_params
    )

    res = client.get_load_state(
        collection_name="customized_setup_2"
    )

    print(res)

    # Output
    #
    # {
    #     "state": "<LoadState: NotLoad>"
    # }

使用多向量字段 (Beta)​

创建包含多个向量字段的 colletion 的过程与定制化创建相似。要创建包含多个向量字段（最多 4 个）的 collection，您需要定义 collection 中所有向量字段的配置。Collection 中的每个向量字段都有自己的名称和用于衡量数据相似度的度量类型。有关向量数据类型和度量的更多信息，请参见相似性度量和 Schema。

📘说明

此功能目前仅适用于已升级到 Beta 版的 Zilliz Cloud 集群。

以下示例代码展示了如何创建包含两个向量字段（text_vector 和 image_vector）的 collection。

# Create a collection with multiple vector fields

schema = client.create_schema(
    auto_id=False,
    enable_dynamic_field=True,
)

# Add primary key field to schema
schema.add_field(field_name="my_id", datatype=DataType.INT64, is_primary=True)

# Add vector field 1 to schema
# The dim value should be an integer greater than 1.
# Binary vector dimensions must be a multiple of 8
schema.add_field(field_name="text_vector", datatype=DataType.BINARY_VECTOR, dim=8)

# Add vector field 2 to schema
# The dim value should be an integer greater than 1.
schema.add_field(field_name="image_vector", datatype=DataType.FLOAT_VECTOR, dim=128)

# Output:
# {'auto_id': False, 'description': '', 'fields': [{'name': 'my_id', 'description': '', 'type': <DataType.INT64: 5>, 'is_primary': True, 'auto_id': False}, {'name': 'text_vector', 'description': '', 'type': <DataType.BINARY_VECTOR: 100>, 'params': {'dim': 8}}, {'name': 'image_vector', 'description': '', 'type': <DataType.FLOAT_VECTOR: 101>, 'params': {'dim': 128}}], 'enable_dynamic_field': True}

在上述示例代码中，

  • create_schema 方法用于为 collection 定义新的 schema，auto_id 设置为 False，并启用动态字段。

  • 向 schema 中添加了一个类型为 INT64 的主键字段 my_id。

  • 添加了两个向量字段：text_vector（维度为 8 的二进制向量）和 image_vector（维度为 128 的浮点向量）。

📘说明

对于 BINARY_VECTOR 类型的向量字段，

  • 维度值（dim）必须是 8 的倍数；

  • 可用的度量类型为 HAMMING 和 JACCARD。

定义 schema 后，您可以分别为每个向量字段创建索引。以下示例代码演示了如何为向量字段 text_vector 和 image_vector 添加索引。

# Prepare index parameters

index_params = client.prepare_index_params()

index_params.add_index(
    field_name="text_vector", 
    # In Zilliz Cloud, the index type should always be `AUTOINDEX`.
    index_type="AUTOINDEX", 
    # For vector of the `BINARY_VECTOR` type, use `HAMMING` or `JACCARD` as the metric type.
    metric_type="HAMMING", 
    params={ "nlist": 128 }
)

index_params.add_index(
    field_name="image_vector", 
    index_type="AUTOINDEX",
    metric_type="IP",
    params={ "nlist": 128 }
)

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

在上述示例代码中，

  • prepare_index_params 方法用于准备索引参数。

  • 为两个向量字段添加索引：text_vector 使用 HAMMING 作为度量类型，image_vector 使用 IP（内积）。

  • create_collection 方法创建具有指定 schema 和索引的 collection。

📘说明

对于 BINARY_VECTOR 类型的向量字段，

  • 维度值（dim）必须是 8 的倍数；

  • 可用的度量类型为 HAMMING 和 JACCARD。

查看 Collection​

您可以通过以下命令查看现有 Collection 详情。

# 5. View Collections
res = client.describe_collection(
    collection_name="customized_setup_2"
)

print(res)

# Output
#
# {
#     "collection_name": "customized_setup_2",
#     "auto_id": false,
#     "num_shards": 1,
#     "description": "",
#     "fields": [
#         {
#             "field_id": 100,
#             "name": "my_id",
#             "description": "",
#             "type": 5,
#             "params": {},
#             "element_type": 0,
#             "is_primary": true
#         },
#         {
#             "field_id": 101,
#             "name": "my_vector",
#             "description": "",
#             "type": 101,
#             "params": {
#                 "dim": 5
#             },
#             "element_type": 0
#         }
#     ],
#     "aliases": [],
#     "collection_id": 448143479230158446,
#     "consistency_level": 2,
#     "properties": {},
#     "num_partitions": 1,
#     "enable_dynamic_field": true
# }

To list all existing collections, you can do as follows:

# 6. List all collection names
res = client.list_collections()

print(res)

# Output
#
# [
#     "customized_setup_2",
#     "quick_setup",
#     "customized_setup_1"
# ]

加载和释放 Collection​

Collection 加载过程中，Zilliz Cloud 会将 Collection 的索引文件加载到内存中。反之，在 Collection 释放过程中， Zilliz Cloud 会将 Collection 索引文件从内存中释放。在执行搜索前，请确保 Collection 处于已加载的状态。

加载 Collection​

# 7. Load the collection
client.load_collection(
    collection_name="customized_setup_2"
)

res = client.get_load_state(
    collection_name="customized_setup_2"
)

print(res)

# Output
#
# {
#     "state": "<LoadState: Loaded>"
# }

释放 Collection​

# 8. Release the collection
client.release_collection(
    collection_name="customized_setup_2"
)

res = client.get_load_state(
    collection_name="customized_setup_2"
)

print(res)

# Output
#
# {
#     "state": "<LoadState: NotLoad>"
# }

设置 Collection 别名（Alias）​

您可以按需设置 Collection 别名（Alias）。一个 Collection 可以有多个 Alias。但是多个 Collection 不可共享同一个 Alias。

创建 Alias​

# 9. Manage aliases
# 9.1. Create aliases
client.create_alias(
    collection_name="customized_setup_2",
    alias="bob"
)

client.create_alias(
    collection_name="customized_setup_2",
    alias="alice"
)

查看现有 Alias​

# 9.2. List aliases
res = client.list_aliases(
    collection_name="customized_setup_2"
)

print(res)

# Output
#
# {
#     "aliases": [
#         "bob",
#         "alice"
#     ],
#     "collection_name": "customized_setup_2",
#     "db_name": "default"
# }

查看 Alias 详情​

# 9.3. Describe aliases
res = client.describe_alias(
    alias="bob"
)

print(res)

# Output
#
# {
#     "alias": "bob",
#     "collection_name": "customized_setup_2",
#     "db_name": "default"
# }

重新分配 Alias​

# 9.4 Reassign aliases to other collections
client.alter_alias(
    collection_name="customized_setup_1",
    alias="alice"
)

res = client.list_aliases(
    collection_name="customized_setup_1"
)

print(res)

# Output
#
# {
#     "aliases": [
#         "alice"
#     ],
#     "collection_name": "customized_setup_1",
#     "db_name": "default"
# }

res = client.list_aliases(
    collection_name="customized_setup_2"
)

print(res)

# Output
#
# {
#     "aliases": [
#         "bob"
#     ],
#     "collection_name": "customized_setup_2",
#     "db_name": "default"
# }

删除 Alias​

# 9.5 Drop aliases
client.drop_alias(
    alias="bob"
)

client.drop_alias(
    alias="alice"
)

删除 Collection​

您可以删除不再使用的 Collection。

# 10. Drop the collections
client.drop_collection(
    collection_name="quick_setup"
)

client.drop_collection(
    collection_name="customized_setup_1"
)

client.drop_collection(
    collection_name="customized_setup_2"
)

Collection 限制​

集群类型

Collection 最大数量

描述

Free

5

您最多可创建 5 个 Collection。

Serverless

100

您最多可创建 100 个 Collection。

Dedicated

每 CU：<= 64

每集群：<= 4096

在企业版集群中，每个计算单元（CU）可创建最多 64 个 Collection，并且集群中的 Collection 总数不能超过 4096。

除了对集群中 Collection 数量的限制外，Zilliz Cloud 还有容量资源相关的限制。具体见下表。

CU 数量

容量

1-8 CU

<= 4,096

12 CU 及以上

Min(512 x CU 数, 65536)

如需了解如何计算集群的已使用容量和通用容量，请查看使用限制。