You need to enable JavaScript to run this app.
导航

create

最近更新时间2024.02.21 11:32:19

首次发布时间2023.11.03 15:00:09

概述

/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

2

索引检索消耗的 CPU 配额,格式为正整数。

  • 与吞吐量有关,和延迟无关,1CPU 核约为 100QPS。
  • N个分片数量N倍的 CPU 消耗;如果检索消耗的 CPU 超过配额,该索引会被限流。
  • 取值范围:[2, 10240]。

description

string

”“

索引的自定义描述。

shard_count

int

1

分片数。索引分片是指在大规模数据量场景下,可以把索引数据切分成多个小的索引块,分发到同一个集群不同节点进行管理,每个节点负责存储和处理一部分数据,可以将查询负载分散到不同的节点上,并发的进行处理。当一个节点发生故障时,系统可以自动将其上的分片数据迁移到其他的正常节点上,保证稳定性,以实现数据的水平扩展和高性能的读写操作。

  • 取值范围:[1, 256]。

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
  • 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。

quant

string

详见参数说明

量化方式。量化方式是索引中对向量的压缩方式,可以降低向量间相似性计算的复杂度。基于向量的高维度和大规模特点,采用向量量化可以有效减少向量的存储和计算成本。取值如下:

  • int8:将4字节的 float 压缩为单个字节,以获取内存和计算延迟的收益,会造成微小的损失精度,比如 cosine 距离会出现大于1的分值。
  • float:全精度,未做压缩量化。
  • fix16:将4字节的 float 压缩为两个字节,以获取内存和计算延迟的收益,会造成微小的损失精度。通过损失一定的检索精度,提升检索性能,节约资源成本。
  • pq:将高维向量转换为低维码本向量,以减少内存占用并提高搜索效率。

int8适用于hnsw、flat索引算法,距离方式为ip、consine。
float适用于hnsw、flat、diskann索引算法,距离方式为ip、l2、consine。
fix16适用于hnsw、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 ***' \
  http://***/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"}