写入和查询数据
写入数据
bulk写入
用户创建向量索引后，即可使用ES BULK API写入数据。不同的index_type与space_type，在数据写入时没有区别。
在以下示例中，我们向my_index索引的field_hnsw和field_linear字段分别写入样例向量数据。
1POST my_index/_bulk
2{"index":{}}
3{"field_hnsw":[3.5,4.5,6.5,6.5], "field_linear":[3.5,4.5,6.5,6.5]}
4{"index":{}}
5{"field_hnsw":[3.5,4.5,6.5,6.5], "field_linear":[3.5,4.5,6.5,6.5]}
6{"index":{}}
7{"field_hnsw":[5.5,6.5,6.5,6.5], "field_linear":[3.5,4.5,6.5,6.5]}
8...集群参数配置
数据写入以后，BES会在后台为向量字段构建向量索引，用户可以通过bpack.knn.index_thread_qty参数设置构建向量索引的并发度，默认值是1，取值范围[1, 32]。并发度越高，构建索引的速度越快，不过CPU消耗也会越高，需要注意过高的bpack.knn.index_thread_qty值可能会导致CPU资源耗尽，影响同时间的检索请求。
bpack.knn.index_thread_qty参数的设置方式如下：
1PUT /_cluster/settings
2{
3 "persistent" : {
4 "bpack.knn.index_thread_qty" : 4
5 }
6}查询数据
hnsw、hnsw_sq8、hnsw_pq 查询示例
因为hnsw、hnsw_sq8、hnsw_pq 类型字段的查询参数相同，所以我们用一个示例进行说明。
在以下示例中，我们基于 my_index 索引的 field_hnsw 和file-type字段进行检索，其中file-type字段是keyword类型，存储了图片类型；field_hnsw字段是bpack_vector类型，存储了图像的embedding向量。
1GET my-index/_search
2{
3 "size": 3, // 期望的查询结果集大小限制
4 "_source": ["id"], // 期望返回的字段列表
5 "query": {
6 "knn": {
7 "field_hnsw": { // 要检索的向量字段
8 "vector": [2, 3, 5, 6], // 查询向量
9 "k": 10, // 查询的最近邻的数量
10 "ef": 256, // hnsw算法的ef_search参数，表示检索最近邻时的动态扫描队列大小
11 "filter": { // 填写所需的filter，不需要filter则省略
12 "term": {
13 "file-type": "png"
14 }
15 }
16 }
17 }
18 }
19}参数说明
| 参数 | 类型 | 是否必填 | 说明 |
|---|---|---|---|
| ef | int | 否 | hnsw算法的ef_search参数，表示检索最近邻时的动态扫描队列大小。提高ef_search参数可以降低检索陷入局部最优解的概率，提高召回率，相应的，也会消耗更多cpu和内存资源，使查询性能降低。取值需大于k，一般建议200以上。 |
hnsw + filter 查询示例
以下示例展示了一个较复杂的filter过滤条件+hnsw检索的查询DSL，其中file-type字段是keyword类型，存储了图片类型；description是text类型，存储了图片的描述；size 是long类型，存储了图片大小；user_id是keyword类型，存储了图片的用户标识；field_hnsw字段是bpack_vector类型，存储了图像的embedding向量。
1GET my-index/_search
2{
3 "size": 3, // 期望的查询结果集大小限制
4 "_source": ["id"], // 期望返回的字段列表
5 "query": {
6 "knn": {
7 "field_hnsw": { // 要检索的向量字段
8 "vector": [2, 3, 5, 6], // 查询向量
9 "k": 10, // 查询的最近邻的数量
10 "ef": 256, // hnsw算法的ef_search参数，表示检索最近邻时的动态扫描队列大小
11 "filter": { // 填写用户所需的filter，不需要filter则省略
12 "bool": {
13 "must": [
14 {
15 "term": {
16 "file-type": "png"
17 }
18 },
19 {
20 "match": {
21 "description": {
22 "query": "little cat"
23 }
24 }
25 },
26 {
27 "range": {
28 "size":{
29 "gte": 1024
30 }
31 }
32 }
33 ],
34 "must_not": [
35 {
36 "terms": {
37 "user_id": ["aaa", "bbb"]
38 }
39 }
40 ]
41 }
42 }
43 }
44 }
45 }
46}ivf、ivf_pq 查询示例
因为ivf、ivf_pq 类型字段的查询参数相同，所以我们用一个示例进行说明。
在以下示例中，我们基于 my_index 索引的 field_ivf 字段进行检索，field_ivf字段是bpack_vector类型，存储了图像的embedding向量。
1GET my-index/_search
2{
3 "size": 3, // 期望的查询结果集大小限制
4 "_source": ["id"], // 期望返回的字段列表
5 "query": {
6 "knn": {
7 "field_ivf": { // 要检索的向量字段
8 "vector": [2, 3, 5, 6], // 查询向量
9 "k": 10, // 查询的最近邻的数量
10 "nprobes": 10 // ivf系索引检索时扫描的桶数量
11 }
12 }
13 }
14}参数说明
| 参数 | 类型 | 是否必填 | 说明 |
|---|---|---|---|
| nprobes | int | 否 | ivf系索引检索时扫描的桶数量，nprobes越大，recall越高，但查询性能越差。可以从 nlist / 32 开始调整。再参照用户目标召回率来调整，如果取值等于nlist，则查询性能会跟暴力检索效果相似。 |
ivf_hnsw、ivf_hnsw_pq 查询示例
因为ivf_hnsw、ivf_hnsw_pq 类型字段的查询参数相同，同时包括ivf索引的参数和hnsw索引的参数，所以我们用一个示例进行说明。
在以下示例中，我们基于 my_index 索引的 field_ivf_hnsw 进行检索，field_ivf_hnsw字段是bpack_vector类型，存储了图像的embedding向量。
1GET my-index/_search
2{
3 "size": 3, // 期望的查询结果集大小限制
4 "_source": ["id"], // 期望返回的字段列表
5 "query": {
6 "knn": {
7 "field_ivf_hnsw": { // 要检索的向量字段
8 "vector": [2, 3, 5, 6], // 查询向量
9 "k": 10, // 查询的最近邻的数量
10 "nprobes": 10, // ivf系索引检索时扫描的桶数量
11 "ef": 256 // hnsw算法的ef_search参数，表示检索最近邻时的动态扫描队列大小
12 }
13 }
14 }
15}精确检索查询示例
bpack_vector类型字段均可以通过指定 linear:true 参数进行精确检索，会遍历全量数据进行暴力计算，确保结果的召回率。不过查询延迟会随着数据量近似线性增长，以hnsw索引字段为例：
1GET my-index/_search
2{
3 "size": 3,
4 "_source": ["id"],
5 "query": {
6 "knn": {
7 "field_hnsw": { // 要检索的向量字段
8 "vector": [2, 3, 5, 6], // 查询向量
9 "k": 10,
10 "linear": true, // true代表直接进行精确检索，即扫描全量数据进行暴力计算，默认false
11 "filter": { // 填写所需的filter，不需要filter则省略
12 "term": {
13 "file-type": "png"
14 }
15 }
16 }
17 }
18 }
19}此外，也可以通过ES的script_score查询通过脚本计算进行精确检索，也是遍历全量数据进行暴力计算。
BES通过自定义script engine实现了简化的script计算逻辑，通过指定"lang":"knn"和"source":"bpack_knn_script"可以使用BES预定义的计算逻辑，只需要在params中指定向量字段和距离算法等参数即可。具体的距离计算公式和score计算公式请参考文档：算法介绍。示例如下：
1POST my-index/_search
2{
3 "size": 3,
4 "_source": ["id"],
5 "query": {
6 "script_score": {
7 "query": { // 填写所需要的filter，不需要filter则使用match_all
8 "match_all": {}
9 },
10 "script": {
11 "source": "bpack_knn_script", //固定参数
12 "lang": "knn", // 固定参数
13 "params": {
14 "space": "cosine", // 距离计算算法，支持 l2/cosine/innerproduct
15 "field": "field1", // 向量字段
16 "vector": [3.5, 2.5] // 查询向量
17 }
18 }
19 }
20 }
21}如果需要更灵活的计算逻辑，也可以直接使用默认的painless脚本语言，在source调用距离计算函数，完成复杂的计算。示例如下：
1GET my-index/_search
2{
3 "size": 3,
4 "_source": ["id"],
5 "query": {
6 "script_score": {
7 "query": { // 填写所需要的filter，不需要filter则使用match_all
8 "match_all": {}
9 },
10 "script": {
11 "source": "(1.0 + cosineSimilarity(params.query_vector, doc[params.field])) / 2", // 支持的距离计算函数包括，l2Squared/cosineSimilarity/innerProduct
12 "params": {
13 "field": "field1", // 向量字段
14 "query_vector": [3.5, 2.5] // 查询向量
15 }
16 }
17 }
18 }
19}