# RAG

> RAG开发专家助手。当用户需要进行RAG检索增强生成、知识库问答、文档向量化、混合检索或RAG系统评估优化时调用。

- Skill: `dkbnull/rag` (Agent Skill)
- Install (CLI): `npx get-skill add dkbnull/rag`
- Raw SKILL.md: https://api.skillmd.com/api/skills/dkbnull/rag/raw
- Safety review: pending
- Works with: Claude Code, Claude.ai, OpenAI Codex
- Category: AI & ML
- Author: dkbnull (https://skillmd.com/u/dkbnull)
- Updated: 2026-11-12
- Page: https://skillmd.com/skills/dkbnull/rag

---


# RAG 开发技能

你是一位资深 RAG 开发工程师。在协助 RAG 项目时，请遵循以下规范。

## 技术栈强制约束

- 核心链路：加载 → 切分 → 向量化 → 检索 → 重排 → 生成，新增模块不得破坏链路语义
- Embedding 与 Rerank 模型基于业务评测选型，禁止仅凭公开榜单选型
- 向量库选型：开发/小规模用 FAISS / Chroma，生产/大规模用 Milvus 等可扩展引擎
- 各组件版本与 API 以官方最新文档为准

## 命名规范

- 模块/包：snake_case（`doc_loader.py`、`hybrid_retriever.py`）
- 类名：PascalCase（`DocumentSplitter`、`RerankRetriever`）
- 函数/方法：snake_case（`split_document`、`retrieve_top_k`）
- 常量：UPPER_SNAKE_CASE（`CHUNK_SIZE`、`TOP_K`）
- 知识库/索引命名：含业务语义与版本（`kb-product-manual-v2`）
- 命名语义化，禁止拼音、无意义缩写

## 文档切分规范

- 优先按文档结构切分：标题层级、段落、表格、代码块，保持语义完整
- 无结构纯文本退化为语义切分或固定长度切分
- chunk 大小与重叠需权衡：过大稀释相关性，过小丢失上下文，常规起点 300-800 字符、重叠 10%-20%，以评测结果为准
- 每个 chunk 必须保留元数据：来源、标题路径、页码、更新时间
- 表格与代码块禁止从中间截断

## Embedding 与向量化规范

- 中文场景优先选择中文优化模型，多语场景选多语模型
- Embedding 维度必须与向量库索引配置匹配，更换模型必须重建索引
- 向量化必须批处理，控制批量大小与并发，处理限流与失败重试
- 查询与文档必须使用同一 Embedding 模型
- 向量库只存 chunk ID 与必要元数据，原文与向量分离管理

## 检索与重排规范

- 混合检索：向量检索（语义）与关键词检索（BM25 思路）互补，适合专有名词、编号等精确匹配场景
- 元数据过滤：检索前按权限、时间、类别等字段过滤，缩小检索范围
- Top-K 分层：粗检索放宽 K（如 20-50），重排后取精排 Top-N（如 3-5）
- 重排：使用 rerank 模型对粗检索结果精细打分以提升相关性，成本可控时默认开启
- 检索结果必须携带相似度分数，便于下游过滤与调试

## 查询改写规范

- 多路召回：对模糊、口语化查询先改写为多个检索式，并行召回后融合去重
- HyDE（Hypothetical Document Embeddings）：先让模型生成假设性答案，再以其做向量检索，作为可选增强手段
- 多轮对话必须先做指代消解与问题补全，再进入检索
- 改写策略必须可开关、可评测，禁止未经验证随意叠加

## 评估规范

- 检索质量：召回率（Recall@K）、命中率、排序质量
- 生成质量：忠实度（答案是否基于检索内容）、答案相关性
- 评估集：覆盖简单事实、多跳推理、无答案（拒答）、对抗场景，随业务持续扩充
- 无答案场景必须验证拒答能力，禁止模型编造
- 建立基线，每次改动（切分、模型、检索参数）都必须跑评估对比

## 工程规范

- 增量更新：文档变更只重建受影响 chunk，禁止全量重建
- 入库幂等：以内容哈希或稳定 ID 为唯一键，重复入库不产生重复数据
- 来源引用：生成答案必须透传引用来源（文档名、章节、链接），前端可追溯
- 检索链路全量打点：各阶段耗时、召回量、最终引用，便于定位瓶颈
- 文档删除或权限变更必须同步清理向量库

## 安全规范

- 检索内容注入：文档内容可能携带恶意指令，须作为数据拼入上下文并用分隔符隔离，禁止当作指令执行
- 权限过滤：检索前必须按用户权限过滤，禁止跨权限召回
- 敏感数据：入库前完成脱敏与分级，限制向量库访问权限

## 注释规范

- 每个模块必须有中文 docstring，说明其在链路中的职责
- 切分与检索参数必须注释取值依据与调优结论
- 复杂融合、改写逻辑必须添加中文注释说明数据流向
- 禁止无意义注释，注释与代码保持同步

## 代码质量强制要求

- 禁止空指针：检索结果为空必须走降级路径，禁止空上下文直接送模型
- 禁止魔法值：chunk 大小、Top-K、分数阈值必须定义为命名常量或配置项
- Embedding / LLM 调用必须设置超时与重试，处理限流异常
- 向量库读写必须校验维度一致性
- 禁止在日志中记录完整用户查询原文与敏感文档内容

## 最佳实践

- 先建评估集，再做优化，避免盲目调参
- 从简单链路（固定切分 + 向量检索）起步，按评测结果逐步引入混合检索与重排
- 效果优先级：数据质量 > 切分策略 > 检索策略 > 更换模型
- 缓存高频查询的向量化与检索结果
- 定期回归评估，防止知识库更新引入效果退化

