SuperBizAgent-java/mvp/architecture/knowledge-retrieval-architecture.md

知识库检索架构说明

一、架构位置

知识库检索是 Agent 工具层的一部分，为所有 Agent 提供知识查询能力。

Agent 层
  ├── Supervisor Agent
  ├── Planner Agent
  ├── SubAgents (ExternalApi, InternalError, Database...)
  └── Verifier Agent
         ↓ 调用
工具层 (Tools)
  ├── searchDoc (文档检索 - L1 向量检索)
  ├── lookup_knowledge (混合检索 - L0+L1) ← 新增
  ├── queryLogs (日志查询)
  ├── queryTrace (链路追踪)
  └── queryOrder (订单查询)
         ↓ 依赖
服务层 (Services)
  ├── VectorSearchService (L1 语义检索 - Milvus)
  ├── KnowledgeIndexService (L0 精确匹配 - 内存) ← 新增
  ├── FrontmatterParser (元数据解析) ← 新增
  └── DocumentManagementService (文档管理)
         ↓ 持久化
数据层
  ├── MySQL (api_document + metadata 字段) ← 增强
  ├── Milvus (向量索引)
  └── Local Files (knowledge_base/) ← 新增

---

二、L0+L1 混合检索架构

2.1 检索流程

Agent 调用 lookup_knowledge(query)
    ↓
┌─────────────────────────────────────────┐
│         LookupKnowledgeTool             │
│         (工具入口)                       │
└────────────┬────────────────────────────┘
             │
             ↓
    ┌────────────────┐
    │ Step 1: L0 精确匹配 │ < 10ms
    │ (内存索引)        │
    └────────┬───────────┘
             │
     ┌───────┴────────┐
     │                │
  唯一匹配          多个/零个匹配
     │                │
     ↓                ↓
高置信度         低置信度
(不调用L1)      (调用L1补充)
     │                │
     │         ┌──────────────────┐
     │         │ Step 2: L1 语义检索 │ 200-500ms
     │         │ (Milvus)          │
     │         └──────────┬─────────┘
     │                    │
     └────────┬───────────┘
              ↓
    ┌─────────────────────┐
    │ Step 3: 组装结果     │
    │ primary + supplement │
    └─────────────────────┘
              ↓
         返回给 Agent

2.2 数据流

文档上传流程：
POST /api/documents/upload
    ↓
DocumentManagementService.uploadDocument()
    ↓
1. 文本提取
2. 保存原始文件 → knowledge_base/{category}/{filename}
3. 解析 frontmatter (FrontmatterParser)
4. 分块 → 向量化 → Milvus 索引 (L1)
5. 元数据存 MySQL (metadata 字段 JSON)
6. 更新 L0 内存索引 (KnowledgeIndexService)
    ↓
完成

文档查询流程：
Agent 调用 lookup_knowledge("ERR_TIMEOUT")
    ↓
KnowledgeIndexService.exactMatch()
    ↓
遍历内存索引 (keywords 精确匹配)
    ↓
找到唯一匹配 → 读取本地文件 (前 2000 字符)
    ↓
返回 primary (高置信度)

---

三、核心组件说明

3.1 FrontmatterParser

职责：解析 Markdown 文件头的 YAML frontmatter

输入：

---
title: 支付网关错误码定义
keywords: [ERR_TIMEOUT, 超时, 支付网关]
summary: 记录了支付网关所有核心错误码的含义及排查方向
category: api
---

# 正文内容

输出：

Frontmatter {
    title: "支付网关错误码定义",
    keywords: ["ERR_TIMEOUT", "超时", "支付网关"],
    summary: "...",
    category: "api"
}

3.2 KnowledgeIndexService

职责：维护 L0 内存索引，提供精确关键词匹配

核心方法：

• @PostConstruct loadIndex() - 启动时扫描 knowledge_base/
• exactMatch(String query) - 精确匹配（不区分大小写）
• readDocument(String filePath, int maxChars) - 读取文档内容
• addToIndex(KnowledgeEntry entry) - 添加到索引
• removeFromIndex(String filePath) - 从索引移除

数据结构：

List<KnowledgeEntry> knowledgeIndex = new CopyOnWriteArrayList<>();

KnowledgeEntry {
    filePath: "knowledge_base/api/payment-errors.md",
    title: "支付网关错误码定义",
    keywords: ["ERR_TIMEOUT", "超时", "支付网关"],
    summary: "...",
    category: "api"
}

3.3 LookupKnowledgeTool

职责：L0+L1 混合检索工具，Agent 可调用

工具定义：

@Tool(description = "查询知识库文档。优先精确匹配关键词，未命中或多个匹配时自动补充语义相关片段。" +
        "参数 query: 查询关键词，例如 'ERR_TIMEOUT'、'支付网关超时'")
public LookupResult lookupKnowledge(String query)

返回格式：

{
  "found": true,
  "primary": {
    "content": "文档内容（前 2000 字符）",
    "source": "knowledge_base/api/payment-errors.md",
    "matchType": "exact_L0",
    "confidence": "high"
  },
  "supplement": {
    "content": "语义相关片段（L1）",
    "source": "metadata",
    "matchType": "semantic_L1"
  }
}

---

四、与现有架构的集成

4.1 Agent 使用场景

ExternalApiSubAgent (接口专家):

诊断步骤：
1. 提取错误码（如 "ERR_TIMEOUT"）
2. 调用 lookup_knowledge("ERR_TIMEOUT")
3. 获得完整错误码定义和排查方向
4. 结合日志/链路追踪进行分析

DatabaseSubAgent (数据库专家):

诊断步骤：
1. 识别数据库问题（如 "连接池满"）
2. 调用 lookup_knowledge("HikariCP")
3. 获得连接池配置最佳实践
4. 提供优化建议

Planner Agent (规划者):

规划阶段：
1. 分析问题类型
2. 调用 lookup_knowledge("故障诊断")
3. 获得标准诊断流程
4. 制定排查策略

4.2 与现有工具对比

工具	检索方式	响应时间	适用场景	置信度
searchDoc	L1 语义检索	200-500ms	模糊查询、语义理解	依赖相似度
lookup_knowledge	L0+L1 混合	< 10ms (高置信)	精确关键词 + 语义补充	high/low

推荐使用策略：

• 已知精确关键词（错误码、配置项）→ lookup_knowledge
• 模糊描述、需要语义理解 → searchDoc

---

五、数据库变更

5.1 api_document 表增强

新增字段：

ALTER TABLE api_document 
ADD COLUMN metadata TEXT COMMENT 'Frontmatter 元数据 (JSON)';

字段说明：

• 类型：TEXT（最大 64KB）
• 格式：JSON 字符串
• 内容：frontmatter 解析结果

示例数据：

{
  "title": "支付网关错误码定义",
  "keywords": ["ERR_TIMEOUT", "超时", "支付网关"],
  "summary": "记录了支付网关所有核心错误码的含义及排查方向",
  "category": "api",
  "version": "1.0",
  "author": "zhangsan"
}

5.2 filePath 字段用途变更

原用途：存储相对路径或 URL

新用途：存储本地文件绝对路径

knowledge_base/api/payment-errors.md
knowledge_base/infrastructure/redis-config.md

用途：

1. L0 索引读取完整文档
2. 支持未来的章节锚点功能

---

六、配置说明

6.1 application.yml 新增配置

knowledge:
  base-path: knowledge_base/

说明：

• 相对于项目根目录
• 启动时递归扫描此目录
• 建议按 category 组织子目录

6.2 目录结构规范

knowledge_base/
├── api/              # API 相关文档
│   └── payment-errors.md
├── infrastructure/   # 基础设施配置
│   ├── redis-config.md
│   ├── mysql-connection-pool.md
│   └── flyway-best-practices.md
├── domain/           # 领域知识
│   └── spring-ai-tool-best-practices.md
└── troubleshooting/  # 故障排查
    └── fault-diagnosis-process.md

---

七、性能指标

7.1 查询性能

场景	L0 耗时	L1 耗时	总耗时
唯一匹配（高置信）	< 5ms	0 (不调用)	< 10ms
多个匹配（低置信）	< 5ms	200-500ms	< 500ms
未匹配（仅L1）	< 5ms	200-500ms	< 500ms

7.2 索引性能

指标	实测值	目标值
启动扫描时间	< 20ms (6 个文档)	< 1s (500 个文档)
内存占用	< 1MB (6 个文档)	< 5MB (500 个文档)
L0 匹配时间	< 5ms	< 10ms

---

八、可观测性

8.1 日志追踪

所有查询都带 requestId（8 位 UUID），可追踪完整流程：

[a1b2c3d4] 收到知识库查询请求: query=ERR_TIMEOUT
[a1b2c3d4] L0精确匹配完成: matches=1, time=2ms
[a1b2c3d4] 置信度判断: highConfidence=true, reason=唯一匹配
[a1b2c3d4] L0唯一匹配，跳过L1检索
[a1b2c3d4] 查询完成: found=true, confidence=high, totalTime=5ms

8.2 关键指标

监控指标：

• L0 查询耗时（P50/P95/P99）
• L1 调用频率（低置信度比例）
• 查询总耗时（端到端）
• 高置信度命中率

告警阈值：

• 查询总耗时 > 2s
• L0 索引加载失败
• 高置信度命中率 < 20%

---

九、限制与注意事项

9.1 MVP 阶段限制

1. L0 索引无持久化

   • 应用重启需要重新扫描
   • 缓解：启动扫描通常 < 1s

2. 章节锚点未实现

   • sectionTitle 参数预留
   • availableSections 返回 null

3. 批量导入不支持

   • 当前仅支持单文件上传

9.2 最佳实践

1. 编写高质量 frontmatter

   • keywords 精准且全面
   • 避免关键词重复（导致多匹配）

2. 知识库目录组织

   • 按 category 分类
   • 文件命名语义化

3. 监控告警配置

   • 慢查询告警
   • L0 索引加载失败告警

---

十、后续增强方向（Phase 2）

1. 章节锚点

   • 支持 sectionTitle 参数
   • 直接定位到文档特定章节

2. L0 索引持久化

   • 序列化到文件
   • 避免重启扫描

3. 批量导入工具

   • 支持目录批量导入
   • 进度监控

4. 知识库管理 API

   • CRUD 接口
   • 在线编辑

5. 向量化元数据

   • title/summary 也参与 L1 检索
   • 提升语义检索准确度