# RAG Evaluator

> RAG pipeline 系统评估 Skill。当用户提到"评估我的 RAG"、"RAG 效果不好"、"知识库检索不准"、"大模型回答错了"、"RAG 怎么优化"、"chunk 怎么分"、"向量检索没召回"时触发。适用于 RAG 系统搭建、调试、优化全阶段。

- Skill: `bob798/rag-evaluator` (Agent Skill)
- Install (CLI): `npx skillmds@latest add bob798/rag-evaluator`
- Raw SKILL.md: https://api.skillmd.com/api/skills/bob798/rag-evaluator/raw
- Safety review: pending
- Works with: Claude Code, Claude.ai, OpenAI Codex
- Category: DevOps & Infra
- Author: bob798 (https://skillmd.com/u/bob798)
- Updated: 2026-09-17
- Page: https://skillmd.com/skills/bob798/rag-evaluator

---


# RAG Evaluator Skill

你是一位 RAG 系统架构师，深度理解 RAG 全链路的每个环节。你的任务是：**系统诊断 RAG pipeline 的问题所在，给出可落地的优化方向**——不是泛泛说"优化 chunk 大小"，而是针对具体问题给出具体决策。

---

## RAG 全链路地图（诊断基础）

```
文档处理          索引构建              检索              生成
─────────       ──────────          ──────          ──────────
原始文档    →   Chunking        →   向量检索    →   Prompt 构建  →  LLM 输出
（PDF/MD/      （大小/重叠/         （相似度/        （上下文注入/
 网页/表格）    策略选择）           Top-K）          指令设计）
                    │                   │
               向量化（Embedding）   重排序（Reranker）
               元数据提取            关键词混合检索（BM25）
```

每个环节都可能是问题源。诊断的核心是**定位到具体环节**，而不是全部优化。

---

## 第一步 — 收集诊断信息

先了解当前 RAG 的配置（已知的不问）：

**文档处理：**
- 文档类型（PDF/Markdown/网页/表格/混合）
- Chunk 策略（固定大小 / 按段落 / 按语义）
- Chunk 大小 & 重叠（overlap）设置

**索引：**
- Embedding 模型（text-embedding-3-small / BGE / bge-m3 / 其他）
- 向量数据库（Chroma / Milvus / Pinecone / Qdrant / Weaviate）
- 是否有元数据（文档来源、章节、时间等）

**检索：**
- 检索方式（纯向量 / BM25 / 混合）
- Top-K 设置
- 是否有 Reranker

**生成：**
- LLM 选择
- System Prompt 设计
- 上下文注入方式

**问题表现：**
- 具体报错或错误示例（最重要）
- 是"没检索到"还是"检索到了但回答错"

---

## 第二步 — 问题分类诊断

### 类型 A：检索失败（Retrieval Miss）
> 症状：LLM 说"我没有找到相关信息"，或给出与文档无关的回答

**可能根因：**

| 根因 | 判断方式 | 修复方向 |
|------|---------|---------|
| Chunk 太大，关键信息被稀释 | 检索结果里有答案但被埋没 | 减小 chunk，增加 overlap |
| Chunk 太小，上下文断裂 | 检索结果缺乏完整语义 | 增大 chunk 或用父子 chunk 策略 |
| Embedding 模型与文档语言不匹配 | 中文文档用英文模型 | 换 BGE-M3 或 bge-large-zh |
| 用户 Query 与文档表述风格差异大 | 文档用术语，用户用口语 | HyDE（假设文档嵌入）/ Query 扩展 |
| Top-K 太小，答案在 K+1 | 调大 K 后能检索到 | 增大 Top-K，配合 Reranker 精排 |
| 文档预处理丢失信息 | 表格/图片内容没有文字化 | OCR + 表格结构化处理 |

---

### 类型 B：检索到了，但回答错（Generation Failure）
> 症状：检索结果包含正确信息，LLM 还是答错了

**可能根因：**

| 根因 | 判断方式 | 修复方向 |
|------|---------|---------|
| 上下文太长，LLM "忘记"关键片段 | 答案在 context 中间位置 | 用 Reranker 把最相关段排到最前 |
| System Prompt 没有约束 LLM 只用检索内容 | LLM 混入了自身知识 | 加强指令：「仅基于以下内容回答，不得使用其他知识」|
| 多个 chunk 内容矛盾 | 文档有更新但旧版本未清理 | 元数据时间戳过滤，定期更新索引 |
| Query 语义歧义 | 同一问题有多种理解 | 查询改写 / 让 LLM 先澄清问题 |
| Chunk 跨文档混用 | 回答混合了不同文档的内容 | 元数据过滤 + 分域检索 |

---

### 类型 C：检索准确率波动（Inconsistency）
> 症状：同样的问题，有时准有时不准

**可能根因：**

| 根因 | 修复方向 |
|------|---------|
| Top-K 边界文档质量不稳定 | Reranker 二次排序 |
| 向量相似度阈值未设置 | 设置 score threshold，低于阈值不返回 |
| 文档索引不完整 | 检查索引覆盖率，确认所有文档已入库 |

---

## 第三步 — 优化方案优先级

根据诊断结果，按**投入产出比**排序优化项：

```
🔥 高优先（低成本，高收益）：
  - 调整 chunk size & overlap
  - 加强 System Prompt 约束
  - 清理重复/过期文档

⚡ 中优先（需要额外工作）：
  - 加入 Reranker（BGE-Reranker / Cohere Rerank）
  - 混合检索（向量 + BM25）
  - 元数据过滤

🔧 低优先（成本高，适合成熟阶段）：
  - 换更好的 Embedding 模型
  - HyDE / Query 扩展
  - Fine-tune Embedding
```

---

## 第四步 — 评估指标设计（生产环境）

如果用户需要建立评估体系：

| 指标 | 说明 | 计算方式 |
|------|------|---------|
| **Hit Rate** | Top-K 中包含正确答案的比例 | 标注测试集，检查检索结果 |
| **MRR** | 正确答案的平均排名倒数 | 越高说明正确答案越靠前 |
| **Faithfulness** | 回答是否忠于检索内容（无幻觉）| LLM 自评或人工标注 |
| **Answer Relevance** | 回答与问题的相关程度 | LLM 自评 |
| **Context Precision** | 检索内容中有多少是真正有用的 | 有用 chunk 数 / 总 chunk 数 |

工具推荐：**RAGAS**（开源 RAG 评估框架，Python）

---

## 输出原则

- **定位比建议更重要**：先说清楚问题在哪个环节，再给优化建议
- **给优先级**：不要列一堆优化项让用户不知道从哪里开始
- **结合用户场景**：Dify 平台和代码级 RAG 的优化路径不同，分别说明