当前位置：首页 > news >正文

PipeANN：十亿向量毫秒级检索，SSD流水线优化实战

news 2026/5/14 10:37:49

1. 项目概述：PipeANN，一个面向十亿级向量的超低延迟SSD向量检索库

如果你正在处理海量的向量数据，比如构建一个需要支持十亿级别向量、同时要求毫秒级响应延迟的推荐系统或图像检索服务，那么内存容量和成本可能会成为你最大的噩梦。传统的基于内存的图索引（如HNSW）虽然快，但动辄需要数百GB甚至TB级别的内存，而像DiskANN这类基于磁盘的解决方案，虽然内存友好，但搜索延迟又常常难以满足在线服务的苛刻要求。正是在这个背景下，PipeANN诞生了。

PipeANN是一个开源的、基于SSD的图向量检索库，它的核心目标非常明确：在保持内存占用极低（十亿向量仅需约40GB内存）的前提下，实现接近内存索引的搜索性能。根据官方数据，在十亿规模（SPACEV-1B数据集）上，PipeANN能做到Top-10召回率90%时，延迟低于1毫秒，吞吐量高达20K QPS，这个性能表现是相当惊人的。它本质上解决了大规模向量检索场景中“既要内存小，又要延迟低”的核心矛盾。

我花了一些时间深入研究并部署测试了PipeANN，它给我的感觉更像是一个“系统级”的优化作品，而不仅仅是一个算法库。它通过一系列精巧的设计，将图搜索算法与SSD的硬件特性（尤其是NVMe SSD的高并发低延迟I/O）深度对齐，从而榨干了硬件的性能潜力。无论是对于需要构建超大规模向量数据库的工程师，还是对于研究近似最近邻搜索（ANNS）算法的研究者，PipeANN都是一个非常值得深入学习和借鉴的项目。

2. 核心设计思路：如何让磁盘搜索跑出内存的速度？

PipeANN的性能突破并非偶然，而是源于其背后几个关键的设计哲学。理解这些，你就能明白它为什么能脱颖而出。

2.1 传统磁盘ANN索引的瓶颈在哪里？

在PipeANN出现之前，基于磁盘的图索引（以DiskANN为代表）的主流搜索算法是“最佳优先搜索”（Best-First Search）。算法逻辑很直观：从一些入口点开始，不断访问邻居节点，并维护一个候选优先队列（通常基于与查询向量的距离）。每次从队列中取出最“有希望”的节点，读取其向量数据和邻居列表，然后将其邻居加入队列，如此循环。

这个过程的瓶颈在于I/O。每一次访问一个新节点，都可能需要一次随机的磁盘读取。尽管有缓存，但在十亿级规模下，缓存命中率有限，大量的随机小I/O（通常4KB或8KB）会导致搜索路径被I/O等待严重拖慢。SSD虽然延迟低，但大量未对齐、未合并的随机I/O请求仍然会带来可观的尾部延迟。

2.2 PipeANN的核心创新：流水线化搜索（Pipelined Search）

PipeANN提出了一个名为“PipeSearch”的算法，这是其低延迟的基石。它的核心思想是将搜索算法的执行与I/O请求的发起解耦，并进行流水线化处理。

想象一下传统搜索：发起I/O -> 等待I/O完成 -> 处理数据 -> 决定下一个I/O -> 发起I/O...。这是一个同步的、串行的过程，CPU在等待I/O时大量空闲。

PipeSearch则将其改为一个异步流水线：

预取阶段：搜索算法在分析当前节点后，会提前预测接下来可能需要访问的多个节点（而不仅仅是一个），并批量发起对这些节点的I/O请求。
重叠执行：当这些I/O请求在SSD队列中排队并执行时，CPU并不空闲，而是继续处理已经加载到内存中的其他节点数据，执行距离计算和队列维护。
动态宽度调整：算法引入了一个“I/O宽度”的参数。在搜索初期，为了快速探索，可以发起较宽的I/O请求（预取更多节点）；在搜索后期，当接近目标时，则收窄宽度，减少不必要的I/O。这通过一个简单的启发式规则（如当前候选队列的质量）来控制。

这样一来，I/O等待时间就被计算时间和其他I/O的执行时间部分或完全隐藏了。SSD的高并发队列深度被充分利用，使得平均每次搜索的“感知延迟”大幅下降。

注意：这种设计高度依赖于io_uring这样的现代Linux异步I/O接口。io_uring允许用户态程序向内核提交一批I/O请求，并异步地收割完成事件，几乎没有系统调用的开销，是实现这种细粒度、高并发I/O调度的理想基础。这也是PipeANN强烈推荐使用Linux并启用io_uring的原因。

2.3 高效更新机制：OdinANN的直接插入

一个实用的向量库必须支持更新。PipeANN集成了其姊妹篇工作OdinANN的更新算法。与许多需要全局重建或复杂合并的向量索引不同，OdinANN采用了一种“直接插入”的策略。

其关键点在于分离了图的结构和向量的存储：

向量数据：顺序追加写入到日志文件。插入操作就是简单的追加，速度极快。
图结构：每个节点在图中存储的是其邻居的ID（标签）。当新向量插入时，算法会为其在现有的图结构中寻找一个位置，连接少量的边（邻居）。这个连接过程是局部的，只影响图中很小的一部分节点。
删除：采用惰性删除标记。被标记的节点在搜索时会被跳过，并在后台的合并过程中被真正清理。

这种设计使得单次插入/删除操作对整体搜索性能的影响极小（论文中显示仅有1.07倍的波动），实现了“持续稳定的性能”。这对于需要频繁更新向量（如用户实时行为向量）的应用场景至关重要。

2.4 内存效率：量化与紧凑布局

为了将十亿向量塞进约40GB内存（这里指搜索时所需的常驻内存，不包括缓存），PipeANN重度依赖产品量化（PQ）。

原始向量（如100维浮点数需400字节）经过PQ压缩后，通常每个向量仅用32字节甚至更少（如配合RaBitQ量化可降至1-5比特）。这带来了超过10倍的压缩率。
在SSD上，索引文件以高度紧凑的格式存储，包括量化后的向量、图邻接表以及元数据。在加载时，PipeANN通过内存映射（mmap）等方式访问，只有热数据才会被缓存在DRAM中。
这种设计使得PipeANN的内存占用与数据集大小呈亚线性关系，主要内存用于缓存热数据和搜索算法的工作集，而不是整个数据集。

3. 从零开始：PipeANN的部署与实战

理论说得再多，不如亲手跑一遍。下面我将带你从环境准备开始，完成一个中等规模数据集（如SIFT100M）的索引构建、搜索和更新全流程。我会补充很多官方文档中一笔带过，但实际操作中必然会遇到的细节。

3.1 硬件与系统环境准备

PipeANN对硬件有一定要求，主要是为了发挥其性能优势。

硬件建议：

CPU：支持AVX2或AVX512指令集的x86处理器。向量距离计算是核心开销，SIMD指令能带来数倍的加速。核心数越多，构建索引和并行搜索的吞吐量越高。
内存：这是关键。对于纯搜索场景，每十亿向量约需40GB内存。对于支持更新的场景，则需要约90GB。这是用于存储索引元数据、缓存和运行时数据结构的内存，不是磁盘索引文件的大小。
SSD：强烈推荐高性能NVMe SSD，如三星PM9A3、Intel P5800X等。高IOPS和低延迟是PipeANN发挥效能的舞台。对于1B向量，你需要准备约700GB-1TB的SSD空间。

系统与软件：

操作系统：Linux内核版本建议5.10以上，以支持完整的io_uring特性。Ubuntu 22.04 LTS是一个稳妥的选择。

依赖库：按照官方指南安装即可。这里强调几个点：

sudo apt update sudo apt install -y make cmake g++ libaio-dev libgoogle-perftools-dev clang-format # MKL数学库对于距离计算性能提升很大，但安装稍复杂。如果追求简便，可以用OpenBLAS替代。 sudo apt install -y intel-mkl-full # 或者安装 OpenBLAS # sudo apt install -y libopenblas-dev

Python环境（可选）：如果你打算用Python接口，需要pybind11。
```
pip3 install pybind11[global] numpy
```

3.2 获取与编译PipeANN

git clone https://github.com/thustorage/PipeANN.git cd PipeANN # 编译第三方库 liburing cd third_party/liburing ./configure && make -j$(nproc) cd ../.. # 编译PipeANN核心库 bash ./build.sh

编译完成后，所有可执行文件（如build_disk_index,search_disk_index）都在build/tests/目录下。

实操心得：编译过程可能会因为MKL库路径问题报错。如果遇到find_package(MKL)失败，可以尝试指定MKL路径，或者直接修改CMakeLists.txt，将find_package(MKL REQUIRED)注释掉，并手动链接libmkl_rt.so。更简单的方法是使用OpenBLAS，在CMakeLists.txt中寻找并启用USE_OPENBLAS的选项。

3.3 数据准备：格式转换与Ground Truth生成

这是最繁琐但至关重要的一步。PipeANN使用的二进制格式（.bin）有一个简单的头结构：[4字节向量数量(int)][4字节向量维度(int)][向量数据(连续存储)]。

以SIFT100M数据集为例，原始数据通常是bigann_base.bvecs格式。你需要使用项目自带的工具进行转换：

# 进入编译输出目录 cd build/tests # 转换向量数据文件 ./utils/vecs_to_bin uint8 /path/to/bigann_base.bvecs /mnt/nvme/data/bigann/bigann_100M.bin # 转换查询文件 ./utils/vecs_to_bin uint8 /path/to/bigann_query.bvecs /mnt/nvme/data/bigann/query.bin # 转换ground truth文件（通常是.ivecs格式） ./utils/vecs_to_bin int32 /path/to/gnd/idx_100M.ivecs /mnt/nvme/data/bigann/groundtruth_100M.bin

关键细节：

数据类型：uint8对应SIFT数据集（每个维度是0-255的整数）。对于DEEP或SPACEV的浮点数据，则用float。
文件路径：建议严格按照官方建议的目录结构（如/mnt/nvme/data/bigann/）存放，否则后续的评测脚本需要大量修改。
Ground Truth：这是用于评估召回率的“标准答案”。对于SIFT1B的子集SIFT100M，你需要找到对应的100M向量的ground truth文件，而不是整个1B的。如果只有整个1B的truth，你需要用工具截取前100M条。这步容易出错，务必核对向量数量。

3.4 构建磁盘索引：参数选择与实战命令

索引构建是最耗时的步骤，参数设置直接影响最终的性能和精度。

# 基本命令格式 ./build_disk_index <data_type> <data_file> <index_prefix> <R> <L> <PQ_bytes> <M_GB> <threads> <metric> <neighbor_type> # 针对SIFT100M的具体示例 ./build_disk_index uint8 \ /mnt/nvme/data/bigann/bigann_100M.bin \ /mnt/nvme2/indices/bigann/100m \ 96 128 32 256 112 l2 pq

参数深度解析：

<R>：图中每个节点的最大出度（邻居数）。这是影响图连通性和搜索路径长度的最关键参数。值越大，图越稠密，搜索精度越高，但每个节点需要读取的数据量也越大（I/O开销增加）。对于1亿规模，96是一个经验值；对于十亿规模，可能需要128或更大。
<L>：构建索引时，为每个节点选择邻居的候选池大小。值越大，构建出的图质量可能越高，但构建时间越长。通常设置为R的1.5到2倍。
<PQ_bytes>：产品量化的字节数。32是常用值。它决定了向量的压缩率。32字节对应将原始向量切分为m段，每段用k=256个质心之一表示（因为256 * m = 2^(8*m)，需要满足m * log2(k) <= PQ_bytes * 8）。减少字节数会降低精度，增加则会提高精度但增加I/O量。
<M_GB>：构建索引时允许使用的最大内存（GB）。构建过程需要维护图状态和计算距离，内存越大，构建速度越快。对于100M向量，256GB是安全的。
<threads>：构建使用的线程数。可以设置为接近CPU逻辑核心数（如nproc）。
<metric>：距离度量，l2（欧氏距离）或ip（内积）。
<neighbor_type>：邻居列表的存储和计算方式。pq是标准方式，支持更新；rabitq或rabitq3等使用1-bit或3-bit量化，能进一步压缩，但仅支持搜索，不支持更新。

构建过程可能需要数小时（100M）到数天（1B）。你可以观察CPU和I/O利用率来监控进度。

3.5 构建内存入口点索引（可选但推荐）

磁盘索引的搜索需要一个起始点（入口点）。PipeANN支持构建一个小的、常驻内存的图索引（通常是原数据集的1%采样）来快速找到高质量的入口点，这能显著提升搜索速度。

# 1. 从数据集中随机采样1% ./utils/gen_random_slice uint8 \ /mnt/nvme/data/bigann/bigann_100M.bin \ /mnt/nvme2/indices/bigann/100m_SAMPLE_RATE_0.01 \ 0.01 # 2. 基于采样数据构建内存索引 ./build_memory_index uint8 \ /mnt/nvme2/indices/bigann/100m_SAMPLE_RATE_0.01_data.bin \ /mnt/nvme2/indices/bigann/100m_SAMPLE_RATE_0.01_ids.bin \ /mnt/nvme2/indices/bigann/100m_mem.index \ 32 64 1.2 $(nproc) l2

这个内存索引很小（百兆级别），但能为每次搜索提供一个很好的起点，减少在磁盘大图中盲目探索的I/O次数。

3.6 执行搜索测试：验证性能

索引构建好后，终于到了检验成果的时刻。

# 基本搜索命令 ./search_disk_index <data_type> <index_prefix> <threads> <beam_width> <query_file> <gt_file> <topk> <metric> <neighbor_type> <search_mode> <mem_L> <L_list...> # 具体示例：使用PipeSearch模式，测试不同的L参数 ./search_disk_index uint8 \ /mnt/nvme2/indices/bigann/100m \ 1 32 \ /mnt/nvme/data/bigann/query.bin \ /mnt/nvme/data/bigann/groundtruth_100M.bin \ 10 l2 pq \ 2 10 \ 10 20 30 40 50

搜索参数详解：

<threads>：搜索并发线程数。单线程测试延迟，多线程测试吞吐。
<beam_width>：可以理解为搜索的“广度”或“贪婪度”。在PipeSearch中，它与I/O宽度相关。32是一个常用值。
<search_mode>：
- 0: DiskANN原版最佳优先搜索。
- 2:PipeANN的流水线搜索（推荐）。
- 1和3分别是为Starling和CoroSearch优化的模式。
<mem_L>：内存入口点索引的搜索参数L_mem。如果没建内存索引，设为0。
<L_list...>：磁盘索引搜索的参数L_disk列表。程序会依次用这些L值进行搜索并输出结果。L越大，搜索越精细，召回率越高，但延迟也越高。

解读输出结果：命令会输出一个表格，包含不同L值下的QPS（每秒查询数）、平均延迟、P99延迟、平均I/O次数和召回率。

L I/O Width QPS Mean Lat P99 Lat Mean Hops Mean IOs Recall@10 ========================================================================================= 10 32 1952.03 490.99 3346.00 0.00 22.28 67.11 20 32 1717.53 547.84 1093.00 0.00 31.11 84.53

QPS和Mean Lat：关注这对权衡。在召回率满足要求的前提下，选择QPS最高或延迟最低的L。
Mean IOs：平均每次查询的I/O次数。这是PipeANN优化的核心，值越低越好，说明其流水线预取有效减少了不必要的I/O。
P99 Lat：99分位延迟。对于在线服务，这个指标比平均延迟更重要，它反映了长尾请求的情况。PipeANN通过减少随机I/O，通常能显著改善P99延迟。

4. 高级功能与生产级考量

掌握了基础流程后，我们来看看PipeANN的一些高级特性以及在实际生产中需要考虑的问题。

4.1 支持更新：OdinANN工作流

要让索引支持插入和删除，需要在编译时启用更新支持（默认是关闭的）。你需要修改CMakeLists.txt，确保没有定义-DREAD_ONLY_TESTS和-DNO_MAPPING这两个宏，然后重新编译。

更新工作流比纯搜索复杂，主要步骤包括：

准备标签文件：每个向量需要一个唯一的64位整数作为标签（tag）。如果使用默认的身份映射（ID即tag），可以跳过。否则需要用gen_tags工具生成。
准备增量Ground Truth：评估更新过程中的召回率变化需要精心设计。官方提供了gt_update工具，它基于一个更大的全局ground truth，为每次插入批次生成一个子集的ground truth。
运行更新基准测试：
- test_insert_search：模拟边插入边搜索的混合负载。
- overall_performance：模拟滑动窗口场景（插入新向量，删除旧向量）。

一个重要警告：PipeANN的更新不是崩溃一致的。如果在插入或删除过程中程序崩溃，索引可能会损坏。生产环境如果需要持久化更新，必须在每次批量更新后，调用final_merge（或类似机制）来生成一个一致的、干净的索引快照。这个操作是离线的，可能会比较耗时。

4.2 过滤搜索：满足业务约束

在许多实际场景中，我们需要的不仅是“最近邻”，还是“满足某些条件的最近邻”。例如，在电商推荐中，只搜索某个特定品类下的相似商品。PipeANN通过AbstractLabel和AbstractSelector抽象类支持了过滤搜索。

其实现原理是在每个节点的磁盘记录末尾，附加了该节点的标签信息（如品类ID）。在搜索过程中，访问到一个节点时，会调用用户定义的Selector的is_member函数，判断该节点的标签是否满足查询条件。如果不满足，则该节点及其邻居会被跳过。

使用过滤搜索需要：

在构建索引时，通过label_file参数指定标签文件。
在搜索时，通过search_disk_index_filtered工具，并指定selector_type和query_label_file（查询自带的过滤条件）。

这为PipeANN在复杂业务系统中的集成提供了强大的灵活性。

4.3 性能调优指南

拿到PipeANN后，如何针对自己的硬件和数据调出最佳性能？

L(搜索列表大小) 与beam_width(束宽)：这是最核心的调优旋钮。L控制精度和计算/I/O量，beam_width控制搜索的广度。通常的做法是：
- 先固定一个beam_width（如32），扫描不同的L（10, 20, 50, 100...），绘制“召回率-延迟”曲线。
- 找到满足你最低召回率要求的那个L值。
- 然后微调beam_width，观察在固定L下，beam_width对延迟和QPS的影响。有时稍大的beam_width能通过更智能的路径选择减少总I/O，反而降低延迟。
I/O深度与队列深度：PipeSearch的性能与SSD的I/O队列深度紧密相关。确保你的Linux内核io_uring设置支持足够的队列深度。在搜索命令中，beam_width参数间接影响了并发的I/O请求数。在高并发搜索线程下，总的未完成I/O请求数可能很大，需要一块高性能的NVMe SSD来承载。
内存索引采样率：构建内存入口点索引时，采样率（默认1%）可以调整。对于数据分布极其不均匀的集合，适当提高采样率（如2%）可能有助于找到更好的入口点，但会增加内存占用和构建时间。这是一个权衡。
量化字节数PQ_bytes：如果发现召回率达不到要求，可以尝试增加PQ_bytes（如从32到48）。但这会增加每个节点的I/O数据量。更优的做法可能是尝试不同的量化器训练方式（PipeANN默认使用随机采样训练，或许可以尝试使用更复杂的聚类算法预处理）。

5. 常见问题、排查技巧与避坑实录

在实际部署和测试中，我遇到了不少问题，这里总结出来，希望能帮你节省时间。

5.1 编译与依赖问题

问题：编译时找不到libmkl或libaio。
- 解决：对于MKL，可以安装intel-mkl-full包，或者改用OpenBLAS（修改CMake文件）。对于libaio，确保安装了libaio-dev。
问题：io_uring相关编译错误。
- 解决：检查内核版本（uname -r）。如果低于5.1，io_uring可能不完整。升级内核或回退使用libaio后端（性能会下降）。在CMakeLists.txt中可能有切换I/O后端的选项。

5.2 数据准备与格式问题

问题：运行vecs_to_bin或搜索时，报错“无法打开文件”或“读取数据错误”。
- 解决：99%的情况是文件路径不对。使用绝对路径，并确保所有数据文件、索引文件、ground truth文件的路径在命令中完全正确。善用pwd和ls -lh命令确认。
问题：搜索结果的召回率异常低（比如低于10%）。
- 解决：
  1. 首先检查ground truth文件是否匹配。这是最常见的原因。确保ground truth文件对应的数据集和你的查询文件、索引文件是同一份数据。
  2. 检查构建索引时使用的metric（l2/ip）和搜索时使用的metric是否一致。
  3. 检查数据文件的data_type（uint8/float）是否在所有步骤中一致。
  4. 尝试增大搜索参数L，如果召回率随之上升，则可能是参数L或beam_width设置过小。

5.3 性能不及预期

问题：QPS远低于论文报告的数据。
- 排查：
  1. 检查SSD性能：使用fio工具测试你的NVMe SSD的4K随机读IOPS和延迟。如果SSD本身性能差（如SATA SSD），或者已经被其他应用占满I/O，PipeANN无法发挥优势。
  2. 检查CPU频率和节能模式：在Linux下，使用cpupower frequency-info查看CPU是否运行在最高性能模式。在BIOS和系统设置中禁用节能选项（如Intel P-States, C-States），并将CPU调控器设置为performance。
  3. 检查内存带宽：如果量化字节数很小，计算可能不再是瓶颈，但内存带宽可能成为限制。使用numactl命令将进程绑定到特定的NUMA节点，确保内存访问是本地化的。
  4. 检查索引构建质量：尝试用更大的R和L参数重新构建索引。一个质量更高的图虽然构建慢，但搜索路径更短。
问题：搜索延迟的P99非常高（有长尾）。
- 解决：这是磁盘ANN的典型挑战。PipeANN已经通过流水线大大改善了这一点。如果仍不理想，可以尝试：
  - 增加beam_width，让搜索更“宽”，减少陷入局部最优而进行大量无效I/O的概率。
  - 确保使用高性能NVMe SSD，并独占使用（不要与其他高I/O应用共享）。
  - 在操作系统层面，尝试调整I/O调度器（如设置为none或mq-deadline）以及io_uring的轮询参数。

5.4 更新功能相关

问题：启用更新支持后编译失败。
- 解决：确保完全删除了之前的编译目录（build/），并从干净的源码重新执行bash ./build.sh。因为更新功能需要不同的预编译宏定义。
问题：插入向量后，搜索性能下降明显。
- 解决：这是正常的，因为新插入的向量可能破坏了原图的局部结构。OdinANN的设计目标是让性能波动控制在很小范围（~7%）。如果下降超过20%，可能需要检查：
  - 插入的批次大小是否过大？建议小批量持续插入，而不是单次海量插入。
  - 考虑定期（例如每天低峰期）执行一次轻量的索引优化或重建。

PipeANN是一个工程上非常精良的系统，它将学术创新与工程实践结合得相当好。虽然上手有一定复杂度，但一旦跑通，其在大规模向量检索上展现出的性能优势是传统方案难以比拟的。对于有超大规模向量检索需求的团队，投入时间研究和部署PipeANN，很可能带来显著的性价比提升。

查看全文

http://www.jsqmd.com/news/814638/