SuperBizAgent-java/mvp/architecture/archive/2026-07-05-legacy/knowledge-retrieval-usage.md

知识库检索使用指南

快速开始

1. 文档格式要求

所有知识库文档必须包含 YAML frontmatter：

---
title: 文档标题（必填）
keywords: [关键词1, 关键词2, 关键词3]（必填）
summary: 文档摘要（必填）
category: api（可选）
version: 1.0（可选）
author: zhangsan（可选）
---

# 正文内容

这里是文档的正文...

2. 上传文档

API 端点：

POST /api/documents/upload
Content-Type: multipart/form-data

参数：
- file: Markdown 文件
- category: 分类（如 api, infrastructure, domain, troubleshooting）

示例：

curl -X POST http://localhost:9900/api/documents/upload \
  -F "file=@payment-errors.md" \
  -F "category=api"

返回：

{
  "docId": "abc123-def456-...",
  "status": "success"
}

3. Agent 调用

在 Agent 对话中，工具会自动可用：

用户：ERR_TIMEOUT 是什么错误？

Agent 内部：
1. 调用 lookup_knowledge("ERR_TIMEOUT")
2. L0 精确匹配找到 payment-errors.md
3. 返回完整错误码定义（高置信度）

Agent 回复：
ERR_TIMEOUT 是支付网关超时错误。
原因：...
排查方向：...

---

编写知识库文档

Frontmatter 字段说明

必填字段

title（标题）

title: 支付网关错误码定义

• 简洁明了，能准确描述文档内容
• 建议 10-30 字

keywords（关键词列表）

keywords: [ERR_TIMEOUT, 超时, 支付网关, 错误码]

• 用于 L0 精确匹配
• 包含所有可能的查询词
• 建议 3-10 个关键词
• 既要精确（ERR_TIMEOUT），也要通用（超时）

summary（摘要）

summary: 记录了支付网关所有核心错误码的含义、原因分析及排查方向

• 一句话描述文档用途
• 建议 30-100 字

可选字段

category（分类）

category: api

• 推荐值：api, infrastructure, domain, troubleshooting
• 用于目录组织

version（版本）

version: 1.0

• 文档版本号
• 便于追踪更新

author（作者）

author: zhangsan

• 文档维护者

关键词设计技巧

✅ 好的关键词设计

keywords: [ERR_TIMEOUT, 超时, 支付网关, timeout, 网关超时, 支付超时]

特点：

• 包含精确术语（ERR_TIMEOUT）
• 包含通用描述（超时）
• 包含组合词（网关超时、支付超时）
• 包含英文（timeout）

❌ 不好的关键词设计

keywords: [错误, 问题]

问题：

• 太宽泛，导致多个文档匹配
• Agent 获得低置信度结果

文档内容建议

结构化内容

# 支付网关错误码定义

## ERR_TIMEOUT

**错误说明**：支付网关调用超时

**可能原因**：
1. 网络延迟
2. 支付网关响应慢
3. 本地超时配置过短

**排查步骤**：
1. 检查网络连通性
2. 查看支付网关监控
3. 检查超时配置

**解决方案**：
- 增加超时时间
- 优化网络链路
- 联系支付网关排查

包含实际示例

## 配置示例

```yaml
payment:
  gateway:
    timeout: 5000ms  # 推荐 5 秒
    retry: 3

日志示例

2026-06-24 10:00:00 ERROR PaymentService - ERR_TIMEOUT: 支付请求超时
orderId: 12345, timeout: 3000ms

---

## 使用场景

### 场景 1: 错误码查询

**用户输入**：

ERR_TIMEOUT 是什么意思？

**Agent 流程**：
1. 调用 `lookup_knowledge("ERR_TIMEOUT")`
2. L0 精确匹配 → 唯一匹配 → 高置信度
3. 返回完整文档内容（前 2000 字符）
4. Agent 基于文档内容回答

**响应时间**：< 10ms

### 场景 2: 配置项查询

**用户输入**：

Redis 连接池怎么配置？

**Agent 流程**：
1. 调用 `lookup_knowledge("Redis")`
2. L0 精确匹配 → 可能多个匹配 → 低置信度
3. 同时调用 L1 语义检索补充
4. 返回 primary (L0) + supplement (L1)
5. Agent 综合两份结果回答

**响应时间**：< 500ms

### 场景 3: 流程查询

**用户输入**：

如何排查生产故障？

**Agent 流程**：
1. 调用 `lookup_knowledge("故障排查")`
2. L0 精确匹配 → 找到故障诊断文档
3. 返回标准诊断流程
4. Agent 按照流程指导用户

### 场景 4: 最佳实践查询

**用户输入**：

Spring AI 工具怎么写？

**Agent 流程**：
1. 调用 `lookup_knowledge("Spring AI")`
2. L0 + L1 混合检索
3. 返回最佳实践文档
4. Agent 提供具体建议和代码示例

---

## 维护知识库

### 文档更新流程

1. **修改本地文件**
   ```bash
   vim knowledge_base/api/payment-errors.md

2. 重新上传

   curl -X POST http://localhost:9900/api/documents/upload \
     -F "file=@payment-errors.md" \
     -F "category=api"
   

3. 验证更新

   • 重启应用（L0 索引重建）
   • 或等待下次部署

文档删除

DELETE /api/documents/{docId}

注意：

• 同时删除 MySQL 记录
• 删除 Milvus 向量索引
• 删除本地文件
• 从 L0 索引移除

查看已索引文档

启动日志中查看：

[INFO] 开始扫描知识库目录: knowledge_base/
[DEBUG] 文档已加入索引: title=支付网关错误码定义
[DEBUG] 文档已加入索引: title=Redis 缓存配置指南
[INFO] 知识库索引加载完成，共 6 个文档

---

故障排查

问题 1: 文档未被索引

症状：

• 上传成功，但 Agent 查询不到

排查：

1. 检查 frontmatter 格式是否正确
2. 查看启动日志是否有 WARN
3. 确认文件保存位置

解决：

# 检查文件是否存在
ls knowledge_base/api/payment-errors.md

# 检查 frontmatter 格式
head -20 knowledge_base/api/payment-errors.md

# 重启应用重建索引

问题 2: 总是调用 L1（低置信度）

症状：

• 查询耗时 > 200ms
• 日志显示调用 L1

原因：

• L0 未匹配（关键词不在 keywords 中）
• L0 多个匹配（关键词重复）

解决：

# 检查关键词是否覆盖查询词
keywords: [ERR_TIMEOUT, 超时, timeout]

# 避免关键词过于宽泛
❌ keywords: [错误, 问题]  # 太宽泛
✅ keywords: [ERR_TIMEOUT, 超时]  # 精准

问题 3: 查询返回不完整

症状：

• 文档内容被截断

原因：

• 文档过长，L0 只返回前 2000 字符

解决：

1. 将长文档拆分成多个短文档
2. 每个文档聚焦一个主题
3. 或等待 Phase 2 章节锚点功能

问题 4: 启动扫描很慢

症状：

• 应用启动时间过长

原因：

• knowledge_base/ 文件过多

解决：

# 检查文档数量
find knowledge_base -name "*.md" | wc -l

# 清理无用文档
rm knowledge_base/.backup/*.md

参考指标：

• 500 个文档：< 1s
• 1000 个文档：可能需要优化

---

性能优化

优化关键词匹配率

目标：提高高置信度命中率（减少 L1 调用）

方法：

1. 分析查询日志，找到常见查询词
2. 将常见查询词加入 keywords
3. 定期审查和优化 keywords

示例：

# 查看低置信度查询
grep "confidence=low" logs/application.log | \
  awk -F'query=' '{print $2}' | \
  awk -F',' '{print $1}' | \
  sort | uniq -c | sort -rn

减少文档数量

策略：

• 删除过时文档
• 合并相似文档
• 归档不常用文档

监控关键指标

配置监控：

• L0 查询耗时（目标 < 10ms）
• L1 调用频率（目标 < 30%）
• 高置信度命中率（目标 > 70%）

---

最佳实践总结

✅ 推荐做法

1. 关键词全面

   • 包含精确术语和通用描述
   • 包含英文和中文
   • 包含常见拼写变体

2. 文档聚焦

   • 一个文档一个主题
   • 避免大而全的文档

3. 结构化内容

   • 使用清晰的标题层次
   • 包含实际示例
   • 提供具体步骤

4. 定期维护

   • 定期审查和更新
   • 删除过时内容
   • 优化关键词

❌ 避免做法

1. 关键词模糊

   ❌ keywords: [错误, 问题]
   ✅ keywords: [ERR_TIMEOUT, 超时]
   

2. 文档过长

   ❌ 一个文档包含 50 个错误码定义（会被截断）
   ✅ 每个错误码一个文档，或按类型分组
   

3. 缺少实际示例

   ❌ Redis 配置很重要，需要优化
   ✅ 
   ```yaml
   spring:
     redis:
       lettuce:
         pool:
           max-active: 8
   

4. 长期不更新

   • 定期审查（建议每季度）
   • 删除过时内容
   • 添加新的常见问题

---

参考资料

• 架构文档：mvp/architecture/knowledge-retrieval-architecture.md
• 可观测性：.docs/knowledge-observability.md
• Handoff 文档：handoff/2026-06-24-lookup-knowledge-integration.md
• OpenSpec：openspec/changes/lookup-knowledge-integration/