参数优化

更新时间：2025-08-20

用户可以参考本文档，对集群性能进行优化。

索引配置 index settings

Setting	默认值	说明
index.bpack.knn.build.enable	true	此参数表示索引当前是否进行构建向量索引结构，修改该参数只对增量有效。对于一次性写入的场景，最佳实践是将index.bpack.knn.build.enable置为false，在写入完成后，执行构建api。

集群配置 cluster settings

Setting	默认值	说明
bpack.knn.index_thread_qty	1	此参数表示 ann lib 构建允许使用的线程数。（默认情况下， ann lib 将此值设置为内核数n。但是，由于Elasticsearch可以创建n个用于生成索引的线程，并且如果每个索引线程都调用 ann lib 来构建算法模型，也就是说每个线程都会生成n个线程，这可能导致同时n^2个线程运行，可能导致100%的CPU利用率。所以默认将此值设为1），取值范围为[1,32]。
bpack.knn.cache.item.expiry.enabled	false	此参数表示缓存数据是否会过期删除。
bpack.knn.cache.item.expiry.time	3h	此参数表示当数据持续这个时间不被访问时，将从缓存中清除。使用TimeUnit格式表示，例如『10s』、『10m』、『3h』等，不可设置为小数值，如『1.5h』。建议设置超过30分钟，使缓存结果能够被接下来的查询有效命中；如果设置过小，则会很快被清除。
bpack.knn.memory.circuit_breaker.limit	50%	此参数表示指示缓存的最大容量。当此时hnsw的缓存超过了缓存的最大容量限制，将触发驱逐操作，并将circuit_breaker_triggered状态设置为true（可以通过查询统计信息api查询）。该值可以设置为百分数，代表除去Elasticsearch的jvm外，服务器剩余内存的百分比，也可以设置为一个带有存储容量单位的值，例如『10kb』、『10mb』、『3g』等，不建议设置为小数值，如『1.5g』。例如，一台机器拥有100GB内存，Elasticsearch的jvm使用了32GB。那么bpack.knn.memory.circuit_breaker.limit的默认值为(50% * (100 -32) = 34GB)。
bpack.knn.circuit_breaker.unset.percentage	75%	此参数表示Circuit Breaker的解除百分比，当缓存容量大小低于bpack.knn.circuit_breaker.unset.percentage时，Circuit Breaker将解除触发，将circuit_breaker_triggered状态设置为false（可以通过查询状态api查询）。
bpack.knn.model.index.number_of_shards	1	存储模型使用的索引的分片数。
bpack.knn.model.index.number_of_replicas	1	存储模型使用的索引的副本分片数。

参数配置建议与性能优化

hnsw 参数

M

M 越大，内存消耗越高，构建索引时间越长，在高维度的数据集下查询性能会越好。通常建议设置在8~48之间。

ef_construction

影响索引时间和索引准确度。ef_construction越大，构建索引时间越长，但查询精度越高。要注意ef_construction 提高并不能无限增加索引的质量，建议取值256以上。需要注意，用户业务需求会要求top k，那这时候ef的取值必须大于k。

ivf 参数

nlist

一般建议 nlist = C * sqrt(N)，C为用户自选的常数，可以根据具体情况调整，比如可以从C=4开始尝试，再根据业务所需要的召回率来调整测试。

nprobe

nprobe越大，recall越高，但查询性能越差。可以从nprobe=16 或 nlist / 32 开始调整。再参照用户目标召回率来调整，如果取值等于nlist，则查询性能会跟暴力检索效果相似。

pq 参数

m

向量字段做pq算法的分段数，一般建议设置为向量维数的1/4；m 取值越小内存占用越小，查询速度越快，精度也更低。

code_size

默认为8，不建议调整

状态查询

查询状态的方式如下：

Plain

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

结果示例如下：