55 lines
2.5 KiB
Markdown
55 lines
2.5 KiB
Markdown
# Modular RAG Pipeline — Brief
|
||
|
||
## 背景
|
||
|
||
`lookup_knowledge` 已经能返回知识库证据，但实现集中在 `LookupKnowledgeTool` 内部：L0 查询分析、L1 向量召回、相关性归一化、证据组装、会话去重和 trace 入库耦合在一起。
|
||
|
||
旧返回契约 `primary/supplement` 也延续了“L0 是主结果、L1 是补充”的语义，和当前设计目标不一致。新的目标是让 L0 只作为 query understanding / filter / rerank / trace 信号，让 L1 向量检索成为事实证据来源。
|
||
|
||
## 目标
|
||
|
||
- 将 `lookup_knowledge` 改造成模块化 RAG pipeline。
|
||
- 保留显式 Agent tool 边界，不改工具名和 query 参数。
|
||
- L0 只提供领域、关键词、实体、category filter 和 trace hint。
|
||
- L1 filtered vector retrieval 失败或低质量时，降级为 raw query unfiltered L1 retry。
|
||
- 输出 evidence-first contract：`evidenceBlocks`、`contextPack`、`retrievalTrace`、`rerankTrace`。
|
||
- 保持 `tool_invocation` 表结构稳定，把新 trace 写入 `retrieval_details` JSON。
|
||
|
||
## 范围
|
||
|
||
已完成：
|
||
|
||
- 新增 pipeline DTO：`KnowledgeQuery`、`RetrievedEvidenceCandidate`、`ContextPack`、`RetrievalTrace`、`RerankTrace`、`EvidencePostprocessResult`。
|
||
- 新增 pipeline service：`KnowledgeQueryTransformer`、`KnowledgeDocumentRetriever`、`KnowledgeEvidencePostProcessor`、`KnowledgeContextPacker`、`LookupResultAssembler`。
|
||
- 重构 `LookupKnowledgeTool` 为薄 orchestration 层。
|
||
- 迁移 `LookupResult`，删除 `primary/supplement` 字段和 `PrimaryResult` / `SupplementResult` 类。
|
||
- 更新 `ToolInvocationRecorder`，记录 query transform、retrieval trace、context pack summary、rerank trace、fallback reason 和 evidence summaries。
|
||
- 更新 executor prompt 和 RAG 架构文档。
|
||
- 补充 lookup、recorder、fallback、rerank、context pack、session dedup 测试。
|
||
|
||
非目标：
|
||
|
||
- 不引入 implicit Advisor。
|
||
- 不引入 cross-encoder、BM25、RRF、Elasticsearch、OpenSearch。
|
||
- 不改文档上传、chunk、embedding 写入、Milvus schema。
|
||
- 不改变 Agent 何时调用 `lookup_knowledge`。
|
||
|
||
## 关联 OpenSpec
|
||
|
||
- `openspec/changes/archive/2026-07-06-modular-rag-pipeline`
|
||
|
||
## 接口影响
|
||
|
||
级别：L4 breaking interface。
|
||
|
||
原因：
|
||
|
||
- 删除旧 `LookupResult.primary` / `LookupResult.supplement`。
|
||
- `lookup_knowledge` tool JSON 输出形状变化。
|
||
|
||
缓解：
|
||
|
||
- 工具名和输入参数保持不变。
|
||
- in-repo 消费方、测试和 prompt 同步迁移。
|
||
- `tool_invocation` 表结构不变。
|