Skip to content

Latest commit

 

History

History
50 lines (34 loc) · 4.4 KB

pgvector.md

File metadata and controls

50 lines (34 loc) · 4.4 KB

pgvector 开发规约(v1.0 已定稿)

状态:已定稿(2026-09-01 评审通过)。供人阅读、供 AI 作为规范上下文使用。 等级:**【强制】违反即缺陷;【推荐】默认遵守、评审后可豁免;【参考】**正向引导。适用 pgvector 0.6+(PostgreSQL 扩展)。前置:继承 postgresql.md 全部条文;本篇只写向量增量。与 Milvus 的选型分工见文末附录。

一、定位与选型

  1. 【强制】向量检索默认起步方案 = pgvector(与主数据同库、事务一致、运维零增量);升级走三档选型:专用库默认 Qdrant(见 qdrant.md),Milvus 仅亿级/GPU 档(见 milvus.md)——升级条件:千万级向量、检索 QPS 拖垮主库、过滤组合复杂。
  2. 【强制】向量数据与业务元数据同库同事务维护:embedding 表挂在业务 schema(或独立 ai schema),禁"向量库+业务库"双写一致性问题自己造。
  3. 【强制】embedding 表设计:主键 + 业务外键 + 内容引用(正文在源表或对象存储,不重复存大文本)+ embedding vector({维度}) + model varchar + created_at。

二、维度与模型纪律

  1. 【强制】维度固定声明(vector(1536) 等,跟随所用 embedding 模型);同表同维度,混维度禁。
  2. 【强制】每行必须记录生成 embedding 的模型标识(model);不同模型的向量禁互相检索(语义空间不同)——查询侧按当前模型过滤。
  3. 【强制】模型变更 = 全量重算:新模型向量写入新列/新表,切换查询路径,旧向量按迁移窗口清理;禁在线混跑新旧模型同一检索路径。
  4. 【强制】embedding 生成的原始文本快照或引用可追溯(版本/哈希),内容更新必须触发重算(CDC 或应用层双写)。

三、索引

  1. 【强制】检索表必须建 ANN 索引:默认 HNSW(hnsw (embedding vector_cosine_ops),查询质量优先);数据量大且可接受召回损失时用 IVFFlat(构建快、内存小)。
  2. 【强制】索引参数显式并登记:HNSW m(默认 16)/ ef_construction(默认 64);IVFFlat lists(官方口径:≤100 万行取 rows/1000,更大取 sqrt(rows))。
  3. 【强制】IVFFlat 索引须在已有数据后构建(空表建索引聚类失效);数据大量变更后重建。
  4. 【推荐】大表可评估 halfvec + half precision 索引(新版本能力)换内存与速度;收益压测说话。

四、查询

  1. 【强制】距离算子与模型口径一致:归一化向量用余弦 <=>;模型输出未归一化时先归一化再入库,禁混用 <->/<#>/<=> 不声明。
  2. 【强制】查询固定形态:ORDER BY embedding <=> $1 LIMIT k(k 取业务 top-N 略宽,如 N+10),禁无 LIMIT。
  3. 【强制】检索 SQL 必须带模型过滤(WHERE model = $当前模型)与权限/租户过滤;标量过滤与 ANN 组合时数据量级与召回评估留档。
  4. 【推荐】SET LOCAL hnsw.ef_search = N(或 ivfflat.probes)按召回率调优,参数与压测结论登记;查询计时纳入慢查询监控。

五、写入与批量

  1. 【强制】embedding 生成走异步任务(队列/调度),业务写入与向量就绪解耦:未就绪不参与检索(部分就绪状态可查)。
  2. 【强制】批量写入/重算:multi-row insert 按千行级分批;重算任务幂等(对齐 xxl-job.md 二-1)。
  3. 【推荐】embedding 生成成本控制:内容变更才重算(哈希比对跳过)。

六、运维基线

  1. 【强制】监控增量:向量表大小与增速、ANN 索引内存(HNSW 常驻)、检索 P99 与召回率抽检、生成队列积压。
  2. 【强制】备份继承 PG 基线(向量随库备份);索引可在恢复后重建(可重算数据源保留)。
  3. 【推荐】召回率回归用例(固定查询集 + 人工/抽样标注)进 CI 或巡检,模型或索引参数变更必跑。

附:分工与来源

  • 向量选型(已落决策,可推翻):pgvector 为默认起步(同库事务、零增量运维);亿级向量/高 QPS/GPU 需求升级 Milvus。类比"新项目默认 PG"哲学:先简单,规模证明需要再复杂。
  • 索引选择与参数口径(HNSW 默认、IVFFlat lists 公式)、算词语义(<=> 余弦等):pgvector 官方 README 与文档。