CreateCollection--向量数据库VikingDB-火山引擎

文档中心

立即注册

导航

CreateCollection

最近更新时间：2025.02.28 23:20:13首次发布时间：2024.04.17 14:21:09

概述

CreateCollection 用于创建一个新的数据集 Collection。创建成功后，可以写入数据。

说明

每一个 Collection 必须指定主键字段。
当定义字段 fields 添加了一个向量类型 vector 的字段后，再添加新的字段时，字段类型不可选择 vector 类型。因为目前只支持单向量，不可添加多个向量字段。
推荐通过 vectorize 参数对图片和文本数据进行向量化，已使用 pipeline 进行文本向量化的用户，pipeline_name 子参数依然提供服务。
当定义字段 fields 添加了带 pipeline_name 的 text 字段，则不允许添加 vector 或 sparse_vector 字段，且只能有一个带 pipeline_name 的 text 字段；当定义字段 fields 添加了不带 pipeline_name 的 text 字段，则允许添加 vector 字段，且允许添加多个不带 pipeline_name 的 text 字段，最多200个。

请求参数

参数	子参数	类型	是否必选	默认值	参数说明
collectionName		string	是		指定创建的 Collection 名称。只能使用英文字母、数字、下划线_，并以英文字母开头，不能为空。长度要求：[1, 128]。 Collection 名称不能重复。
description		string	否	""	自定义 Collection 的描述。长度要求：[0, 65535]。
fields 说明 Field 实例的列表，一个 Collection 里的 Field 实例数量上限是 200。	FieldName	string	是		指定自定义字段的名称。只能使用英文字母、数字、下划线_，并以英文字母开头，不能为空。长度要求：[1, 128]。字段名称不能重复。
	FieldType	string	是		指定自定义字段类型，如 vikingDB.String，可选值详见 fieldType 可选值说明。
	DefaultVal	和 FieldType 一致	否		指定自定义字段默认值，默认值详见 FieldType 可选值说明。当 FieldName 作为主键时，DefaultVal 不生效，同时也不会被校验。
	Dim	int	FieldType 为vector 时必选		指定自定义字段向量维度。取值范围：[4, 4096]，且必须是 4 的倍数。向量维度是指向量中包含的元素的数量。
	IsPrimaryKey	bool	是	False	指定自定义字段是否为主键，主键用于唯一标识一行数据。仅当自定义字段类型为 int64 类型 / string 类型时支持设置其为主键。每个 Collection 有且仅有一个主键，其它字段 is_primary_key 默认为 False。若全部 fields 该字段均为 False，将自动生成主键。枚举值：True/False。
vectorize 注意如果有vectorize参数，则fields里不应填pipeline。	dense	map	否（填写 vectorize 时必选）	--	稠密向量的向量化参数。子参数见下"向量化参数"表。
vectorize 注意如果有vectorize参数，则fields里不应填pipeline。	sparse	map	否	--	稀疏向量的向量化参数。如果无需稀疏向量，则不必填写。子参数见下"向量化参数"表。

说明

推荐通过**vectorize参数**对文本进行向量化，已使用 pipeline 的用户，pipeline_name 子参数依然提供服务。

参数	子参数	类型	是否必选	默认值	参数说明
fields 注意如果使用了`vectorize`参数，则 fields 里不能使用pipeline_name。	PipelineName	string	field_type 为 text 时可选	--	文本。纯文本预处理能力 pipeline 是指向量数据库将文本切片、文本向量化、入库、存储自动化的预处理流程。支持以string形式写入原始数据。 pipeline_name 枚举值如下： text_doubao_embedding； text_doubao_embedding_and_m3； text_bge_large_zh； text_bge_m3； text_bge_large_and_m3。模型参数参考“模型列表”

参数

子参数

类型

是否必选

默认值

参数说明

fields

注意

如果使用了vectorize参数，则 fields 里不能使用pipeline_name。

PipelineName

string

field_type 为 text 时可选

文本。纯文本预处理能力 pipeline 是指向量数据库将文本切片、文本向量化、入库、存储自动化的预处理流程。支持以string形式写入原始数据。
pipeline_name 枚举值如下：

text_doubao_embedding；
text_doubao_embedding_and_m3；
text_bge_large_zh；
text_bge_m3；
text_bge_large_and_m3。

模型参数参考**“模型列表”**

fieldType 可选值

字段类型	可用索引类型	defaultVal默认值	数据写入时取值范围	defaultVal 取值范围	可为主键	说明
int64	枚举	0	int64 范围	int64 范围	是	整数
float32	范围	0.0	float32 范围	float32 范围	否	浮点数
string	枚举	"default"		长度<=128	是	字符串
bool	枚举	false	true/false	true/false	否	布尔类型
list<string>	枚举	["default"]	List 长度<=32	List 长度<=32	否	字符串数组
list<int64>	枚举	[0]	List 长度<=32	List 长度<=32	否	整数数组
vector	向量		维度 4-2048		否	稠密向量。 fieldType 设置为 vector 时必选参数 dim。
sparse_vector	稀疏向量		非零元下标无限制非零元值为 float32 范围		否	稀疏向量。 sparse_vector不能单独设置，必须与 vector 字段组合设置。接收形为<index,value>的json字典列表，来表示稀疏稀疏向量的关键词及其对应的权重值。示例： sparse_vector={"什么": 0.34, "是": 0.03, "B": 0.11, "M":0.32, "25": 0.03}
text					否	文本，可用于向量化。
image	--	--	--	--	否	当前支持写入tos路径。格式为：`tos://{bucket}/{object_key}`。可用于向量化。

注意

field_type 设置为 text 时可选参数 pipeline_name。
当定义字段 fields 添加了带 pipeline_name 的 text 字段，则不允许添加 vector 字段或 sparse_vector 字段，有一个带 pipeline_name 的 text 字段只能有各一个；当定义字段 fields 添加了不带 pipeline_name 的 text 字段，则允许添加 vector 和 sparse_vector 字段，且允许添加多个不带 pipeline_name 的 text 字段，字段最多200个。

向量化参数

参数名	类型	必选	默认值	备注
text_field	string	否	/	待向量化的文本字段
image_field	string	否	/	待向量化的图片字段
model_name	string	是	/	模型名称。对应下面“模型列表”的模型名称。
model_version	string	否	/	模型版本。如果某模型有多个版本，可指定具体版本。如果使用默认版本模型或该模型没有多版本，则无需填写该字段。
dim	int	否	/	如果需要生成稠密向量，指定向量维度。默认使用模型默认的维度。

注意

text_field和image_field的设置，与model的选择需要对应。例如，model_name选择了纯文本embedding模型，则不允许有image_field。

模型列表

模型名称	支持向量化类型	默认稠密向量维度	可选稠密向量维度	支持稀疏向量	need instruction	默认版本	可选版本
bge-large-zh	text	1024	1024	否	否
bge-m3	text	1024	1024	是	否
bge-visualized-m3	text_image、image	1024	1024	否	否
doubao-embedding	text	2048	512, 1024, 2048	否	是	240515	240515、240715
doubao-embedding-large	text	2048	512, 1024, 2048, 4096	否	是	240915	240915
doubao-embedding-vision	text_image、image 说明在纯图场景下也会有额外的少量文本token消耗（20tokens左右）	3072	3072	否	是	241215	241215

示例

请求参数

import (
        "fmt"
        "testing"
        "github.com/volcengine/volc-sdk-golang/service/vikingdb"
)

创建稠密向量+稀疏向量数据集

fields := []vikingdb.Field{
    {FieldName: "f_id", FieldType: vikingdb.String, IsPrimaryKey: true},  // 主键字段
    {FieldName: "f_int64", FieldType: vikingdb.Int64},  // 整型字段
    {FieldName: "f_vector", FieldType: vikingdb.Vector, Dim: 4},  // 向量字段，维度为 4
    {FieldName: "f_sparse_vector", FieldType: vikingdb.Sparse_Vector},  // 稀疏向量字段
}

// 创建集合，指定集合名称、字段定义和其他参数
collection, err := service.CreateCollection("test_coll_for_sdk_2", fields, "")
if err != nil {
    // 错误处理
    panic(err)
}

// 输出集合名称
fmt.Println(collection.CollectionName)

创建多模态数据集

fields := []vikingdb.Field{
    {FieldName: "f_id", FieldType: vikingdb.String, IsPrimaryKey: true},  // 主键字段
    {FieldName: "f_int64", FieldType: vikingdb.Int64},  // 整型字段
    {FieldName: "f_text1", FieldType: vikingdb.Text},  // 文本字段
    {FieldName: "f_text2", FieldType: vikingdb.Text},  // 文本字段
    {FieldName: "f_image1", FieldType: vikingdb.Image},  // 图片字段
    {FieldName: "f_image2", FieldType: vikingdb.Image},  // 图片字段
}

// 定义向量化配置
vectorize := []*vikingdb.VectorizeTuple{
    vikingdb.NewVectorizeTuple().
    // 设置密集向量和稀疏向量配置
    SetDense(vikingdb.NewVectorizeModelConf().
        SetTextField("f_text1").
        SetImageField("f_image1").
        SetModelName("doubao-embedding-vision").
        SetModelVersion("241215").
        SetDim(3072)).
    SetSparse(vikingdb.NewVectorizeModelConf().
        SetTextField("f_text2").
        SetModelName("bge-m3")),
}

// 创建集合，指定集合名称、字段定义、其他参数和向量化配置
collection, err := service.CreateCollection("test_coll_for_sdk_with_vectorize", fields, "", vectorize)
if err != nil {
    // 错误处理
    panic(err)
}

// 输出集合名称
fmt.Println(collection.CollectionName)

返回值

Go 调用执行上面的任务，返回 Collection 结构体地址 (*Collection)。Collection 结构体包含的属性如下表所示。

属性	类型	说明
CollectionName	string	显示创建的 Collection 名称。
Description	string	显示创建的 Collection 的描述。
Fields	[]Field	显示创建的字段列表。
Indexes	[]interface{}	显示创建的索引列表。
Stat	map	统计/状态信息。 data_number：数据量条数。 data_storage：数据占用的存储大小，单位是字节。
CreateTime	string	数据集创建时间。
UpdateTime	string	数据集更新时间。
UpdatePerson	string	数据集更新人。