rag-ingestion-auditor

Imported from zw2497205736/AI (.codex/skills/rag-ingestion-auditor/SKILL.md). Install upstream with npx skills add zw2497205736/AI --skill rag-ingestion-auditor. Copyright stays with the author.

RAG 入库治理

这个 skill 只服务一个明确目标：

• 让知识库里的文档更适合检索，让 RAG 回答更稳定

不要把它用于普通聊天、PR 审查、前端布局、部署问题。

适用场景

只有在这些场景才使用：

1. 修改文档上传 / 解析逻辑
2. 修改文档切分策略
3. 修改向量入库策略
4. 评审某类文档是否适合进入知识库
5. 排查为什么知识库“看起来有文档，但命中效果差”

本项目里的真实痛点

RAG 不是“文档一上传就一定好用”。本项目知识库长期使用中，最容易出现这些问题：

1. 文档质量参差不齐 有些文档结构清楚，有些文档噪声极多。

2. 分块策略不稳定 同样的内容，切得太碎会丢上下文，切得太大又会降低检索精度。

3. 脏数据入库 提取文本失败、空文档、格式错乱、无关文档进入知识库后，会直接拉低检索质量。

4. 知识库有内容，但命中不准 用户会感觉“文档明明上传了，为什么问不出来”。

这个 skill 的目标就是围绕这些问题，治理入库链路。

管理范围

重点关注这些位置：

• backend/services/document_service.py
• backend/utils/text_splitter.py
• backend/services/embedding_service.py
• backend/services/rag_service.py
• 文档上传相关路由和知识库命中展示逻辑

设计原则

1. 不是所有文档都适合直接入库

优先适合入库的文档：

• 项目说明
• 制度文档
• 技术方案
• FAQ
• 接口说明
• 课程资料 / 团队资料

不适合直接入库的文档包括：

• 纯图片型 PDF
• 提取后几乎没有文字的文件
• 结构极度混乱的扫描件
• 与团队问答无关的噪声文档

2. 先保证“能提取出有效文本”，再谈检索

如果文档提取后几乎没有有效内容：

• 不应正常入库
• 应标记错误或提示不可提取

不要把明显无效的文档也塞进知识库。

3. 分块策略要围绕“可检索性”设计

切分策略的核心不是“切得整齐”，而是：

• 每个 chunk 信息完整
• 每个 chunk 尽量语义自洽
• 不要把强相关内容硬切开
• 不要把完全不相关内容拼成一个块

4. 检索问题很多时候不是模型问题，而是入库问题

如果出现这些现象，优先怀疑入库链路：

• 明明上传了文档，但总搜不到
• 命中片段明显无关
• 同一类问题命中极不稳定
• 来源卡片内容很碎、很乱

文档入库检查标准

每次评审入库链路时，至少看这几项：

1. 文档是否成功提取文本
2. 提取后的文本是否有效
3. 分块大小是否合适
4. chunk 是否语义完整
5. metadata 是否足够支持来源展示
6. 入库后检索结果是否能命中核心问题

分块策略治理

1. 切块不能只追求固定长度

固定 token 长度只是底线，不是目标。

更重要的是：

• 段落是否被硬切断
• 标题和正文是否被分开
• 关键定义和解释是否被拆散

2. overlap 要服务于上下文连续性

适当 overlap 的作用是：

• 防止重要语义落在边界处被切断
• 提高相邻 chunk 的可读性

但 overlap 过大也会带来：

• 冗余 chunk 过多
• 检索结果重复
• 向量存储噪声增加

3. 不同文档类型要区别对待

例如：

• FAQ 文档适合较小 chunk
• 长篇技术方案适合中等 chunk
• 结构化说明文档适合按段或按节切分

不要默认所有文档都只靠一套分块参数。

检索质量评审标准

知识库入库后，至少要能支持这三类问题：

1. 直接事实型问题 例如某个模块是什么、某个配置是什么

2. 解释型问题 例如某个机制怎么做、某个流程为什么这样设计

3. 定位型问题 例如哪份文档提到了某个主题、某类内容在哪个文件里

如果这三类问题经常答不好，优先回头查：

• 文档是否适合入库
• chunk 是否合适
• metadata 是否完整

修改入库链路时的检查清单

每次改动后，至少检查：

1. 新文档是否能正常解析
2. 空文档 / 异常文档是否被正确拦截
3. chunk 数量是否合理
4. 检索结果是否更稳定
5. 来源展示是否还能对应到正确文件

最终标准

这个 skill 的目标不是“让知识库文件变多”，而是：

1. 进库的文档更干净
2. chunk 更适合检索
3. 命中结果更稳定
4. 回答和来源展示更可信

如果做不到这几点，就说明这次 RAG 入库治理还不够到位。