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

文档中心

立即注册

导航

create_collection

最近更新时间：2025.06.05 17:31:30首次发布时间：2024.04.17 14:21:06

概述

create_collection 用于创建一个新的数据集 Collection。创建成功后，可以写入数据。
异步调用使用async_create_collection接口，参数不变。

说明

每一个 Collection 必须指定主键字段。
当定义字段 fields 添加了一个向量类型 vector 的字段后，再添加新的字段时，字段类型不可选择 vector 类型。因为目前只支持单向量，不可添加多个向量字段。
创建数据集时，请根据数据类型明确配置方式：若为已有向量数据，请填写 vector 字段；若需对多模态数据（如图文）进行向量化，请配置 vectorize 参数。二者为不同的数据处理逻辑，创建时仅可选择其一，不可同时使用。
Field 实例的列表，一个 Collection 里的 Field 实例数量上限是 200个

请求参数

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

field_type 可选值

字段类型	可用索引类型	default_val默认值	数据写入时取值范围	default_val 取值范围	可为主键	说明
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		否	稠密向量。 field_type 设置为 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}`。图片，可用于向量化。

向量化参数

参数名	类型	必选	默认值	备注
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	默认版本	可选版本
doubao-embedding	text	字节自研的轻量 Doubao 向量化模型，输出稠密向量，适配大多数检索场景，向量化速度更快	2048	512, 1024, 2048	否	是	240515	240515、240715
doubao-embedding-large	text	采用能力更强的 Doubao 语言模型为基座，输出稠密向量，适合对检索精度有较高要求且时间不敏感的场景	2048	512, 1024, 2048, 4096	否	是	240915	240915
doubao-embedding-vision	text、text_image、image 说明在纯图场景下也会有额外的少量文本token消耗（20tokens左右）	字节自研的图文多模态向量化模型，主要面向图文多模向量检索的使用场景，支持图片输入及中、英双语文本输入，最长 8K 上下文长度。	2048	1024、2048	否	是	250328	241215、250328 说明 241215版本只支持3072维稠密向量
bge-large-zh	text	仅支持中文，输出1024维度的稠密向量，适用于短文本	1024	1024	否	否
bge-m3	text	支持 100 多种语言及跨语言向量化能力，可输出稠密向量和稀疏向量，适配长文本多语言场景	1024	1024	是	否
bge-visualized-m3	text、text_image、image	可对文本或图片进行单独编码，或者对文本图片对联合编码，输出1024维度的稠密向量	1024	1024	否	否

示例

请求参数

若报错，则尝试更新一下SDK包：pip install --upgrade volcengine

从向量化开始-写入图文数据

已有向量数据

创建数据集时配置text，image类型字段，并配置vectorize字段信息用于embedding。请勿配置vector类型字段

# 定义数据集字段，包括主键、字符串字段、文本字段和图片字段
fields = [
    Field(field_name="f_id", field_type=FieldType.String, is_primary_key=True),  # 主键字段
    Field(field_name="f_string", field_type=FieldType.String, default_val=""),  # 字符串字段
    Field(field_name="f_text1", field_type=FieldType.Text),  # 文本字段1
    Field(field_name="f_text2", field_type=FieldType.Text),  # 文本字段2
    Field(field_name="f_image1", field_type=FieldType.Image),  # 图片字段1
    Field(field_name="f_image2", field_type=FieldType.Image),  # 图片字段2
]

# 定义向量化配置，包括密集向量和稀疏向量
vectorize = [
    VectorizeTuple(
        dense=VectorizeModelConf(
        model_name="doubao-embedding-vision",  # 使用的模型名称
        model_version="241215",  # 模型版本
        text_field="f_text1",  # 文本字段1
        image_field="f_image1",  # 图片字段1
        dim=3072,  # 向量的维度
        ),
        sparse=VectorizeModelConf(
            model_name="bge-m3",  # 使用的稀疏模型名称
            text_field="f_text1",  # 稀疏向量化文本字段
        )
    )
]

# 创建数据集，提供字段定义、描述和向量化配置
collection = vikingdb_service.create_collection(
    "test_coll_for_sdk_with_vectorize",  # 数据集名称
    fields=fields,  # 字段定义
    description="test for sdk",  # 数据集描述
    vectorize=vectorize  # 向量化配置
)

# 打印数据集信息
print(collection.collection_name)  # 输出数据集名称
print(collection.description)  # 输出数据集描述
print(collection.vectorize)  # 输出数据集的向量化配置

创建数据集时配置vector类型字段信息，请勿配置image或text类型字段以及vectorize。

# 定义数据集字段，包括主键、字符串字段、文本字段和图片字段
fields = [
    Field(field_name="f_id", field_type=FieldType.String, is_primary_key=True),  # 主键字段
    Field(field_name="f_string", field_type=FieldType.String, default_val=""),  # 字符串字段
    Field(field_name="image_description", field_type=FieldType.vector),  # 向量字段
]

# 创建数据集，提供字段定义、描述和向量化配置
collection = vikingdb_service.create_collection(
    "test_coll_for_sdk_with_vectorize",  # 数据集名称
    fields=fields,  # 字段定义
    description="test for sdk",  # 数据集描述
)

# 打印数据集信息
print(collection.collection_name)  # 输出数据集名称
print(collection.description)  # 输出数据集描述

返回值

Python 调用执行上面的任务，返回 Collection 实例。Collection 实例包含的属性如下表所示。

属性	类型	说明
collection_name	string	Collection 名称。
description	string	Collection 的描述。
fields	List	字段列表。
indexes	List	索引列表。
stat	map	统计/状态信息。 data_number：数据量条数。 data_storage：数据占用的存储大小，单位是字节。
create_time	string	数据集创建时间。
update_time	string	数据集更新时间。
update_person	string	数据集更新人。