用途
pgvector-semantic-search 用于在 PostgreSQL 中搭建向量相似度搜索，服务于 AI/ML 嵌入、RAG 应用或语义搜索。语义搜索按含义而非精确关键词查找内容：嵌入模型把文本转换为高维向量，含义相近的文本映射到相近的点；pgvector 将这些向量存储在 PostgreSQL 中，并使用近似最近邻（ANN）索引快速找到最接近的匹配，无需离开数据库即可扩展到数百万行。存储文本及其嵌入，查询时把搜索文本转换为向量并返回距离最小的行。
该指南覆盖 pgvector 的配置与调优，不涉及嵌入模型选择或文本分块——这两者会显著影响搜索质量。使用全部特性（halfvec、binary_quantize、迭代扫描）需要 pgvector 0.8.0+。
主要能力
- 默认推荐配置（Golden Path）：嵌入列类型 halfvec(N)，N 为嵌入维度（须处处一致，示例用 1536）；距离使用余弦（<=>）；索引使用 HNSW（m = 16，ef_construction = 64），配合 halfvec_cosine_ops 并以 <=> 查询；查询时召回设置 SET hnsw.ef_search = 100；查询模式为 ORDER BY embedding <=> $1::halfvec(N) LIMIT k。
- 核心规则：每个数据库启用扩展 CREATE EXTENSION IF NOT EXISTS vector; 默认使用 HNSW 索引（速度—召回权衡更优，可在空表上创建，无需训练步骤），仅在写入密集或内存受限时考虑 IVFFlat；默认使用 halfvec（存储和索引缩小 50%，召回损失极小）；初始数据批量加载后再建索引；生产环境用 CREATE INDEX CONCURRENTLY 并发创建；默认使用余弦距离；查询操作符须与索引 ops 匹配；查询向量始终显式转换类型；数据与查询必须使用同一嵌入模型。
- 类型规则：嵌入存为 halfvec(N)，查询向量转换为 halfvec(N)，二值量化向量存为生成列中的 bit(N)；不要混用 vector / halfvec / bit 而不显式转换；不要在 ORDER BY 中对表列调用 binary_quantize()，应预先存储；维度必须匹配。
- 标准模式：建表时 contents TEXT NOT NULL、embedding halfvec(1536) NOT NULL，创建 HNSW 索引，查询返回最接近的 10 条。
- HNSW 索引：推荐索引类型，构建多层可导航图，速度—召回权衡更优，可在空表上创建。参数包括 m（默认 16，每层最大连接数，越高召回越好、内存越多）、ef_construction（默认 64，构建时候选列表，越高图质量越好、构建越慢）、hnsw.ef_search（默认 40，查询时候选列表，越高召回越好、查询越慢，应 ≥ LIMIT）。指南给出 ef_search 调优的粗略参考：40 约 1x 基线速度、100 约 2x 慢、200 约 4x 慢、400 约 8x 慢（实际结果因数据集而异）。
- IVFFlat 索引（通常不推荐）：仅在 HNSW 运维成本比峰值召回更重要时使用，例如写入密集或数据频繁变化且愿意频繁重建索引、需要可预测的构建时间与内存、内存紧张无法常驻 HNSW 图、数据分区或分层且索引位于较冷分区。需要低延迟下最高召回、最少调优或“设置后不管”的索引时应避免。IVFFlat 要求建索引前数据已存在，召回取决于 lists 和 ivfflat.probes。
- 量化策略：量化是内存决策而非召回决策。默认用 halfvec 存储和索引；估算 HNSW 索引占用约每 1536 维 halfvec（m=16）4–6 KB（数量级），3072 维约 2 倍，m=32 大致使 HNSW 链接/图开销翻倍。若 p95/p99 延迟上升而 CPU 大多空闲，HNSW 索引可能已不再常驻内存。halfvec 放不下时使用二值量化 + 重排序。指南给出 1536 维在 m=16 下的 halfvec 容量粗略范围（16GB 约 2–3M 向量、32GB 约 4–6M、64GB 约 8–12M、128GB 约 16–25M），3072 维除以约 2，m=32 也除以约 2。
- 二值量化（超大数据集）：内存减少 32 倍，配合重排序获得可接受召回。使用生成列 embedding_bq bit(1536) GENERATED ALWAYS AS (binary_quantize(embedding)::bit(1536)) STORED，创建 hnsw (embedding_bq bit_hamming_ops) 索引，查询时先按二值距离取候选（如 800 条），再按 halfvec 距离重排序取 10 条；80 倍过采样（10 条结果取 800 候选）是合理起点。
- 按数据集规模的性能建议：小规模 <100K 用默认值（索引可选但改善尾部延迟）；中规模 100K–5M 用默认值并监控 p95 延迟；大规模 5M+ 用 ef_construction=100+，内存常驻关键；超大规模 10M+ 用二值量化 + 重排序，可能的话先加内存或分区。先调 ef_search 提升召回，仅当召回停滞且内存允许时才增加 m。
- 过滤最佳实践：过滤向量搜索需谨慎。迭代扫描（过滤选择性高时推荐）：SET hnsw.iterative_scan = relaxed_order; 若结果仍稀疏可增大 SET hnsw.max_scan_tuples = 50000（提高召回但可能显著增加延迟）。不需要迭代扫描的情形：过滤匹配表中大部分行（低选择性）、通过 B-tree 索引预过滤、查询单个分区或部分索引。过滤策略：高选择性过滤（约 1 万行以下）在过滤列建 B-tree 索引预过滤；低基数过滤（不同值少）按过滤值建部分 HNSW 索引；过滤值多或数据集大时按过滤键分区。关键规则：匹配少量行的过滤需要预过滤、分区或迭代扫描；始终在真实负载下测量 p95/p99 延迟和访问元组数来验证过滤查询。替代方案：pgvectorscale 的 StreamingDiskANN 索引支持 smallint[] 列上的过滤索引，适合带标签过滤的大数据集。
- 批量加载：COPY 最快，二进制格式更快但需正确编码；加载后再建索引，可设置 maintenance_work_mem = '4GB' 和 max_parallel_maintenance_workers = 7。
- 维护：更新/删除后定期 VACUUM（陈旧条目可能保留到 vacuum 后）；高变更后性能下降可 REINDEX；写入密集且频繁删除的工作负载可考虑 IVFFlat 或按时间分区（hypertables）。
- 监控与调试：检查索引大小、用 EXPLAIN (ANALYZE, BUFFERS) 调试查询性能、通过 pg_stat_progress_create_index 监控索引构建进度、对比近似与精确召回（SET LOCAL enable_indexscan = off）、强制使用索引调试（SET LOCAL enable_seqscan = off）。
- 常见问题（症状 → 修复）：查询未使用 ANN 索引（缺少 ORDER BY + LIMIT、操作符不匹配或隐式转换）；过滤查询结果少于预期（HNSW 因过滤提前停止）；未过滤查询结果少于预期（ANN 召回太低，增大 hnsw.ef_search）；高延迟低 CPU（HNSW 索引未常驻内存）；索引构建慢（构建内存或并行不足）；内存不足错误（索引对可用 RAM 过大）；零结果或缺失结果（NULL 或零向量，避免 NULL 嵌入，余弦距离下不要用零向量）。
使用方式
按指南给出的 SQL 模式操作：启用扩展、建表并定义 halfvec 嵌入列、创建 HNSW 索引、以 ORDER BY embedding <=> $1::halfvec(N) LIMIT k 查询；根据数据规模与过滤需求调整 ef_search、迭代扫描、量化与分区策略。
适用场景
AI/ML 嵌入检索、RAG 应用、语义搜索，以及需要在 PostgreSQL 内进行向量相似度搜索并扩展到百万级行的场景。
限制
该指南不覆盖嵌入模型选择与文本分块；全部特性需要 pgvector 0.8.0+；数据与查询必须使用同一嵌入模型；维度必须一致；过滤查询需要额外策略以避免结果缺失或延迟上升；容量估算为范围而非保证，需通过监控缓存常驻与 p95/p99 延迟验证。