# RAG 评测框架设计文档

> 版本：v1.0  
> 日期：2026-04-13  
> 背景：为 dagent agent 平台设计的独立 RAG 评测框架

---

## 一、背景与目标

### 为什么做成独立框架

dagent 平台已具备完整的 RAG 能力（知识库切片、向量检索、ReAct Agent），但缺乏系统性的评测手段。将评测能力做成**独立框架**而非嵌入现有 backend，原因如下：

- **平台无关**：通过标准化 Adapter 接口，可评测任何 RAG 系统，不只是 dagent
- **独立部署**：不影响生产服务，可单独扩缩容，评测任务不占用业务资源
- **技术栈自由**：可选最适合评测场景的工具和模型
- **可复用**：其他项目也能接入使用

### 目标

1. 提供**检索层**和**生成层**的完整评测指标体系
2. 支持通过 **Python SDK** 集成到 CI/CD 流程
3. 提供 **Web UI** 供非技术人员操作和查看报告
4. 对接 dagent 平台，同时保持对其他平台的扩展能力

---

## 二、评测指标体系

### 2.1 检索层评测（Retrieval Evaluation）

评测知识库切片的召回质量，**不依赖 LLM**，纯计算指标。

| 指标 | 全称 | 说明 | 计算方式 |
|------|------|------|----------|
| **Hit Rate@K** | 命中率 | Top-K 结果中是否包含至少一个相关切片 | 二值判断，对所有样本取均值 |
| **MRR@K** | Mean Reciprocal Rank | 第一个相关切片排名的倒数均值 | `MRR = mean(1 / rank_i)`，rank_i 为第一个相关切片的位置 |
| **NDCG@K** | Normalized Discounted Cumulative Gain | 考虑排名权重的相关性得分，最全面的检索指标 | `NDCG = DCG / IDCG`，DCG 对高排名相关结果给予更高权重 |
| **Context Precision** | 上下文精确率 | 召回的切片中有多少是真正相关的（信噪比） | LLM-as-judge 判断每个召回切片是否相关 |
| **Context Recall** | 上下文召回率 | 回答所需信息有多少被召回覆盖 | LLM 将参考答案分解为原子声明，检查每条声明是否被召回内容覆盖 |

**指标公式**

```
Hit Rate@K = (1/|Q|) * Σ 1[∃ relevant chunk in top-K results]

MRR@K = (1/|Q|) * Σ (1 / rank_i)
  rank_i = position of first relevant chunk for query i

DCG@K = Σ_{i=1}^{K} rel_i / log2(i+1)
NDCG@K = DCG@K / IDCG@K
  IDCG = DCG of ideal (perfect) ranking

Context Precision = |relevant ∩ retrieved| / |retrieved|
Context Recall = |ground truth claims covered by context| / |total ground truth claims|
```

### 2.2 生成层评测（Generation Evaluation）

评测 Agent 基于召回内容的回复质量，**依赖 LLM Judge**。

| 指标 | 说明 | 计算方式 | 是否需要参考答案 |
|------|------|----------|-----------------|
| **Faithfulness（忠实度）** | 回答中每个声明是否都有召回内容支撑，无幻觉 | LLM 分解答案为原子声明 → 逐条判断是否可从 context 推导 → 支持数/总数 | 否 |
| **Answer Relevance（答案相关性）** | 回答是否切题，有没有答非所问 | LLM 从答案反向生成问题 → 与原问题做 Embedding 相似度 | 否 |
| **Answer Correctness（答案正确性）** | 回答与标准答案的事实一致程度 | LLM judge 评分 + Embedding 相似度加权 | 是 |
| **Groundedness（可溯源性）** | 回答中每个声明是否可追溯到具体切片 | LLM-as-judge，带 chain-of-thought | 否 |

**Faithfulness 计算原理（最重要的指标）**

```
1. LLM 将 answer 分解为原子声明列表
   例："答案：北京是中国首都，人口约2200万"
   → ["北京是中国首都", "北京人口约2200万"]

2. 对每条声明，LLM 判断：能否从 retrieved context 中推导出来？
   → [True, False]  （第二条无法从 context 推导 = 幻觉）

3. Faithfulness = 支持的声明数 / 总声明数 = 1/2 = 0.5
```

### 2.3 端到端综合指标

| 指标 | 计算方式 | 说明 |
|------|----------|------|
| **RAG Score** | 调和均值(Faithfulness, Answer Relevance, Context Precision, Context Recall) | 综合评分，任一短板都会拉低总分 |
| **Hallucination Rate** | 含幻觉样本数 / 总样本数（Faithfulness < 阈值） | 幻觉发生率 |

---

## 三、系统架构

### 3.1 整体架构

```
┌─────────────────────────────────────────────────────────────────┐
│                      RAG Eval Framework                          │
│                                                                 │
│  ┌──────────────┐    ┌──────────────────┐    ┌───────────────┐  │
│  │  Python SDK  │    │  FastAPI Server  │    │  React Web UI │  │
│  │  (核心逻辑)   │ ←→ │  (REST API)      │ ←→ │  (可视化报告)  │  │
│  │  CLI 支持    │    │  任务队列         │    │  测试集管理    │  │
│  └──────────────┘    └──────────────────┘    └───────────────┘  │
│          ↓                    ↓                                  │
│  ┌──────────────────────────────────────────────────────────┐   │
│  │                    核心模块                               │   │
│  │  Adapters  │  Evaluators  │  LLM Judge  │  Dataset Gen   │   │
│  └──────────────────────────────────────────────────────────┘   │
└─────────────────────────────────────────────────────────────────┘
                    ↕ HTTP API（标准化 Adapter 接口）
┌─────────────────────────────────────────────────────────────────┐
│         dagent platform  /  任何其他 RAG 系统                     │
└─────────────────────────────────────────────────────────────────┘
```

### 3.2 数据流

```
测试集 (question + relevant_chunk_ids + reference_answer)
         ↓
    EvalRunner.run(dataset, agent_id, knowledge_hub_id)
         ↓
    ┌────────────────────────────────────────────────────┐
    │  for each sample:                                  │
    │                                                    │
    │  Step 1: adapter.retrieve(question)                │
    │    → 获取 Top-K 召回切片                            │
    │    → 计算 Hit Rate / MRR / NDCG（与标注对比）       │
    │                                                    │
    │  Step 2: adapter.chat(question)                    │
    │    → 获取 Agent 回复 + 引用切片                     │
    │    → judge.score_faithfulness(answer, context)     │
    │    → judge.score_relevance(question, answer)       │
    │    → judge.score_correctness(answer, reference)    │
    └────────────────────────────────────────────────────┘
         ↓
    EvalReport（每条样本详情 + 汇总统计 + 趋势对比）
```

---

## 四、项目结构

```
rag-eval/
├── sdk/                                # Python SDK（核心）
│   ├── rag_eval/
│   │   ├── __init__.py
│   │   ├── runner.py                   # 评测任务执行器（入口）
│   │   ├── adapters/                   # 平台适配器
│   │   │   ├── base.py                 # 抽象接口定义
│   │   │   └── dagent.py               # dagent 适配器实现
│   │   ├── evaluators/                 # 评测器
│   │   │   ├── retrieval.py            # 检索层：Hit Rate / MRR / NDCG
│   │   │   └── generation.py           # 生成层：Faithfulness / Relevance / Correctness
│   │   ├── judge/                      # LLM Judge
│   │   │   ├── base.py                 # 抽象接口
│   │   │   └── openai_compatible.py    # 兼容 DeepSeek / Qwen / OpenAI
│   │   ├── dataset/                    # 测试集管理
│   │   │   ├── schema.py               # 数据结构定义（Pydantic）
│   │   │   └── generator.py            # LLM 自动生成测试集
│   │   └── report.py                   # 报告生成与格式化
│   ├── pyproject.toml
│   └── README.md
│
├── server/                             # FastAPI 后端
│   ├── main.py
│   ├── api/
│   │   ├── dataset.py                  # 测试集 CRUD
│   │   ├── task.py                     # 评测任务管理
│   │   ├── report.py                   # 报告查询
│   │   └── config.py                   # 平台连接 & Judge 配置
│   ├── service/
│   │   ├── task_service.py
│   │   └── report_service.py
│   ├── models/                         # 数据库模型（SQLite / PostgreSQL）
│   │   └── schema.sql
│   └── requirements.txt
│
├── frontend/                           # React 前端
│   ├── src/
│   │   ├── pages/
│   │   │   ├── Dataset/                # 测试集管理（上传/生成/标注）
│   │   │   ├── Task/                   # 评测任务（配置/提交/进度）
│   │   │   └── Report/                 # 报告 & 可视化（雷达图/趋势图）
│   │   └── components/
│   └── package.json
│
└── docker-compose.yml                  # 一键部署
```

---

## 五、核心接口设计

### 5.1 Adapter 抽象接口

```python
# sdk/rag_eval/adapters/base.py

from abc import ABC, abstractmethod
from dataclasses import dataclass

@dataclass
class RetrievedChunk:
    chunk_id: str
    content: str
    score: float          # 相似度分数
    headers: str          # 所属章节标题
    file_id: str

@dataclass
class AgentResponse:
    answer: str
    retrieved_chunks: list[RetrievedChunk]   # Agent 实际使用的切片
    latency_ms: int

class RAGAdapter(ABC):
    """
    任何 RAG 平台都需要实现这两个方法。
    框架通过此接口与平台交互，不依赖平台内部实现。
    """

    @abstractmethod
    async def retrieve(
        self,
        query: str,
        knowledge_hub_id: str,
        top_k: int = 10,
        **kwargs
    ) -> list[RetrievedChunk]:
        """调用平台检索接口，返回召回的切片列表"""
        ...

    @abstractmethod
    async def chat(
        self,
        query: str,
        agent_id: str,
        **kwargs
    ) -> AgentResponse:
        """调用平台 Agent 对话接口，返回回复和引用的切片"""
        ...
```

### 5.2 dagent 适配器

```python
# sdk/rag_eval/adapters/dagent.py

class DagentAdapter(RAGAdapter):
    """
    对接 dagent 平台的适配器。
    通过 HTTP API 调用，不依赖 dagent 内部代码。
    """

    def __init__(self, base_url: str, org_id: str, token: str):
        self.base_url = base_url
        self.org_id = org_id
        self.headers = {"Authorization": f"Bearer {token}"}

    async def retrieve(self, query, knowledge_hub_id, top_k=10, **kwargs):
        # 调用 dagent 知识库检索接口
        # POST /dagent/knowledge/retrieve
        async with aiohttp.ClientSession() as session:
            resp = await session.post(
                f"{self.base_url}/dagent/knowledge/retrieve",
                json={"query": query, "knowledge_hub_id": knowledge_hub_id,
                      "top_k": top_k, "org_id": self.org_id},
                headers=self.headers
            )
            data = await resp.json()
        return [RetrievedChunk(**chunk) for chunk in data["chunks"]]

    async def chat(self, query, agent_id, **kwargs):
        # 调用 dagent Agent 对话接口（SSE 流式，解析完整回复）
        # POST /dagent/agent/chat
        ...
```

### 5.3 LLM Judge

```python
# sdk/rag_eval/judge/openai_compatible.py

class OpenAICompatibleJudge(LLMJudge):
    """
    兼容所有 OpenAI 协议的模型：DeepSeek / Qwen / OpenAI / Azure OpenAI
    评判逻辑使用中文 prompt，适合中文 RAG 场景
    """

    def __init__(self, base_url: str, api_key: str, model: str):
        self.client = AsyncOpenAI(base_url=base_url, api_key=api_key)
        self.model = model

    async def score_faithfulness(self, answer: str, context: list[str]) -> float:
        """
        原理：
        1. 让 LLM 把 answer 分解为原子声明列表
        2. 对每条声明，判断是否可从 context 推导
        3. 返回 支持声明数 / 总声明数
        """
        context_text = "\n\n".join(context)

        # Step 1: 分解为原子声明
        decompose_prompt = f"""
请将以下回答分解为独立的原子声明列表，每条声明是一个不可再分的事实陈述。
回答：{answer}
输出格式：JSON 数组，如 ["声明1", "声明2", ...]
"""
        claims = await self._call_json(decompose_prompt)

        # Step 2: 逐条判断是否有 context 支撑
        supported = 0
        for claim in claims:
            verify_prompt = f"""
参考资料：
{context_text}

声明：{claim}

问题：上述声明是否可以从参考资料中推导出来？
只回答 yes 或 no。
"""
            result = await self._call(verify_prompt)
            if "yes" in result.lower():
                supported += 1

        return supported / len(claims) if claims else 0.0

    async def score_relevance(self, question: str, answer: str) -> float:
        """
        原理：
        1. 让 LLM 从 answer 反向生成 N 个问题
        2. 计算这些问题与原 question 的 Embedding 相似度
        3. 返回均值
        """
        ...

    async def score_correctness(self, answer: str, reference: str) -> float:
        """
        原理：LLM 对比 answer 和 reference，给出 0-1 分数
        """
        prompt = f"""
请评估以下回答与参考答案的事实一致程度，给出 0 到 1 之间的分数。
1.0 = 完全一致，0.0 = 完全错误或无关。

参考答案：{reference}
待评估回答：{answer}

只输出一个 0 到 1 之间的小数。
"""
        result = await self._call(prompt)
        return float(result.strip())
```

### 5.4 测试集数据结构

```python
# sdk/rag_eval/dataset/schema.py

@dataclass
class EvalSample:
    id: str
    question: str                        # 测试问题
    reference_answer: str                # 标准参考答案
    relevant_chunk_ids: list[str]        # 标注的相关切片 ID（用于检索层评测）
    knowledge_hub_id: str                # 所属知识库
    source_file_id: str | None = None    # 来源文件（可选）
    metadata: dict = field(default_factory=dict)

@dataclass
class EvalDataset:
    id: str
    name: str
    description: str
    samples: list[EvalSample]
    created_at: datetime
```

### 5.5 SDK 使用示例

```python
from rag_eval import EvalRunner
from rag_eval.adapters import DagentAdapter
from rag_eval.judge import OpenAICompatibleJudge

# 配置适配器（对接 dagent）
adapter = DagentAdapter(
    base_url="http://dagent-backend:8000",
    org_id="org_xxx",
    token="your-token"
)

# 配置 LLM Judge（独立于 dagent，使用 DeepSeek）
judge = OpenAICompatibleJudge(
    base_url="https://api.deepseek.com/v1",
    api_key="sk-xxx",
    model="deepseek-chat"
)

# 运行评测
runner = EvalRunner(adapter=adapter, judge=judge)
report = await runner.run(
    dataset="./my_dataset.json",
    agent_id="agent_xxx",
    knowledge_hub_id="hub_xxx",
    top_k=10,
)

# 查看结果
print(report.summary())
# ┌─────────────────────────────────────────┐
# │           评测报告摘要                    │
# ├──────────────────────┬──────────────────┤
# │ 样本数               │ 200              │
# │ Hit Rate@10          │ 0.87             │
# │ MRR@10               │ 0.72             │
# │ NDCG@10              │ 0.81             │
# │ Context Precision    │ 0.76             │
# │ Context Recall       │ 0.83             │
# │ Faithfulness         │ 0.91             │
# │ Answer Relevance     │ 0.88             │
# │ Answer Correctness   │ 0.79             │
# │ RAG Score            │ 0.84             │
# │ Hallucination Rate   │ 4.5%             │
# └──────────────────────┴──────────────────┘

report.save("./eval_report_20260413.json")
```

---

## 六、测试集构建方案

### 6.1 数据结构

每条测试样本：
```json
{
  "id": "sample_001",
  "question": "什么是向量数据库？",
  "reference_answer": "向量数据库是专门存储和检索高维向量的数据库系统...",
  "relevant_chunk_ids": ["chunk_abc123", "chunk_def456"],
  "knowledge_hub_id": "hub_xxx",
  "source_file_id": "file_yyy"
}
```

### 6.2 构建方式

**方式 A：LLM 自动生成（推荐先用）**

```python
from rag_eval.dataset import DatasetGenerator

generator = DatasetGenerator(judge=judge, adapter=adapter)
dataset = await generator.generate(
    knowledge_hub_id="hub_xxx",
    questions_per_chunk=2,
    question_types=["factual", "reasoning", "comparison", "unanswerable"]
)
# 自动生成问题 + 参考答案 + 标注 relevant_chunk_ids
```

原理：
1. 遍历知识库中所有切片
2. 对每个切片，用 LLM 生成 2-3 个不同类型的问题
3. 用 LLM 基于切片内容生成参考答案
4. 自动标注 `relevant_chunk_ids`（生成来源切片）
5. 建议人工抽检 10-20% 过滤低质量样本

**方式 B：人工标注（质量最高）**

通过 Web UI 提供标注界面：
- 输入问题
- 搜索并标注相关切片
- 填写参考答案

**问题类型覆盖建议**

| 类型 | 示例 | 占比建议 |
|------|------|----------|
| 事实查询 | "X 是什么？" | 40% |
| 多跳推理 | "X 和 Y 的关系是？" | 20% |
| 比较 | "X 和 Y 有什么区别？" | 20% |
| 不可回答 | 文档中不存在的信息 | 10% |
| 摘要 | "总结 X 的主要内容" | 10% |

推荐测试集规模：**200-500 条**，低于 100 条统计意义不足。

---

## 七、Web 端功能规划

| 页面 | 核心功能 |
|------|----------|
| **测试集管理** | 上传 JSON 测试集、LLM 自动生成、人工标注界面、样本预览 |
| **评测任务** | 配置 Adapter（平台连接）、配置 Judge 模型、提交任务、实时进度 |
| **评测报告** | 各指标得分雷达图、样本级别明细表、多次评测趋势对比、问题样本下钻 |
| **配置管理** | 平台连接配置（URL/Token）、Judge 模型配置（API Key/Model）|

---

## 八、数据库设计（Server 端）

```sql
-- 平台连接配置
CREATE TABLE platform_config (
    id          TEXT PRIMARY KEY,
    name        TEXT NOT NULL,
    type        TEXT NOT NULL,          -- 'dagent' | 'custom'
    base_url    TEXT NOT NULL,
    org_id      TEXT,
    token       TEXT,
    created_at  DATETIME
);

-- Judge 模型配置
CREATE TABLE judge_config (
    id          TEXT PRIMARY KEY,
    name        TEXT NOT NULL,
    base_url    TEXT NOT NULL,
    api_key     TEXT NOT NULL,
    model       TEXT NOT NULL,
    created_at  DATETIME
);

-- 测试集
CREATE TABLE eval_dataset (
    id          TEXT PRIMARY KEY,
    name        TEXT NOT NULL,
    description TEXT,
    sample_count INTEGER,
    created_at  DATETIME
);

-- 测试样本
CREATE TABLE eval_sample (
    id                  TEXT PRIMARY KEY,
    dataset_id          TEXT NOT NULL,
    question            TEXT NOT NULL,
    reference_answer    TEXT NOT NULL,
    relevant_chunk_ids  TEXT NOT NULL,   -- JSON array
    knowledge_hub_id    TEXT NOT NULL,
    source_file_id      TEXT,
    metadata            TEXT             -- JSON
);

-- 评测任务
CREATE TABLE eval_task (
    id                  TEXT PRIMARY KEY,
    name                TEXT,
    dataset_id          TEXT NOT NULL,
    platform_config_id  TEXT NOT NULL,
    judge_config_id     TEXT NOT NULL,
    agent_id            TEXT NOT NULL,
    knowledge_hub_id    TEXT NOT NULL,
    top_k               INTEGER DEFAULT 10,
    status              TEXT NOT NULL,   -- pending | running | done | failed
    progress            INTEGER DEFAULT 0,
    created_at          DATETIME,
    finished_at         DATETIME
);

-- 样本级评测结果
CREATE TABLE eval_result (
    id                  TEXT PRIMARY KEY,
    task_id             TEXT NOT NULL,
    sample_id           TEXT NOT NULL,
    retrieved_chunks    TEXT,            -- JSON
    agent_answer        TEXT,
    hit_rate            REAL,
    mrr                 REAL,
    ndcg                REAL,
    context_precision   REAL,
    context_recall      REAL,
    faithfulness        REAL,
    answer_relevance    REAL,
    answer_correctness  REAL,
    judge_detail        TEXT             -- JSON，LLM judge 的推理过程
);

-- 评测汇总报告
CREATE TABLE eval_report (
    id                      TEXT PRIMARY KEY,
    task_id                 TEXT NOT NULL UNIQUE,
    sample_count            INTEGER,
    avg_hit_rate            REAL,
    avg_mrr                 REAL,
    avg_ndcg                REAL,
    avg_context_precision   REAL,
    avg_context_recall      REAL,
    avg_faithfulness        REAL,
    avg_answer_relevance    REAL,
    avg_answer_correctness  REAL,
    rag_score               REAL,
    hallucination_rate      REAL,
    created_at              DATETIME
);
```

---

## 九、开发优先级

| 阶段 | 内容 | 说明 |
|------|------|------|
| **Phase 1** | SDK 核心：Adapter 接口 + 检索评测器 | 无 LLM 依赖，最快验证，Hit Rate/MRR/NDCG |
| **Phase 2** | dagent Adapter 实现 | 对接现有平台 HTTP API |
| **Phase 3** | LLM Judge 模块 | Faithfulness / Relevance / Correctness |
| **Phase 4** | 测试集自动生成器 | 降低标注成本 |
| **Phase 5** | FastAPI Server | 把 SDK 包成 Web 服务，支持异步任务 |
| **Phase 6** | React 前端 | 报告可视化、测试集管理 |

---

## 十、技术选型

| 模块 | 技术 | 理由 |
|------|------|------|
| SDK | Python 3.10+, asyncio, Pydantic | 与 dagent 保持一致，异步支持并发评测 |
| Server | FastAPI + SQLite（开发）/ PostgreSQL（生产） | 轻量，易部署 |
| 任务队列 | asyncio.Queue（轻量）/ Celery（生产） | 评测任务耗时长，需异步执行 |
| Frontend | React + TypeScript + Ant Design | 与 dagent 前端技术栈一致 |
| LLM Judge | OpenAI SDK（兼容 DeepSeek/Qwen） | 统一接口，灵活切换模型 |
| 部署 | Docker Compose | 一键启动 server + frontend |

---

## 十一、与 dagent 平台的集成方式

框架通过 **HTTP API** 调用 dagent，不依赖 dagent 内部代码。

dagent 需要提供（或框架调用现有接口）：

1. **检索接口**：`POST /dagent/knowledge/retrieve`
   - 输入：query, knowledge_hub_id, top_k, org_id
   - 输出：切片列表（chunk_id, content, score, headers, file_id）

2. **对话接口**：`POST /dagent/agent/chat`（现有 SSE 接口）
   - 输入：question, agent_id, org_id
   - 输出：回复文本 + 引用切片信息

如果 dagent 现有接口不完全满足，可在 dagent 侧新增一个**评测专用接口**，返回更详细的检索过程信息（如每个切片的 cosine distance、rerank score 等）。