RAG 运行时
在线聊天里的 RAG 不是单一函数，而是一条会根据 Agent 配置、source 治理状态和 query 形态动态变化的能力链。
当前运行顺序
- 从 Agent 挂载关系解析 active sources
- 解析 active sources 中哪些属于
managed_correction - 按 query 生成 embedding，并在需要时做 multi-query expansion
- 先做向量召回
- 对 managed correction sources 单独再做一轮补充召回
- 合并结果并按 source priority / source kind / score 排序
- 如果 query 适合关键词回退，则执行 keyword fallback 补位
- 如果开启 rerank，则做 rerank 阶段
- 回表加载真实 chunk 文本
- 生成最终上下文，并把 provenance / debug payload 写进 turn
各阶段在代码里在哪里
| 阶段 | 关键实现 |
|---|---|
| active source 解析 | get_active_source_metadata_for_agent() |
| managed correction source 识别 | _list_managed_correction_source_ids() |
| multi-query expansion | ai_service/services/multi_query.py |
| 向量召回 | QdrantVectorService.search() + _search_with_query_expansion() |
| keyword fallback | _extract_keyword_fallback_term_list() 与 _build_keyword_fallback_match_list() |
| rerank | ai_service/services/rerank.py |
| 回表取 chunk | get_document_chunks_by_ids() |
multi-query 当前怎么工作
当前 multi-query 不是硬编码改写，而是一个独立服务：
- 入口：
ai_service/services/multi_query.py - 行为：用 LLM 把原始 query 改写成多个语义等价变体
- 容错：任何失败都退回到
[原始 query]
这意味着 multi-query 是增强阶段，不是阻塞性依赖。
keyword fallback 当前怎么工作
当前代码不是简单 LIKE %query%。它会：
- 先规范化 query
- 过滤过短 token 和 stopword
- 对短 query 与 CJK token 做特殊处理
- 生成 fallback term list
- 基于命中词项数和 exact query match 计算 deterministic fallback score
这个阶段的作用不是替代向量检索，而是给召回不足的 query 补一层可解释的文本命中能力。
managed correction source 当前怎么工作
当前检索链路会显式识别 KnowledgeSourceKind.MANAGED_CORRECTION。
它的作用是：
- 把已经发布的对话纠错作为一种特殊知识源参与检索
- 在最终排序中给予 correction source boost
- 让运营侧可以通过 correction publish 快速修补错误知识，而不用先改原始文档库
rerank 当前怎么工作
当前 RerankService 已经是独立阶段，但有两个现实要点：
- 如果
config.rerank.enabled为false，直接保留原始向量排序 - 即使启用，当前实现也还是 deterministic stage，真正的专用 rerank endpoint 还没接入
所以现在的 rerank 更像“明确分离好的阶段”，已经有架构位，但效果强度仍受后端集成深度限制。
运行时会留下哪些调试痕迹
当前系统会为一次 RAG turn 保留：
- multi-query 是否启用
- rerank 是否启用
- raw candidates
- final retrieved chunks
- rerank drift top3
- provenance 信息
这些信息会进入 turn 级记录或 retrieval debug report，供运营和研发复盘。
运行时依赖
- 聊天编排器提供时序与状态
rag_retrieval.py提供主检索逻辑rag_debug.py提供解释性报告- Agent 配置决定 source 范围、阈值、重排与注入策略
Qdrant提供向量召回- PostgreSQL 提供 chunk 回表和 source 治理真相源
最常见的 3 类运行时问题
有 source，但完全召回不到
优先怀疑：
- Agent 没有正确挂载 source
- 文档并未真正 indexed
- 向量状态异常
能召回，但内容不对
优先怀疑：
- chunking strategy 不适合
- rerank 没开或不够强
- source priority / correction source 排序影响了最终结果
能召回，但线上答复和 debug 不一致
优先怀疑：
- turn 级上下文里实际注入的 chunk 集合和你看的测试条件不一致
- 会话状态、Agent 配置或 mounted source 在测试前后发生了变化