检索:一条 SQL 与可引用结果
结论
Retrieval 没有神秘黑箱:query 经过与入库相同的 embedding provider 变成向量,repository.py 用 pgvector 的 <=> 算余弦距离并排序,再把行映射成 ChunkHit。搜索接口和问答图复用同一个查询函数。
问题与设计
检索层要同时解决三件事:
- 比较向量,找出最相近的切片。
- 恢复内容上下文:标题、章节路径、站内 URL。
- 给出可供前端排序和展示的相似度。
只返回文本,生成模型无法可靠引用;只返回 slug,前端不知道标题和章节。因此 repository 输出的不是数据库行,而是应用级结果类型。
关键代码
查询 SQL:
SELECT c.id, c.text, c.heading_path, c.document_slug,
d.title, d.url, d.kind, d.published_date, d.tags,
1 - (c.embedding <=> %s) AS score
FROM chunks c
JOIN documents d ON d.slug = c.document_slug
ORDER BY c.embedding <=> %s
LIMIT %s
<=> 是 cosine distance,越小越近;1 - distance 转成越大越相似的 score。query vector 和 limit 都走参数绑定,不拼接用户输入。
行映射保留内部字段和外部契约的边界:
@dataclass(frozen=True)
class ChunkHit:
id: str
text: str
heading_path: tuple[str, ...]
slug: str
title: str
url: str
kind: str
date: str
tags: tuple[str, ...]
score: float
def as_result(self) -> dict[str, object]:
return {
"text": self.text,
"headingPath": list(self.heading_path),
"slug": self.slug,
"title": self.title,
"url": self.url,
"score": self.score,
...
}
def as_source(self, number: int) -> dict[str, object]:
return {
"n": number,
"title": self.title,
"url": self.url,
"slug": self.slug,
"score": round(self.score, 4),
}
/api/search 负责组装依赖,get_retriever() 把同一查询包成聊天用的闭包。两条路径共用 search_chunks(),不是两套检索逻辑。
验证
用真实 embedding 查询当前索引:
query: 多阶段构建解决了什么问题?
0.6014 build-practice-05-deployment-docker ()
0.5488 build-practice-05-deployment-docker ('它解决什么问题',)
0.5212 build-practice-05-deployment-docker ('我怎么试的', '1. 先画三个阶段')
0.5102 build-practice-05-deployment-docker ('适合谁',)
0.4614 build-practice-05-deployment-docker ('我怎么试的', '6. 为什么不在服务器上构建')
分数是相对相似度,不是概率。这个例子也暴露了另一个问题:前几条全来自同一篇文章,后续需要用上下文选择策略处理,详见调优系列。
边界
- 当前只有
chunks.document_slug普通索引,没有向量 ANN 索引;查询是精确排序,131 个切片够用,数据增长后要评估 HNSW / IVFFlat。 search_chunks()要求调用方先register_vector(conn),否则 psycopg 无法适配 vector 类型。- SQL 字段顺序和
row[0]映射耦合;改查询时要同步改映射。 - score 依赖 embedding 模型和内容分布,不能跨模型直接比较,也不能解释成正确率。
- 当前每次请求新建数据库连接,没有连接池。
下一篇看生成:检索结果怎样进入 LangGraph,并变成 sources → token → done 的 SSE 事件。