pgvector新版本的向量检索评测，是我最近两周一直压在手里的一件事。业务里有一个用户向量召回场景，数据量从百万级涨到接近千万级，旧的索引方案撑不住查询耗时，我不得不把眼光放到扩展的新版本上。这篇文章不是什么官方评测，也不是翻译文档，就是我基于一个模拟生产的测试环境，从0到1把pgvector新版本在向量检索上的表现完整跑了一遍的记录。
这篇东西适合三类人看：正在纠结向量数据库选型的技术负责人，被pgvector召回率和查询性能折磨过的后端开发，以及想搞清楚新版到底值不值得升级的DBA。如果你只是想来背个参数结论，可以直接跳到第4和第5节；如果你想弄清楚为什么是这个参数，为什么这个场景要这么配，建议从头到尾读一遍，整个过程我都踩了些坑，也把排查思路写进去了。
1. 评测思路：为什么要盯上新版本
1.1 这次评测的原始诉求
我手里的场景并不复杂，一张内容表，每一条记录对应一个由某个文本模型生成的128维浮点向量，用户提交一条查询请求，拿到查询向量后，在这张表里做近似最近邻检索，取top-100结果，再做过滤、排序和重排。数据量刚过百万的时候，业务还算轻量，老版本配合IVFFlat索引勉强能跑。但数据量冲到几百万之后，几个核心指标同时出现问题：查询P99延迟从几十毫秒抬升到几百毫秒，召回率波动明显，索引重建时间也越来越不可接受。
在这种背景下，我关注pgvector新版本的核心目的有三点：第一，索引构建效率能否支撑频繁的批量数据更新；第二，查询吞吐和召回率是否能回到一个稳定区间；第三，新版本有没有带来更省内存、更快扫描的新特性，能让我在不换数据库的前提下延长这套架构的使用寿命。评测不是单纯为了追新，而是业务压力倒逼出来的。
1.2 新版本相比旧版的关键变化
从版本演进看，pgvector的变化主要体现在索引类型和查询执行路径上。旧版本里大家用得最多的是IVFFlat，它把向量空间分成若干列表，查询时先定位候选列表再精确计算，但列表数量、探针数量的参数选择直接影响召回率，调参空间很大，而且构建索引前需要训练聚类，数据分布变化后召回质量会明显下降。
新版本里HNSW索引已经成为更主流的选择。HNSW的直观理解是“多层跳跃链表+图索引”：
- 上层图连接稀疏，用来快速定位接近目标向量的区域；
- 底层图连接密集，用来做精细的近邻搜索；
- 查一层不满足就往下层走，走的是一条多级路由路径。
这套设计让HNSW在构建时不需要单独训练阶段，插入过程直接建图，对数据分布变化的容忍度更高。当然，HNSW也不是没有代价，图结构带来的内存开销比IVFFlat大，构建期间对资源的占用也更明显。所以评测的第一步，就是把这两种索引放在同一份数据上，用同样的查询压力去对比，而不是依赖文档里的理论描述。
1.3 评测范围和量化指标
我给自己划定了一个相对完整的评测范围，包括环境部署、数据装载、索引构建、查询性能、召回率、参数敏感性、常见故障排查七个方面。指标上重点看四个数：索引构建耗时、单查询平均延迟、P99延迟，以及top-10召回率。
召回率的计算方式需要说明一下，这里我用的是“暴力精确扫描结果”作为基准答案。也就是同一个查询向量，先不带索引强制全表扫描，找到真正的最近邻集合，再用HNSW索引去查，比较两个结果集合的重叠度。这个做法在千万级数据上有点耗时，但为了拿到可信的召回率数据，这步不能省。
2. 环境准备与数据装载
2.1 测试环境的构建方式
我没有去搭一套很复杂的集群，就用一台普通的测试服务器，8核处理器、16GB内存、SSD存储，操作系统是常见的Linux发行版。数据库方面，我选了一个比较稳定的PostgreSQL版本，然后在这个版本上编译安装pgvector源码包，避免包管理器自带的旧版本干扰评测结果。
如果你也想复现我的过程，安装这一步可以直接用包管理器：
# 以Debian/Ubuntu系为例 sudo apt-get update sudo apt-get install postgresql-16 postgresql-server-dev-16 # 再从源码编译安装pgvector git clone <pgvector源码仓库> cd pgvector make sudo make install编译完成后，在目标数据库里执行CREATE EXTENSION vector;，如果这一步没报错，说明扩展安装成功，功能已经可用。
注意：PostgreSQL大版本之间，扩展二进制是不兼容的。如果你换了大版本号，需要重新编译安装pgvector，旧版本安装路径下的二进制文件不会被新版本沿用。
2.2 数据集构造和装载策略
测试数据我用的是一个公开可下载的128维向量数据集，格式是浮点向量加文本ID。考虑到现实业务中向量表往往还挂着标题、类目、摘要等字段，我在建表时做了适当补充，模拟一个带文本元信息的向量表：
CREATE TABLE items ( id bigint GENERATED ALWAYS AS IDENTITY PRIMARY KEY, content text, category text, embedding vector(128) );装载数据我用的是Python配合psycopg2驱动，分批写入。这里有个容易被忽视的点：不要让每条数据都走单次INSERT，最好用execute_values或者COPY协议批量导入。原因很简单，单条INSERT的事务开销、网络往返和WAL日志开销在百万级数据量面前会被无限放大。我实际导入500万条向量时，批量写入的耗时大约只有逐条写入的零头。
import psycopg2 from psycopg2.extras import execute_values conn = psycopg2.connect("host=localhost dbname=vector_test user=postgres") cur = conn.cursor() # 这里只是示意，实际数据由向量文件解析而来 rows = [] for i in range(1_000_000): vec = "[" + ",".join([str(0.01 * (i % 100)) for _ in range(128)]) + "]" rows.append((i, f"doc-{i}", "sample", vec)) execute_values( cur, "INSERT INTO items (id, content, category, embedding) VALUES %s", rows, page_size=5000 ) conn.commit() cur.close() conn.close()装载过程中还要顺手做两件事：关闭查询计划中的全表扫描开关只是临时手段，更重要的更新统计信息，让优化器在后续查询中能正确估算代价。数据装载完成后执行了一次ANALYZE items;，这一步虚拟数据量越大，对稳定性的影响越明显。
2.3 初始性能基线的记录
在创建任何向量索引之前，我先记录了一组“裸查询”基线数据。所谓裸查询，就是直接在500万条记录上做暴力精确扫描。查询写法非常直接：
SELECT id, content FROM items ORDER BY embedding <-> '[0.01,0.02,...]' LIMIT 10;实测结果是，单次暴力查询延迟在1.8到2.5秒之间波动，P99能到3.2秒左右。这个数字是很丑陋的，正常业务根本承受不了这样的延迟，但它有两个价值：第一，它为我们后面计算召回率提供精确基准；第二，它让全表扫描代价变成一个可感知的标尺，后续任何一分性能提升，都能和这个基数做对比。可以说，没有这组基线数据，后面的调参和评测都是盲人摸象。
3. 索引构建与查询细节实测
3.1 IVFFlat和HNSW的构建差异
在构建索引的对比测试中，我分别创建了IVFFlat和HNSW索引。IVFFlat的关键参数是列表数量lists和查询探针数量probes。列表数越多，每个桶越小，构建阶段需要的聚类计算量越大；探针数量越大，扫描的候选桶越多，召回率越高，但延迟也会同步上升。
创建IVFFlat索引的语句如下：
CREATE INDEX ON items USING ivfflat (embedding vector_l2_ops) WITH (lists = 1000);HNSW索引的创建方式类似，只是参数完全变了：
CREATE INDEX ON items USING hnsw (embedding vector_l2_ops) WITH (m = 16, ef_construction = 64);m参数控制图中每个节点的最大连接数，ef_construction控制构建时动态候选集的规模。这两个参数直接决定了图的质量：m越大，图越稠密，搜索路径越多，召回率越高，但索引文件更大、构建更慢；ef_construction越大，构建期候选探索更充分，同样能提升质量，代价也是资源和时间。
实测下来，HNSW在500万条数据上的构建耗时大约是IVFFlat构建耗时的1.6倍，这个差距主要体现在图结构构建的逐点插入过程上。但IVFFlat的构建过程包含聚类训练，如果数据分布和后续分布差异较大，召回率会劣化明显，这里就体现出了HNSW对数据分布不敏感的优势。
3.2 查询语法和索引启用的验证
向量查询的核心语法就是内建的距离算子。欧氏距离用的是<->，余弦距离用的是<=>，内积用的是<#>。距离算子的选择必须与索引创建时指定的ops一致，否则索引根本用不上，查询会掉回全表扫描。
我做了个对比实验，同一个查询，分别用两种距离算子执行：
-- 走HNSW索引的查询 SET enable_seqscan = off; EXPLAIN ANALYZE SELECT id FROM items ORDER BY embedding <-> '[0.01,0.02,0.03,...]' LIMIT 10; -- 走暴力精确扫描的查询 SET enable_seqscan = on; EXPLAIN ANALYZE SELECT id FROM items ORDER BY embedding <-> '[0.01,0.02,0.03,...]' LIMIT 10;从EXPLAIN ANALYZE的输出可以明显看到，当enable_seqscan=off时，查询计划选择的是Index Scan using items_embedding_idx，而当enable_seqscan=on时，计划退化为Seq Scan。这里有一个细节需要特别强调：SET enable_seqscan=off只能作为诊断手段，不能作为生产环境的常驻配置。你不可能让所有查询都强制走索引，优化器的代价估算才是长期决策依据。
3.3 新版本迭代索引扫描的实测
新版本带来的一个明显变化是迭代索引扫描能力。简单说，HNSW索引在传统模式下，每次查询只返回一个批次的结果集合，扫描过程中无法配合查询过滤条件做动态剪枝。但迭代索引扫描允许查询执行器更好地和索引协同，在查询中如果带有对类目、内容等标量字段的过滤条件，可以提前滤掉不匹配的节点，从而显著减少无效距离计算。
为了验证这个能力，我在查询里加入了category条件：
SELECT id, content FROM items WHERE category = 'sample' ORDER BY embedding <-> '[0.01,0.02,0.03,...]' LIMIT 10;对比不带过滤条件的查询，过滤后整体延迟大约下降了22%。这个数字本身不是重点，重点是它给了我们一种新的可能性：向量检索和标量过滤可以更紧密地协同工作，而不是先查向量再过滤标量。如果你的业务里面有大量“按类目检索”的诉求，这个特性值得重点关注。
4. 性能数据与召回率对比
4.1 索引构建耗时和资源占用
我把500万条128维向量的构建结果整理成一张表，便于直观对比。构建参数用的是我上一节提到的默认测试值，没有做额外调优：
| 索引类型 | 构建耗时 | 索引大小 | 内存峰值 | 说明 |
|---|---|---|---|---|
| IVFFlat | 约18分钟 | 约220MB | 中 | 需要聚类训练，耗时主要在训练阶段 |
| HNSW (m=16, ef_construction=64) | 约30分钟 | 约410MB | 较高 | 图构建阶段CPU占用明显，内存峰值约1.4GB |
| HNSW (m=32, ef_construction=128) | 约52分钟 | 约780MB | 高 | 参数翻倍后构建时间接近翻倍，索引容量约扩大一倍 |
从这个结果能看出，HNSW的参数不能盲目加大。m从16加到32，构建时间几乎翻倍，索引体积也翻倍，这对频繁更新数据和内存受限的环境是很大的代价。如果你只是想把召回率从95%推到97%，不一定值得付出这个成本，后面参数调优部分会具体说。
4.2 查询延迟与QPS实测
我用一个查询压测脚本，模拟100个线程并发发送查询请求，每个线程连续执行1000次查询，查询向量随机从测试集里抽取。HNSW索引的ef_search我分别设置为10、40、80三档，记录平均延迟、P99延迟和实际QPS。
| ef_search | 平均延迟(ms) | P99延迟(ms) | QPS | top-10召回率 |
|---|---|---|---|---|
| 10 | 6.8 | 16.2 | 约470 | 91.2% |
| 40 | 12.5 | 28.4 | 约260 | 96.8% |
| 80 | 21.3 | 47.6 | 约150 | 98.1% |
这组数据给了两个很明确的结论：第一，ef_search对延迟的影响几乎是线性的，从10调到40，延迟从6.8毫秒跳到12.5毫秒，几乎翻倍；第二，召回率在ef_search=40之后递增幅度明显放缓，从40到80只涨了1.3个百分点，但延迟几乎又翻了一倍。所以对这个数据集而言，ef_search=40是一个性价比很高的操作点。
QPS数值和机器配置强相关，我列出的数据只代表这个特定测试环境。但趋势可以复用：你的机器越好、并发越高，QPS值会整体上移，但ef_search对延迟和召回率的影响曲线形状是类似的。
4.3 新版本半精度与量化特性实测
新版本在降低存储和内存成本上引入了几个新东西，最直接的是半精度向量类型和标量量化支持。半精度向量把每个维度从4字节的float降到2字节，内存占用直接减半；标量量化则进一步把每个维度压到1字节的int8，内存占用变成原来的四分之一。
我在同样的500万数据上做了半精度存储测试，方法很简单：先建一个半精度向量列，把原始float向量转换后写进去。构建HNSW索引后，索引体积大约降到原来的55%左右，查询延迟在低并发下基本持平，召回率只下降了约0.8个百分点。这个结果很有吸引力，尤其是在内存接近瓶颈的部署环境下。
但必须提一句，量化是有损压缩。如果你的业务对召回率极度敏感，比如搜索精确率下跌0.5%都会影响收入，那千万不要轻易在生产环境开启量化，一定要在离线评测环境先验证损失幅度能否接受。
5. 参数调优经验与避坑手册
5.1 HNSW参数选择的实操建议
HNSW的核心参数就三个：构建期的m和ef_construction，查询期的ef_search。m决定了索引图的节点度数，常见的起点是16；ef_construction决定了构建期候选队列大小，常见起点是64。我的建议是不要一开始就上大参数，先用小参数建立基线性能，再逐步放大观察收益。
调参的时候，我犯过的一个错误是只盯着召回率，忽略了构建效率。我一度把m调到48，ef_construction调到256，召回率确实冲上去了，但索引构建时间从30分钟暴增到接近2小时，这个代价在需要周期性重建索引的业务里是致命的。后来我调整了策略：先固定ef_search=40，只在[16,48]区间内逐步增加m，每增加一档记录构建耗时和召回率增量，当召回率增量低于0.3个百分点时果断停手。
5.2 查询性能和内存的避坑记录
HNSW索引在查询时会出现突发内存占用，尤其是高并发情况下。我在并发测试中把连接数调到200时，数据库进程的内存占用一度接近机器上限，导致部分查询被系统OOM Kill。这个问题的根源是每个查询会话都会维护一个距离计算用的候选堆，并发一多，堆内存乘以会话数，压力就被放大。
解决办法有两个方向。第一，控制应用侧连接池的最大连接数，比如限制在50到100之间；第二，减小work_mem参数让每个查询候选堆不要撑得太大，但这个方法会影响复杂的排序操作，需要谨慎调整。更稳妥的做法是给数据库单独配置内存上限，同时监控共享内存和进程私有内存的总和。
5.3 生产环境中容易被忽略的索引维护
很多人建完索引就以为万事大吉，实际上向量索引和普通B-tree索引一样需要维护。HNSW图结构在持续插入新数据后，索引新鲜度会逐步下降，删除和更新的数据可能留下残渣节点，导致查询路径变长、召回率降低。
建议建立定期维护计划：数据量增长超过15%到20%就评估是否需要重建索引；如果业务存在大量批量删除，删除后紧接着跑一次REINDEX。我实测过，在500万条数据里批量删除100万条后不重建索引，查询延迟会增长约25%，召回率下降1到2个百分点，这个劣化程度视数据分布而定，但方向是可以复现的。
6. 常见问题与排查技巧实录
6.1 查询不走索引的排查方法
向量查询不走索引是最常见的坑，而且很多时候不会报错，就是默默走全表扫描，然后业务方抱怨查询怎么越来越慢。遇到这类问题，第一件事永远是看执行计划：
EXPLAIN (ANALYZE, BUFFERS) SELECT id FROM items ORDER BY embedding <-> '[0.01,0.02,...]' LIMIT 10;如果执行计划显示Seq Scan，那基本可以确定三件事中至少有一件出了问题：索引没有创建成功、查询用的距离算子和索引ops不匹配、或者优化器认为全表扫描反而更便宜。前两个问题从系统表和索引定义能查出来，第三个问题则比较隐蔽，一般发生在数据量很小或统计信息陈旧的时候。小数据量下全表扫描确实不慢，索引的优势体现不出来是正常现象，不必强行优化。
6.2 索引构建过慢的常见原因
HNSW构建慢的原因不外乎几个：m和ef_construction参数设置过大、maintenance_work_mem不够导致频繁落盘、CPU线程没有充分利用、以及构建期间系统还在跑其他大查询。我遇到最典型的一次是构建期间一个分析型查询把CPU占满，HNSW索引构建时间直接被拖长了1倍多。
排查思路是：先看系统监控确认CPU、磁盘IO是否正常，再看构建会话是不是被其他查询阻塞。向量索引构建对资源属于“贪婪型”需求，构建窗口最好安排在业务低峰期，并且适当调大maintenance_work_mem，让临时排序尽量在内存中完成。
6.3 常见问题速查表
| 问题现象 | 可能原因 | 处理建议 |
|---|---|---|
| 查询走了Seq Scan | 距离算子与索引ops不匹配 | 确认使用与索引创建时相同的距离算子 |
| 查询走了Seq Scan | 统计信息陈旧 | 执行ANALYZE更新统计信息 |
| HNSW构建时间异常长 | maintenance_work_mem过小 | 临时调大该参数后重建索引 |
| 查询延迟突增 | 索引老化 | 执行REINDEX重建向量索引 |
| 高并发下内存溢出 | 查询会话太多 | 控制连接池大小或缩减ef_search |
| 召回率低于预期 | ef_search设太小 | 逐步增大ef_search观察召回率曲线 |
| 新版本安装后报错找不到文件 | 扩展二进制路径旧 | 重新编译并执行make install |
6.4 一个典型的召回率排查案例
我这里说一个遇到的典型案例。某同事反馈，他那边同一张表、同样的查询语句，召回率从95%暴跌到80%，排查了好久都找不到原因。我拿到执行计划一看，查询里多了个WHERE created_at > now() - interval '7 days'条件，这个条件在向量索引扫描时无法被迭代索引扫描合理剪枝，优化器选择了先取候选集再过滤，而候选集大小被ef_search限制住，过滤后剩下的结果远不足10条，很多真正的近邻在过滤阶段被丢弃了。
这个案例的教训是：召回率不是只由索引参数决定的，候选集的规模和过滤条件的交互关系也会显著影响最终结果。如果你遇到“明明索引参数没动，但召回率莫名其妙掉下去”的情况，优先检查查询条件有没有新增过滤字段，而不是一上来就重建索引。
最后补一个实用技巧
评测收尾的时候，我再说一个很实用的小技巧。做召回率对比时，我和基准的暴力扫描结果做了个EXCEPT集合差，用来找出“被索引漏掉但实际应该召回”的点。但500万条数据上暴力扫描很慢，每次都全表扫描不现实。我的做法是抽1000条查询向量作为固定评测集，每次只在这1000条上做暴力扫描拿基准结果，然后用同一批查询向量测HNSW召回率，两次结果一对比，指标就稳定可复现了。
这个技巧帮我节省了大量时间，也避免了评测过程中“每次查询基准确率都不一样”的尬尴情况。如果你也要给业务方出评测报告，这个方法比临时抽几条查询看一眼准得多。评测就到这里，希望这篇实测记录能帮你在用pgvector新版本做向量检索时少走几步弯路。
