# ADR：`pg36_shop` 检索试点

- 状态：`1.3-proposal`
- 决策日期：2026-07-29
- 决策范围：商品标题与描述的英语检索试点

## 问题

用户输入同时包含精确词、拼写错误和只描述意图的短语。只做全文检索会漏掉
拼写错误与部分语义表达；只做模糊匹配会把字符串相似误当成业务相关；只做向量
检索则会丢掉精确词的可解释优势，并引入模型、索引和召回治理成本。

## 决策

1. 以 `pg_catalog.english` 构造存储生成的 `tsvector`，标题权重为 A，描述
   权重为 B；使用 GIN 产生词法候选。
2. 对小写标题使用 `pg_trgm`，结合 `similarity` 与 `word_similarity`
   产生容错候选；生产版本必须另设最低分门槛，不能把零分的 Top-K 当成命中。
3. 用带版本号的向量模型字段保存向量；本试点使用可复现的四维手工坐标和 L2，
   只验证数据库机制，不声称它是真实语义模型。
4. 质量基准始终使用精确向量排序；HNSW 只是待测的线上候选路径。近似召回必须
   与精确结果对照，不能由执行计划替代。
5. 三路候选各取前四名，使用 `k = 60` 的等权 RRF 融合，向应用返回前三名。
   RRF 合并名次而不是不可比的原始分数，因此无需伪造跨检索器的分数标定。
6. 先应用 `active` 与 `category` 过滤，再参与质量计算；停用商品 17 不得出现在
   任何排名结果中。

## 验收

- 固定 17 个商品、8 个查询与 24 条分级相关性标注可以从数据库逐字节导出；
- 混合检索在该集合上 Recall@3、MRR@3 都为 1，平均 NDCG@3 为
  `0.962929`；
- 全文检索在两个拼写错误查询上无命中，证明需要召回补偿；
- `q02` 上混合排序不如纯模糊排序，证明“混合必胜”不是合同；
- `q06` 的精确与 HNSW 前三名交集为 3，但该单点结果只验证测量通路；
- 应用角色可读、不可写，未授权更新返回 SQLSTATE `42501`。

## 被否决的方案

- **只用 `ILIKE '%term%'`**：缺少语言归一化、相关性排序与稳定的多词语义。
- **只用全文检索**：本数据集直接证明拼写错误查询存在零召回。
- **只用向量检索**：精确词优势、可解释性与退出成本不符合当前风险收益。
- **把原始分数线性相加**：不同检索器的分数尺度不可直接比较，必须先校准。
- **用 HNSW 结果生成质量黄金值**：近似索引的目的正是以召回换速度，会污染
  质量基线。

## 复审触发器

- 更换嵌入模型、距离函数、维度、分词配置、字典或融合参数；
- 语料、查询分布、过滤选择性或相关性标注发生实质变化；
- Recall、MRR、NDCG、P95/P99 延迟、资源或副本延迟越过发布门槛；
- 扩展版本、PostgreSQL 大版本、Pigsty 软件包或部署拓扑变化；
- 需要多语言、跨字段权限过滤、重排器或外部搜索系统。

## 退出路径

文本、查询、标注与向量均可导出为普通 CSV；全文生成列、三类索引和本章视图均
位于 `shop_ch15`。精确复位只删除这个 schema 中经 marker 认证的对象，保留
第 14 章管理的 `pg_trgm` 与 `vector` 扩展。