向量近邻检索是一种基于向量空间模型的检索方法，它通过计算向量间的相似度来进行检索。在给定的向量数据集中，向量近邻检索依据某种度量方式（如内积、欧氏距离），为向量构建一种在时间和空间上较为高效的数据结构，从而高效地检索出与目标向量相似的K个向量。
本页面重点介绍如何基于/index/search接口实现向量近邻检索。
说明
Collection 数据写入/删除后，Index 数据更新时间最长滞后 20s，不能立即在 Index 检索到。
说明
请求向量数据库 VikingDB 的 OpenAPI 接口时，需要构造签名进行鉴权，详细的 OpenAPI 签名调用方法请参见 API签名调用指南。
URI | /api/index/search | 统一资源标识符 |
|---|---|---|
请求方法 | POST | 客户端对向量数据库服务器请求的操作类型 |
请求头 | Content-Type: application/json | 请求消息类型 |
Authorization: HMAC-SHA256 *** | 鉴权 |
最简洁的向量检索可通过配置search接口下的order_by_vector参数来实现，支持依据输入的向量或主键值对数据集中的向量进行检索，如果输入了多个查询，会对输入的查询依次做检索并返回多组检索结果。请求参数如下：
参数 | 子参数 | 类型 | 是否必选 | 默认值 | 参数说明 |
|---|---|---|---|---|---|
collection_name/collection_alias | string | 是 | 指定检索的 Index 所属的 Collection 名称/别名。
| ||
index_name | string | 是 | 指定检索的 Index 名称。
| ||
resource_id | string | 否 | 资源ID | ||
search | order_by_vector | map | 是 | 根据向量距离做检索，可选值如下，vectors 和 primary_keys 二选一：
注意 索引类型为 hnsw_hybrid的索引暂不支持 primary_keys 检索。 |
在下面的示例中，假设 Collection 已经存放了如下 10 条数据。每条数据都有 id, vector, name,city, salary这几个字段。
{"id":"1","vector":[0.12,0.98,0.45,...,0.33,0.77],"name":"Alice","city":"New York","salary":85000} {"id":"2","vector":[0.55,0.22,0.91,...,0.14,0.68],"name":"Bob","city":"San Francisco","salary":120000} {"id":"3","vector":[0.31,0.44,0.27,...,0.88,0.15],"name":"Charlie","city":"Chicago","salary":78000} {"id":"4","vector":[0.66,0.39,0.72,...,0.58,0.23],"name":"Diana","city":"London","salary":95000} {"id":"5","vector":[0.09,0.81,0.34,...,0.47,0.56],"name":"Ethan","city":"Toronto","salary":91000} {"id":"6","vector":[0.48,0.29,0.67,...,0.12,0.99],"name":"Fiona","city":"Sydney","salary":104000} {"id":"7","vector":[0.25,0.73,0.58,...,0.46,0.31],"name":"George","city":"Berlin","salary":83000} {"id":"8","vector":[0.94,0.16,0.39,...,0.85,0.02],"name":"Hannah","city":"Paris","salary":98000} {"id":"9","vector":[0.53,0.67,0.41,...,0.29,0.76],"name":"Ian","city":"Tokyo","salary":89000} {"id":"10","vector":[0.77,0.51,0.24,...,0.63,0.40],"name":"Julia","city":"Singapore","salary":115000}
curl -i -X POST \ -H 'Content-Type: application/json' \ -H 'Authorization: HMAC-SHA256 ***' \ https://api-vikingdb.volces.com/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] ] } } }'
curl -i -X POST \ -H 'Content-Type: application/json' \ -H 'Authorization: HMAC-SHA256 ***' \ https://api-vikingdb.volces.com/api/index/search \ -d '{ "collection_name": "test_name", //用于检索的集合的名称 "index_name": "index_test", //用于检索的索引名称 "search": { "order_by_vector": { //用于检索的主键列表 "primary_keys": ["1", "2"] } } }'
执行成功返回：
{ "code": 0, "data": [[{ "fields": { "city": "New York", "id": 1, "name": "Alice", "salary": 85000 }, "id": 1, "score": 1.0002950429916382 }, { "fields": { "city": "San Francisco", "id": 2, "name": "Bob", "salary": 120000 }, "id": 2, "score": -0.017884135246276855 }], [{ "fields": { "city": "San Francisco", "id": 2, "name": "Bob", "salary": 120000 }, "id": 2, "score": 0.9990343451499939 }, { "fields": { "city": "New York", "id": 1, "name": "Alice", "salary": 85000 }, "id": 1, "score": -0.018528103828430176 }]], "message": "success", "request_id": "02174781958394600000000000000000000ffff0a00744bebcae7" }
如果在创建索引时划分了子索引 partition，并且查询目标可以具体到其中的一个 partition，可以在检索时指定在特定partiton中进行检索，从而减少扫描的数据量，提高检索速度。
在基础向量检索的基础上，通过配置search接口下的partition参数可以实现对特定子索引的检索：
参数 | 子参数 | 类型 | 是否必选 | 默认值 | 参数说明 |
|---|---|---|---|---|---|
search | partition | string/int | 否 | "default" | 子索引名称，类型与 partition_by 的 field_type 一致，字段值对应 partition_by 的 field_value。
|
假设在创建索引时设置了city字段为子索引字段，根据city字段的取值将数据集划分成了不同的子数据集，现在想对名为London的partiton进行检索，可以通过如下方式实现：
curl -i -X POST \ -H 'Content-Type: application/json' \ -H 'Authorization: HMAC-SHA256 ***' \ https://api-vikingdb.volces.com/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] ] }, "partiton": "London" } }'
检索过滤是指在向量相似度检索过程中，结合结构化的元数据（如数值、布尔值、字符串等）对候选数据进行筛选的过程。这种过滤可以提高检索结果的相关性和精度。
检索过滤为可选能力，需要配合基础的向量检索能力使用，可以配置一种或多种检索过滤方式。
标量过滤检索是指在向量数据库中，同时使用向量检索和标量检索两种方法进行检索。在标量过滤检索中，使用向量检索来匹配向量的相似度，同时使用标量检索来匹配向量的标量值。
在基础向量检索的基础上，可以通过配置search接口下的filter参数来实现对检索结果的标量过滤，详细的使用方法参考标量过滤。
主键过滤是指在向量检索时，仅对指定主键值数据执行近邻搜索，从而有效缩小检索范围并提升性能与准确度
在基础向量检索的基础上，可以通过配置search接口下的 primary_key_in/primary_key_not_in 子参数对特定主键值的数据进行检索，详细的使用方法参考主键过滤。
后置过滤是 VikingDB 提供的一种检索后处理能力，用于在向量召回之后，对候选数据进行进一步的过滤和优化，确保最终返回的搜索结果更加精准、高效。VikingDB 提供了以下几种后置过滤能力：
在基础向量检索的基础上，可以通过配置search接口下的 post_process_ops和post_process_input_limit配置后置过滤能力，详细的使用方法详见后置处理算子。
通过配置search接口下的 output_fields子参数可以限制检索结果只返回指定的字段:
参数 | 子参数 | 类型 | 是否必选 | 默认值 | 参数说明 |
|---|---|---|---|---|---|
search | output_fields | list<string> | 否 | 过滤字段，指定要返回的标量或向量字段列表。
如果索引的距离方式为cosine，向量字段返回的向量是归一化后的向量。 |
例如希望在返回结果中只保留“name”字段：
curl -i -X POST \ -H 'Content-Type: application/json' \ -H 'Authorization: HMAC-SHA256 ***' \ https://api-vikingdb.volces.com/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]] }, "output_fields": ['name'] } }'
分页能力通过在检索请求中指定 offset 和 limit参数，将结果分批返回，在降低单次响应延迟的同时便于前端交互和资源管理
参数 | 子参数 | 类型 | 是否必选 | 默认值 | 参数说明 |
|---|---|---|---|---|---|
search | limit | int | 否 | 10 | 检索结果数量，最大5000个。 |
offset | int | 否 | 0 | 偏移量。仅分页场景下使用，不建议设置过大值，否则有深分页影响。默认值为0。设置值至少为0，语义和mysql的offset相同。 |
例如指定返回10个结果：
curl -i -X POST \ -H 'Content-Type: application/json' \ -H 'Authorization: HMAC-SHA256 ***' \ https://api-vikingdb.volces.com/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, # 每页返回 2 条结果 "offset": 4 # 跳过前 4 条结果,获取第三页结果 } }'
参数 | 参数说明 |
|---|---|
code | 状态码 |
message | 返回信息 |
request_id | 标识每个请求的唯一标识符 |
data | 检索结果，向量检索会返回检索到的主键、score、fields。 |
状态码 | http状态码 | 返回信息 | 状态码说明 |
|---|---|---|---|
0 | 200 | drop index success | 向量检索成功。 |
1000008 | 400 | index not exist | 指定的 Index 不存在。 |
1000003 | 400 | invalid request | 非法参数：
|
1000001 | 401 | unauthorized | 请求头中缺乏鉴权信息。 |
1000002 | 403 | no permission | 权限不足。 |
1000016 | 400 | invalid vectors for index_recall | 输入的向量格式不合法。 |
1000029 | 429 | 请求已达上限, 请调整CPU核数 | 需要调大 cpu_quota |
curl -i -X POST \ -H 'Content-Type: application/json' \ -H 'Authorization: HMAC-SHA256 ***' \ https://api-vikingdb.volces.com/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], ], }, "partiton": "London"，//指定partition， "filter": { "op": "range", "field": "salary", "gte": 10000 }， "post_process_ops": { "op": "string_contain", "field": "name", "pattern": "s" }， "output_fields": ['name']， "limit": 2, # 每页返回 2 条结果 "offset": 4 # 跳过前 4 条结果,获取第三页结果 } } }'
执行成功返回：
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": { "name": "Alice" } }, { "id": 2, "score": 0.98, "fields": { "name": "Fiona" } } ], [ { "id": 9, "score": 0.95, "fields": { "name": "Charlie" } }, { "id": 8, "score": 0.84, "fields": { "name": "Ethan" } } ] ] }
执行失败返回：
HTTP/1.1 400 OK Content-Length: 43 Content-Type: application/json {"code":1000008, "msg":"index not exist","request_id":"021695029537650fd001de666660000000000000000000230da93"}