LEANN 基准测试与回归验证指南DiskANN 与 HNSW 后端对比、距离函数正确性与端到端 sanity check【免费下载链接】LEANN[MLsys2026 Best Paper]: https://arxiv.org/abs/2506.08276. RAG on Everything with LEANN. Enjoy 97% storage savings while running a fast, accurate, and 100% private RAG application on your personal device.项目地址: https://gitcode.com/GitHub_Trending/le/LEANNLEANNLocal Embedding-based ANN是一个面向个人设备、主打隐私与存储效率的 RAG 检索系统。本文基于仓库 benchmarks/README.md 展开系统讲解 LEANN 的基准测试benchmark与健全性测试sanity check体系如何对比 DiskANN 与 HNSW 两个后端在搜索延迟、索引体积、构建时间上的差异如何验证 MIPS / L2 / Cosine 三种距离度量的正确性以及如何把这一整套验证接入 CI/CD 流水线。读完本文你将掌握 LEANN 性能验证的标准操作流程、各测试脚本的命令行用法与关键参数并能从源码层面理解其背后的实现原理。一、benchmarks 目录在 LEANN 中的角色benchmarks/目录承载了两类任务一类是后端性能对比基准如 DiskANN vs HNSW 的速度对比脚本 benchmarks/diskann_vs_hnsw_speed_comparison.py另一类是健全性测试distance function、L2 验证、端到端 sanity check用于在多种配置下对系统做冒烟验证确保每次改动后检索链路仍然正确。从目录结构看benchmarks/下还包含bm25_diskann_baselines/BM25 与 DiskANN 基线对比、enron_emails/、financebench/、laion/、update/等专项评测而本文聚焦的正是目录入口文档 benchmarks/README.md 所描述的四个测试脚本及其配套方法。值得注意的一点README 中列举的tests/sanity_checks/test_distance_functions.py、test_l2_verification.py、test_sanity_check.py三个脚本在当前仓库快照中尚未落盘其对应的功能覆盖由 tests/ 目录下的 pytest 测试如 tests/test_basic.py、tests/test_diskann_partition.py承担。下文以 README 记载的脚本与命令为准进行讲解并同时给出当前仓库中可实际运行的等价验证途径。二、DiskANN vs HNSW 性能对比基准2.1 脚本职责与覆盖点benchmarks/diskann_vs_hnsw_speed_comparison.py 是 README 中唯一一个当前仓库真实存在的基准脚本其对比目标非常明确搜索延迟Search latency两个后端均在开启 recompute 模式下对比索引体积Index size与构建时间build time量化两种图索引在磁盘占用上的差异分数有效性Score validity确保检索结果中不出现-inf分数可配置数据集规模支持通过命令行参数调整文档数与查询数脚本内部通过create_test_texts(n_docs)生成合成测试文档使用固定随机种子np.random.seed(42)保证可复现从 10 个主题machine learning、NLP、computer vision、data science 等中循环取样并拼接内容变化量形成规模可控的测试语料benchmarks/diskann_vs_hnsw_speed_comparison.py 第 28-55 行。2.2 命令行用法README 给出的两种运行方式# 快速对比500 篇文档、10 条查询 python benchmarks/diskann_vs_hnsw_speed_comparison.py # 大规模对比2000 篇文档、20 条查询 python benchmarks/diskann_vs_hnsw_speed_comparison.py 2000 20脚本还内置了-h/--help帮助信息支持[n_docs] [n_queries]两个位置参数默认值分别为 500 与 10当文档数达到 2000 以上时可明显拉开两个后端在构建时间和搜索延迟上的差距脚本第 231-260 行的参数解析逻辑。2.3 两组后端的公平配置为了公平对比脚本对两个后端做了参数对齐脚本第 161-183 行后端关键参数取值作用HNSWis_recomputeTrue开启重算模式保证与 DiskANN 同一精度基线HNSWM16HNSW 图每个节点的最大连接数HNSWefConstruction200建图时的候选队列大小越大图质量越高DiskANNis_recomputeTrue开启图分区graph partitioningDiskANNnum_neighbors32图邻居数DiskANNsearch_list_size50搜索时的候选列表大小两个后端统一使用facebook/contriever嵌入模型、sentence-transformers嵌入模式脚本第 73-78 行构建完成后用LeannSearcher(index_path)对同样的 10 条查询执行top_k5检索并统计平均耗时。2.4 输出与判定逻辑脚本最终打印一张对比表Build Time / Search Time / Index Size / Score Validity 四行指标并给出两个结论性摘要若search_speedup 1则输出 DiskANN is X.XXx faster than HNSW for search反之输出 HNSW 更快根据索引体积比值输出哪个后端占用更多或更少存储同时报告两个后端共同的分数有效性下限脚本第 215-228 行。分数有效性通过遍历所有result.score统计既非-inf也非inf的占比得到——这是对 README 所述确保没有 -inf 分数的代码级印证脚本第 112-121 行。从源码结构看该脚本刻意在finally块中执行gc.collect()并调用os._exit(0)强制退出以避免 atexit 钩子或残留线程导致进程挂起脚本第 262-287 行。三、距离函数健全性测试MIPS / L2 / Cosine3.1 测试目标test_distance_functions.py对 DiskANN 后端支持的全部距离函数做回归验证MIPSMaximum Inner Product Search最大内积搜索L2欧氏距离Cosine余弦相似度三种度量的语义截然不同MIPS 偏好模长大的向量适合非归一化嵌入L2 度量的是空间直线距离Cosine 只关心方向、忽略模长适合归一化嵌入。3.2 源码层的度量映射距离度量的支持在 DiskANN 后端中是通过 packages/leann-backend-diskann/leann_backend_diskann/diskann_backend.py 完成的其中将字符串参数显式映射到底层 diskannpy 的枚举mips: diskannpy.Metric.INNER_PRODUCT, l2: diskannpy.Metric.L2, cosine: diskannpy.Metric.COSINE,diskann_backend.py 第 70-72 行若传入不支持的度量名称后端会抛出Unsupported distance_metric ...的ValueError第 252-256 行默认值则是mips。3.3 运行方式uv run python tests/sanity_checks/test_distance_functions.pyREADME 同时提示必须在项目根目录下运行否则会出现 Import 错误。当前仓库中与三种距离度量相关的实际测试还包括 tests/test_document_rag.py验证归一化嵌入被自动检测并使用 cosine 距离。归一化检测与自动切换逻辑位于 packages/leann-core/src/leann/api.py 的LeannBuilder.__init__当检测到 OpenAI、Voyage、Cohere 等输出归一化向量的模型时会自动把distance_metric设置为cosine并发出UserWarning第 469-536 行。3.4 为什么需要区分度量从 api.py 的实现可以推断归一化嵌入L2 范数为 1应使用 cosine 而非 MIPS否则检索排序会偏离预期。因此健全性测试不仅要验证三种度量都能跑通还要验证不同度量产生符合各自语义的分数区间与排序。这正是 README 中Score ranges are appropriate for each metric type与Different metrics can produce different rankings (as expected)两句验收标准的含义。四、L2 距离专门验证test_l2_verification.py针对 L2 度量做专项验证方法论包含三步分别用L2与Cosine度量构建索引对比两者的搜索结果与分数范围验证不同度量确实产生符合预期的分数模式。uv run python tests/sanity_checks/test_l2_verification.pyL2 与 Cosine 在数学上存在关联对归一化向量L2 距离越小等价于余弦相似度越大但分数符号与量纲不同。该测试存在的意义是防止后端在实现度量时出现张冠李戴——例如错误地把 L2 结果当 cosine 分数返回或者出现符号反转。从代码结构看HNSW 后端在 packages/leann-core/src/leann/api.py 的更新流程中也会依据distance_metric cosine对增量向量做 L2 归一化后再写入索引第 995-999 行这说明度量选择会贯穿构建、更新、检索全链路专项验证非常必要。五、端到端 Sanity Checktest_sanity_check.py是覆盖面最广的综合验证README 列出的验证维度包括距离函数测试嵌入模型兼容性搜索结果正确性验证后端集成测试uv run python tests/sanity_checks/test_sanity_check.py在当前仓库中与之目标等价的 pytest 实现是 tests/test_basic.py它通过pytest.mark.parametrize(backend_name, [hnsw, diskann])对两个后端分别执行建索引 → 搜索 → 断言结果的完整链路第 21-58 行并使用facebook/contrieversentence-transformers的组合与基准脚本一致test_large_index()则用 1000 篇文档验证大语料下的top_k10检索第 64-85 行。另外 tests/test_diskann_partition.py 专门测试 DiskANN 图分区is_recomputeTrue下的建索引、分区文件生成与大文件清理存储节省并包含 DiskANN分区与 HNSW 的性能对比——它因硬件与计算时间要求较高在 CI 中默认跳过仅在本地机器运行。六、这些测试到底在验证什么README 用四个维度总结了全部测试的验收目标这里结合源码逐一展开6.1 距离函数支持三种度量MIPS、L2、Cosine均能正确工作每种度量的分数范围符合其语义如 cosine 分数通常落在合理区间而非-inf/inf不同度量可以产生不同排序符合预期而非实现缺陷。6.2 后端集成DiskANN 后端能正确初始化并构建索引图构建过程无错误完成搜索操作返回有效结果。源码层面DiskANN 后端在 diskann_backend.py 中把complexity搜索候选列表大小默认 64与graph_degree图度数默认 32透传给底层建图调用第 313-314 行搜索侧complexity也以默认 64 参与候选扩展第 479 行起。这两个参数直接决定速度 vs 精度的取舍。6.3 嵌入流水线实时嵌入计算可用支持多种嵌入模型ZMQ 服务器通信正常。嵌入流水线的实现位于 packages/leann-core/src/leann/api.pycompute_embeddings()在use_serverTrue搜索阶段时通过compute_embeddings_via_server()走 ZMQ REQ 套接字向嵌入服务器发送 msgpack 序列化的文本块并接收浮点数组第 117-150 行在use_serverFalse构建阶段时走 embedding_compute.py 直接计算。支持sentence-transformers、mlx、openai、gemini等多种嵌入模式第 87-91 行。6.4 端到端功能完整的建索引 → 搜索 → 取结果流水线元数据在全程中得到保留错误处理与优雅降级。LeannBuilder.build_index()会同时写出.passages.jsonl、.passages.idx与.meta.jsonapi.py 第 561-683 行LeannSearcher通过元数据中的passage_sources定位文本与偏移文件从而在向量检索命中后还原原始文本与元数据PassageManager.get_passage()采用分片偏移映射按需读取避免在超大语料上物化全局大字典第 245-257 行。七、预期输出所有测试通过时终端应看到如下形式的汇总README 原文 测试结果总结: mips : ✅ 通过 l2 : ✅ 通过 cosine : ✅ 通过 测试完成!八、故障排查8.1 Import 错误确保从项目根目录运行cd /path/to/leann uv run python tests/sanity_checks/test_distance_functions.pyLEANN 的后端leann_backend_diskann、leann_backend_hnsw与核心leann均以包形式安装在项目环境中脱离根目录执行会导致模块找不到。8.2 内存不足对于资源受限系统可通过降低图的复杂度来缩减内存builder LeannBuilder( backend_namediskann, graph_degree8, # 从默认值下调 complexity16, # 从默认值下调 )需要说明的是从 diskann_backend.py 的源码看graph_degree与complexity的实际默认值分别是 32 与 64第 313-314 行README 示例中Reduced from 16 / 32的表述对应的可能是不同版本或用户自定义基线实际降配时应以源码默认值为参照。降低graph_degree会缩小图邻接表降低complexity会减少搜索候选二者都能显著减少内存与构建开销但会牺牲一定召回率。8.3 ZMQ 端口冲突测试会使用不同端口以避免冲突但如果残留的嵌入服务器进程占用了端口可先清理pkill -f embedding_server这与 api.py 中通过EmbeddingServerManager动态启动、按需停止嵌入服务器的设计相呼应更新索引时若needs_recompute为真会临时拉起 ZMQ 嵌入服务器并在finally中关闭第 1122-1166 行。九、性能预期3 篇文档、消费级硬件README 给出了小规模场景下的经验参考值注意这些数据是在极小语料3 篇文档与消费级硬件上测得的不代表大规模场景指标经验值说明索引构建每个距离函数 2–5 秒小语料下建图开销搜索查询50–200 ms单条查询端到端延迟Recompute 模式5–15 秒开启重算时精度更高、耗时更长索引存储每个距离函数约 1–2 MB磁盘占用运行时内存约 500 MB含模型加载模型常驻内存从基准脚本的设计可以推断构建时间与索引体积会随文档数近似线性增长而搜索延迟随图规模增长较缓——这正是图索引HNSW/DiskANN相比暴力检索的核心优势所在。文档规模增大时建议用python benchmarks/diskann_vs_hnsw_speed_comparison.py 2000 20这类参数获取更有区分度的对比数据。十、接入 CI/CD这些测试被设计为可在自动化环境运行README 给出了 GitHub Actions 的最小示例# GitHub Actions example - name: Run Sanity Checks run: | uv run python tests/sanity_checks/test_distance_functions.py uv run python tests/sanity_checks/test_l2_verification.py测试被设计为确定性的deterministic固定随机种子、固定语料、固定参数因此跨平台应产生一致结果。当前仓库中 pytest 体系的 CI 集成方式见 tests/README.md要点包括用uv sync --only-group test安装测试依赖全量运行pytest tests/可加--covleann、-n auto等参数通过标记marker控制范围-m not openai、-m not slow、-m not integration按后端定向测试pytest tests/test_basic.py::test_backend_basic[hnsw]或[diskann]或pytest tests/ -k diskannCI 在打包 wheel 后于多 Python 版本3.9–3.13、Ubuntu 与 macOS 上运行pytest.ini配置了 600 秒默认超时与HF_HUB_DISABLE_SYMLINKS、TOKENIZERS_PARALLELISM等环境变量。十一、总结一套可复用的验证方法论从 benchmarks/README.md 可以提炼出 LEANN 性能与正确性验证的完整方法论用固定种子合成语料保证可复现 → 用统一的LeannBuilder/LeannSearcherAPI 屏蔽后端差异 → 用公平参数对齐recompute 相同嵌入模型做横向对比 → 用分数有效性检查兜底数值异常 → 用距离函数专项测试锁定度量语义 → 最终接入 CI 实现持续回归。这套体系对 RAG 系统开发者同样具有迁移价值无论使用哪个 ANN 后端性能对比都应显式声明数据集规模、图参数与重算模式健全性测试则应覆盖度量选择、嵌入流水线、端到端元数据保留三个层面。相关源码与测试可直接在仓库中查阅benchmarks/diskann_vs_hnsw_speed_comparison.py、packages/leann-core/src/leann/api.py、packages/leann-backend-diskann/leann_backend_diskann/diskann_backend.py、tests/test_basic.py 与 tests/test_diskann_partition.py。【免费下载链接】LEANN[MLsys2026 Best Paper]: https://arxiv.org/abs/2506.08276. RAG on Everything with LEANN. Enjoy 97% storage savings while running a fast, accurate, and 100% private RAG application on your personal device.项目地址: https://gitcode.com/GitHub_Trending/le/LEANN创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考