Endee向量数据库元数据过滤深度解析：RoaringBitmap预过滤如何让检索快10倍

【免费下载链接】endeeEndee.io – A high-performance vector database, designed to handle up to 1B vectors on a single node, delivering significant performance gains through optimized indexing and execution. Also available in the cloud at https://endee.io and under the Endee Enterprise license. Free 30-day evaluation: https://docs.endee.io/v2/quick-start/enterprise项目地址https://gitcode.com/gh_mirrors/en/endee点击查看免费下载Endee是一个高性能开源向量数据库vector database目标是让单节点承载多达 10 亿向量。在 RAG 检索、商品搜索等场景中你几乎总需要带着元数据条件做查询例如「City NY 且 Age ∈ [18,25]」。Endee 的过滤系统采用RoaringBitmap 预过滤Pre-Filtering架构先用位图集合运算算出合法 ID 集合再自适应选择暴力搜索或过滤版 HNSW 图搜索。在高选择性过滤条件下相比先搜后滤这条路径的检索延迟可以缩短一个数量级约 10 倍。下面从执行流程、优化技巧到存储设计带你完整看懂它的实现。后过滤的困境top-k 结果被过滤打穿传统的**后过滤Post-Filtering**思路是先让 HNSW 返回 top-k再逐个检查是否满足条件。问题在于——如果 100 条结果里只有 2 条符合条件系统被迫扩大ef参数重新搜索图遍历开销成倍增加最终召回的候选数量可能远超你需要计算距离的数量。预过滤Pre-Filtering则反转了这个顺序先确定哪些 ID 有资格参与比较再在这个候选集上做距离计算。Endee 的官方设计文档 docs/filter.md 明确将这一策略列为全局执行主线The system prioritizesPre-Filteringfollowed by an adaptive search execution path.RoaringBitmap 预过滤一次过滤查询的三步执行流程Endee 的所有元数据索引都以 RoaringBitmap 作为统一的中间表示——它压缩存储 ID 集合并让AND交集、OR并集、contains()成员判断都是接近 O(1) 或 O(n/64) 的位运算。一次带过滤的查询会经历三个阶段核心实现在 src/filter/filter.hpp#L209-L377 的computeFilterBitmap第 1 步解析条件并估计基数Cardinality过滤条件使用类 MongoDB 的 JSON 语法支持三种操作符操作符示例适用类型$eq{City: {$eq: NY}}全部类型$in{City: {$in: [NY, London]}}全部类型$range{Age: {$range: [18, 25]}}仅数值类型每个原子条件先被翻译成一个位图同时位图的cardinality()元素个数给出了该条件结果集的规模估计。第 2 步最便宜优先——小集合先交集空集立即终止这是整套设计中最精妙的一处优化。多个条件AND语义的位图会先按基数从小到大排序再依次求交集// src/filter/filter.hpp — 按基数排序后逐个 AND std::sort(partial_results.begin(), partial_results.end(), [](const ndd::RoaringBitmap a, const ndd::RoaringBitmap b) { return a.cardinality() b.cardinality(); });见 src/filter/filter.hpp#L361-L374背后的直觉很简单City NY可能只剩 500 个 ID而Age ∈ [18,25]还有 1 万个先交小的那个中间结果会迅速瘦身。更妙的是早期终止——一旦中间交集变空直接返回剩余条件根本不用算。对于不可能同时满足的组合查询这一步就能把成本压到接近零。第 3 步自适应搜索路径——暴力还是 HNSW得到最终的合法 ID 位图后Endee 并不会无脑走 HNSW而是根据位图规模在两条路径之间切换决策逻辑在 src/core/ndd.hpp#L1564-L1614合法 ID 数量策略原因少于阈值默认 10,000暴力搜索批量取向量直接算距离候选集已很小图遍历的开销反而成了浪费达到或超过阈值过滤版 HNSW位图注入图搜索过程候选集大仍需要图结构加速定位近邻阈值由常量PREFILTER_CARDINALITY_THRESHOLD定义默认 10,000见 src/utils/settings.hpp#L104并可通过查询参数prefilter_threshold按请求调整见 src/main.cpp#L932-L933。两条搜索路径的底层实现策略 A小规模暴力搜索。直接遍历位图中的 ID批量从向量存储中取出向量调用hnswlib::searchKnnSubset在子集上计算距离。因为候选集只有几千个全量计算距离比走图更快——跳过了图的建边、邻域展开等一切固定开销。策略 B过滤版 HNSW。位图被封装成一个判断器挂到 HNSW 的searchKnn搜索循环上定义见 src/filter/filter.hpp#L48-L55class BitMapFilterFunctor : public hnswlib::BaseFilterFunctor { bool operator()(ndd::idInt id) override { return bitmap_.contains(id); // 位图成员判断近乎 O(1) } };图搜索每扩展到一个节点就用位图判断它是否有资格不合格的直接跳过、继续前进。距离计算只发生在合法节点上这就是快 10 倍的主要来源——被过滤掉的向量连距离都不用算。三类元数据索引为不同字段选对数据结构预过滤能快前提是条件 → 位图这一步本身要快。Endee 按字段类型提供了三套存储设计完整方案见 docs/filter.md数值索引混合桶 B 树为范围查询而生数值字段如 Age、Price走的是 src/filter/numeric_index.hpp 中的混合桶结构LMDB 充当粗粒度 B 树键是[字段ID] [32位基值]。浮点数先通过位翻转技巧映射为字典序与数值序一致的整数float_to_sortable见 src/filter/numeric_index.hpp#L34-L41这样一次范围扫描就能覆盖整个区间桶内压缩存储每个桶最多 1024 个值用uint16_t增量相对基值的差值存储大幅压缩空间桶级 Summary Bitmap每个桶预存了一份桶内所有 ID 的并集位图。范围查询完全覆盖的中间桶直接取这份位图零数组访问O(1) 拿结果只有部分重叠的边缘桶才需要逐值扫描。类别索引倒排索引为精确匹配而生类别字段如 City用文本键倒排索引src/filter/category_index.hpp键为字段名:值如City:NY值就是序列化的 RoaringBitmap。精确匹配是一次键查找$in查询则是多次查找后做位图并集。这个设计还天然支持前缀扫描为后续 faceting分面统计留了余地。布尔索引双键设计排在最后处理布尔字段如is_active是类别索引的特例只有两个键is_active:0和is_active:1。由于布尔条件通常选中约 50% 的数据选择性低Endee 把它放在交集链的最后处理避免用大而松散的位图拖累前面的交集运算。实用调优清单让你的过滤检索更快给条件排序不是必须的了引擎会自动按基数排序执行但你在业务上把最挑剔的条件写进过滤表达式依然能受益于空集早期终止调prefilter_threshold如果你的过滤结果普遍在几千以内调低阈值可以让更多查询走暴力小集合路径跳过图开销反之若过滤很宽松调高阈值避免小图搜索退化成全量扫描字段类型首写定终身Endee 采用 First-Write Wins 的类型绑定见 docs/filter.md#L88-L95某字段第一次被索引的类型数值/类别/布尔会永久生效后续类型不匹配的写入会被拒绝。设计数据模型时先定好字段类型能避免索引腐坏过滤字段别太长类别值上限 255 字节超长会直接报错混合检索同样受益带过滤的查询中稀疏检索与稠密检索并行执行两者都接收同一份过滤位图最终用 RRF 融合见 src/core/ndd.hpp#L1617-L1658。关键源码路径速查模块路径说明过滤设计文档docs/filter.md全局策略与三类索引的完整设计过滤入口与位图交集src/filter/filter.hpp#L209-L377条件解析、基数排序、早期终止位图判断器src/filter/filter.hpp#L48-L55注入 HNSW 的BitMapFilterFunctor数值索引混合桶src/filter/numeric_index.hpp#L60-L117桶结构、增量压缩、Summary Bitmap类别索引倒排src/filter/category_index.hpp文本键 序列化位图自适应搜索决策src/core/ndd.hpp#L1564-L1614暴力 vs 过滤版 HNSW 的切换逻辑阈值与配置src/utils/settings.hpp#L104PREFILTER_CARDINALITY_THRESHOLD 10,000过滤行为测试tests/filter_test.cpp类别/布尔/数值/混合条件的用例RoaringBitmap 库third_party/roaring_bitmap/roaring.h底层位图数据结构小结Endee 元数据过滤的速度秘密可以浓缩成三句话用 RoaringBitmap 把记录检查升级为位图集合运算按基数从小到大求交集并尽早终止在暴力小集合搜索与过滤版 HNSW 之间自适应切换。预过滤不是单纯的一个技巧而是一套存储结构 集合运算 执行路径协同设计的结果——这正是它能在一亿级向量上依然保持毫秒级过滤检索的原因。想动手验证的话tests/filter_test.cpp 中的用例覆盖了从简单精确匹配到多条件混合逻辑的完整链路是最好的入门路径。赞分享【免费下载链接】endeeEndee.io – A high-performance vector database, designed to handle up to 1B vectors on a single node, delivering significant performance gains through optimized indexing and execution. Also available in the cloud at https://endee.io and under the Endee Enterprise license. Free 30-day evaluation: https://docs.endee.io/v2/quick-start/enterprise项目地址https://gitcode.com/gh_mirrors/en/endee点击查看免费下载相关推荐如何基于Endee构建RAG检索层语义搜索元数据过滤完整实践指南如何基于Endee构建RAG检索层语义搜索元数据过滤完整实践指南 Endee 是一个高性能的开源 向量数据库 专为 RAG检索增强生成、 语义搜索 与LlamaIndex VectorDB Tool 深度解析用 auto_retrieve_fn 为 Agent 赋予带元数据过滤的向量检索能力LlamaIndex VectorDB Tool 深度解析用 auto_retrieve_fn 为 Agent 赋予带元数据过滤的向量检索能力 llama i人工智能RAG大模型langchaingo 接入 Chroma 向量数据库实战指南从 Docker 部署到相似度检索与元数据过滤langchaingo 接入 Chroma 向量数据库实战指南从 Docker 部署到相似度检索与元数据过滤 本篇技术指南围绕 langchaingo 内置的人工智能大模型AI AgentRAG后端创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考