检索

检索做三件事：把问题变成向量、在知识库里找最近的分块、把命中的片段交给上下文组装。

向量

embedding 模型由用户在引导页配置。CongoRAG 不内置模型，也不假设维度。

引导时会发一次真实请求，量出维度 N，把 document_chunks.embedding 改成 halfvec(N)，再建 HNSW 索引。维度上限是 4000。

换 embedding 模型后，旧向量不可比。界面提供“清空并重建”，重建后旧分块会被重新切分、重新向量化。

索引与查询

• 向量列：halfvec
• 索引：HNSW，opclass halfvec_cosine_ops
• 距离：余弦距离 <=>
• 默认 topK：5，调用方可以覆盖

检索会按 embedding_model 过滤，只比较同一个模型算出来的向量。不同模型的向量混在一起算距离，轻则排序错，重则维度不匹配直接报错。

为什么会有一次精确查询

HNSW 是近似索引。全局索引 + 按知识库过滤时，小知识库可能拿不满 topK：索引扫到的候选里，属于这个知识库的行不够。

代码在 ANN 结果不足 topK 时，会对这个知识库做一次精确的距离计算，补足结果。代价是要扫这个知识库的分块；好处是结果不受过滤影响，不会因为知识库小就少给。

这不是 reranker。CongoRAG v5.0.2 没有重排模型；返回的就是向量距离最近的 topK 个分块。

检索调试

POST /api/v1/knowledge-bases/{id}/search 直接返回命中的分块和相似度，不经过 chat 模型。

排查“为什么答错”时先看这个接口：

• 没命中：文档没进库、切分不合适、embedding 模型不对。
• 命中但排序不对：问题表述和文档用词差太远，或者 topK 太小。
• 命中对了但回答没用上：问题在上下文组装或模型。

上下文

检索结果会按 token 预算组装进上下文。超预算的历史交给模型压缩。压缩会丢细节；重要的信息放在知识库里，比放在对话历史里可靠。

citation 随流下发，包含 chunkId、documentId、filename、snippet、score。这些字段来自检索结果，不是模型生成的。