RAG 架构

RAG 的核心职责不是“把文件丢进向量库”这么简单，而是把知识源中的文档转成一条可检索、可调试、可修复、可追溯的知识链路。

当前主链路

flowchart TB
  Upload[Upload Source File]
  Source[Knowledge Source]
  Inspect[Inspect / Preview]
  Ingest[Ingestion Job]
  Parse[Parse Text]
  Snapshot[Persist Parse Snapshot]
  Chunk[Chunk Strategy]
  Embed[Embedding]
  PG[(PostgreSQL)]
  Qdrant[(Qdrant)]
  Minio[(MinIO)]
  Retrieve[Runtime Retrieval]
  Correction[Managed Correction Recall]
  Keyword[Keyword Fallback]
  Rerank[Rerank Stage]
  Build[Context Build]
  Trace[Turn Context + Debug Payload]
  Answer[LLM Answer]

  Upload --> Minio
  Upload --> Source
  Source --> Inspect
  Inspect --> Ingest
  Ingest --> Parse --> Snapshot --> Chunk --> Embed
  Snapshot --> PG
  Chunk --> PG
  Embed --> Qdrant
  PG --> Retrieve
  Qdrant --> Retrieve
  Retrieve --> Correction --> Keyword --> Rerank --> Build --> Trace --> Answer

分层说明

1. 知识源层

知识进入系统前先归属于 KnowledgeSource，而不是直接归属于向量库。

这层决定：

文档归哪一个业务主题
哪些 Agent 能看到这个 source
source 的优先级和 source kind
是否属于 managed_correction

2. 摄取层

摄取主流程在 ai_service/services/ingestion.py，当前明确包含：

从 MinIO 下载原始文件
调 parser 解析文本
持久化 parse snapshot
用指定 chunking strategy 切块
生成 embeddings
PostgreSQL 落 chunk 元数据
Qdrant 落向量
立刻回读 Qdrant 做 point count 校验

这里最关键的一点是：系统不是“写完向量就默认健康”，而是会记录 expected_point_count、actual_point_count 和 vector_status。

3. 在线检索层

在线检索由 ai_service/services/rag_retrieval.py 负责，当前已经不是单一向量检索函数，而是多阶段链路：

active source 解析
vector recall
managed correction source boost
keyword fallback
rerank
chunk 回表与最终上下文拼装

4. 诊断与修复层

当前项目已经形成一套完整的运维闭环：

能力	路径	作用
retrieval debug	`ai_service/services/rag_debug.py`	解释为什么召回 / 没召回
manual inspection	`ai_service/services/manual_inspection.py`	做 vector health 或 chunking preview
vector reconciliation	`ai_service/services/document_vector_reconciliation.py`	启动期核验 indexed 文档的向量健康
snapshot rebuild	`ai_service/services/snapshot_rebuild.py`	从 parse snapshot 重建指定文档
managed correction publish	`ai_service/services/knowledge_correction_service.py`	把对话纠错沉淀成服务器维护的知识源

当前数据落点

数据	主要位置	说明
原始文件	MinIO	上传源文件与部分下载入口
parse snapshot	PostgreSQL	用于后续 rebuild，不依赖原始文件始终可得
chunk 元数据	PostgreSQL	provenance、page number、block type、chunking strategy
向量	Qdrant	检索主索引
文档 / source / mount 关系	PostgreSQL	运行时可见性真相源
turn 级调试信息	PostgreSQL	对话复盘、RAG debug、turn context

当前设计重点

摄取与在线检索解耦

ingest 阶段负责把知识准备好
retrieval 阶段只消费 mounted sources 和向量 / chunk 元数据
但两边都通过统一 source / document / chunk 模型相连

managed correction 是主链路的一部分

对话纠错不是一套旁路数据。当前实现里，managed_correction source 会被显式识别，并在检索排序上获得优先权。

keyword fallback 不是“兜底搜索页”，而是召回补位阶段

当前代码会从 query 中抽取有效词项，必要时对短 query、CJK 字符串和 exact query match 做特殊处理，用它补位那些向量召回不足的情况。

rerank 已经有独立阶段

虽然当前 RerankService 还没有接入真正的专用 rerank API，但代码结构上已经把 rerank 分离出来，并且会记录 pre-rerank / post-rerank 的顺序变化。

一句总结

当前项目的 RAG 已经不是“上传文档 -> 向量检索 -> 拼 prompt”的轻量实现，而是一个带 source 治理、向量健康、调试报告、人工检查和托管纠错的知识运行系统。