跳到主要内容
Ed. notes

检索:一条 SQL 与可引用结果

长文 · 2026-11-11 · 合集第 8 / 11 篇

  • PostgreSQL
  • pgvector
  • SQL
  • RAG
第 8 / 11 篇 · 查看全部章节 → 当前:检索:一条 SQL 与可引用结果

结论

Retrieval 没有神秘黑箱:query 经过与入库相同的 embedding provider 变成向量,repository.py 用 pgvector 的 <=> 算余弦距离并排序,再把行映射成 ChunkHit。搜索接口和问答图复用同一个查询函数。

问题与设计

检索层要同时解决三件事:

  1. 比较向量,找出最相近的切片。
  2. 恢复内容上下文:标题、章节路径、站内 URL。
  3. 给出可供前端排序和展示的相似度。

只返回文本,生成模型无法可靠引用;只返回 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 事件。