pgvector 与带范围的向量检索

1. 解决什么问题

教材资料需要同时支持向量相似度、教学等级、适用语言、地区与版本过滤。pgvector 把向量检索放进 PostgreSQL，便于与来源记录和业务数据关联，减少独立服务的同步复杂度。

2. 原理与术语

<=> 表示余弦距离，查询按距离升序取候选。当前分数为 1 - distance，并非可信度概率。精确检索在符合范围的行上比较距离；HNSW/IVFFlat 是可选近似索引，可能牺牲部分召回换取速度。

3. 输入输出与执行

retrieve 接收 query、任务范围、limit 和 strategy。范围包含 level、target_language、region、namespace。SQL 将 chunks 与 documents 连接，只读取 active 资料，返回片段文本、来源 URL、文档版本与显式 facts。

4. 混淆点

本项目演示和真实模式都使用精确向量查询，没有建立 ANN 索引。迁移中的 document_filter 是元数据过滤索引，不是向量索引。真实 PostgreSQL 查询加演示哈希向量，也不能称为真实语义检索效果验证。

5. 最小示例

下面是 pgvector 距离运算，可直接在数据库执行：

SELECT '[1,0]'::vector <=> '[1,0]'::vector AS same,
       '[1,0]'::vector <=> '[0,1]'::vector AS orthogonal;

同方向距离应为 0，正交距离应为 1。这个数学例子不涉及教材语义。

6. 实际实现

retrieve(..., strategy='vector') 直接返回前 k 个范围内结果。当前没有最低相关性阈值，因而“有结果”不等于资料足够相关。关键词基线采用有限的字符词项计数，hybrid 使用排名融合；不是 BM25 或已接入 Reranker。

7. 源码与数据结构

阅读 system/app/retrieval.py::retrieve、settings.py::namespace 与 system/migrations。向量列没有统一固定维度，查询隔离依赖 namespace；导入端负责维度验证。namespace 与地区条件必须始终存在，不能为了补足 k 条随意移除。

8. 取舍与替代

小规模精确查询是评测近似索引的良好基线。数据增长后应先采集查询、过滤选择性和执行计划，再测试 ANN。带过滤的近似检索可能返回不足 k；迭代扫描、分区或过滤索引各有成本，不应直接照搬参数。

9. 实验与验收

在 system 目录查看实际扩展版本和距离：

docker compose exec db psql -U hanlink -d hanlink -c "SELECT extversion FROM pg_extension WHERE extname='vector';"
docker compose exec db psql -U hanlink -d hanlink -c "SELECT '[1,0]'::vector <=> '[0,1]'::vector AS distance;"
curl -s -G -H "X-API-Key: ${LAB_API_KEY:-}" --data-urlencode 'query=校园生活' \
  --data 'level=A1' --data 'language=en' --data 'region=SA' http://127.0.0.1:8000/api/search

把 region 改为没有资料的区域，预期空列表，不能返回 SA 数据。记录返回片段的文档版本和来源，验收过滤与溯源，不把这些检查写成模型质量评测。

10. 故障排查

找不到 vector 类型先查扩展迁移；维度不同查 namespace；空结果查 active、元数据值和导入模式；慢查询看 EXPLAIN、数据量与过滤条件。当前无 ANN，不能用调大 hnsw 参数解释本实现的慢查询。

11. 面试题与追问

问：为什么选 pgvector？ 业务已需要关系库，来源、版本与过滤可在 SQL 中关联。追问：一定比专用库好吗？ 不一定，应按规模、并发与运维评估。再追问：如何证明 ANN 没漏太多？ 与相同查询的精确结果比较 Recall@k。

STAR 应用：假设实验场景，R 为应核对的证据

对应	S：情境	T：目标	A：行动	R：验收证据
主问	已有关系数据与向量资料	选择易追溯存储	用SQL关联来源和元数据过滤	返回可核对的文档版本与片段
追问一	规模增长后查询变慢	验证替代方案	固定并发与过滤条件做对照	报告实测，不作通用产品性能排名
追问二	准备增加ANN索引	控制近似遗漏	与精确查询比较Recall@k	记录速度和召回的共同变化

这些是设计讨论的参考表达，实际执行前不能改写为已取得的历史成果。

12. 官方资料与版本

pgvector 官方仓库、PostgreSQL SELECT。Compose 镜像 pgvector/pgvector:0.8.1-pg16；核验日期 2026-11-03。运行实例的精确版本由上述命令与验收报告确认。