1346 words
7 minutes
enterprise RAG docs spec
知识库文档规范
本文档定义企业知识库 RAG 系统中 Markdown 源文档的格式、结构和编写规范。
文件位置
所有知识库文档放在仓库根目录下的 enterprise-kb/ 目录中,以模块名为文件名(不含特殊字符),后缀为 .md。
文档结构
每篇文档由两部分组成:YAML front-matter 和 Markdown 正文。
---skill_points: - 技能点A - 技能点Bmodule: 模块名score_points: - "基础: 描述" - "进阶: 描述" - "高级: 描述"---# 标题
## 大章节 ← 上下文标题,不单独成块
### 子主题 ← 上下文前缀,每个 #### chunk 的内容前缀
#### 具体知识点A ← 最小分块单位内容...
#### 具体知识点B ← 每个 #### 独立成一个 chunk内容...Front-matter 字段
| 字段 | 类型 | 必填 | 说明 ||------|------|------|------|| `skill_points` | list[string] | 是 | 文档关联的技能点列表,供 `/retrieve/by-skill` 检索用 || `module` | string | 是 | 所属模块名(唯一),供 `/retrieve/by-module` 检索用 || `score_points` | list[string] | 是 | 评分要点,按难度分级:基础 / 进阶 / 高级 |正文标题层级规范
| 层级 | 类型 | 行为 ||------|------|------|| `#` | 一级标题 | 文档标题,跳过,不产生 chunk || `##` | 二级标题 | 父级上下文标记,不单独成块 || `###` | 三级标题 | 上下文前缀,每个 `####` chunk 的内容前缀 || `####` | 四级标题 | **最小分块单位**,每个 `####` 及其下内容合成一个 chunk |代码块边界
代码块(```)是”粘性”的。当一个 #### chunk 内包含未关闭的代码块时,遇到下一个 #### 标题不会触发切块,以避免代码块被截断。
#### String最基础类型...```pythonr.set('user:1001', ...)``` ← 代码块正常关闭#### Hash ← 可以安全切块
#### List内容...```pythonr.lpush('key', 'val')``` ← 代码块正常关闭### 下一个主题 ← flush 后此 ### 成为下一个 chunk 的前缀分块结果示例
对于如下正文:
## 功能规范
### 数据类型与适用场景
#### String最基础类型,最大 512MB...
```python r.set('user:1001', ...) ```#### Hash适合存储对象结构...
```python r.hset('product:2001', mapping={...}) ```
#### List有序列表...将产生 3 个 chunk:
| chunk | heading_path | content 片段 |
|---|---|---|
| 0 | 功能规范 > String | ### 数据类型与适用场景\n#### String\n最基础类型...\n```python\nr.set... |
| 1 | 功能规范 > Hash | ### 数据类型与适用场景\n#### Hash\n适合存储对象结构...\n```python\nr.hset... |
| 2 | 功能规范 > List | ### 数据类型与适用场景\n#### List\n有序列表...\n```python\nr.lpush... |
heading_path 格式:## 父标题 > #### 当前标题(两级,简化版)。
skill_points 编写规范
- 每个文档至少 2 个技能点
- 技能点名称应具体、可用作检索关键词
- 命名惯例:使用中文名词短语,如「Redis数据类型」「缓存穿透」
- 避免过于宽泛的名称(如「Redis」应写「Redis数据类型」或「Redis缓存」)
score_points 编写规范
- 必须包含「基础」「进阶」「高级」三个级别
- 每级 1-3 条,简洁描述评判标准
- 格式:
"级别: 描述"(冒号前为级别,冒号后为具体要求)
示例
Redis缓存模块
---skill_points: - Redis数据类型 - 缓存穿透 - 缓存击穿 - 缓存雪崩module: Redis缓存score_points: - "基础: 能否正确选择 String/Hash/List/Set 类型并说明适用场景" - "进阶: 能否设计缓存穿透、击穿、雪崩的防御方案" - "高级: 能否根据业务场景制定完整的缓存生命周期管理策略"---# Redis缓存模块
## 功能规范
### 数据类型与适用场景
#### String最基础类型,最大 512MB。适用于简单的键值缓存,如用户 Token、配置项。
```python r = redis.Redis(host='localhost', port=6379, db=0) r.set('user:1001', json.dumps({'name': 'Alice'}), ex=3600) ```
#### Hash适合存储对象结构,按字段访问。适用于用户画像、商品信息。
```python r.hset('product:2001', mapping={'name': 'Mouse', 'price': 99.9}) ```
#### List有序列表,支持两端插入删除。适用于最新消息流、任务队列。
```python r.lpush('recent:articles', 'article:1045') r.lrange('recent:articles', 0, 9) ```
### 缓存问题与防御
#### 缓存穿透大量请求查询不存在的数据绕过缓存直接打满数据库。防御方案:布隆过滤器 + 空值缓存。
#### 缓存击穿热点键过期瞬间,大量并发请求同时穿透到数据库。防御方案:互斥锁 + 逻辑过期。
#### 缓存雪崩大量键同时过期或 Redis 宕机,导致数据库压力骤增。防御方案:过期时间随机偏移 + 主从哨兵高可用。
## 配置说明
### 关键配置项
| 配置项 | 默认值 | 说明 ||--------|--------|------|| `maxmemory` | 0(不限制) | 最大内存,建议设为物理内存的 70% || `maxmemory-policy` | `noeviction` | 内存满时的淘汰策略 |
## 评分要点
### 基础级- 能说出 String、Hash、List、Set、ZSet 的特点和基本命令- 能配置 Redis 基本连接和简单存取操作
### 进阶级- 能根据业务场景选择合适的数据类型- 能识别并防御缓存穿透、击穿、雪崩问题
### 高级- 能设计完整的缓存生命周期管理策略- 能规划 Redis 集群架构,处理故障转移命名规则
| 要素 | 规则 |
|---|---|
| 文件名 | enterprise-kb/{模块名}.md,如 Redis缓存.md |
module | 与文件名一致,不含后缀 |
skill_points | 具体技能名称,中文为主 |
score_points | 格式 "级别: 描述",级别为「基础」「进阶」「高级」 |
提交流程
- 在
enterprise-kb/目录下创建/编辑.md文件 - 确保 front-matter 三个字段齐全且格式正确
- 运行索引构建:
Terminal window uv run python scripts/build_index.py --source ./enterprise-kb/ - 提交 git 并推送,触发 post-commit hook 自动增量更新
enterprise RAG docs spec
https://sgjki547.top/posts/rag-doc-spec/