状态:已定稿(2026-09-01 评审通过)。供人阅读、供 AI 作为规范上下文使用。 等级:**【强制】违反即缺陷;【推荐】默认遵守、评审后可豁免;【参考】**正向引导。适用 pgvector 0.6+(PostgreSQL 扩展)。前置:继承 postgresql.md 全部条文;本篇只写向量增量。与 Milvus 的选型分工见文末附录。
- 【强制】向量检索默认起步方案 = pgvector(与主数据同库、事务一致、运维零增量);升级走三档选型:专用库默认 Qdrant(见 qdrant.md),Milvus 仅亿级/GPU 档(见 milvus.md)——升级条件:千万级向量、检索 QPS 拖垮主库、过滤组合复杂。
- 【强制】向量数据与业务元数据同库同事务维护:embedding 表挂在业务 schema(或独立
aischema),禁"向量库+业务库"双写一致性问题自己造。 - 【强制】embedding 表设计:主键 + 业务外键 + 内容引用(正文在源表或对象存储,不重复存大文本)+
embedding vector({维度})+model varchar+created_at。
- 【强制】维度固定声明(
vector(1536)等,跟随所用 embedding 模型);同表同维度,混维度禁。 - 【强制】每行必须记录生成 embedding 的模型标识(
model);不同模型的向量禁互相检索(语义空间不同)——查询侧按当前模型过滤。 - 【强制】模型变更 = 全量重算:新模型向量写入新列/新表,切换查询路径,旧向量按迁移窗口清理;禁在线混跑新旧模型同一检索路径。
- 【强制】embedding 生成的原始文本快照或引用可追溯(版本/哈希),内容更新必须触发重算(CDC 或应用层双写)。
- 【强制】检索表必须建 ANN 索引:默认 HNSW(
hnsw (embedding vector_cosine_ops),查询质量优先);数据量大且可接受召回损失时用 IVFFlat(构建快、内存小)。 - 【强制】索引参数显式并登记:HNSW
m(默认 16)/ef_construction(默认 64);IVFFlatlists(官方口径:≤100 万行取rows/1000,更大取sqrt(rows))。 - 【强制】IVFFlat 索引须在已有数据后构建(空表建索引聚类失效);数据大量变更后重建。
- 【推荐】大表可评估
halfvec+ half precision 索引(新版本能力)换内存与速度;收益压测说话。
- 【强制】距离算子与模型口径一致:归一化向量用余弦
<=>;模型输出未归一化时先归一化再入库,禁混用<->/<#>/<=>不声明。 - 【强制】查询固定形态:
ORDER BY embedding <=> $1 LIMIT k(k 取业务 top-N 略宽,如 N+10),禁无 LIMIT。 - 【强制】检索 SQL 必须带模型过滤(
WHERE model = $当前模型)与权限/租户过滤;标量过滤与 ANN 组合时数据量级与召回评估留档。 - 【推荐】
SET LOCAL hnsw.ef_search = N(或 ivfflat.probes)按召回率调优,参数与压测结论登记;查询计时纳入慢查询监控。
- 【强制】embedding 生成走异步任务(队列/调度),业务写入与向量就绪解耦:未就绪不参与检索(部分就绪状态可查)。
- 【强制】批量写入/重算:multi-row insert 按千行级分批;重算任务幂等(对齐 xxl-job.md 二-1)。
- 【推荐】embedding 生成成本控制:内容变更才重算(哈希比对跳过)。
- 【强制】监控增量:向量表大小与增速、ANN 索引内存(HNSW 常驻)、检索 P99 与召回率抽检、生成队列积压。
- 【强制】备份继承 PG 基线(向量随库备份);索引可在恢复后重建(可重算数据源保留)。
- 【推荐】召回率回归用例(固定查询集 + 人工/抽样标注)进 CI 或巡检,模型或索引参数变更必跑。
- 向量选型(已落决策,可推翻):pgvector 为默认起步(同库事务、零增量运维);亿级向量/高 QPS/GPU 需求升级 Milvus。类比"新项目默认 PG"哲学:先简单,规模证明需要再复杂。
- 索引选择与参数口径(HNSW 默认、IVFFlat lists 公式)、算词语义(
<=>余弦等):pgvector 官方 README 与文档。