向量检索--向量数据库VikingDB-火山引擎

文档中心

导航

向量检索

最近更新时间：2024.12.12 20:27:34首次发布时间：2024.04.17 14:21:07

概述

/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/collection_alias		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类型。注意索引类型为 hnsw_hybrid的索引暂不支持 primary_keys 检索。
	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个。
	dense_weight	float	否	0.5	混合检索中稠密向量的权重，1 表示纯稠密检索，0表示纯字面检索。只有索引是混合索引时有效。范围 [0.2, 1]
	output_fields	list<string>	否		过滤字段，指定要返回的标量或向量字段列表。 output_fields 不传时，返回所有的标量字段，不返回向量字段。 output_fields 为空列表时，不返回 fields 字段。 output_fields 格式错误或者过滤字段不是 collection 里的字段时, 接口返回错误。如果索引的距离方式为cosine，向量字段返回的向量是归一化后的向量。
	primary_key_in	list<int64>或list<string>	否		设定此参数，会限定仅在主键列表范围内进行检索。传入空列表和不传此参数效果相同。
	primary_key_not_in	list<int64>或list<string>	否		设定此参数，将把主键列表范围内的数据从检索结果中排除。

响应消息

参数	参数说明
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	输入的向量格式不合法。
1000029	429	请求已达上限, 请调整CPU核数	需要调大 cpu_quota

完整示例

请求消息

以向量检索参数order_by_vector选择vectors，并检索稠密向量为例：

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,
        "output_fields": ["time", "author"]
    }
}
}'

以向量检索参数order_by_vector 选择 vectors，并检索稠密向量和稀疏向量为例：

说明

检索混合索引时，需要同时输入稠密向量和稀疏向量。稠密向量为列表形式，稀疏向量为 json 字段形式，k 为关键词的字面值，v 为关键词的权重。两种向量可以以列表的形式传入多条记录，记录的数量需要一致，列表下标一致的稠密向量和稀疏向量表示同一条查询。

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],
            ],  
            "sparse_vectors": [
                {"什么": 0.34, "是": 0.03, "B": 0.11, "M":0.32, "25": 0.03}, 
                {"一": 0.08, "种": 0.14, " 信息": 0.19, " 检索": 0.63, " 算法":0.97} 
            ]     
        }, 
        "limit": 2,
        "dense_weight": 0.5,
        "output_fields": ["time", "author"]
    }
}
}'

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

curl -i -X POST \
  -H 'Content-Type: application/json' \
  -H 'Authorization: token=********************' \
  https://api-vikingdb.volces.com/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"}