请求方法

GET

客户端对向量数据库服务器请求的操作类型

请求头

Content-Type: application/json

请求消息类型

Authorization: HMAC-SHA256 ***

鉴权

collection_name

string

是

指定要查询索引所属的 Collection 名称。

• 只能使用英文字母、数字、下划线_，并以英文字母开头，不能为空。
• 长度要求：[1, 128]。
• Collection 名称不能重复。

code

状态码

message

返回信息

request_id

标识每个请求的唯一标识符

data

索引信息，每个索引的详细信息见 Index 参数说明。

collection_name

string

显示创建索引所属的 Collection 名称。

index_name

string

显示创建的索引 Index 名称。

cpu_quota

int

显示索引线上检索消耗的 CPU 配额。

description

string

显示索引的自定义描述。

shard_policy

string

索引分片是指在大规模数据量场景下，将索引数据均分成多个小的索引数据块，并分发到同一个集群不同节点进行管理，每个节点负责存储和处理一部分数据，查询会同时请求不同节点上的索引数据块。由于单节点的容量有限，无法将索引全部数据存放到单节点中，因此需要设置合适的索引分片数，否则会影响索引到数据的时效性。另，分片数与成本相关， 分片数越多成本越高。

• 索引分片类型，可选值为auto/custom，auto为自动分片、custom为自定义分片。

shard_count

int

自定义分片数。

• 当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个。
• partition_by 参数未设置时，则子索引 partition 默认为 “default”。
• 适用场景：适用于将数据集划分为多个子数据集，在某个子数据集/子索引内部检索等检索模式固定的场景。比如，根据国家ID将数据集拆分，针对某个国家ID的子索引检索场景，无需对国家ID进行过滤，提升检索性能。

vector_index

index_type

string

显示向量索引类型。取值如下：

• 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：全称是 Inner Product，内积，该算法基于向量的内积，即两个元素的对应元素相乘并求和的结果计算相似度，内积值越大相似度越高。
• l2：欧几里得距离，它计算两个向量的欧几里得空间距离，欧式距离越小相似度越高。
• cosine：余弦相似度（Cosine Similarity），也称为余弦距离（Cosine Distance），用于计算两个高维向量的夹角余弦值从而衡量向量相似度，夹角余弦值越小表示两向量的夹角越大，则两个向量差异越大。
  当 distance=cosine 时，默认对向量做归一化处理。

quant

string

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

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

hnsw_m

数值

hnsw 索引参数，表示邻居节点个数。

• 当 index_type 配置为 hnsw 时可选配置。

hnsw_cef

数值

hnsw 索引参数，表示构建图时搜索邻居节点的广度。

• 当 index_type 配置为 hnsw 时可选配置。

hnsw_sef

数值

hnsw 索引参数，表示线上检索的搜索广度。

• 当 index_type 配置为 hnsw 时可选配置。

enum_index

array

根据 scalar_index 推断出可用于枚举检索的标量字段名称，非 float 字段可用于枚举检索。

range_index

array

根据 scalar_index 推断出可用于范围检索的标量字段名称，float、int64 字段可用于范围检索。

scalar_index

field_name

string

标量字段名称。

field_type

string

标量字段类型。

status

string

索引状态。取值如下：

• INIT：初始化，在构建或加载中。
• CHANGING：变更中，在变更构建或加载中
• READY：已上线，可以正式提供服务。

index_cost

cpu_core

int

索引占用的 CPU 核数。

mem_gb

string

索引所占内存大小。

create_time

string

索引创建时间。

update_time

string

索引更新时间。

update_person

string

索引更新人。

0

200

list index success

查询指定 Collection 的索引列表成功。

1000005

400

collection not exist

指定的 Collection 不存在。

1000003

400

invalid request：%s

非法参数：

• 缺失必选参数。

1000001

401

unauthorized

请求头中缺乏鉴权信息。

1000002

403

no permission

权限不足。