1. 向量检索卡在哪先把瓶颈说清楚1.1 从一次线上事故说起我之前接手过一个推荐服务的重构核心逻辑很简单把内容用 Embedding 模型转成向量存进数据库用户请求来时算相似度取 Top-K 返回。最初上线时数据量只有二十万条一次查询大概 30ms大家都觉得挺快。结果半年后数据涨到 120 万条接口耗时直接冲到 700ms 以上高峰时段甚至出现连接池被占满的情况。当时第一反应是换专用向量数据库但团队里没人愿意为了一个推荐场景多维护一套中间件。后来我们盯上了 PostgreSQL 的 pgvector 扩展它直接把向量类型做成数据库的一等公民不需要额外部署服务日常备份、权限、监控全走 PostgreSQL 原有体系。这篇文章就是把那次优化的完整过程复盘一遍从安装、建表、索引选型到源码层面的理解覆盖你在生产环境真正会遇到的效率问题。1.2 pgvector 的核心模型pgvector 做的事情其实很朴素在 PostgreSQL 里新增了一种vector类型支持固定维度的浮点数组然后提供了几个距离算子算子含义说明-欧氏距离L2最常用取最小值表示最相似#负内积实际返回负内积ORDER BY 升序时等价于按内积降序余弦距离返回1 - cosine_similarity对向量模长不敏感L1 距离0.7.0 之后加入曼哈顿距离场景可用查询语法非常直白SELECT id, embedding [0.12, 0.34, ...] AS distance FROM items ORDER BY embedding [0.12, 0.34, ...] LIMIT 10;本质上就是ORDER BY ... LIMIT这让它和传统 SQL 的兼容性极好任何会写 SQL 的人都能在五分钟内上手。但也正是这种“朴素”隐藏了性能问题没有索引时这条 SQL 就是一次全表扫描把每一行的向量都算一遍距离再排序。数据量小没问题数据量大了就是灾难。1.3 效率瓶颈的三个层次根据个人排障经验向量检索慢通常不是单一原因我习惯把瓶颈拆成三层看存储层向量列本身怎么存。默认float4数组768 维的向量一行就要占 3KB 左右再加上 PostgreSQL 行头和 TOAST 的开销表体膨胀得很快。索引层有没有合适的近似最近邻ANN索引。没有索引就是全表扫描有索引但参数不合理召回率和延迟也不可控。查询层查询写法是否触发索引、过滤条件是否把索引的优势抵消掉、shared_buffers和工作内存是否够用。后面所有的优化动作都围绕这三层展开。先把这条主线记住后面遇到任何EXPLAIN ANALYZE的结果你都能大致定位问题出在哪一层。2. 环境准备Windows 安装与源码编译的完整链路2.1 版本对应关系要提前确认pgvector 是 PostgreSQL 的扩展版本兼容性主要看两件事PostgreSQL 大版本要支持pgvector 版本自身的特性差异。以我们用的 PostgreSQL 14 为例pgvector 0.5.0 及以上都能正常跑0.7.0 之后的版本对 HNSW 构建速度和扫描迭代器做了大幅优化所以强烈建议直接装最新稳定版。判断方法很简单装完执行SELECT extversion FROM pg_extension WHERE extname vector;看到 0.7 以上就说明你的索引体验和半年前完全是两个时代。2.2 Windows 环境安装实测“Windows 如何安装 pgvector”是搜索量很高的词这里把实测过程完整写出来。pgvector 官方其实发布了 Windows 安装包不用自己折腾 Visual Studio 编译。第一步到 pgvector 的 GitHub Releases 页面下载vector-版本.windows-x64.exe注意看清楚你的 PostgreSQL 是 64 位还是 32 位现在基本全是 64 位。第二步关闭 pgAdmin 和所有正在连接目标实例的工具然后右键以管理员身份运行安装包。第三步安装器会让你选择 PostgreSQL 的安装目录一般会自动识别例如C:\Program Files\PostgreSQL\14确认后一路下一步。第四步安装完成后打开psql或者 pgAdmin 的查询工具执行CREATE EXTENSION vector; SELECT vector_dims([]::vector);能返回0且不报错就说明安装成功。如果CREATE EXTENSION报“无法找到文件”通常是安装器选错了 PostgreSQL 版本目录卸载重装时手动指定正确路径即可。如果官方 Windows 安装包不匹配你的 PostgreSQL 小版本还有一个备用方案用 conda 建一个带 pgvector 的 PostgreSQL 环境。不过这适合开发测试生产 Windows 环境我建议直接用官方安装包最省心。2.3 Linux 源码编译安装Linux 上我倾向于源码编译因为能拿到最新的优化也能随时看源码。前提是已经安装 PostgreSQL 的开发包Debian/Ubuntu 下执行sudo apt install postgresql-server-dev-14 build-essential git git clone --branch v0.8.0 https://github.com/pgvector/pgvector.git cd pgvector make sudo make install编译安装完成后同样在 psql 里执行CREATE EXTENSION vector;。这里特别提醒如果 PostgreSQL 是通过 EDB 安装器或编译安装到非默认路径pg_config可能不在 PATH 里编译前先which pg_config确认路径必要时手动指定PG_CONFIGmake PG_CONFIG/usr/lib/postgresql/14/bin/pg_config源码编译的好处是你可以随时进src/hnsw.c、src/ivfflat.c看实现后面章节我会讲从源码里能挖出哪些关键信息。3. 先建基线表结构、写入与距离算子3.1 建表与批量写入的细节不要一上来就建索引先建一张干净的表把数据灌进去测出全表扫描的基线后面所有优化才有对比依据。CREATE TABLE items ( id bigserial PRIMARY KEY, title text, embedding vector(768) );写入数据时有一个很容易被忽略的点不要一条一条 INSERT要批量写入。pgvector 对单条写入的开销并不比普通类型低多少但批量插入可以用到 PostgreSQL 的批量写入优化同时减少 WAL 刷盘次数。用 Python 脚本灌数据的话建议用copy_expert配合 CSV或者直接用INSERT ... SELECT unnest(...)的方式INSERT INTO items (title, embedding) SELECT g, ([ || array_to_string(ARRAY(SELECT 0.01 * random() FROM generate_series(1, 768)), ,) || ])::vector FROM generate_series(1, 10000) AS g;这个写法适合生成测试数据生产场景建议直接用COPY导入预先算好的向量文件。另外768 维的向量每个有 3KB 左右如果不需要精确浮点可以评估halfvec类型存储直接减半速度也会有提升。3.2 三种距离算子怎么选选距离算子要看 Embedding 模型的训练方式而不是拍脑袋余弦距离绝大多数文本 Embedding 模型包括 OpenAI 的 text-embedding-ada-002、bge 系列都推荐余弦相似度。pgvector 的内部会做归一化所以向量模长不影响排序结果。欧氏距离-如果用向量直接表示坐标点之类的空间位置L2 距离更直观。注意对已归一化的向量余弦距离和欧氏距离的排序结果在数学上是等价的但距离数值不同。内积#适合模型明确按内积相似度训练的场景。#返回负内积所以ORDER BY embedding # query会优先返回内积最大的结果。这里有个实战细节如果用了余弦距离索引创建时也要保持一致vector_cosine_ops对应vector_l2_ops对应-vector_ip_ops对应#。算子族配错了索引不会被查询用到这是非常隐蔽的“为什么建了索引还是全表扫描”的原因之一。3.3 全表扫描的基线数据我拿 100 万条 768 维随机向量做了测试本机是 8 核 16GB 内存的普通服务器PostgreSQL 14 pgvector 0.8.0。不建索引时执行EXPLAIN (ANALYZE, BUFFERS) SELECT id FROM items ORDER BY embedding [0.01, 0.02, ...] LIMIT 10;结果稳稳地落在 600ms 到 800msshared_buffers配大一点也就压到 500ms 左右。这个数据就是典型的“没有索引的向量检索”一旦并发上来数据库 CPU 直接被打满。别急着怪硬件先给这条查询建索引。4. 索引选型IVFFlat 与 HNSW 的取舍逻辑4.1 IVFFlat 的原理与 lists 选择pgvector 提供两种 ANN 索引IVFFlat 和 HNSW。IVFFlat 的思路是“先聚类再精搜”。它会对全表向量做 k-means 聚类把向量空间划分成lists个桶每个向量只存进最近的桶。查询时先算查询向量到每个聚类中心的距离挑出距离最近的probes个桶再在这些桶里做线性扫描。IVFFlat 有两个关键参数lists建索引时指定表示聚类的数量。probes查询时通过 GUC 参数ivfflat.probes控制表示要搜索多少个桶。lists选多少有经验公式一般取sqrt(总行数)。100 万行就是 1000再往上收益递减行数少于 1 万时lists取个 100 以内就行。probes的经验起点是lists / 10也就是 1000 个桶时先试 100看召回率够不够再调。IVFFlat 有一个巨坑建索引时表里必须有数据因为 k-means 是从已有数据里学习聚类中心的。空表建索引不会报错但后面插入的新数据分布如果和初始聚类差异很大召回率会很难看。4.2 HNSW 的原理与参数速览HNSWHierarchical Navigable Small World的思路完全不同它把向量组织成一张多层图上层是稀疏的“高速公路”下层是密集的“街区路网”。查询时从顶层入口开始沿着距离最近的邻居往下跳最终收敛到底层的最优区域。pgvector 里创建 HNSW 索引CREATE INDEX ON items USING hnsw (embedding vector_cosine_ops) WITH (m 16, ef_construction 64);两个构建期参数m每个节点的最大连接数默认 16。越大图越稠密召回越高但索引体积和构建时间也越大。ef_construction构建时搜索的候选队列大小默认 64。越大构建越慢但图质量更好。查询期还有一个参数hnsw.ef_search默认是 40。它控制查询时保留的候选队列大小值越大召回越高但延迟也越高。注意它和 IVFFlat 的probes一样都是运行时设置改完立刻生效不用重建索引。4.3 两者对比与适用场景直接给结论这张表是我实践后整理的维度IVFFlatHNSW构建速度较快较慢但 0.7 版本提升明显查询速度较快但召回依赖 probes更快尤其高维数据召回精度需要调 probes 换默认参数下召回优秀索引体积更小更大约为向量的额外 50%-80%对空表建索引不允许必须有数据可以适合场景数据量大、可接受离线重建在线服务、对延迟敏感我的建议新项目无脑 HNSW除非你的数据量到千万级以上且磁盘吃紧或者更新频繁需要定期重建 IVFFlat。HNSW 不需要像 IVFFlat 那样担心新数据分布偏移的问题运维负担小很多。5. HNSW 调参落地四个旋钮逐个试5.1 m 与 ef_construction构建期的空间换时间很多人建索引直接用默认参数其实m和ef_construction是召回率和资源消耗的源头。我习惯的做法是固定ef_construction 100起步然后分别测试m 16、m 32、m 48。为什么先动ef_construction因为构建期的候选队列越大图中每个节点的邻居越接近真实最近邻查询时“迷路”的概率越低。但如果ef_construction已经很大比如 200继续加对召回的影响就不明显了这时候该动m。m影响的是图的稠密度m 32的索引体积基本比m 16大一倍但查询吞吐的提升不是线性的到了一定阈值后收益骤减。构建时记得调大maintenance_work_memSET maintenance_work_mem 2GB;HNSW 构建过程非常吃内存默认 64MB 的 maintenance_work_mem 会让构建过程频繁落盘速度慢得离谱。我用 100 万条向量测试加大到 2GB 之后构建时间从 40 分钟缩到 9 分钟。5.2 ef_search查询期的召回率旋钮ef_search是线上你唯一需要频繁调整的参数。它和LIMIT的关系很微妙如果业务只需要 Top-10ef_search 40通常就够如果业务要 Top-100ef_search至少得 100 以上否则尾部结果的质量会明显下降。设置方式有两种-- 会话级 SET hnsw.ef_search 100; -- 事务级适合每个请求按业务调整 BEGIN; SET LOCAL hnsw.ef_search 200; SELECT ... COMMIT;我在生产环境用的是服务启动后按路由维度设置普通搜索ef_search 32高精度搜索ef_search 128这样同一个索引服务两种召回率需求。5.3 用 EXPLAIN ANALYZE 验证优化效果优化不能靠感觉每次调参后用EXPLAIN ANALYZE验证索引是否真的生效EXPLAIN (ANALYZE, BUFFERS) SELECT id FROM items ORDER BY embedding [0.01, 0.02, ...] LIMIT 10;关键看两处扫描方式必须是Index Scan using items_embedding_idx如果看到Seq Scan说明索引没被用上。Execution Time是否从几百毫秒降到了几十毫秒。另外推荐一个验证召回率的方法先用全表扫描得到一个精确的 Top-100 列表再用 HNSW 查同一个查询向量得到近似 Top-100对比两个集合的重合比例。召回率低于 90% 时调大ef_search或重建索引。6. 源码层面的几个关键真相6.1 为什么 pgvector 能直接给出结果而不需要别的中间件很多不了解的人以为 pgvector 只是“套了一层 SQL 的向量数据库客户端”其实它的核心是 PostgreSQL 的自定义索引访问方法。简单说PostgreSQL 允许第三方扩展实现一套新的索引 AM注册到pg_am系统表里查询优化器就能像对待 B-tree 一样对待 HNSW 索引。在源码里你能看到src/vector.c注册了类型src/hnsw.c实现 HNSW 的插入、扫描、构建逻辑src/ivfflat.c实现 IVFFlat 的倒排逻辑。正因为是本地实现的索引 AMpgvector 才能把“排序 LIMIT”优化成索引扫描而不是把全表数据拉出来再排序。这对你意味着什么意味着它的性能天花板取决于索引 AM 的质量而不是 SQL 层。所以当你发现查询慢先看是不是真的走到了索引扫描再看索引参数别急着怪扩展没用。6.2 HNSW 图的存储与内存成本从源码和实验数据来看HNSW 索引体积偏大的原因在于每个向量在图里通常有多个“邻居指针”底层每个节点要存m个连接上层节点数递减但也要连接。一个 768 维、100 万行的表HNSW 索引常常要额外吃 1.2GB 到 1.8GB 空间。这个体积在线上是有代价的PostgreSQL 的索引页会缓存在shared_buffers里索引越大冷查询触发磁盘读的概率越高。如果你发现查询延迟时高时低先看索引是否已经超出shared_buffers的合理覆盖范围必要时给实例单独配一个 SSD 或者拆库。6.3 新版本在构建速度上做了什么我编译过 0.5.0 和 0.8.0 的源码最大的感受是 HNSW 构建的优化是跳跃式的。早期版本构建 100 万条 768 维向量的 HNSW 索引动辄一两个小时而且内存控制很差。新版本通过改进图构建时的候选队列管理、减少不必要的距离重复计算以及利用 PostgreSQL 的并行索引构建能力把同样规模的构建时间压到了十几分钟以内。所以我的第一个建议就是如果你还在用 0.5 或 0.6升级到 0.7 以上光这一项就能省下大量运维时间。升级后最好重建一次索引让新代码的构建逻辑真正生效。7. 进阶过滤查询、分区与混合检索7.1 WHERE 过滤的问题向量检索一接业务马上就会遇到过滤需求只搜某个类目下的内容、只搜某个时间范围内的内容。直接写SELECT id FROM items WHERE category_id 10 ORDER BY embedding [0.01, ...] LIMIT 10;这条 SQL 在 pgvector 里通常还能走 HNSW 索引但索引扫描会按相似度顺序吐出候选行然后逐行过滤category_id 10直到凑满 10 条。如果符合条件的数据在向量空间中很稀疏索引可能要扫描成千上万个候选才能凑够性能直接崩掉。我实践的解法有三种轻度过滤保持现状调大ef_search换取足够的候选池让过滤能尽早凑够 LIMIT。中度过滤先缩小候选集再精排比如先用子查询取相似度 Top-500再在外层做过滤和排序。重度过滤考虑把过滤条件冗余到向量索引里也就是让同一个类目单独建一张子表或分区。7.2 分区与向量索引如果业务天然按时间、租户、类目切分数据分区表是压缩索引规模的有效手段。把 1000 万行拆成 10 个分区每个分区 100 万行每个分区建一个 HNSW 索引查询时如果优化器能裁剪到单个分区候选范围直接缩小到原来的十分之一。要注意的是pgvector 索引是建在分区上的不是建在父表上的。也就是说对每个分区分别建索引父表不需要建。查询时确保 WHERE 条件包含分区键否则会扫描全部分区的索引反而更慢。7.3 向量 全文检索的混合方案很多内容推荐场景是关键词 语义混合检索。pgvector 可以和 PostgreSQL 内置全文检索叠加不需要引入 ES。做法是先做全文检索过滤掉无关内容再对剩余数据做向量精排WITH matched AS ( SELECT id FROM items WHERE to_tsvector(english, title) to_tsquery(postgresql vector) LIMIT 100 ) SELECT i.id FROM items i JOIN matched m ON i.id m.id ORDER BY i.embedding [0.01, ...] LIMIT 10;这个方案在候选集不大时有奇效但如果全文检索本身命中率很高它还是要对大量行做向量距离计算。更稳妥的做法是在应用层做召回融合把全文结果和向量结果的分数加权合并这也是目前 RAG 场景比较主流的做法。8. 实测结果与避坑清单8.1 一组实测对比最后给出一组我在 100 万条 768 维向量上的实测数据机器不变索引均为 HNSWm 16, ef_construction 100查询时ef_search 40方案平均查询耗时备注无索引全表扫描680msCPU 占用高IVFFlatlists1000, probes1045ms召回率约 92%HNSW默认参数28ms召回率约 97%HNSWef_search10052ms召回率约 99.5%可以看到从无索引到有索引是数量级的提升而 HNSW 在默认参数下已经具备相当好的召回和速度。如果你的业务对精度要求没那么苛刻完全不必为了追求 99% 召回而把ef_search调到 200那会让延迟翻倍。8.2 容易踩的坑这些坑都是我自己踩过或者帮别人排查过的一条条列出来算子和索引算子族不匹配查询必须配合vector_cosine_ops建索引用错算子族会导致索引完全不被使用。小表建索引反而更慢数据量低于几千条时HNSW 索引的查询开销可能超过全表扫描。先看基线别盲目建索引。忘了在事务里用 SET LOCAL连接池复用连接时会话级SET hnsw.ef_search会影响下一个请求尽量用SET LOCAL包在事务里。更新和删除后索引膨胀HNSW 索引对数据更新和删除不是特别友好频繁变更的表建议定期REINDEX INDEX否则索引体积变大、查询变慢。索引构建时 OOM100 万条以上向量构建 HNSW 时务必把maintenance_work_mem调到 2GB 以上并且预留足够的系统内存。8.3 几个让运维更舒服的小习惯每次给表加新向量数据后我都会跑一遍召回率验证脚本对比精确 Top-K 和索引 Top-K 的重合率并把结果记录到一张监控表里。这样能第一时间发现数据分布偏移导致的召回率下降而不是等线上用户反馈。另外pgvector 的 GUC 参数比较隐蔽建议在数据库配置文件的模板里统一写清楚默认值hnsw.ef_search 40 ivfflat.probes 10同时准备好一份关于索引体积、构建时间、查询耗时的巡检口径。向量检索的优化不是一锤子买卖数据量、维度、召回需求都在变定期把这套流程重跑一遍比什么都管用。
PostgreSQL pgvector 向量检索优化实战：从全表扫描到 HNSW 索引调参
1. 向量检索卡在哪先把瓶颈说清楚1.1 从一次线上事故说起我之前接手过一个推荐服务的重构核心逻辑很简单把内容用 Embedding 模型转成向量存进数据库用户请求来时算相似度取 Top-K 返回。最初上线时数据量只有二十万条一次查询大概 30ms大家都觉得挺快。结果半年后数据涨到 120 万条接口耗时直接冲到 700ms 以上高峰时段甚至出现连接池被占满的情况。当时第一反应是换专用向量数据库但团队里没人愿意为了一个推荐场景多维护一套中间件。后来我们盯上了 PostgreSQL 的 pgvector 扩展它直接把向量类型做成数据库的一等公民不需要额外部署服务日常备份、权限、监控全走 PostgreSQL 原有体系。这篇文章就是把那次优化的完整过程复盘一遍从安装、建表、索引选型到源码层面的理解覆盖你在生产环境真正会遇到的效率问题。1.2 pgvector 的核心模型pgvector 做的事情其实很朴素在 PostgreSQL 里新增了一种vector类型支持固定维度的浮点数组然后提供了几个距离算子算子含义说明-欧氏距离L2最常用取最小值表示最相似#负内积实际返回负内积ORDER BY 升序时等价于按内积降序余弦距离返回1 - cosine_similarity对向量模长不敏感L1 距离0.7.0 之后加入曼哈顿距离场景可用查询语法非常直白SELECT id, embedding [0.12, 0.34, ...] AS distance FROM items ORDER BY embedding [0.12, 0.34, ...] LIMIT 10;本质上就是ORDER BY ... LIMIT这让它和传统 SQL 的兼容性极好任何会写 SQL 的人都能在五分钟内上手。但也正是这种“朴素”隐藏了性能问题没有索引时这条 SQL 就是一次全表扫描把每一行的向量都算一遍距离再排序。数据量小没问题数据量大了就是灾难。1.3 效率瓶颈的三个层次根据个人排障经验向量检索慢通常不是单一原因我习惯把瓶颈拆成三层看存储层向量列本身怎么存。默认float4数组768 维的向量一行就要占 3KB 左右再加上 PostgreSQL 行头和 TOAST 的开销表体膨胀得很快。索引层有没有合适的近似最近邻ANN索引。没有索引就是全表扫描有索引但参数不合理召回率和延迟也不可控。查询层查询写法是否触发索引、过滤条件是否把索引的优势抵消掉、shared_buffers和工作内存是否够用。后面所有的优化动作都围绕这三层展开。先把这条主线记住后面遇到任何EXPLAIN ANALYZE的结果你都能大致定位问题出在哪一层。2. 环境准备Windows 安装与源码编译的完整链路2.1 版本对应关系要提前确认pgvector 是 PostgreSQL 的扩展版本兼容性主要看两件事PostgreSQL 大版本要支持pgvector 版本自身的特性差异。以我们用的 PostgreSQL 14 为例pgvector 0.5.0 及以上都能正常跑0.7.0 之后的版本对 HNSW 构建速度和扫描迭代器做了大幅优化所以强烈建议直接装最新稳定版。判断方法很简单装完执行SELECT extversion FROM pg_extension WHERE extname vector;看到 0.7 以上就说明你的索引体验和半年前完全是两个时代。2.2 Windows 环境安装实测“Windows 如何安装 pgvector”是搜索量很高的词这里把实测过程完整写出来。pgvector 官方其实发布了 Windows 安装包不用自己折腾 Visual Studio 编译。第一步到 pgvector 的 GitHub Releases 页面下载vector-版本.windows-x64.exe注意看清楚你的 PostgreSQL 是 64 位还是 32 位现在基本全是 64 位。第二步关闭 pgAdmin 和所有正在连接目标实例的工具然后右键以管理员身份运行安装包。第三步安装器会让你选择 PostgreSQL 的安装目录一般会自动识别例如C:\Program Files\PostgreSQL\14确认后一路下一步。第四步安装完成后打开psql或者 pgAdmin 的查询工具执行CREATE EXTENSION vector; SELECT vector_dims([]::vector);能返回0且不报错就说明安装成功。如果CREATE EXTENSION报“无法找到文件”通常是安装器选错了 PostgreSQL 版本目录卸载重装时手动指定正确路径即可。如果官方 Windows 安装包不匹配你的 PostgreSQL 小版本还有一个备用方案用 conda 建一个带 pgvector 的 PostgreSQL 环境。不过这适合开发测试生产 Windows 环境我建议直接用官方安装包最省心。2.3 Linux 源码编译安装Linux 上我倾向于源码编译因为能拿到最新的优化也能随时看源码。前提是已经安装 PostgreSQL 的开发包Debian/Ubuntu 下执行sudo apt install postgresql-server-dev-14 build-essential git git clone --branch v0.8.0 https://github.com/pgvector/pgvector.git cd pgvector make sudo make install编译安装完成后同样在 psql 里执行CREATE EXTENSION vector;。这里特别提醒如果 PostgreSQL 是通过 EDB 安装器或编译安装到非默认路径pg_config可能不在 PATH 里编译前先which pg_config确认路径必要时手动指定PG_CONFIGmake PG_CONFIG/usr/lib/postgresql/14/bin/pg_config源码编译的好处是你可以随时进src/hnsw.c、src/ivfflat.c看实现后面章节我会讲从源码里能挖出哪些关键信息。3. 先建基线表结构、写入与距离算子3.1 建表与批量写入的细节不要一上来就建索引先建一张干净的表把数据灌进去测出全表扫描的基线后面所有优化才有对比依据。CREATE TABLE items ( id bigserial PRIMARY KEY, title text, embedding vector(768) );写入数据时有一个很容易被忽略的点不要一条一条 INSERT要批量写入。pgvector 对单条写入的开销并不比普通类型低多少但批量插入可以用到 PostgreSQL 的批量写入优化同时减少 WAL 刷盘次数。用 Python 脚本灌数据的话建议用copy_expert配合 CSV或者直接用INSERT ... SELECT unnest(...)的方式INSERT INTO items (title, embedding) SELECT g, ([ || array_to_string(ARRAY(SELECT 0.01 * random() FROM generate_series(1, 768)), ,) || ])::vector FROM generate_series(1, 10000) AS g;这个写法适合生成测试数据生产场景建议直接用COPY导入预先算好的向量文件。另外768 维的向量每个有 3KB 左右如果不需要精确浮点可以评估halfvec类型存储直接减半速度也会有提升。3.2 三种距离算子怎么选选距离算子要看 Embedding 模型的训练方式而不是拍脑袋余弦距离绝大多数文本 Embedding 模型包括 OpenAI 的 text-embedding-ada-002、bge 系列都推荐余弦相似度。pgvector 的内部会做归一化所以向量模长不影响排序结果。欧氏距离-如果用向量直接表示坐标点之类的空间位置L2 距离更直观。注意对已归一化的向量余弦距离和欧氏距离的排序结果在数学上是等价的但距离数值不同。内积#适合模型明确按内积相似度训练的场景。#返回负内积所以ORDER BY embedding # query会优先返回内积最大的结果。这里有个实战细节如果用了余弦距离索引创建时也要保持一致vector_cosine_ops对应vector_l2_ops对应-vector_ip_ops对应#。算子族配错了索引不会被查询用到这是非常隐蔽的“为什么建了索引还是全表扫描”的原因之一。3.3 全表扫描的基线数据我拿 100 万条 768 维随机向量做了测试本机是 8 核 16GB 内存的普通服务器PostgreSQL 14 pgvector 0.8.0。不建索引时执行EXPLAIN (ANALYZE, BUFFERS) SELECT id FROM items ORDER BY embedding [0.01, 0.02, ...] LIMIT 10;结果稳稳地落在 600ms 到 800msshared_buffers配大一点也就压到 500ms 左右。这个数据就是典型的“没有索引的向量检索”一旦并发上来数据库 CPU 直接被打满。别急着怪硬件先给这条查询建索引。4. 索引选型IVFFlat 与 HNSW 的取舍逻辑4.1 IVFFlat 的原理与 lists 选择pgvector 提供两种 ANN 索引IVFFlat 和 HNSW。IVFFlat 的思路是“先聚类再精搜”。它会对全表向量做 k-means 聚类把向量空间划分成lists个桶每个向量只存进最近的桶。查询时先算查询向量到每个聚类中心的距离挑出距离最近的probes个桶再在这些桶里做线性扫描。IVFFlat 有两个关键参数lists建索引时指定表示聚类的数量。probes查询时通过 GUC 参数ivfflat.probes控制表示要搜索多少个桶。lists选多少有经验公式一般取sqrt(总行数)。100 万行就是 1000再往上收益递减行数少于 1 万时lists取个 100 以内就行。probes的经验起点是lists / 10也就是 1000 个桶时先试 100看召回率够不够再调。IVFFlat 有一个巨坑建索引时表里必须有数据因为 k-means 是从已有数据里学习聚类中心的。空表建索引不会报错但后面插入的新数据分布如果和初始聚类差异很大召回率会很难看。4.2 HNSW 的原理与参数速览HNSWHierarchical Navigable Small World的思路完全不同它把向量组织成一张多层图上层是稀疏的“高速公路”下层是密集的“街区路网”。查询时从顶层入口开始沿着距离最近的邻居往下跳最终收敛到底层的最优区域。pgvector 里创建 HNSW 索引CREATE INDEX ON items USING hnsw (embedding vector_cosine_ops) WITH (m 16, ef_construction 64);两个构建期参数m每个节点的最大连接数默认 16。越大图越稠密召回越高但索引体积和构建时间也越大。ef_construction构建时搜索的候选队列大小默认 64。越大构建越慢但图质量更好。查询期还有一个参数hnsw.ef_search默认是 40。它控制查询时保留的候选队列大小值越大召回越高但延迟也越高。注意它和 IVFFlat 的probes一样都是运行时设置改完立刻生效不用重建索引。4.3 两者对比与适用场景直接给结论这张表是我实践后整理的维度IVFFlatHNSW构建速度较快较慢但 0.7 版本提升明显查询速度较快但召回依赖 probes更快尤其高维数据召回精度需要调 probes 换默认参数下召回优秀索引体积更小更大约为向量的额外 50%-80%对空表建索引不允许必须有数据可以适合场景数据量大、可接受离线重建在线服务、对延迟敏感我的建议新项目无脑 HNSW除非你的数据量到千万级以上且磁盘吃紧或者更新频繁需要定期重建 IVFFlat。HNSW 不需要像 IVFFlat 那样担心新数据分布偏移的问题运维负担小很多。5. HNSW 调参落地四个旋钮逐个试5.1 m 与 ef_construction构建期的空间换时间很多人建索引直接用默认参数其实m和ef_construction是召回率和资源消耗的源头。我习惯的做法是固定ef_construction 100起步然后分别测试m 16、m 32、m 48。为什么先动ef_construction因为构建期的候选队列越大图中每个节点的邻居越接近真实最近邻查询时“迷路”的概率越低。但如果ef_construction已经很大比如 200继续加对召回的影响就不明显了这时候该动m。m影响的是图的稠密度m 32的索引体积基本比m 16大一倍但查询吞吐的提升不是线性的到了一定阈值后收益骤减。构建时记得调大maintenance_work_memSET maintenance_work_mem 2GB;HNSW 构建过程非常吃内存默认 64MB 的 maintenance_work_mem 会让构建过程频繁落盘速度慢得离谱。我用 100 万条向量测试加大到 2GB 之后构建时间从 40 分钟缩到 9 分钟。5.2 ef_search查询期的召回率旋钮ef_search是线上你唯一需要频繁调整的参数。它和LIMIT的关系很微妙如果业务只需要 Top-10ef_search 40通常就够如果业务要 Top-100ef_search至少得 100 以上否则尾部结果的质量会明显下降。设置方式有两种-- 会话级 SET hnsw.ef_search 100; -- 事务级适合每个请求按业务调整 BEGIN; SET LOCAL hnsw.ef_search 200; SELECT ... COMMIT;我在生产环境用的是服务启动后按路由维度设置普通搜索ef_search 32高精度搜索ef_search 128这样同一个索引服务两种召回率需求。5.3 用 EXPLAIN ANALYZE 验证优化效果优化不能靠感觉每次调参后用EXPLAIN ANALYZE验证索引是否真的生效EXPLAIN (ANALYZE, BUFFERS) SELECT id FROM items ORDER BY embedding [0.01, 0.02, ...] LIMIT 10;关键看两处扫描方式必须是Index Scan using items_embedding_idx如果看到Seq Scan说明索引没被用上。Execution Time是否从几百毫秒降到了几十毫秒。另外推荐一个验证召回率的方法先用全表扫描得到一个精确的 Top-100 列表再用 HNSW 查同一个查询向量得到近似 Top-100对比两个集合的重合比例。召回率低于 90% 时调大ef_search或重建索引。6. 源码层面的几个关键真相6.1 为什么 pgvector 能直接给出结果而不需要别的中间件很多不了解的人以为 pgvector 只是“套了一层 SQL 的向量数据库客户端”其实它的核心是 PostgreSQL 的自定义索引访问方法。简单说PostgreSQL 允许第三方扩展实现一套新的索引 AM注册到pg_am系统表里查询优化器就能像对待 B-tree 一样对待 HNSW 索引。在源码里你能看到src/vector.c注册了类型src/hnsw.c实现 HNSW 的插入、扫描、构建逻辑src/ivfflat.c实现 IVFFlat 的倒排逻辑。正因为是本地实现的索引 AMpgvector 才能把“排序 LIMIT”优化成索引扫描而不是把全表数据拉出来再排序。这对你意味着什么意味着它的性能天花板取决于索引 AM 的质量而不是 SQL 层。所以当你发现查询慢先看是不是真的走到了索引扫描再看索引参数别急着怪扩展没用。6.2 HNSW 图的存储与内存成本从源码和实验数据来看HNSW 索引体积偏大的原因在于每个向量在图里通常有多个“邻居指针”底层每个节点要存m个连接上层节点数递减但也要连接。一个 768 维、100 万行的表HNSW 索引常常要额外吃 1.2GB 到 1.8GB 空间。这个体积在线上是有代价的PostgreSQL 的索引页会缓存在shared_buffers里索引越大冷查询触发磁盘读的概率越高。如果你发现查询延迟时高时低先看索引是否已经超出shared_buffers的合理覆盖范围必要时给实例单独配一个 SSD 或者拆库。6.3 新版本在构建速度上做了什么我编译过 0.5.0 和 0.8.0 的源码最大的感受是 HNSW 构建的优化是跳跃式的。早期版本构建 100 万条 768 维向量的 HNSW 索引动辄一两个小时而且内存控制很差。新版本通过改进图构建时的候选队列管理、减少不必要的距离重复计算以及利用 PostgreSQL 的并行索引构建能力把同样规模的构建时间压到了十几分钟以内。所以我的第一个建议就是如果你还在用 0.5 或 0.6升级到 0.7 以上光这一项就能省下大量运维时间。升级后最好重建一次索引让新代码的构建逻辑真正生效。7. 进阶过滤查询、分区与混合检索7.1 WHERE 过滤的问题向量检索一接业务马上就会遇到过滤需求只搜某个类目下的内容、只搜某个时间范围内的内容。直接写SELECT id FROM items WHERE category_id 10 ORDER BY embedding [0.01, ...] LIMIT 10;这条 SQL 在 pgvector 里通常还能走 HNSW 索引但索引扫描会按相似度顺序吐出候选行然后逐行过滤category_id 10直到凑满 10 条。如果符合条件的数据在向量空间中很稀疏索引可能要扫描成千上万个候选才能凑够性能直接崩掉。我实践的解法有三种轻度过滤保持现状调大ef_search换取足够的候选池让过滤能尽早凑够 LIMIT。中度过滤先缩小候选集再精排比如先用子查询取相似度 Top-500再在外层做过滤和排序。重度过滤考虑把过滤条件冗余到向量索引里也就是让同一个类目单独建一张子表或分区。7.2 分区与向量索引如果业务天然按时间、租户、类目切分数据分区表是压缩索引规模的有效手段。把 1000 万行拆成 10 个分区每个分区 100 万行每个分区建一个 HNSW 索引查询时如果优化器能裁剪到单个分区候选范围直接缩小到原来的十分之一。要注意的是pgvector 索引是建在分区上的不是建在父表上的。也就是说对每个分区分别建索引父表不需要建。查询时确保 WHERE 条件包含分区键否则会扫描全部分区的索引反而更慢。7.3 向量 全文检索的混合方案很多内容推荐场景是关键词 语义混合检索。pgvector 可以和 PostgreSQL 内置全文检索叠加不需要引入 ES。做法是先做全文检索过滤掉无关内容再对剩余数据做向量精排WITH matched AS ( SELECT id FROM items WHERE to_tsvector(english, title) to_tsquery(postgresql vector) LIMIT 100 ) SELECT i.id FROM items i JOIN matched m ON i.id m.id ORDER BY i.embedding [0.01, ...] LIMIT 10;这个方案在候选集不大时有奇效但如果全文检索本身命中率很高它还是要对大量行做向量距离计算。更稳妥的做法是在应用层做召回融合把全文结果和向量结果的分数加权合并这也是目前 RAG 场景比较主流的做法。8. 实测结果与避坑清单8.1 一组实测对比最后给出一组我在 100 万条 768 维向量上的实测数据机器不变索引均为 HNSWm 16, ef_construction 100查询时ef_search 40方案平均查询耗时备注无索引全表扫描680msCPU 占用高IVFFlatlists1000, probes1045ms召回率约 92%HNSW默认参数28ms召回率约 97%HNSWef_search10052ms召回率约 99.5%可以看到从无索引到有索引是数量级的提升而 HNSW 在默认参数下已经具备相当好的召回和速度。如果你的业务对精度要求没那么苛刻完全不必为了追求 99% 召回而把ef_search调到 200那会让延迟翻倍。8.2 容易踩的坑这些坑都是我自己踩过或者帮别人排查过的一条条列出来算子和索引算子族不匹配查询必须配合vector_cosine_ops建索引用错算子族会导致索引完全不被使用。小表建索引反而更慢数据量低于几千条时HNSW 索引的查询开销可能超过全表扫描。先看基线别盲目建索引。忘了在事务里用 SET LOCAL连接池复用连接时会话级SET hnsw.ef_search会影响下一个请求尽量用SET LOCAL包在事务里。更新和删除后索引膨胀HNSW 索引对数据更新和删除不是特别友好频繁变更的表建议定期REINDEX INDEX否则索引体积变大、查询变慢。索引构建时 OOM100 万条以上向量构建 HNSW 时务必把maintenance_work_mem调到 2GB 以上并且预留足够的系统内存。8.3 几个让运维更舒服的小习惯每次给表加新向量数据后我都会跑一遍召回率验证脚本对比精确 Top-K 和索引 Top-K 的重合率并把结果记录到一张监控表里。这样能第一时间发现数据分布偏移导致的召回率下降而不是等线上用户反馈。另外pgvector 的 GUC 参数比较隐蔽建议在数据库配置文件的模板里统一写清楚默认值hnsw.ef_search 40 ivfflat.probes 10同时准备好一份关于索引体积、构建时间、查询耗时的巡检口径。向量检索的优化不是一锤子买卖数据量、维度、召回需求都在变定期把这套流程重跑一遍比什么都管用。
