百度 Elasticsearch （简称BES）7.4.2版本同样提供的向量数据库能力，其API和功能与最新版（7.10.2+）略有区别，本文详细说明了7.4.2版本向量数据库能力的API和兼容说明。

注意：7.4.2版本的向量检索插件处于仅维护的状态，新增的feature和性能优化不会更新到7.4.2版本上，建议所有使用向量能力的用户使用7.10.2版本的BES集群。

升级兼容说明

用户升级到高版本BES（7.10.2+）时，当前已经启用向量检索的索引依旧可以使用，但是新建索引必须使用7.10版本的API，才能使用最新的向量检索功能特性。

背景

近年来基于Text(Document) Embedding、特征向量等的向量检索在推荐系统、图片的相似度检索中得到了广泛使用。用户可以使用Word2vec等工具将图像、音频、自然语言等复杂的数据信息映射为特征向量，再通过向量检索算法检索特征向量，从而实现了对复杂的数据信息的处理。为了处理向量数据，百度Elasticsearch向量检索插件提供了两种向量检索算法：linear算法和hnsw算法。

注意：目前向量检索插件支持功能发布后新创建的7.4.2的实例，您可以通过以下API查询集群是否支持knn插件，不支持向量检索插件的集群请提交工单，BES团队会协助升级集群，升级方式参见ES版本升级。

Plain Text 复制

1GET _cat/plugins?v

插件介绍

用户在写入数据前，需要根据自己向量的维度信息，并根据性能需求配置knn参数，选择需要的距离计算算法，创建所需的knn索引。创建好索引后，即可以写入数据，在索引完成构建后，可以通过下文提供的查询方式，进行向量检索查询。

创建knn索引

我们需要预先创建knn索引，创建方式如下：

如下示例，我们创建了一个名为test-index的索引，包含了field1和field2字段。您也可以根据自身需求，自定义索引名称和字段名称。

1PUT /test-index
2{
3    "settings": {
4      "index": {
5         "codec": "bpack_knn_hnsw",
6         "bpack.knn.hnsw.space": "cosine",
7         "bpack.knn.hnsw.m": 16,
8         "bpack.knn.hnsw.ef_construction": 512
9      }
10   },
11   "mappings": {
12      "properties": {
13         "field1": {
14            "type": "bpack_vector",
15            "dims": 2
16         },
17         "field2": {
18            "type": "bpack_knn_vector",
19            "dims": 2
20         }
21      }
22   }
23}

settings中的bpack.knn.hnsw参数含义见下文中索引级别参数优化。

写入与查询数据

写入数据

我们向刚才创建的索引test-index的_doc中写入数据，写入数据示例如下：

1POST /test-index/_doc/
2{
3    "field1" : [6.5, 2.5],
4    "field2" : [6.5, 2.5],
5    "price":10
6}

其中field1是我们刚设置为bpack_vector类型的字段，field2是我们刚设置为bpack_knn_vector类型的字段，price是其他普通字段。

在索引完成构建后，我们可以查询数据如下：

线性 linear 查询

linear算法可以查询bpack_knn_vector类型的字段，也可以查询bpack_vector类型的字段。下例中，我们查询的是bpack_vector类型的字段field1。

1POST /test-index/_search
2{
3   "query": {
4      "script_score": {
5         "query": {
6            "match_all": {}
7         },
8         "script": {
9            "source": "bpack_knn_script",
10            "lang": "knn",
11            "params": {
12               "space": "cosine",
13               "field": "field1",
14               "vector": [3.5, 2.5]
15            }
16         }
17      }
18   },
19   "size": 100
20}
21或
22POST /test-index/_search
23{
24  "query": {
25    "function_score": {
26      "boost_mode": "replace",
27      "script_score": {
28        "script": {
29          "source": "bpack_knn_script",
30          "lang": "knn",
31          "params": {
32            "space": "cosine",
33            "field": "field1",
34            "vector": [3.5, 2.5]
35          }
36        }
37      }
38    }
39  },
40  "size": 100
41}

其中查询参数含义为：

hnsw查询

使用hnsw的方式查询，该索引必须指定index.codec为bpack_knn_hnsw，且要查询的向量字段mapping指定的type必须是bpack_knn_vector。下例中，我们查询的是bpack_knn_vector类型的字段field2。

1POST /test-index/_search
2{
3    "size" : 10,
4    "query": {
5        "hnsw": {
6            "field2": {
7                "vector": [3, 4],
8                "k": 2,
9                "ef": 512
10            }
11        }
12    }
13}

2025-08-05后创建的集群使用字段"hnsw"进行查询，之前的集群使用"knn"进行查询，如下：

Plain Text 复制

1POST /test-index/_search
2{
3 "size" : 10,
4 "query": {
5     "knn": {
6         "field2": {
7             "vector": [3, 4],
8             "k": 2,
9             "ef": 512
10         }
11     }
12 }
13}

其中查询参数含义为：

Elasticsearch Score详解

向量检索引擎支持余弦距离（cosine）、欧式距离（l2）、点积（dot_prod）。

linear

距离算法	距离公式	Elasticsearch Score
l2
cosine
dot_prod
hammingbit（仅支持long型字段）	countSetBits(X ⊕ Y)	1 / (1 + countSetBits(X ⊕ Y))

hnsw

距离算法	距离公式	Elasticsearch Score
l2
cosine

参数优化

索引级别的参数

创建索引时必须提供索引settings参数。如果用户不进行配置，将使用默认值。注意，以下参数只能在创建索引时配置，索引创建后不可修改。具体参数解析如下：

集群级别的参数

通用参数

缓存设置

Elasticsearch向量检索插件使用Guava cache管理内存。

linear算法缓存参数设置

hnsw算法缓存参数设置

Circuit Breaker（断路器）设置

当加载到内存中的图形达到了集群的限制，并使集群性能下降时，Circuit Breaker将会启动。目前，当内存达到此限制，会触发驱逐机制，驱逐不常用的缓存项，而不会执行其他操作。

示例

1PUT /_cluster/settings
2{
3    "persistent" : {
4        "bpack.knn.hnsw.index_thread_qty" : 1,
5        "bpack.knn.cache.item.expiry.enabled": true,
6        "bpack.knn.cache.item.expiry.time": "15m",
7        "bpack.knn.memory.cache.limit": "1g",
8        "bpack.knn.memory.cache.expiry.time":"10m",
9        "bpack.knn.memory.circuit_breaker.limit" : "55%",
10        "bpack.knn.circuit_breaker.unset.percentage": 23
11    }
12}

查看hnsw算法的相关统计信息

查询状态的方式如下：

1GET /_bpack/_knn/stats
2GET /_bpack/_knn/nodeId1,nodeId2/stats/statName1,statName2

结果示例如下：

1{
2   "_nodes": {
3      "total": 1,
4      "successful": 1,
5      "failed": 0
6   },
7   "cluster_name": "my-application",
8   "circuit_breaker_triggered": false,
9   "nodes": {
10      "HYMrXXsBSamUkcAjhjeN0w: {
11         "eviction_count" : 0,
12         "miss_count" : 1,
13         "graph_memory_usage_kb" : 1,
14         "cache_capacity_reached" : false,
15         "load_exception_count" : 0,
16         "hit_count" : 0,
17         "load_success_count" : 1,
18         "total_load_time_nanos" : 2878745
19      }
20   }
21}

集群状态参数：

节点状态参数：

性能对比

• 内存配置：30G
• cpu配置：逻辑核数56，2个物理cpu，每个cpu cores : 14
• Elasticsearch 节点：单节点

性能对比结果如下：

算法总结

• linear算法适用场景：

  • 数据量小(通常单分片在100w以下)；
  • 先执行正常的搜索过滤条件，然后在过滤后的结果集上进行向量检索计算；
  • 召回率100%，查询性能相比hnsw较慢

• hnsw算法适用场景：

  • 数据量相对大(集群数据量在千万级)；
  • 向量检索计算和其他过滤同时进行，建议适当的增大hnsw的查询参数k，以保证尽可能多的满足过滤条件的数据参与计算；
  • 查询性能要求高，召回率在90%以上

典型实践

• 建议写入结束后，在业务低峰期进行定期forceMerge，有助于降低查询延迟。
• 使用linear算法查询时，要根据数据量大小，定义好"bpack.knn.memory.cache.limit"参数。比如节点数据量为10G，如果使用"bpack.knn.memory.cache.limit"的默认值（计算2型默认值为30G*10%=3G），则会无法缓存。当大量查询时，有可能触发Elasticsearch的熔断操作，报错circuitBreakingException。

• 当构建较大数据量的向量索引时，可能会出现build较慢的情况，可以根据分片数和节点cpu核数，在写入数据前适当调整"bpack.knn.hnsw.index_thread_qty" 。例如，1kw数据量，1节点2分片，节点为16核cpu，我们可以把"bpack.knn.hnsw.index_thread_qty" 设置为4-6（如果设置为8，会使cpu满载，生产环境可能有风险），可以提高构建效率。

  需要注意的是，"bpack.knn.hnsw.index_thread_qty" 参数设置偏大，会导致构建时启动线程过多。在负载比较高的集群，不建议调整这个参数，以免集群满载。如果写入和构建向量索引偏慢，可以通过临时减少集群负载（减少其他写入和查询），并调大"bpack.knn.hnsw.index_thread_qty"的方式来加快构建 ，等到构建结束，再将"bpack.knn.hnsw.index_thread_qty" 调整回1。

• 当写入数据量为1kw条（比如约为10G）、1节点1分片、计算2型节点（16核cpu、64G内存）时，推荐参数设置为：

  Plain Text 复制

  1PUT /_cluster/settings
  2{
  3    "persistent" : {
  4        "bpack.knn.hnsw.index_thread_qty" : 1,
  5        "bpack.knn.cache.item.expiry.time": "1h",
  6        "bpack.knn.memory.circuit_breaker.limit" : "70%"
  7    }
  8}

Plain Text 复制

1   分析：
2
3   1. `"bpack.knn.hnsw.index_thread_qty" : 1`：通常情况下，建议设置为1；当索引构建过慢，可以参考上一条建议适当调整这个参数。
4   2. `"bpack.knn.cache.item.expiry.time": "1h"`：可以根据自己需求的业务设定超时时间。
5   3.  `"bpack.knn.memory.circuit_breaker.limit" : "70%"`：计算2型Elasticsearch的默认jvm内存为30G。"bpack.knn.memory.circuit_breaker.limit"为 70%*（64-30）=23.8G，可以容纳数据所占据的堆外内存。

常见问题

• Q：召回率是怎么定义的？

  A：用同样的向量查询两种查询方式，对比召回的文档，取二者相同的文档与召回文档总数的比值，即为待测向量的召回率。我们用召回率来表征查询的准确率。

• Q：为什么写入已经成功完成，索引的文档数并没有增加或完全达到写入量，且此时可能会查询失败？

  A：向量索引的构建发生在refresh或flush期间，虽然写入已经完成，但后台的向量索引构建任务可能仍然在继续。

• Q：如何安装向量检索插件？

  A：新申请的7.4.2+版本集群，自带向量检索插件；如果您需要在集群安装向量检索插件，可以联系客服协助安装。