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

向量检索

最近更新时间2024.02.22 10:10:14

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

概述

/index/search 接口用于实现检索,本页面主要介绍如何实现向量检索。
向量检索是一种基于向量空间模型的检索方法,通过计算向量之间的相似度进行检索。在一个给定向量数据集中,向量检索按照某种度量方式(比如内积、欧式距离),对向量构建的一种时间和空间上比较高效的数据结构,能够高效地检索出与目标向量相似的 K 个向量。

说明

Collection 数据写入/删除后,Index 数据更新时间最长滞后 20s,不能立即在 Index 检索到。

前提条件
  • Collection 创建时,定义字段 fields 已添加 vector 字段。
  • Collection 数据写入时,已写入 vector 类型的字段名称和字段值。
  • Index 创建时,已创建 vector_index 向量索引。

请求接口

说明

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

URI

/api/index/search

统一资源标识符

请求方法

POST

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

请求头

Content-Type: application/json

请求消息类型

Authorization: HMAC-SHA256 ***

鉴权

请求参数

参数

子参数

类型

是否必选

默认值

参数说明

collection_name

string

指定检索的 Index 所属的 Collection 名称。

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

index_name

string

指定检索的 Index 名称。

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

search

order_by_vector

map

根据向量距离做检索,可选值如下,vectors 和 primary_keys 二选一:

  • vectors:用于检索的向量列表,最大10个。
  • primary_keys: 用于检索的数据主键列表,最大10个。会先根据主键查到对应的向量,再对向量做近似检索。支持int类型/string类型。

partition

string/int

"default"

子索引名称,类型与 partition_by 的 field_type 一致,字段值对应 partition_by 的 field_value。

  • field_type 为 int64,list<int64> 时,partition 输入类型为 int64。
  • field_type 为 string,list<string> 时,partition 输入类型为 string,格式要求 "^[a-zA-Z0-9._]+$"。

limit

int

10

检索结果数量,最大5000个。

output_fields

list<string>

过滤标量字段,指定要返回的标量字段列表。

  • output_fields 不传时,返回所有的标量字段。
  • output_fields 为空列表时,不返回 fields 字段。
  • output_fields 格式错误或者过滤字段不是 collection 里的字段时, 接口返回错误。

响应消息

参数

参数说明

code

状态码

message

返回信息

request_id

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

data

检索结果,向量检索会返回检索到的主键、score、fields。

状态码说明

状态码

http状态码

返回信息

状态码说明

0

200

drop index success

向量检索成功。

1000008

400

index not exist

指定的 Index 不存在。

1000003

400

invalid request:%s

非法参数:

  • 缺失必选参数。
  • 缺乏检索输入。
  • 不满足约束条件。

1000001

401

unauthorized

请求头中缺乏鉴权信息。

1000002

403

no permission

权限不足。

1000016

400

invalid vectors for index_recall

输入的向量格式不合法。

完整示例

请求消息

以向量检索参数order_by_vector选择vectors为例:

curl -i -X POST \
  -H 'Content-Type: application/json' \
  -H 'Authorization: HMAC-SHA256 ***' \
  http://***/api/index/search \
  -d '{
    "collection_name": "test_name",
    "index_name": "index_test",
    "search": {
        "order_by_vector": {
            "vectors": [
                [0.1, 0.2, 0.3......0.9], 
                [0.01, 0.02, 0.03......0.09],
            ],         
        }, 
        "limit": 2,
        "output_fields": ["time", "author"]
    }
}
}'

以向量检索参数order_by_vector选择primary_keys为例:

curl -i -X POST \
  -H 'Content-Type: application/json' \
  -H 'Authorization: token=********************' \
  http://***/api/index/search \
  -d '{
    "collection_name": "test_name",
    "index_name": "index_test",
    "search": {
        "order_by_vector": {
            "primary_keys":  [100, 101],  
        }, 
        "limit": 2,
        "output_fields": ["time", "author"]
    }
}
}'

响应消息

执行成功返回:

HTTP/1.1 200 OK
Content-Length: 43
Content-Type: application/json
 
{
    "code":0,
    "msg":"search success",
    "request_id":"021695029537650fd001de666660000000000000000000230da93",
    "data": [
        [
            {
                "id": 1,
                "score": 0.99,
                "fields": {
                    "time": 1690529704,
                    "author": "zhangsan"
                } 
            },
            {
                "id": 2,
                "score": 0.98,
                "fields": {
                    "time": 1690529701,
                    "author": "lisi"
                } 
            }
        ],
        [
            {
                "id": 9,
                "score": 0.95,
                "fields": {
                    "time": 1690529708,
                    "author": "wangwu"
                } 
            },
            {
                "id": 8,
                "score": 0.84,
                "fields": {
                    "time": 1690529710,
                    "author": "zhaoliu"
                } 
            }            
        ]
    ]
}

执行失败返回:

HTTP/1.1 400 OK
Content-Length: 43
Content-Type: application/json
 
{"code":1000008, "msg":"index not exist","request_id":"021695029537650fd001de666660000000000000000000230da93"}