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

文档中心

导航

create

最近更新时间：2024.07.18 12:24:20首次发布时间：2024.04.17 14:21:06

概述

/index/create 接口用于为指定的数据集 Collection 创建索引 Index。
创建索引可以加速向量的相似度搜索，它根据指定的索引算法和数据结构将向量库中的原始数据进行分组排序，提高相似度搜索的效率和准确性，是驱动向量数据库在短时间内筛选出候选的核心所在。

请求接口

说明

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

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

请求参数

参数	子参数	类型	是否必选	默认值	参数说明
collection_name		string	是		指定创建索引所属的 Collection 名称。只能使用英文字母、数字、下划线_，并以英文字母开头，不能为空。长度要求：[1, 128]。 Collection 名称不能重复。
index_name		string	是		指定创建的索引 Index 名称。只能使用英文字母、数字、下划线_，并以英文字母开头，不能为空。长度要求：[1, 128]。索引名称不能重复。
cpu_quota		int	否	1	索引检索消耗的 CPU 配额，格式为正整数。与吞吐量有关，和延迟无关，1CPU 核约为 100QPS。 N个分片数量N倍的 CPU 消耗；如果检索消耗的 CPU 超过配额，该索引会被限流。取值范围：[1, 10240]。
description		string	否	”“	索引的自定义描述。
shard_policy		string	否	“”	索引分片类型可选值为auto/custom，auto为自动分片、custom为自定义分片。索引分片是指在大规模数据量场景下，将索引数据均分成多个小的索引数据块，并分发到同一个集群不同节点进行管理，每个节点负责存储和处理一部分数据，查询会同时请求不同节点上的索引数据块。由于单节点的容量有限，无法将索引全部数据存放到单节点中，因此需要设置合适的索引分片数，否则会影响索引到数据的时效性。另，分片数与成本相关，分片数越多成本越高。
shard_count		int	否	1	自定义分片数。当shard_policy为auto时，shard_count不生效。当shard_policy为custom时，shard_count。取值范围：[1, 256]。默认为1，分片数预估参考：数据预估数据量/3000万。
partition_by		string	否	“”	partition_by 用于划分子索引 partition 。根据某个标量字段可以将数据集划分成不同的子数据集，不同的子数据集构建为不同的子索引，实现混合检索时在子索引内检索并减少过滤，从而提升检索性能。 partition_by 对应字段名称 field_name，支持 field 类型为 int64、list<int64>、string、list<string>。partition 对应 field 的字段值。 partition_by 划分的子索引 partition 数量建议不超过1000个。子索引数量过多会导致索引无法ready或更新每个子索引无论数据量多少，都会至少占用 100000维度系数字节的内存，子索引数量过多的话，会导致内存占用过大，计费增加 partition_by 参数未设置时，则子索引 partition 默认为 “default”。适用场景：适用于将数据集划分为多个子数据集，在某个子数据集/子索引内部检索等检索模式固定的场景。比如，根据国家ID将数据集拆分，针对某个国家ID的子索引检索场景，无需对国家ID进行过滤，提升检索性能。
vector_index	index_type	string	是	hnsw	向量索引类型。取值如下： hnsw：全称是 Hierarchical Navigable Small World，一种用于在高维空间中采用 ANN 搜索的数据结构和算法，是基于图的索引。HNSW通过构建多层网络减少搜索过程中需要访问的节点数量，实现快速高效地搜索最近邻，适合对搜索效率要求较高的场景。 hnsw的相关参数包含 quant、distance、hnsw_m、hnsw_cef、hnsw_sef。 hnsw_hybrid：支持混合索引的 hnsw 算法。混合索引算法可以同时对数据集中的稠密向量和稀疏向量进行索引，并在检索时返回兼顾两种类型相似性的结果。适用于对搜索效率要求较高，且需要同时检索稀疏和稠密向量的场景。 hnsw_hybrid的相关参数包含 quant、distance、hnsw_m、hnsw_cef、hnsw_sef。 hnsw_hybrid所索引的数据集必须包含 sparse_vector类型数据，即定义了sparse_vector类型字段，或绑定了能产生sparse_vector 类型向量的 pipeline。 flat：暴力索引，搜索时遍历整个向量数据库的所有向量与目标向量进行距离计算和比较，查询速度较慢，但是 flat 能提供100％的检索召回率，适用于向量候选集较少，且需要100％检索召回率的场景。 flat 的相关参数包含 quant、distance。 ivf：倒排索引，利用倒排的思想保存每个聚类中心下的向量，每次查询向量的时候找到最近的几个中心，分别搜索这几个中心下的向量，速度较快，但是精度略低，适合中等规模数据量，对搜索效率要求高，精度次之的场景。 ivf 的相关参数包含 quant、distance。 diskann：基于 Vamana 图的磁盘索引算法，将 Vamana 图与 PQ 量化压缩方案结合，构建DiskANN索引。图索引和原始数据存在SSD中，压缩索引放在内存中。检索请求时会将query向量与聚簇中心比较，然后从磁盘读取对应的原始数据进行算分。适用于大规模数据量，性能不是特别敏感，内存成本更低，且召回率较高的场景。 diskann的相关参数包含 quant、distance、diskann_m、diskann_cef、cache_ratio、pq_code_ratio。
	distance	string	否	ip	距离类型，衡量向量之间距离的算法。取值如下： ip：全称是 Inner Product，内积，该算法基于向量的内积，即两个元素的对应元素相乘并求和的结果计算相似度，内积值越大相似度越高。 l2：欧几里得距离，它计算两个向量的欧几里得空间距离，欧式距离越小相似度越高。 cosine：余弦相似度（Cosine Similarity），也称为余弦距离（Cosine Distance），用于计算两个高维向量的夹角余弦值从而衡量向量相似度，夹角余弦值越小表示两向量的夹角越大，则两个向量差异越大。当 distance=cosine 时，默认对向量做归一化处理。当索引算法选择IVF时，距离类型可选ip、consine。对于hnsw_hybrid索引算法，距离类型选择只对稠密向量生效，稀疏向量仅支持内积。
	quant	string	否	详见参数说明	量化方式。量化方式是索引中对向量的压缩方式，可以降低向量间相似性计算的复杂度。基于向量的高维度和大规模特点，采用向量量化可以有效减少向量的存储和计算成本。取值如下： int8：将4字节的 float 压缩为单个字节，以获取内存和计算延迟的收益，会造成微小的损失精度，比如 cosine 距离会出现大于1的分值。 float：全精度，未做压缩量化。 fix16：将4字节的 float 压缩为两个字节，以获取内存和计算延迟的收益，会造成微小的损失精度。通过损失一定的检索精度，提升检索性能，节约资源成本。 pq：将高维向量转换为低维码本向量，以减少内存占用并提高搜索效率。 int8适用于hnsw、hnsw_hybrid、flat索引算法，距离方式为ip、consine。 float适用于hnsw、hnsw_hybrid、flat、diskann索引算法，距离方式为ip、l2、consine。 fix16适用于hnsw、hnsw_hybrid、flat索引算法，距离方式为ip、l2、consine。 pq适用于diskann、ivf索引算法，距离方式为ip、l2、consine。
	hnsw_m	数值	否	20	hnsw 索引参数，表示邻居节点个数。当 index_type 配置为 hnsw 时可选配置。
	hnsw_cef	数值	否	400	hnsw 索引参数，表示构建图时搜索邻居节点的广度。当 index_type 配置为 hnsw 时可选配置。
	hnsw_sef	数值	否	800	hnsw 索引参数，表示线上检索的搜索广度。当 index_type 配置为 hnsw 时可选配置。
	diskann_m	数值	否	64	diskann参数，标识邻居节点个数。当 index_type 配置为 diskann时可选配置。
	diskann_cef	数值	否	100	diskann参数，表示构建图时搜索邻居节点的广度。当 index_type 配置为 diskann时可选配置。
	cache_ratio	float	否	0.1	diskann参数，缓存节点数与原始数据的比率，较大的值会提高索引性能并增加内存使用量。范围 [0.0,0.3)。当 index_type 配置为 diskann时可选配置。
	pq_code_ratio	float	否	0.125	diskann参数，向量维度编码的大小限制。值越大，召回率越高，但会增加内存使用量，范围 (0.0, 0.25]。当 index_type 配置为 diskann时可选配置。
scalar_index		array	否	None	标量字段列表，用于设置需要构建到标量索引的字段。其中，float、int64 字段可用于范围检索，非 float 字段可用于枚举检索。 scalar_index 默认为 None，表示所有字段构建到标量索引。 scalar_index 为 [] 时，表示无标量索引。 scalar_index 为非空列表时，表示将列表内字段构建到标量索引。

响应消息

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

状态码说明

状态码	http状态码	返回信息	状态码说明
0	200	success	索引 Index 创建成功。
1000005	400	collection not exist	索引相关的 Collection 不存在。
1000007	400	Index already exist	索引名称已存在。
1000003	400	invalid request：%s	非法参数：缺失必选参数。 Index 命名不符合规范。
1000001	401	unauthorized	请求头中缺乏鉴权信息。
1000002	403	no permission	权限不足。

完整示例

请求消息

curl -i -X POST \
  -H 'Content-Type: application/json' \
  -H 'Authorization: HMAC-SHA256 ***' \
  https://api-vikingdb.volces.com/api/index/create \
  -d '{
    "collection_name": "test_name",
    "index_name": "index_test"
    "description": "test for index",
    "cpu_quota": 10,
    "partition_by": "country"   //partition_by 对应字段名称 field_name
    "vector_index": {
        "index_type": "hnsw",
        "distance": l2,
        "quant": "float"
    },
    "scalar_index": ["city", "date", "score"],
}'

响应消息

执行成功返回：

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

执行失败返回：

HTTP/1.1 400 OK
Content-Length: 43
Content-Type: application/json
 
{"code":1000005, "message":"collection not exist", "request_id":"021695029736548fd001de66666000000000000000000029aa917"}