241 lines
5.6 KiB
Markdown
241 lines
5.6 KiB
Markdown
# 知识库文档编写与维护
|
||
|
||
**更新日期**：2026-07-05
|
||
**状态**：当前建议规范
|
||
**参考历史文档**：`archive/2026-07-05-legacy/knowledge-retrieval-usage.md`
|
||
|
||
## 1. 定位
|
||
|
||
知识库文档不是普通 Markdown 资料堆叠，而是 RAG 检索的输入资产。写得好的文档会提升：
|
||
|
||
- L0 hint 的关键词和领域识别。
|
||
- L1 向量召回质量。
|
||
- `breadcrumb` 上下文恢复能力。
|
||
- Verifier 可引用的证据质量。
|
||
|
||
当前推荐写法：结构化 Markdown + frontmatter + 明确分类 + 可检索关键词。
|
||
|
||
## 2. 文档进入系统的链路
|
||
|
||
```mermaid
|
||
flowchart TD
|
||
Markdown["Markdown file"] --> Upload["POST /api/documents/upload"]
|
||
Upload --> Parse["FrontmatterParser"]
|
||
Parse --> Enrich["DocumentFieldEnricher"]
|
||
Enrich --> Metadata["api_document.metadata"]
|
||
Upload --> Chunk["DocumentChunkService"]
|
||
Chunk --> Breadcrumb["title / breadcrumb / chunkIndex"]
|
||
Breadcrumb --> Embedding["VectorIndexService embedding text"]
|
||
Embedding --> Milvus["Milvus/Zilliz"]
|
||
Metadata --> L0["KnowledgeIndexService L0 index"]
|
||
Milvus --> L1["VectorSearchService L1 retrieval"]
|
||
```
|
||
|
||
## 3. Frontmatter
|
||
|
||
推荐模板：
|
||
|
||
```markdown
|
||
---
|
||
title: 支付网关错误码定义
|
||
keywords: [ERR_TIMEOUT, 支付超时, payment timeout, 支付网关]
|
||
summary: 记录支付网关核心错误码的含义、常见原因和排查步骤
|
||
category: api
|
||
version: 1.0
|
||
author: sre-team
|
||
---
|
||
|
||
# 支付网关错误码定义
|
||
|
||
...
|
||
```
|
||
|
||
字段说明：
|
||
|
||
| 字段 | 必填 | 用途 |
|
||
|---|---:|---|
|
||
| `title` | 是 | 文档标题，进入 L0 索引和 embedding 上下文 |
|
||
| `keywords` | 是 | L0 hint 的主要来源 |
|
||
| `summary` | 是 | 文档摘要，进入知识域描述和 Agent 上下文 |
|
||
| `category` | 建议 | 知识域、metadata filter、上传目录 |
|
||
| `version` | 可选 | 文档版本 |
|
||
| `author` | 可选 | 维护人 |
|
||
|
||
当前解析器会提示缺少 `title`、`keywords`、`summary` 的情况；缺失不一定阻断上传，但会降低检索质量。
|
||
|
||
## 4. category 建议
|
||
|
||
`category` 会影响：
|
||
|
||
- 上传文件本地目录。
|
||
- Milvus metadata。
|
||
- L0 domain hint。
|
||
- `knowledge_domain` 聚合。
|
||
- VectorStore / SDK category filter。
|
||
|
||
推荐保持稳定，不要频繁换名。
|
||
|
||
| category | 用途 |
|
||
|---|---|
|
||
| `api` | 接口、错误码、请求/响应协议 |
|
||
| `infrastructure` | MySQL、Redis、JVM、网络、中间件 |
|
||
| `troubleshooting` | 通用排障流程、Runbook |
|
||
| `domain` | 业务领域规则 |
|
||
| `spring-ai` | Spring AI / Agent / 工具最佳实践 |
|
||
|
||
注意：分类过细会导致 filter 召回不足；分类过粗会降低 L0 hint 解释力。
|
||
|
||
## 5. 关键词写法
|
||
|
||
好的关键词应该覆盖：
|
||
|
||
- 精确实体：错误码、服务名、指标名。
|
||
- 常用中文说法。
|
||
- 英文别名。
|
||
- 组合词。
|
||
|
||
示例：
|
||
|
||
```yaml
|
||
keywords: [ERR_TIMEOUT, timeout, 支付超时, 支付网关超时, payment-service, gateway timeout]
|
||
```
|
||
|
||
避免：
|
||
|
||
```yaml
|
||
keywords: [错误, 问题, 系统]
|
||
```
|
||
|
||
原因：过宽关键词会让 L0 hint 变脏，多个文档同时命中，影响解释性和 category filter。
|
||
|
||
## 6. Markdown 结构
|
||
|
||
推荐结构：
|
||
|
||
```markdown
|
||
# 文档总标题
|
||
|
||
## 场景或错误码
|
||
|
||
### 含义
|
||
|
||
### 常见原因
|
||
|
||
### 排查步骤
|
||
|
||
### 处理方案
|
||
|
||
### 日志示例
|
||
```
|
||
|
||
为什么这样写：
|
||
|
||
- `DocumentChunkService` 会按 Markdown 标题切分。
|
||
- 标题层级会生成 `breadcrumb`。
|
||
- `title + breadcrumb + content` 会一起进入 embedding 文本。
|
||
- 命中 chunk 时，Agent 更容易知道证据属于哪个章节。
|
||
|
||
## 7. 内容建议
|
||
|
||
每个可诊断条目尽量包含：
|
||
|
||
- 现象。
|
||
- 判断条件。
|
||
- 可能原因。
|
||
- 证据来源。
|
||
- 排查步骤。
|
||
- 处理建议。
|
||
- 日志或配置示例。
|
||
|
||
示例：
|
||
|
||
```markdown
|
||
## ERR_TIMEOUT
|
||
|
||
### 含义
|
||
|
||
支付网关请求超过本地或上游超时时间。
|
||
|
||
### 常见原因
|
||
|
||
1. 第三方支付服务响应慢。
|
||
2. 本地 timeout 配置过短。
|
||
3. 网络链路抖动。
|
||
|
||
### 排查步骤
|
||
|
||
1. 查询 payment-service 日志中的请求耗时。
|
||
2. 查看网关 5xx 和 timeout 指标。
|
||
3. 对比当前 timeout 配置。
|
||
|
||
### 处理建议
|
||
|
||
- 短期：重试受影响订单。
|
||
- 长期：调整 timeout 和重试策略，并监控上游延迟。
|
||
```
|
||
|
||
## 8. 上传与索引
|
||
|
||
上传接口：
|
||
|
||
```text
|
||
POST /api/documents/upload
|
||
Content-Type: multipart/form-data
|
||
|
||
file=<markdown file>
|
||
category=<category>
|
||
```
|
||
|
||
系统处理：
|
||
|
||
1. 计算文件 hash，避免重复上传。
|
||
2. 保存原始文件。
|
||
3. 解析 frontmatter。
|
||
4. 补全文档字段。
|
||
5. 写入 `api_document`。
|
||
6. Markdown-aware chunking。
|
||
7. 写入 Milvus/Zilliz。
|
||
8. 更新 L0 索引和 `knowledge_domain`。
|
||
|
||
## 9. 重建索引注意事项
|
||
|
||
当以下内容变化时，需要重新索引：
|
||
|
||
- 正文内容。
|
||
- 标题层级。
|
||
- `category`。
|
||
- `title`、`summary`、`keywords`。
|
||
- embedding 输入策略，例如加入 `breadcrumb`。
|
||
|
||
特别注意：
|
||
|
||
```text
|
||
修改 Markdown 或 embedding 输入策略，不会自动改变已有向量。
|
||
必须重新上传或重建索引后，live retrieval 才能体现变化。
|
||
```
|
||
|
||
可用 live 验收：
|
||
|
||
```bash
|
||
python scripts/eval_rag_live_acceptance.py
|
||
```
|
||
|
||
## 10. 维护 checklist
|
||
|
||
新增文档前检查：
|
||
|
||
- frontmatter 是否包含 `title`、`keywords`、`summary`。
|
||
- `category` 是否属于现有稳定分类。
|
||
- 关键词是否既有精确词也有常用表达。
|
||
- Markdown 标题层级是否清晰。
|
||
- 每个故障条目是否包含可执行排查步骤。
|
||
- 日志/配置示例是否脱敏。
|
||
|
||
更新文档后检查：
|
||
|
||
- `api_document.status` 是否为 `INDEXED`。
|
||
- `/api/search/similar` 是否能搜到目标文档。
|
||
- `eval/rag-retrieval` 是否需要新增 golden case。
|
||
- Trace 中 `tool_invocation` 是否记录到正确 source 和 breadcrumb。
|
||
|