478 lines
8.7 KiB
Markdown
478 lines
8.7 KiB
Markdown
# 知识库检索使用指南
|
||
|
||
## 快速开始
|
||
|
||
### 1. 文档格式要求
|
||
|
||
所有知识库文档必须包含 YAML frontmatter：
|
||
|
||
```markdown
|
||
---
|
||
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）
|
||
```
|
||
|
||
**示例**：
|
||
```bash
|
||
curl -X POST http://localhost:9900/api/documents/upload \
|
||
-F "file=@payment-errors.md" \
|
||
-F "category=api"
|
||
```
|
||
|
||
**返回**：
|
||
```json
|
||
{
|
||
"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**（标题）
|
||
```yaml
|
||
title: 支付网关错误码定义
|
||
```
|
||
- 简洁明了，能准确描述文档内容
|
||
- 建议 10-30 字
|
||
|
||
**keywords**（关键词列表）
|
||
```yaml
|
||
keywords: [ERR_TIMEOUT, 超时, 支付网关, 错误码]
|
||
```
|
||
- 用于 L0 精确匹配
|
||
- 包含所有可能的查询词
|
||
- 建议 3-10 个关键词
|
||
- 既要精确（ERR_TIMEOUT），也要通用（超时）
|
||
|
||
**summary**（摘要）
|
||
```yaml
|
||
summary: 记录了支付网关所有核心错误码的含义、原因分析及排查方向
|
||
```
|
||
- 一句话描述文档用途
|
||
- 建议 30-100 字
|
||
|
||
#### 可选字段
|
||
|
||
**category**（分类）
|
||
```yaml
|
||
category: api
|
||
```
|
||
- 推荐值：api, infrastructure, domain, troubleshooting
|
||
- 用于目录组织
|
||
|
||
**version**（版本）
|
||
```yaml
|
||
version: 1.0
|
||
```
|
||
- 文档版本号
|
||
- 便于追踪更新
|
||
|
||
**author**（作者）
|
||
```yaml
|
||
author: zhangsan
|
||
```
|
||
- 文档维护者
|
||
|
||
### 关键词设计技巧
|
||
|
||
#### ✅ 好的关键词设计
|
||
|
||
```yaml
|
||
keywords: [ERR_TIMEOUT, 超时, 支付网关, timeout, 网关超时, 支付超时]
|
||
```
|
||
|
||
**特点**：
|
||
- 包含精确术语（ERR_TIMEOUT）
|
||
- 包含通用描述（超时）
|
||
- 包含组合词（网关超时、支付超时）
|
||
- 包含英文（timeout）
|
||
|
||
#### ❌ 不好的关键词设计
|
||
|
||
```yaml
|
||
keywords: [错误, 问题]
|
||
```
|
||
|
||
**问题**：
|
||
- 太宽泛，导致多个文档匹配
|
||
- Agent 获得低置信度结果
|
||
|
||
### 文档内容建议
|
||
|
||
#### 结构化内容
|
||
|
||
```markdown
|
||
# 支付网关错误码定义
|
||
|
||
## ERR_TIMEOUT
|
||
|
||
**错误说明**：支付网关调用超时
|
||
|
||
**可能原因**：
|
||
1. 网络延迟
|
||
2. 支付网关响应慢
|
||
3. 本地超时配置过短
|
||
|
||
**排查步骤**：
|
||
1. 检查网络连通性
|
||
2. 查看支付网关监控
|
||
3. 检查超时配置
|
||
|
||
**解决方案**：
|
||
- 增加超时时间
|
||
- 优化网络链路
|
||
- 联系支付网关排查
|
||
```
|
||
|
||
#### 包含实际示例
|
||
|
||
```markdown
|
||
## 配置示例
|
||
|
||
```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. **重新上传**
|
||
```bash
|
||
curl -X POST http://localhost:9900/api/documents/upload \
|
||
-F "file=@payment-errors.md" \
|
||
-F "category=api"
|
||
```
|
||
|
||
3. **验证更新**
|
||
- 重启应用（L0 索引重建）
|
||
- 或等待下次部署
|
||
|
||
### 文档删除
|
||
|
||
```bash
|
||
DELETE /api/documents/{docId}
|
||
```
|
||
|
||
**注意**：
|
||
- 同时删除 MySQL 记录
|
||
- 删除 Milvus 向量索引
|
||
- 删除本地文件
|
||
- 从 L0 索引移除
|
||
|
||
### 查看已索引文档
|
||
|
||
启动日志中查看：
|
||
```
|
||
[INFO] 开始扫描知识库目录: knowledge_base/
|
||
[DEBUG] 文档已加入索引: title=支付网关错误码定义
|
||
[DEBUG] 文档已加入索引: title=Redis 缓存配置指南
|
||
[INFO] 知识库索引加载完成，共 6 个文档
|
||
```
|
||
|
||
---
|
||
|
||
## 故障排查
|
||
|
||
### 问题 1: 文档未被索引
|
||
|
||
**症状**：
|
||
- 上传成功，但 Agent 查询不到
|
||
|
||
**排查**：
|
||
1. 检查 frontmatter 格式是否正确
|
||
2. 查看启动日志是否有 WARN
|
||
3. 确认文件保存位置
|
||
|
||
**解决**：
|
||
```bash
|
||
# 检查文件是否存在
|
||
ls knowledge_base/api/payment-errors.md
|
||
|
||
# 检查 frontmatter 格式
|
||
head -20 knowledge_base/api/payment-errors.md
|
||
|
||
# 重启应用重建索引
|
||
```
|
||
|
||
### 问题 2: 总是调用 L1（低置信度）
|
||
|
||
**症状**：
|
||
- 查询耗时 > 200ms
|
||
- 日志显示调用 L1
|
||
|
||
**原因**：
|
||
- L0 未匹配（关键词不在 keywords 中）
|
||
- L0 多个匹配（关键词重复）
|
||
|
||
**解决**：
|
||
```yaml
|
||
# 检查关键词是否覆盖查询词
|
||
keywords: [ERR_TIMEOUT, 超时, timeout]
|
||
|
||
# 避免关键词过于宽泛
|
||
❌ keywords: [错误, 问题] # 太宽泛
|
||
✅ keywords: [ERR_TIMEOUT, 超时] # 精准
|
||
```
|
||
|
||
### 问题 3: 查询返回不完整
|
||
|
||
**症状**：
|
||
- 文档内容被截断
|
||
|
||
**原因**：
|
||
- 文档过长，L0 只返回前 2000 字符
|
||
|
||
**解决**：
|
||
1. 将长文档拆分成多个短文档
|
||
2. 每个文档聚焦一个主题
|
||
3. 或等待 Phase 2 章节锚点功能
|
||
|
||
### 问题 4: 启动扫描很慢
|
||
|
||
**症状**：
|
||
- 应用启动时间过长
|
||
|
||
**原因**：
|
||
- knowledge_base/ 文件过多
|
||
|
||
**解决**：
|
||
```bash
|
||
# 检查文档数量
|
||
find knowledge_base -name "*.md" | wc -l
|
||
|
||
# 清理无用文档
|
||
rm knowledge_base/.backup/*.md
|
||
```
|
||
|
||
**参考指标**：
|
||
- 500 个文档：< 1s
|
||
- 1000 个文档：可能需要优化
|
||
|
||
---
|
||
|
||
## 性能优化
|
||
|
||
### 优化关键词匹配率
|
||
|
||
**目标**：提高高置信度命中率（减少 L1 调用）
|
||
|
||
**方法**：
|
||
1. 分析查询日志，找到常见查询词
|
||
2. 将常见查询词加入 keywords
|
||
3. 定期审查和优化 keywords
|
||
|
||
**示例**：
|
||
```bash
|
||
# 查看低置信度查询
|
||
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. **关键词模糊**
|
||
```yaml
|
||
❌ keywords: [错误, 问题]
|
||
✅ keywords: [ERR_TIMEOUT, 超时]
|
||
```
|
||
|
||
2. **文档过长**
|
||
```markdown
|
||
❌ 一个文档包含 50 个错误码定义（会被截断）
|
||
✅ 每个错误码一个文档，或按类型分组
|
||
```
|
||
|
||
3. **缺少实际示例**
|
||
```markdown
|
||
❌ 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/`
|