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

文档中心

立即注册

导航

create

最近更新时间：2024.12.10 15:17:41首次发布时间：2024.04.17 14:21:06

概述

/collection/create 接口用于创建一个新的数据集 Collection。创建成功后，可以写入数据。

说明

每一个 Collection 必须指定主键字段。
当定义字段 fields 添加了一个向量类型 vector 的字段后，再添加新的字段时，字段类型不可选择 vector 类型。因为目前只支持单向量，不可添加多个向量字段。
当定义字段 fields 添加了带 pipeline_name 的 text 字段，则不允许添加 vector 或 sparse_vector 字段，且只能有一个带 pipeline_name 的 text 字段；当定义字段 fields 添加了不带 pipeline_name 的 text 字段，则允许添加 vector 字段，且允许添加多个不带 pipeline_name 的 text 字段，text 字段最多200个。

请求接口

说明

请求向量数据库 VikingDB 的 OpenAPI 接口时，需要构造签名进行鉴权，详细的 OpenAPI 签名调用方法请参见 API签名调用指南。

URI	/api/collection/create	统一资源标识符
请求方法	POST	客户端对向量数据库服务器请求的操作类型
请求头	Content-Type: application/json	请求消息类型
请求头	Authorization: HMAC-SHA256 ***	鉴权

请求参数

参数	子参数	类型	是否必选	默认值	参数说明
collection_name	--	string	是	--	指定创建的 Collection 名称。只能使用英文字母、数字、下划线_，并以英文字母开头，不能为空。长度要求：[1, 128]。 Collection 名称不能重复。
collection_aliases	--	array	否	--	自定义数据集的别名。可设置多个别名，每个别名回车确认。相同数据集别名不能重复。设置的别名已映射其他数据集，设置后将与原数据集解除，与当前数据集映射。只能使用英文字母、数字、下划线_，并以英文字母开头。长度要求：[1, 128]。
description	--	string	否	""	自定义 Collection 的描述。长度要求：[0, 65535]。
primary_key	--	string	是	--	主键用于唯一标识一行数据。自定义主键：可以从 fields 定义的字段列表中选出某一个 int64 类型 / string 类型的字段作为主键字段。自动生成主键：可设置为 `__AUTO_ID__`系统会自动为该主键生成 int64 数字作为主键值。
fields 说明一个 Collection 里的 fields 数量上限是 200。	field_name	string	是	--	指定自定义字段的名称。只能使用英文字母、数字、下划线_，并以英文字母开头，不能为空。长度要求：[1, 128]。字段名称不能重复。
	field_type	string	是	--	指定自定义字段类型，可选值详见 field_type 可选值说明。
	default_val	和field_type一致	否	--	指定自定义字段默认值，默认值详见 field_type 可选值说明。当 field_name 作为主键时，default_val 不会生效，同时也不会被校验。
	dim	int	field_type 为vector 时必选	--	指定自定义字段向量维度。取值范围：[4, 4096]，且必须是 4 的倍数。向量维度是指向量中包含的元素的数量。
	pipeline_name	string	field_type 为 text 时可选	--	文本。纯文本预处理能力 pipeline 是指向量数据库将文本切片、文本向量化、入库、存储自动化的预处理流程。支持以string形式写入原始数据。 pipeline_name 枚举值如下： text_split_bge_large_zh：向量数据库使用切分器将长文本切分成短文本，调用 embedding 模型将短文本向量化。 text_bge_large_zh：向量数据库不切分文本，直接调用 embedding 模型将文本向量化。 text_split_bge_m3：向量数据库使用切分器将长文本切分成短文本，调用 bge m3 模型抽取短文本的稀疏特征和稠密特征，存入系统预设的稠密向量字段和稀疏向量字段。 text_bge_m3：向量数据库不切分文本，直接调用 bge m3 抽取短文本的稀疏特征和稠密特征，存入系统预设的稠密向量字段和稀疏向量字段。 text_split_bge_large_and_m3：向量数据库使用切分器将长文本切分成短文本，调用 bge v1.5 模型抽取短文本的稠密特征，存入系统预设的稠密向量字段；调用 bge m3 模型抽取短文本的稀疏特征，存入系统预设的稀疏向量字段。 text_bge_large_and_m3：向量数据库不切分文本，调用 bge v1.5 模型抽取短文本的稠密特征，存入系统预设的稠密向量字段；调用 bge m3 模型抽取短文本的稀疏特征，存入系统预设的稀疏向量字段。 text_doubao_embedding：向量数据库不切分文本，直接调用doubao-embedding模型抽取短文本的稠密特征，这个模型是字节跳动自研向量化模型，支持中英双语和高精度纯语义检索 text_split_doubao_embedding：向量数据库使用切分器将长文本切分成短文本，调用doubao-embedding模型抽取短文本的稠密特征，这个模型是字节跳动自研向量化模型，支持中英双语和高精度纯语义检索 text_doubao_embedding_and_m3：向量数据库不切分文本，直接调用doubao-embedding模型抽取短文本的稠密特征，调用bge_m3模型抽取短文本的稀疏特征，这个模型融合语义检索和关键词匹配，支持混合检索，适用大多数场景，检索效果表现最佳 text_split_doubao_embedding_and_m3：向量数据库使用切分器将长文本切分成短文本，调用doubao-embedding模型抽取短文本的稠密特征和调用bge_m3模型抽取短文本的稀疏特征，这个模型融合语义检索和关键词匹配，支持混合检索，适用大多数场景，检索效果表现最佳

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	--	--	--	--	否	文本，注意事项： 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 字段，text 字段最多200个。

响应消息

参数	参数说明
code	状态码
message	返回信息
request_id	标识每个请求的唯一标识符

状态码说明

状态码	http状态码	返回信息	状态码说明
0	200	success	创建 Collection 执行成功。
1000004	400	collection exist	Collection 已存在。
1000003	400	invalid request：%s	非法参数：缺失必选参数。 Collection 命名不符合规范。字段类型与相关字段属性不满足约束条件。
1000001	401	unauthorized	请求头中缺乏鉴权信息。
1000002	403	no permission	权限不足。

完整示例

请求消息

创建带有稠密向量、稀疏向量字段和标量字段的 Collection 为例：

curl -i -X POST \
  -H 'Content-Type: application/json' \
  -H 'Authorization: HMAC-SHA256***' \
  https://api-vikingdb.volces.com/api/collection/create \
  -d '{
    "collection_name": "test_name",
    "description": "test dataset",
    "primary_key": "id",            
    "fields": [                               
        {
            "field_name": "id",       
            "field_type": "int64"
        },
        {
            "field_name": "text",                     
            "field_type": "string", 
            "default_val": ""
        },
        {
            "field_name": "vector_field",
            "field_type": "vector",      
            "dim": 768
        },
        {
            "field_name": "sparse_vector_field",
            "field_type": "sparse_vector"
        },
        {
            "field_name": "time",
            "field_type": "int64",       
            "default_val": 0
        },
        {
            "field_name": "author",
            "field_type": "string",      
            "default_val": "null"
        },
    ]
}'

创建带有文本字段的 Collection 为例：

curl -i -X POST \
  -H 'Content-Type: application/json' \
  -H 'Authorization: HMAC-SHA256***' \
  https://api-vikingdb.volces.com/api/collection/create \
  -d '{
        "collection_name": "test_raw_data_collection",
        "description": "test_raw_data_collection",
        "primary_key": "id",  
        "fields": [{
                "field_name": "id",
                "field_type": "int64",
                "default_val": 0
        }, {
                "field_name": "gap",
                "field_type": "float32",
                "default_val": 3.1
        }, {
                "field_name": "content",   # 文本字段名
                "field_type": "text",
                "pipeline_name": "text_split_bge_large_zh"
        }]
}'

响应消息

执行成功返回：

HTTP/1.1 200 OK
Content-Length: 43
Content-Type: application/json
 
{"code":0,"message":"success","request_id":"021695029537650fd001de666660000000000000000000230da93"}

执行失败返回：

HTTP/1.1 400 OK
Content-Length: 43
Content-Type: application/json
 
{"code":1000004,"message":"collection exist","request_id":"021695029537650fd001de666660000000000000000000230da93"}