企业官网建设流程全解析

图索引参数调优实战：VexDB-Lite 的 m、ef_construction 与 ef_search 如何配置最优

【免费下载链接】VexDB-LiteA cross-platform vector database, which can be integrated into existing databases as a plugin.项目地址: https://gitcode.com/gh_mirrors/ve/VexDB-Lite

VexDB-Lite 是一款可嵌入 PostgreSQL、DuckDB、SQLite 的跨平台向量数据库。它的图索引（GRAPH INDEX / vexdb_graph）性能与召回率，几乎完全由三个参数决定：m、ef_construction和ef_search。本文带你从零理解这三个图索引参数的作用机制，并给出一套可直接上手的调优方法，帮你快速配出"又快又准"的向量索引。

一、先搞懂：三个参数各管什么？

VexDB-Lite 的图索引是一种多层图结构。可以把建图想象成"修路网"，把查询想象成"按图找最近邻居"：

• m（图连接度）：决定了图的"宽度"。m 越大，图越稠密，路径越多，长距离可达性越好，但索引体积和构建时间同步上升。
• ef_construction（建图候选队列）：插入新节点时，引擎会维护一个长度不小于 ef_construction 的候选集来挑选最终邻居。值越大，边质量越高、召回上限越高，但建图越慢。
• ef_search（查询候选队列）：查询时在图中动态维护的候选长度。它不改变索引文件，随时可调，是成本最低的调优旋钮。

📌 参数合法范围与默认值集中定义在 graph_index_param.h：

⚠️ 隐藏约束：建图时ef_construction必须≥ 2 × m，否则直接报错，见 graph_index_build.cpp。也就是说 m 调到 50 时，ef_construction 至少要 100。

二、图片向量检索：调优的典型场景

向量检索最常见的落地场景之一是"以图搜图"——把图片编码成向量后入库，再按相似度查询。VexDB-Lite 的 iOS Demo 就内置了这类演示数据（下图为其中的检索测试样本）：

这类 768 维左右的 embedding 向量，正是参数调优的主战场：维度高、数据量大，m 和 ef_construction 的取值会显著影响召回率与内存占用。

三、实战配置建议（分场景）

3.1 小数据集 / 低维向量（< 256 维、< 10 万条）

直接用默认值即可：m = 16, ef_construction = 64, ef_search = 40。参数过小（如m = 1或m = 200）会被拒绝，参数校验用例可见 graph_index_params.yaml。

3.2 中等规模通用配置（128 维、百万级以内）

CREATE INDEX idx_items_vec ON items USING vexdb_graph (vec floatvector_l2_ops) WITH ( m = 16, ef_construction = 128 );

这是官方文档推荐的起步配置（见 README.md），也是 SIFT-1M 基准测试所用的建图参数。查询端把ef_search提到 100~200 即可获得很稳的召回。

3.3 高质量场景（768 维、recall ≥ 0.99）

项目内部对 Cohere-1M（100 万条 768 维、余弦距离）的压测中，稳定达到 recall@10 ≈ 0.996 的组合是：

m = 24, ef_construction = 200, ef_search = 200

完整过程与数据记录在 2026-07-24-cohere-1m-parallel-retest.md。若数据量达到百万级且内存有限，可配合parallel_workers并行建图，并考虑 RaBitQ 量化压缩索引体积（compact 模式下物理体积可减少约 60%）。

3.4 查询端：ef_search 随时可调，无需重建索引

ef_search 是运行时参数，不同后端设置方式不同：

• PostgreSQL：SET vexdb.ef_search = 100;（见 README.md）
• DuckDB：SET vdb_vexdb_ef_search = 100;（运行时设置项vexdb_ef_search）

经验法则：ef_search ≥ 4 × topk时召回基本收敛；对精度要求极高（金融、医疗）可拉到 topk 的 8~10 倍，但 QPS 会近似线性下降，需自行权衡。

四、调优五步法：先建后调，用数据说话

1. 默认值建图：m = 16, ef_construction = 64，先跑通全链路；
2. 建立基准：准备 100~1000 条查询，用暴力检索算出 Ground Truth，测当前 recall@k 和 QPS（可参考 graph_index_recall.yaml 的写法）；
3. 先调 ef_search：从 40 逐步翻倍（80 → 160 → 320），观察 recall/QPS 曲线，这一步零重建成本；
4. 不够再动建图参数：若 ef_search 拉满仍达不到目标召回，把m提到 24~32、ef_construction提到 128~200，重建索引；
5. 回归验证：用vexdb_index_info()确认索引状态与参数生效（用法见 index_info.yaml），再复测 recall 与 QPS。

💡 核心心法：ef_search 管下限内的弹性，m 和 ef_construction 管天花板。天花板不够时，任何查询端技巧都救不回来。

五、常见误区避坑清单

六、总结

VexDB-Lite 图索引参数调优可以浓缩为一句话：

小数据用默认值（16/64/40），大数据提建图参数（24/200），精度不够先拉 ef_search，天花板不够再重建。

结合 graph_index_param.h 中的合法范围做约束检查，再用 recall/QPS 双指标闭环验证，你就能在速度、精度和存储之间找到属于自己的最优解。

【免费下载链接】VexDB-LiteA cross-platform vector database, which can be integrated into existing databases as a plugin.项目地址: https://gitcode.com/gh_mirrors/ve/VexDB-Lite