Method 与 URL
在已创建的 Base 类 Database 中创建 Collection:
POST https://{实例访问 IP 地址}:{实例网络端口}/collection/create
。使用示例
注意:
如下示例 api_key 的值 A5VOgsMpGWJhUI0WmUbY******************** 与 10.0.X.X,需要分别替换为具体实例的 API Key 以及访问地址。
创建一个名为 book-vector 的集合,不配置 Embedding 模型相关参数,用于写入 3 维向量数据。
curl -i -X POST \\-H 'Content-Type: application/json' \\-H 'Authorization: Bearer account=root&api_key=A5VOgsMpGWJhUI0WmUbY********************' \\http://10.0.X.X:80/collection/create \\-d '{"database": "db-test","collection": "book-vector","replicaNum": 0,"shardNum": 1,"description": "this is the collection description","indexes": [{"fieldName": "id","fieldType": "string","indexType": "primaryKey"},{"fieldName": "vector","fieldType": "vector","indexType": "HNSW","dimension": 3,"metricType": "COSINE","params": {"M": 16,"efConstruction": 200}},{"fieldName": "sparse_vector","fieldType": "sparseVector","indexType": "inverted","metricType": "IP"},{"fieldName": "bookName","fieldType": "string","indexType": "filter"},{"fieldName": "author","fieldType": "string","indexType": "filter"}]}'
创建一个名为 book-emb 的集合 ,配置 Embedding 模型相关参数,用于写入原始文本。Embedding 模型自动将原始文本进行向量化。
curl -i -X POST \\-H 'Content-Type: application/json' \\-H 'Authorization: Bearer account=root&api_key=A5VOgsMpGWJhUI0WmUbY********************' \\http://10.0.X.X:80/collection/create \\-d '{"database": "db-test","collection": "book-emb","replicaNum": 0,"shardNum": 1,"description": "this is the collection description","embedding": {"field": "text","vectorField": "vector","model": "bge-base-zh"},"indexes": [{"fieldName": "id","fieldType": "string","indexType": "primaryKey"},{"fieldName": "vector","fieldType": "vector","indexType": "HNSW","metricType": "COSINE","params": {"M": 16,"efConstruction": 200}},{"fieldName": "sparse_vector","fieldType": "sparseVector","indexType": "inverted","metricType": "IP"},{"fieldName": "bookName","fieldType": "string","indexType": "filter"},{"fieldName": "author","fieldType": "string","indexType": "filter"}]}'
请求参数
参数 | 参数含义 | 子参数 | 是否必选 | 参数配置 |
database | 指定 Collection 所在的 Database 名称。 | - | 是 | |
collection | 指定 Collection 的名称。 | - | 是 | Collection 命名要求如下: 只能使用英文字母,数字,下划线_、中划线-,并以英文字母开头。 长度要求:[1,128]。 |
replicaNum | 指定 Collection 的副本数。副本数是指每个主分片有多个相同的备份,用来容灾和负载均衡。
| - | 是 | 取值类型:uint64。 取值范围如下所示。搜索请求量越高的索引,建议设置越多的副本数,避免负载不均衡。 单可用区实例:0。 两可用区实例:[1,节点数-1]。 三可用区实例:[2,节点数-1]。 |
shardNum
| 指定 Collection 的分片数。分片是把大数据集切成多个子数据集。 | - | 是 | 取值类型:uint64。 取值范围:[1,100]。例如:5。 配置建议:在搜索时,全部分片是并发执行的,分片数量越多,平均耗时越低,但是过多的分片会带来额外开销而影响性能。 单分片数据量建议控制在300万以内,例如500万向量,可设置2个分片。 如果数据量小于300万,建议使用1分片。系统对1分片有特定优化,可显著提升性能。 |
embedding
| 配置 Embedding 参数 说明: 使用 Embedding 功能才需要配置该参数。 |
field | 否 | 指定文本字段名称。 取值类型为:string 字符型。当前仅支持文本到向量的 Embedding 能力。 写入(/document/upsert/)、更新(/document/update)或者检索(/document/search)数据时,Embedding 模型会自动将该字段的文本内容转换成向量数据。 |
| | vectorField | 否 | 指定向量字段。通过 Embedding 模型生成的向量会自动存储在该字段中。固定为 vector 。 |
| | model | 否 | 取值如下所示: bge-base-zh:适用中文,768维,推荐使用。 m3e-base:适用中文,768维。 e5-large-v2:适用英文,1024维。 text2vec-large-chinese:适用中文,1024维。 multilingual-e5-base:适用于多种语言类型,768维。 |
description | 指定 Collection 的描述信息 | - | 否 | 取值类型:string。 字符长度要求:[1,256]。 示例:this is the collection description。 |
indexes 说明: 创建 Collection需根据不同 Index 类型指定索引字段。 | 主键索引 说明: | fieldName | 是 | 指定索引对象为文档 id 。即该参数固定配置为 id 。 |
| | fieldType | 是 | 指定索引对象的数据类型。该参数固定为 string 。 |
| | indexType | 是 | 指定索引对象的索引类型。该参数固定配置为 primaryKey ,即默认以 id 为主键构建索引。 |
| 向量索引 说明: | fieldName | 是 | 指定索引对象为 vector。该参数固定配置为 vector 。 |
| | fieldType | 是 | 指定索引对象为 vector 的数据类型。该参数固定为 vector 。 |
| | indexType | 是 | FLAT:暴力检索,召回率100%,但检索效率低。 HNSW:可通过参数调整召回率,检索效率高,但数据量大后写入效率会变低。具体测试数据,请参见性能白皮书的 测试结果。 IVF_FLAT、IVF_PQ、IVF_SQ4, IVF_SQ8, IVF_SQ16:IVF 系列索引,适用于上亿规模的数据集,检索效率高,内存占用低,写入效率高。 注意: 如果选择 IVF 系列索引类型,那么,请务必在 /document/upsert 插入数据时,将参数 buildIndex 设置为 false,在插入数据之后,通过 /Index/rebuild 重建索引。具体操作,请参见 应用 IVF 系列索引。 |
| | dimension | 否 | 指定向量维度。 取值类型:uint64。 取值范围:[1,4096]。 配置建议:维度建议为4的整数倍,字节对齐有助于提升搜索性能。维度越高,存储成本越高,检索效率越低。 说明:
使用 Embedding 功能,则无需配置该字段。该参数将自动配置为 Embedding 模型对应的向量维度。 |
| | metricType | 是 | 指定向量之间距离度量的算法。取值如下: L2:全称是 Euclidean distance,指欧几里得距离,它计算向量之间的直线距离,所得的值越小,越与搜索值相似。L2在低维空间中表现良好,但是在高维空间中,由于维度灾难的影响,L2的效果会逐渐变差。 IP:全称为 Inner Product,是一种计算向量之间相似度的度量算法,它计算两个向量之间的点积(内积),所得值越大越与搜索值相似。 COSINE:余弦相似度(Cosine Similarity)算法,是一种常用的文本相似度计算方法。它通过计算两个向量在多维空间中的夹角余弦值来衡量它们的相似程度,所得值越大越与搜索值相似。 |
| | params | 是 | 指定索引类型参数。 索引类型 indexType 为 HNSW ,需配置如下参数。 M:每个节点在检索构图中可以连接多少个邻居节点。 取值类型:uint64。 取值范围:[4,64]。一般可设置为16。 efConstruction:搜索时,指定寻找节点邻居遍历的范围。数值越大构图效果越好,构图时间越长。 取值类型:uint64。 取值范围:[8,512]。一般可设置为200。 索引类型 indexType 为 IVF_FLAT、 IVF_PQ、 IVF_SQ4, IVF_SQ8, IVF_SQ16需配置如下参数。 nlist :指索引中的聚类中心数量。 取值类型:uint64。取值范围:[1,65536]。 M: 指乘积量化中原始数据被拆分的子向量的数量。该参数仅 IVF_PQ 索引类型需配置。更多信息,请参见 索引与计算。 取值要求:原始数据的向量的维度 D(即向量中元素的个数)必须能够被 m 整除,m 必须是一个正整数。 取值范围:[1,向量维度]。 |
| Filter 索引 | fieldName | 是 | 配置可作为 Filter 索引的自定义扩展的标量字段名。 说明: Filter 索引(Filter Index)是建立在标量字段的索引。该标量字段名称、类型均由用户自定义,不限制标量字段数量。 标量字段被建立 Filter 索引之后,向量检索时,将依据 Filter 指定的标量字段的条件表达式进行过滤查询和范围查询以此来匹配相似向量。 |
| | fieldType | 是 | 指定自定义字段的数据类型。取值如下: string:字符型。 uint64:指无符号整数(unsigned integer)。 array:数组类型,数组元素为 string。 |
| |
indexType
| 是 | 指定自定义扩展的字段是否需要设置 Filter 索引。若需要设置,请将该参数设置为 filter ,那么在通过 /document/search 检索相似数据时,可对该字段设置 Filter 条件表达式进行 混合检索。注意: 建立 Filter 索引时,选取需要使用 Filter 表达式高效过滤数据的标量字段。不做过滤查询、检索的标量字段不必建立 Filter 索引。切勿将所有标量字段建立索引,导致内存资源的浪费。 |
| 稀疏向量索引 | fieldName | 否 | 稀疏向量的字段名,可自定义。 |
| | fieldType | 否 |
稀疏向量字段类型,固定为 sparseVector。
|
| |
indexType
| 否 |
稀疏向量的索引类型,当前定义为 inverted。
|
| | metricType | 否 | 稀疏向量之间距离度量的算法。当前仅支持设置为 IP, 欧几里得距离,计算向量之间的直线距离,所得的值越小,越与搜索值相似。 |
ttlConfig | 配置 TTL 属性 | enabled | 否 | 标识数据库是否开启 TTL 配置。 true:开启。 false:关闭。 |
| | timeField | 否 | 指定存储数据过期时间戳的字段名。插入数据时,以标准的 Unix 时间戳指定该字段的值。字段名要求如下: 数据类型:unit64。 索引类型:Filter 索引。 示例:expired_at,则在 upsert 时,需指定 expired_at 值。 |
响应消息
执行成功,输出如下信息。
{"code":0,"msg":"Operation success","affectedCount":1}
参数名 | 参数含义 |
affectedCount | 影响行数,即为创建集合数量。 |