接口定义
CreateCollection()
用于为已创建的 Base 类向量数据库创建 Collection。创建一个新的 Collection 需要指定所需的副本、分片、索引字段等关键参数,如果应用 Embedding 功能,则还需配置文本向量化模型及其相关字段。CreateCollection(ctx context.Context, name string, shardNum uint32, replicasNum uint32, description string, indexes tcvectordb.Indexes, params ...*tcvectordb.CreateCollectionParams) (*tcvectordb.Collection, error)
构建索引结构
创建 Collection 之前,需要为集合构建索引结构。
必须构建唯一的 Document id 为主键索引,用于快速查找特定行的数据。
必须构建 vector 向量数据索引,指定索引类型,当前支持 FLAT、HNSW、 IVF 系列向量索引方式。如何选择,请参见 Index。
选取需要使用 Filter 表达式高效过滤数据的标量字段。
说明:
不做过滤查询、检索的标量字段不必建立 Filter 索引。切勿将所有标量字段建立索引,导致内存资源的浪费。
插入数据时动态增加的标量字段暂不支持创建索引。创建 Collection 时,需规划好 Filter 索引的字段。
index := tcvectordb.Indexes{// 指定embedding时,vector的维度可以不传,系统会使用embedding model的维度VectorIndex: []tcvectordb.VectorIndex{{FilterIndex: tcvectordb.FilterIndex{FieldName: "vector",FieldType: tcvectordb.Vector,IndexType: tcvectordb.HNSW,},MetricType: tcvectordb.COSINE,Params: &tcvectordb.HNSWParam{M: 16,EfConstruction: 200,},},},SparseVectorIndex: []tcvectordb.SparseVectorIndex{{FieldName: "sparse_vector",FieldType: tcvectordb.SparseVector,IndexType: tcvectordb.SPARSE_INVERTED,MetricType: tcvectordb.IP,},},FilterIndex: []tcvectordb.FilterIndex{{FieldName: "id",FieldType: tcvectordb.String,IndexType: tcvectordb.PRIMARY,},{FieldName: "bookName",FieldType: tcvectordb.String,IndexType: tcvectordb.FILTER,},{FieldName: "author",FieldType: tcvectordb.String,IndexType: tcvectordb.FILTER,},{FieldName: "tags",FieldType: tcvectordb.Array,IndexType: tcvectordb.FILTER,},},}
参数 | 子参数 | 是否必选 | 参数含义 |
FilterIndex | FieldName | 否 | 配置可作为 Filter 索引的自定义扩展的标量字段名。 说明: Filter 索引(Filter Index)对标量字段建立的索引。标量字段名称、类型均由用户自定义,不限制标量字段数量. 标量字段被建立 Filter 索引之后,向量检索时,将依据 Filter 指定的标量字段的条件表达式进行过滤查询和范围查询以此来匹配相似向量。 建立 Filter 索引时,选取需要使用 Filter 表达式高效过滤数据的标量字段。不做过滤查询、检索的标量字段不必建立 Filter 索引。切勿将所有标量字段建立索引,导致内存资源的浪费。 必须构建唯一的 Document id 为主键的 Filter 索引,配置 name 固定为 id 。 配置其他自定义扩展的可作为 Filter 索引的标量字段,例如:author、page 等。该标量字段名称、类型均由用户自定义,且不限制字段数量。 |
| FiledType | 是 | 指定 Filter 字段的数据类型。当前支持如下类型: String:字符型。若 name 为 id,则该参数固定为
tcvectordb.String。 Uinit64:指无符号整数,该参数可设置为 tcvectordb.Uint64。 Array:数组类型。该参数可设置为 tcvectordb.Array,数组元素默认为 String。 |
| IndexType | 是 | 指定 Filter 字段的索引类型。 若 FieldName 为 id,该参数固定配置为 tcvectordb.PRIMARY,即以 id 为主键构建索引。 若 FieldName 为其他自定义的标量字段,该参数设置自定义字段的索引类别。该字段设置为 tcvectordb.FILTER,在后续检索数据时,才能对该字段设置 Filter 条件表达式进行 混合检索。 |
VectorIndex | FieldName | 是 | 指定向量数据的索引字段为 vector。 |
| FiledType | 是 | 指定向量索引的数据类型,固定为 tcvectordb.Vector。 |
| IndexType | 是 | FLAT:暴力检索,召回率100%,但检索效率低。 HNSW:可通过参数调整召回率,检索效率高,但数据量大后写入效率会变低。具体测试数据,请参见性能白皮书的测试结果。 IVF_FLAT、IVF_PQ、IVF_SQ4、IVF_SQ8、IVF_SQ16:IVF 系列索引,适用于上亿规模的数据集,检索效率高,内存占用低,写入效率高。 |
| Dimension | 是 | 指定向量数据维度。 取值类型:uint 64。 取值范围:[1,4096]。 配置建议:维度建议为4的整数倍,字节对齐有助于提升搜索性能。维度越高,存储成本越高,检索效率越低。 |
| MetricType | 是 | 指定目标向量与查询向量之间距离度量的相似性算法。取值如下: L2:全称是 Euclidean distance,指欧几里得距离,它计算向量之间的直线距离,所得的值越小,越与搜索值相似。L2在低维空间中表现良好,但是在高维空间中,由于维度灾难的影响,L2的效果会逐渐变差。 IP:全称为 Inner Product,是一种计算向量之间相似度的度量算法,它计算两个向量之间的点积(内积),所得值越大越与搜索值相似。 COSINE:余弦相似度(Cosine Similarity)算法,是一种常用的文本相似度计算方法。它通过计算两个向量在多维空间中的夹角余弦值来衡量它们的相似程度。所得值越大越与搜索值相似。 |
| Params | 否 | 如果索引类型 indexType 为 HNSW ,则需配置如下 HNSWParams 参数。 M:每个节点在检索构图中可以连接多少个邻居节点。 取值类型:uint64。 取值范围:[4,64]。默认为16。 EfConstruction:搜索时,指定寻找节点邻居遍历的范围。数值越大构图效果越好,构图时间越长。 取值类型:uint64。 取值范围:[8,512]。默认为200。 |
| | 否 | 索引类型 indexType 分别为 IVF_FLAT、 IVF_PQ、 IVF_SQ4、 IVF_SQ8、 IVF_SQ16,则分别对应配置如下 IVFFLATParams、IVFPQParams、IVFSQ8Params 参数。 NList :指索引中的聚类中心数量。 取值类型:uint64。 取值范围:[1,65536]。 M: 指乘积量化中原始数据被拆分的子向量的数量。该参数仅 IVF_PQ 索引类型需配置。更多信息,请参见 索引与计算。 取值要求:原始向量的维度 D(即向量中元素的个数)必须能够被 m 整除,m 必须是一个正整数。 取值范围:[1,向量维度]。 |
SparseVectorIndex | FieldName | 否 | 可选择构建稀疏向量索引,字段名固定为 sparse_vector。 每个集合仅支持创建1个稀疏向量索引,无需指定稀疏向量维度。 |
| FiledType | 否 | 稀疏向量字段类型固定为 tcvectordb.SparseVector。 |
| IndexType | 否 | 稀疏向量索引类型固定为 tcvectordb.SPARSE_INVERTED。 |
| MetricType | 否 | 稀疏向量创建索引,当前仅支持设置为 IP 与COSINE。 |
(可选)配置 Embedding 参数
如果创建 Embedding 集合,则需配置其相关参数,如下示例,指定文本输入字段 text,向量数据字段为 vector,选择 Embedding 模型 BGE_BASE_ZH。
// 设置embedding字段和模型param := &tcvectordb.CreateCollectionParams{Embedding: &tcvectordb.Embedding{Field: "text",VectorField: "vector",Model: tcvectordb.BGE_BASE_ZH,},}
参数名 | 是否必选 | 参数含义 |
Model | 否 | BGE_BASE_ZH:适用中文,768维,推荐使用。 M3E_BASE:适用中文,768维。 E5_LARGE_V2:适用英文,1024维。 TEXT2VEC_LARGE_CHINESE:适用中文,1024维。 MULTILINGUAL_E5_BASE:适用于多种语言类型,768维。 |
Field | 否 | 指定文本字段名称。取值类型:String。 说明: 写入数据或更新数据时,Embedding 模型会自动将该字段的文本内容转换成向量数据。 |
VectorField | 否 | 指定向量字段。通过 Embedding 模型生成的向量会自动存储在该字段中。固定为 vector 。 |
创建 Collection
说明:
当前版本一个数据库实例下,不支持创建同名的 Collection。
创建 Collection 时可以根据预估数据规模和业务需求,指定集合的副本数和分片数。
分片数量:可根据数据规模判断,单分片数据量建议控制在300万以内,例如,若某个 Collection 有500万向量,可设置2个分片。如果数据量小于300万,建议使用1分片。系统对1分片有特定优化,可显著提升性能。当前支持的分片数量最小为1分片,最大为100分片。
副本数量:可以根据业务容灾以及吞吐量来判断,当前支持的副本数量两可用区最少为1个(不包含主节点),三可用区最少为2个,最大不超过实例的节点数量。搜索请求量越高的索引,建议设置越多的副本数,避免负载不均衡。并且,副本默认为可读,可以分担主节点的读压力,提升系统性能。
如下示例,创建 Embedding 的集合,指定 Embedding
var (ctx = context.Background()database = "go-sdk-test-db"embeddingCollection = "go-sdk-test-emcoll")db := client.Database(database)coll, _ := db.CreateCollection(ctx, embeddingCollection, 1, 0, "desription doc", index, param)log.Printf("CreateCollection success: %v: %v", coll.DatabaseName, coll.CollectionName)
var (ctx = context.Background()database = "go-sdk-test-db"collectionName = "book-vector")db := client.Database(database)coll, _ := db.CreateCollection(ctx, collectionName, 1, 0, "test collection", index)log.Printf("CreateCollection success: %v: %v", coll.DatabaseName, coll.CollectionName)
参数 | 参数含义 | 是否必选 | 配置要求 |
name | 指定 Collection 的名称。 | 是 | Collection 命名要求如下: 只能使用英文字母,数字,下划线_、中划线-,并以英文字母开头。 长度要求:[1,128]。 |
replicaNum | 指定 Collection 的副本数。副本数是指每个主分片有多个相同的备份,用来容灾和负载均衡。 | 是 | 取值类型:int。 取值范围:[2,9]。例如:5。 |
shardNum
| 指定 Collection 的分片数。分片是把大数据集切成多个子数据集。 | 是 | 取值类型:int。 取值范围:[1,100]。例如:5。 |
description | 指定 Collection 的描述信息。 | 否 | 取值类型:string。 字符长度要求:[1,256]。 示例:this is the collection description。 |
TtlConfig | 标识数据库是否开启 TTL 配置,指定存储数据过期时间戳字段名。 | 否 | Enable:标识数据库是否开启 TTL 属性。 true:开启。 false:关闭。 |
| | | TimeField:指定存储数据过期时间戳的字段名。插入数据时,以标准的 Unix 时间戳指定该字段的值。字段名要求如下: 数据类型:unit64。 索引类型:Filter 索引。 示例:expired_at。
|
返回结果
CreateCollection() 执行之后,如果抛出异常,说明创建 Collection 失败。具体异常原因,可根据提示信息进行分析。无任何提示信息说明创建 Collection 执行成功,可使用 listCollections() 查看已经创建的 Collection 配置信息。