# RAG Eval 平台技术规格说明书

| 属性 | 内容 |
|------|------|
| 文档版本 | v1.0 |
| 适用代码库 | `rag-eval/` |
| 最后更新 | 2026-05-18 |
| 读者对象 | 后端/前端开发、算法工程师、测试与运维 |
| 关联文档 | [框架设计稿](./rag-eval-framework-design.md)、[14 组分批规则](./循环测试_14组分批规则.md) |

---

## 目录

1. [概述](#1-概述)
2. [系统架构](#2-系统架构)
3. [技术栈与代码组织](#3-技术栈与代码组织)
4. [核心模块设计](#4-核心模块设计)
5. [数据模型](#5-数据模型)
6. [业务流程与时序图](#6-业务流程与时序图)
7. [评测指标体系](#7-评测指标体系)
8. [REST API 概览](#8-rest-api-概览)
9. [前端架构](#9-前端架构)
10. [部署、运维与安全](#10-部署运维与安全)
11. [扩展开发指南](#11-扩展开发指南)

---

## 1. 概述

### 1.1 背景与定位

RAG Eval（RAG Evaluation Framework）是一套**独立于业务 RAG 服务**的评测平台，最初为 **dagent** 知识库与 Agent 能力构建，但通过 `RAGAdapter` 抽象层保持**平台无关**：任何能通过 HTTP 提供「语义检索」与「Agent 对话」能力的系统均可接入。

将评测从生产服务中剥离的设计动机包括：

- **资源隔离**：大批量评测（数万条问答、多轮循环）不占用线上推理配额；
- **技术选型自由**：Judge 模型、Embedding 服务、存储均可独立升级；
- **可复用**：同一套指标与 UI 可对比不同版本 dagent、不同知识库切片策略或竞品 RAG；
- **可自动化**：SDK/CLI 适合接入 CI，在发版前做回归门禁。

### 1.2 设计目标

| 目标 | 实现方式 |
|------|----------|
| 检索 + 生成全链路评测 | `EvalRunner` 编排 retrieve → 规则指标 → chat → LLM Judge |
| 低标注成本 | LLM 自动出题、Faithfulness 等无需 gold chunk |
| 知识库专项能力 | 单跳/多跳召回、循环压测、MD 问答集解析 |
| 人机协作 | Web UI 审核出题、查看 Judge 推理明细 |
| 可观测 | 任务进度、分章节报告、AI 文字解读 |

### 1.3 能力矩阵

平台在「评测深度」与「使用场景」两个维度上提供六类能力：

| 能力 | 典型用户 | 是否依赖 LLM Judge | 主要产出 |
|------|----------|---------------------|----------|
| 综合评测（eval_task） | 算法/质量 | 是（部分指标） | `eval_report`、雷达图 |
| 测试集 LLM 生成 | 数据标注 | 是 | `eval_sample` |
| 单跳召回测试 | 检索工程师 | 否 | 命中率、余弦相似度 |
| 多跳召回测试 | 检索工程师 | 可选 | 分跳命中、全链路命中 |
| QA 生成（qa_gen） | 数据生产 | 是 | `qa_gen_question` |
| 循环测试（loop） | 大规模压测 | 是 | 多轮问答 + 召回验证 |

### 1.4 术语表

| 术语 | 含义 |
|------|------|
| **切片（Chunk）** | 知识库中文档经切分后的最小检索单元，含 `chunk_id`、headers、正文 |
| **单跳（Single-hop）** | 一个问题对应一次检索即可回答 |
| **多跳（Multi-hop）** | 需按跳次（hop）依次检索不同章节/文件 |
| **Judge** | 使用 LLM（及 Embedding）对回答/上下文打分的组件 |
| **Adapter** | 对接外部 RAG 平台的 HTTP 客户端封装 |
| **循环任务（Loop）** | 多轮「生成问答 → 去重 → 单跳验证」的自动化流水线 |
| **任务组 / 批次** | 大规模循环测试时，按每 100 切片一批、每 3 批一组的规划单位 |

---

## 2. 系统架构

### 2.1 逻辑分层架构

系统采用经典三层架构，**评测核心逻辑集中在 Python SDK**，Server 负责持久化、任务调度与 API 暴露，Frontend 负责交互与可视化。

```mermaid
flowchart TB
    subgraph Presentation["表现层"]
        UI["React Web UI<br/>Ant Design + ECharts"]
        CLI["rag-eval CLI"]
    end

    subgraph Application["应用层 (server/)"]
        API["FastAPI Routers<br/>11 模块"]
        SVC["Services<br/>task_service / loop_engine / dedup"]
        DB[("SQLite<br/>aiosqlite + WAL")]
    end

    subgraph Domain["领域层 (sdk/rag_eval/)"]
        RUN["EvalRunner"]
        ADP["RAGAdapter"]
        JUD["LLMJudge"]
        EVA["Retrieval Evaluators"]
        SJ["single_jump / multi_hop"]
        GEN["DatasetGenerator"]
    end

    subgraph External["外部系统"]
        DAG["dagent Platform<br/>semantic_search / agent/chat"]
        LLM["OpenAI 兼容 API<br/>DeepSeek / GPT / Qwen"]
        EMB["Embedding API"]
    end

    UI -->|REST JSON| API
    CLI --> RUN
    API --> SVC
    SVC --> RUN
    SVC --> SJ
    SVC --> DB
    RUN --> ADP
    RUN --> JUD
    RUN --> EVA
    ADP --> DAG
    JUD --> LLM
    JUD --> EMB
    SJ --> DAG
```

**关键设计决策：**

1. **Server 通过 `sys.path.insert` 引用 SDK**，而非将 SDK 发布为独立 wheel 后再依赖——开发迭代快，但部署时需保证 `sdk/` 与 `server/` 目录相对位置固定。
2. **长任务采用「提交后立即返回 + 后台 asyncio 协程」**，状态写入 SQLite，前端轮询进度。
3. **循环任务暂停/恢复**通过进程内 `_loop_controls` 字典 + `asyncio.Event` 实现，多 Worker 部署时需注意状态不共享（当前为单进程假设）。

### 2.2 部署架构

```mermaid
flowchart LR
    subgraph Dev["开发环境"]
        Vite["Vite Dev :5173"]
        Uvicorn["uvicorn :8021"]
        Vite -->|proxy /api| Uvicorn
    end

    subgraph Prod["生产 / Docker"]
        Nginx["nginx :80"]
        FE["frontend/dist 静态资源"]
        BE["uvicorn server:app"]
        SQL[("rag_eval.db")]
        Nginx --> FE
        Nginx -->|/api| BE
        BE --> SQL
        BE -->|挂载| FE2["StaticFiles 可选单端口"]
    end

    BE --> DAGENT["dagent 远程集群"]
    BE --> JUDGE["Judge API"]
```

| 组件 | 默认端口 | 说明 |
|------|----------|------|
| FastAPI | 8021（`main.py`）/ 8003（文档示例） | 开发时常用 8021 |
| Vite | 5173 | 仅开发，`vite.config` 代理 API |
| SQLite 文件 | `server/data/rag_eval.db` | WAL 模式，`busy_timeout=30s` |

### 2.3 与 dagent 的集成边界

```mermaid
flowchart LR
    RE["RAG Eval"]
    RE -->|POST /dagent/knowledge/hub/semantic_search_knowledge/detail| SRCH["语义检索"]
    RE -->|POST /dagent/agent/chat SSE| CHAT["Agent 对话"]
    RE -->|知识库文件列表等| META["元数据 API<br/>qa_gen_dagent 使用"]

    SRCH --> CHUNKS["RetrievedChunk[]"]
    CHAT --> ANSWER["AgentResponse"]
```

`DagentAdapter` **不 import dagent 内部 Python 包**，仅通过 HTTP 契约交互，保证评测框架可独立发版。

---

## 3. 技术栈与代码组织

### 3.1 技术栈

| 层级 | 技术 | 版本策略 |
|------|------|----------|
| 语言 | Python 3.10+ | Server + SDK |
| Web 框架 | FastAPI | 异步路由、OpenAPI |
| 数据库 | SQLite + aiosqlite | 嵌入式，适合单机大规模评测 |
| HTTP 客户端 | aiohttp（Adapter）、httpx/openai（Judge） | 全异步 |
| 前端 | React 18、TypeScript、Vite、Ant Design | SPA |
| 图表 | ECharts（报告雷达图） | — |
| 包管理 | pip（server）、npm（frontend）、Poetry 可选（sdk） | — |

### 3.2 仓库目录详解

```
rag-eval/
├── docs/                              # 文档与数据资产
│   ├── RAG-Eval平台技术规格说明书.md     # 本文档
│   ├── task_groups_plan.json          # 14 组 × 42 批次机器可读规划
│   ├── exports/                       # 全量问答导出
│   └── …
├── sdk/rag_eval/
│   ├── adapters/          base.py, dagent.py
│   ├── judge/             base.py, openai_compatible.py
│   ├── evaluators/        retrieval.py（Hit/MRR/NDCG）
│   ├── dataset/           schema.py, generator.py
│   ├── single_jump/       parser, mapper, tester, report
│   ├── multi_hop/         parser, tester, report
│   ├── runner.py          综合评测编排
│   ├── report.py          EvalReport / SampleResult
│   └── cli.py             run / generate 子命令
├── server/
│   ├── main.py            应用入口、路由注册、静态资源
│   ├── api/               11 个 APIRouter 模块
│   ├── service/           后台任务与循环引擎
│   └── models/            db.py, schema.sql, 轻量迁移
└── frontend/src/
    ├── pages/             Config, Dataset, Task, Report, SingleJump, MultiHop, QaGen
    └── services/api.ts    REST 封装
```

### 3.3 进程内依赖关系

```mermaid
graph TD
    main["server/main.py"] --> api_mod["api/*"]
    main --> loop_eng["service/loop_engine.py"]
    api_mod --> task_svc["service/task_service.py"]
    task_svc --> runner["sdk: EvalRunner"]
    task_svc --> dagent["sdk: DagentAdapter"]
    loop_eng --> qa_api["api/qa_gen 逻辑"]
    loop_eng --> sj_api["api/single_jump 逻辑"]
    runner --> judge["sdk: OpenAICompatibleJudge"]
```

---

## 4. 核心模块设计

### 4.1 RAGAdapter 抽象层

**职责**：屏蔽各 RAG 平台 API 差异，向上提供统一的 `retrieve` 与 `chat`。

```python
# sdk/rag_eval/adapters/base.py（概念接口）
class RAGAdapter(ABC):
    async def retrieve(query, knowledge_hub_id, top_k=10, **kwargs) -> list[RetrievedChunk]
    async def chat(query, agent_id, **kwargs) -> AgentResponse
```

**`RetrievedChunk` 字段：**

| 字段 | 说明 |
|------|------|
| `chunk_id` | 切片唯一 ID（dagent 为 `knowledge_md_header_split_id`） |
| `content` | 正文，用于 Judge 与展示 |
| `score` | 相似度得分（dagent 由 `1 - cosine_distance` 推导） |
| `headers` | 切片标题路径 |
| `file_id` | 所属文件 |

**`DagentAdapter.retrieve` 实现要点：**

- 请求体：`query`, `org_id`, `top_k`, 可选 `knowledge_hub_id`, `file_id_list`
- 合并 `standard_answer_results` 与 `related_knowledge_rerank_results_top` 两路结果后截断至 `top_k`

**`DagentAdapter.chat` 实现要点：**

- SSE 流式解析 `data:` 行，拼接 `message_type` 为 answer 的文本块
- 记录端到端 `latency_ms`

### 4.2 EvalRunner 综合评测编排器

`EvalRunner.run()` 对数据集中每个 `EvalSample`：

1. 受 `asyncio.Semaphore(concurrency)` 限制并发；
2. 按 `RunConfig.should_eval()` 决定计算哪些指标；
3. 检索与生成可独立开关，也支持 `selected_metrics` 精细选择。

**单样本流水线（逻辑顺序）：**

```mermaid
flowchart TD
    A[EvalSample] --> B{need_retrieval?}
    B -->|是| C[adapter.retrieve]
    C --> D{有 relevant_chunk_ids?}
    D -->|是| E[hit_rate / mrr / ndcg]
    C --> F{有 reference_answer?}
    F -->|是| G[Judge: context_precision / recall]
    B -->|否| H{need_generation?}
    E --> H
    G --> H
    H -->|是| I[adapter.chat]
    I --> J{无 retrieved_chunks?}
    J -->|是| K[补一次 retrieve]
    J --> L[Judge: faithfulness / relevance / groundedness / correctness]
    K --> L
    L --> M[SampleResult]
```

**报告聚合：**

- 各指标算术平均（忽略 `None`）；
- **RAG Score** = Faithfulness、Answer Relevance、Context Precision、Context Recall 四者的**调和均值**（任一项偏低则显著拉低总分）；
- **Hallucination Rate** = Faithfulness < `faithfulness_threshold`（默认 0.7）的样本占比。

### 4.3 LLMJudge（OpenAI 兼容实现）

**设计原则**：Prompt 为中文；输出要求 JSON；失败时返回 `(0.0, raw_detail)` 便于排查。

| 方法 | 算法概要 | 输出范围 |
|------|----------|----------|
| `score_faithfulness` | 回答拆声明 → 逐条验证是否可由 context 推出 | 支持声明占比 |
| `score_relevance` | 由回答反推 3 个问题 → 与原始问题 Embedding 相似度均值 | 0–1 |
| `score_correctness` | 与 reference 的事实一致性 JSON 评分 | 0–1 |
| `score_groundedness` | 声明级标注来源切片编号 | 有源声明占比 |
| `score_context_precision` | 逐 chunk 判定是否对答题有用 | useful/(total) |
| `score_context_recall` | 参考答案拆陈述 → 是否在检索文中被支持 | supported/total |

Faithfulness 两步法降低单次长上下文 Judge 的不稳定性，但会增加 LLM 调用次数（约 1 + N 次 claim 验证）。

### 4.4 单跳召回模块（single_jump）

| 子模块 | 职责 |
|--------|------|
| `parser.py` | 解析 MD：`# 章` → `## section_path` → `Qn` / `**An:**` |
| `mapper.py` | `section_path` 模糊匹配知识库 `file_id`（exact/contains/fuzzy） |
| `tester.py` | 并发调用 dagent 检索 API，写 `RecallResult` |
| `report.py` | 汇总召回率、文件命中率、章节匹配率 |

**命中判定**：在 `hit_top_k` 范围内检查 `expected_chunk_id` 或 `file_id` 是否出现在召回列表。

### 4.5 多跳召回模块（multi_hop）

解析带 `type`、`hops[]` 的多跳问答 MD；对每一跳构造检索 query，分别召回并合并去重；支持 Agent 最终回答与分跳贡献分析。详见 [multi-hop-example.md](./multi-hop-example.md)。

### 4.6 循环引擎（loop_engine）

**目标**：对指定 `file_ids` 列表，在多轮中持续生成不重复问答并用单跳召回验证质量，直至达到 `max_rounds` / `max_questions` 或连续空轮。

**单轮阶段：**

```mermaid
stateDiagram-v2
    [*] --> FetchExisting: 新一轮开始
    FetchExisting --> QaGen: 拉取历史已批准题
    QaGen --> Dedup: LLM 出题 + 质量分
    Dedup --> SingleJump: Embedding 向量去重
    SingleJump --> WaitComplete: 创建单跳任务
    WaitComplete --> UpdateStats: 轮询完成
    UpdateStats --> CheckTerminate: 更新 loop_round
    CheckTerminate --> FetchExisting: 未终止
    CheckTerminate --> [*]: 达到上限或 stop
```

**控制面：**

| 操作 | 机制 |
|------|------|
| 暂停 | `pause_event.clear()` + DB `status=paused` |
| 恢复 | `pause_event.set()` |
| 停止 | `stop=True` + DB `status=stopped` |
| 孤儿恢复 | 启动时 `recover_orphaned_loops()` 将异常退出时的 `running` 改为 `paused` |

### 4.7 去重服务（dedup）

循环任务中默认使用 **Embedding 余弦相似度**（非 LLM）在 section 内及全局（`global_dedup`）检测重复题，阈值可配。历史题目从 `qa_gen_question` 表加载，支持跨任务全局去重以应对 14 组 42 批次大规模跑数。

---

## 5. 数据模型

### 5.1 ER 关系概览

```mermaid
erDiagram
    platform_config ||--o{ eval_task : uses
    judge_config ||--o{ eval_task : uses
    eval_dataset ||--o{ eval_sample : contains
    eval_dataset ||--o{ eval_task : ""
    eval_task ||--o{ eval_result : produces
    eval_task ||--|| eval_report : summarizes

    loop_task ||--o{ loop_round : has
    loop_round }o--|| qa_gen_task : links
    loop_round }o--|| single_jump_task : links
    qa_gen_task ||--o{ qa_gen_question : contains
    single_jump_task ||--o{ single_jump_result : contains

    multi_hop_task ||--o{ multi_hop_result : contains
    multi_hop_gen_task ||--o{ multi_hop_gen_question : contains
    prompt_template ||--o{ qa_gen_task : optional
```

### 5.2 核心表说明

| 表名 | 用途 | 关键字段 |
|------|------|----------|
| `platform_config` | dagent 连接信息 | `base_url`, `org_id`, `token` |
| `judge_config` | Judge + Embedding | `model`, `embed_model` |
| `eval_dataset` / `eval_sample` | 综合评测数据集 | `relevant_chunk_ids` JSON |
| `eval_task` / `eval_result` / `eval_report` | 综合评测任务与结果 | `status`, `progress`, 各指标均值 |
| `single_jump_task` / `single_jump_result` | 单跳召回 | `retrieved` JSON, `is_file_hit` |
| `multi_hop_task` / `multi_hop_result` | 多跳召回 | `hops`, `actual_hops` JSON |
| `qa_gen_task` / `qa_gen_question` | 出题与审核 | `status`, `embedding`, `chunk_id` |
| `loop_task` / `loop_round` | 循环压测 | `current_round`, 累计统计字段 |
| `multi_hop_gen_task` | 多跳 QA 生成 | `source` file/dagent |
| `prompt_template` | Prompt 管理 | `content` |

### 5.3 任务状态机（综合评测）

```mermaid
stateDiagram-v2
    [*] --> pending: 创建任务
    pending --> running: 后台开始
    running --> done: EvalRunner 成功
    running --> failed: 异常
    done --> [*]
    failed --> [*]
```

### 5.4 迁移策略

`models/db.py` 中 `_run_migrations()` 对已有库做**向前兼容**列追加（`PRAGMA table_info` 检测），避免破坏已有 `rag_eval.db`。新环境执行 `schema.sql` 全量建表。

---

## 6. 业务流程与时序图

### 6.1 综合评测任务（Web → Server → SDK）

```mermaid
sequenceDiagram
    autonumber
    actor User as 用户
    participant UI as React UI
    participant API as task.py
    participant SVC as task_service
    participant DB as SQLite
    participant RUN as EvalRunner
    participant ADP as DagentAdapter
    participant JUD as LLMJudge
    participant DG as dagent

    User->>UI: 新建评测任务
    UI->>API: POST /api/task/run
    API->>DB: INSERT eval_task (pending)
    API-->>UI: task_id
    API->>SVC: asyncio.create_task(run_eval_task)

    SVC->>DB: status=running
    SVC->>DB: 加载 dataset / configs
    SVC->>RUN: run(dataset, RunConfig)

    loop 每个 EvalSample（并发 N）
        RUN->>ADP: retrieve(question)
        ADP->>DG: semantic_search
        DG-->>ADP: chunks
        RUN->>JUD: context_precision / recall
        JUD-->>RUN: scores
        RUN->>ADP: chat(question)
        ADP->>DG: agent/chat SSE
        DG-->>ADP: answer stream
        RUN->>JUD: faithfulness / relevance / ...
        RUN->>DB: INSERT eval_result（批量或逐条）
    end

    RUN-->>SVC: EvalReport
    SVC->>JUD: 生成 interpretation 文案
    SVC->>DB: INSERT eval_report, status=done
    UI->>API: GET /api/report/{task_id}
    API-->>UI: 雷达图 + 明细
```

### 6.2 Faithfulness 评判（两步法）

```mermaid
sequenceDiagram
    participant RUN as EvalRunner
    participant JUD as OpenAICompatibleJudge
    participant LLM as Judge LLM

    RUN->>JUD: score_faithfulness(answer, contexts)
    JUD->>LLM: Prompt: 分解为原子声明 JSON
    LLM-->>JUD: ["声明1", "声明2", ...]
    loop 每条声明
        JUD->>LLM: Prompt: 声明是否可由资料推出 yes/no
        LLM-->>JUD: yes | no
    end
    JUD-->>RUN: score = supported_count / total_claims
```

### 6.3 单跳召回测试

```mermaid
sequenceDiagram
    actor User as 用户
    participant API as single_jump.py
    participant P as MD Parser
    participant M as FileMapper
    participant T as SingleJumpTester
    participant DG as dagent

    User->>API: POST /api/single-jump/task (multipart MD)
    API->>P: parse(md_content)
    P-->>API: sections[] + qa_pairs[]
    API->>M: map(section_path → file_id)
    M->>DG: 文件列表 / 路径匹配
    API->>DB: INSERT task + results (pending)

    loop 每条 QA（并发）
        T->>DG: semantic_search(question)
        DG-->>T: retrieved[]
        T->>T: 计算 is_file_hit, chunk_hit, cosine_sim
        T->>DB: UPDATE single_jump_result
    end

    API->>DB: task status=done
    User->>API: GET summary / results
```

### 6.4 循环测试（单轮）

```mermaid
sequenceDiagram
    participant LE as loop_engine
    participant DB as SQLite
    participant QG as qa_gen 流程
    participant DD as dedup
    participant SJ as single_jump 流程
    participant DG as dagent

    LE->>DB: 读取 loop_task / 历史轮次
    LE->>DB: 汇总已批准问题（可选 global_dedup）
    LE->>QG: 按 file_ids 拉切片 → LLM 出题
    QG->>DB: qa_gen_question (pending)
    LE->>DD: Embedding 相似度过滤
    DD->>DB: status=approved | rejected
    LE->>SJ: 生成 MD → 创建 single_jump_task
    SJ->>DG: 批量检索
  SJ->>DB: single_jump_result
    LE->>DB: 更新 loop_round 统计
    LE->>LE: 检查 max_rounds / max_questions / stop
```

### 6.5 LLM 自动出题（测试集 / qa_gen）

```mermaid
sequenceDiagram
    participant API as dataset.py / qa_gen.py
    participant GEN as DatasetGenerator
    participant ADP as DagentAdapter
    participant JUD as LLMJudge
    participant DG as dagent

    API->>ADP: 获取文件切片列表
    ADP->>DG: 知识库 API
    loop 每个切片
        GEN->>JUD: 根据 chunk 内容生成 Q&A
        JUD-->>GEN: question + answer
        GEN->>JUD: quality_score 评估
    end
    GEN->>API: EvalSample[] 或 qa_gen_question
    API->>DB: 持久化
```

### 6.6 配置管理流程

```mermaid
sequenceDiagram
    actor User as 用户
    participant UI as Config 页面
    participant API as config.py
    participant DB as SQLite

    User->>UI: 添加平台配置 / Judge 配置
    UI->>API: POST /api/config/platform | /judge
    API->>DB: INSERT（API Key 明文存库，需注意权限）
    API-->>UI: config_id
    Note over UI,DB: 后续所有任务通过 config_id 引用
```

---

## 7. 评测指标体系

### 7.1 检索层（规则指标）

设召回序列为 $[c_1, \ldots, c_K]$，相关集合为 $R$。

| 指标 | 公式 / 定义 | 需要标注 |
|------|-------------|----------|
| **Hit Rate@K** | 若 $R \cap \{c_1..c_K\} \neq \emptyset$ 则为 1，否则 0 | `relevant_chunk_ids` |
| **MRR@K** | $\frac{1}{\text{rank}}$，rank 为第一个相关 chunk 的位置 | 同上 |
| **NDCG@K** | 按相关度折损的 DCG 归一化 | 同上，实现见 `evaluators/retrieval.py` |

### 7.2 检索层（LLM 指标）

| 指标 | 含义 | 典型问题 |
|------|------|----------|
| **Context Precision** | 召回切片中有多少比例对回答真正有用 | 噪声切片多 → 低 |
| **Context Recall** | 参考答案中的事实有多少能在召回中找到 | 切片不全 → 低 |

### 7.3 生成层

| 指标 | 含义 | 低分常见原因 |
|------|------|--------------|
| **Faithfulness** | 回答是否可仅从检索内容推出 | 幻觉、过度推断 |
| **Answer Relevance** | 回答是否切题 | 答非所问、冗长 |
| **Answer Correctness** | 与参考答案事实一致性 | 错误细节 |
| **Groundedness** | 声明是否有明确切片来源 | 无出处断言 |

### 7.4 综合指标

**RAG Score（调和均值）：**

$$
\text{RAG Score} = \frac{n}{\sum_{i=1}^{n} \frac{1}{s_i}}
$$

其中 $s_i$ 为 Faithfulness、Answer Relevance、Context Precision、Context Recall 中非空且 $>0$ 的项。

**Hallucination Rate：**

$$
\text{Hallucination Rate} = \frac{|\{i : \text{faithfulness}_i < \tau\}|}{n}, \quad \tau = 0.7
$$

### 7.5 单跳召回专用指标

| 指标 | 计算 |
|------|------|
| 召回率 | 有检索结果的问题数 / 总问题数 |
| 文件命中率 | `is_file_hit=1` / 有检索结果数 |
| 切片命中率 | `expected_chunk_id` 出现在 top-K |
| 平均余弦相似度 | 召回列表 $1 - \text{cosine\_distance}$ 的统计 |
| 章节匹配率 | 成功映射 file_id 的 section 数 / 总 section 数 |

### 7.6 指标解读阈值（建议）

| 指标 | 优秀 | 良好 | 需关注 |
|------|------|------|--------|
| Hit Rate | > 0.90 | 0.70–0.90 | < 0.70 |
| MRR | > 0.80 | 0.60–0.80 | < 0.60 |
| Faithfulness | > 0.85 | 0.70–0.85 | < 0.70 |
| RAG Score | > 0.80 | 0.65–0.80 | < 0.65 |
| Hallucination Rate | < 5% | 5–15% | > 15% |

---

## 8. REST API 概览

所有路由前缀为 `/api`。下表为模块级索引，完整参数见 Swagger `/docs`。

| 前缀 | 模块文件 | 职责 |
|------|----------|------|
| `/api/config` | `config.py` | 平台 / Judge CRUD |
| `/api/dataset` | `dataset.py` | 数据集、样本、导入、LLM 生成 |
| `/api/task` | `task.py` | 综合评测任务 |
| `/api/report` | `report.py` | 报告与样本明细 |
| `/api/single-jump` | `single_jump.py` | 单跳任务与结果 |
| `/api/multi-hop` | `multi_hop.py` | 多跳任务 |
| `/api/qa-gen` | `qa_gen.py` + `qa_gen_dagent.py` | 出题（文件 / dagent 数据源） |
| `/api/multi-hop-gen` | `multi_hop_gen.py` | 多跳 QA 生成 |
| `/api/loop` | `loop.py` | 循环任务、暂停/恢复、导出 |
| `/api/prompt-template` | `prompt_template.py` | Prompt CRUD |
| `/api/health` | `main.py` | 健康检查 |

**异步任务通用约定：**

- 创建接口返回 `task_id`；
- `GET .../task/{id}` 含 `status`, `progress`, `total`, `error_message`；
- 完成后通过 report 或 export 接口拉取结果。

---

## 9. 前端架构

### 9.1 路由与页面

| 路径 | 页面 | 功能 |
|------|------|------|
| `/config` | Config | 平台 / Judge 配置 |
| `/dataset` | Dataset | 列表、详情、导入、生成 |
| `/task` | Task | 创建综合评测 |
| `/report/:taskId` | Report | 雷达图、明细、Judge 下钻 |
| `/single-jump` | SingleJump | 上传 MD、进度、分章节报告 |
| `/multi-hop` | MultiHop | 多跳测试 |
| `/qa-gen` | QaGen | 出题任务与审核 |

### 9.2 数据流

```mermaid
flowchart LR
    Pages["pages/*"] --> API["services/api.ts"]
    API --> HTTP["services/http.ts<br/>axios baseURL=/api"]
    HTTP --> BE["FastAPI"]
```

开发模式 Vite 将 `/api` 代理至 `http://127.0.0.1:8021`；生产构建后由同源 FastAPI 或 nginx 转发。

### 9.3 报告可视化

`Report` 页使用 ECharts 雷达图展示各维度均值；表格列出 `eval_result` 逐条指标；Modal 展示 `judge_detail` JSON 供人工复核 LLM 评判理由。

---

## 10. 部署、运维与安全

### 10.1 Docker Compose

`docker-compose.yml` 定义 `server` 与 `frontend` 服务；`Dockerfile.server` 安装 Python 依赖并启动 uvicorn；`Dockerfile.frontend` 多阶段构建静态资源。

### 10.2 数据备份

- **核心资产**：`server/data/rag_eval.db`（循环测试后可达数 GB）；
- **导出副本**：`docs/exports/` 下 MD/JSON；
- **规划文件**：`docs/task_groups_plan.json`。

建议定期备份 DB 与 exports，避免仅依赖单机 SQLite。

### 10.3 性能调优

| 旋钮 | 位置 | 说明 |
|------|------|------|
| `concurrency` | `RunConfig` / 任务表单 | 增大可加速，受 dagent/Judge 限流约束 |
| `top_k` | 检索配置 | 影响检索耗时与 Context 指标 |
| SQLite WAL | `db.py` | 已启用，避免长事务锁库 |
| 循环 `global_dedup` | loop 创建参数 | 真时跨任务查重 SQL 较重 |

### 10.4 安全注意

- `judge_config.api_key` 存于 SQLite **明文**，需限制 DB 文件权限；
- CORS 当前为 `allow_origins=["*"]`，公网部署应收紧；
- 导出脚本与 API 可能含完整问答与切片内容，注意数据分级。

### 10.5 运维脚本

| 脚本 | 用途 |
|------|------|
| `server/scripts/export_loop_all_groups.py` | 从 DB 导出 14 组全量问答 |
| `server/scripts/batch_create_tasks.py` | 批量创建循环任务 |
| `server/scripts/export_loop_batches_recall_md.py` | 导出召回 MD |

---

## 11. 扩展开发指南

### 11.1 新增 RAG 平台 Adapter

1. 在 `sdk/rag_eval/adapters/` 新建 `my_platform.py`；
2. 实现 `retrieve` / `chat`，映射为 `RetrievedChunk` / `AgentResponse`；
3. 在 `platform_config.type` 增加枚举，Server 侧 `task_service` 按 type 实例化。

### 11.2 新增评测指标

1. 在 `LLMJudge` 增加 `score_xxx` 方法；
2. `EvalRunner._eval_sample` 中调用；
3. `SampleResult` / `eval_result` 表增加列 + 迁移；
4. 前端 Report 增加展示卡片。

### 11.3 新增 API 模块

1. `server/api/` 新建路由文件；
2. `main.py` `include_router`；
3. `frontend/services/api.ts` 增加客户端方法。

### 11.4 测试建议

- **单元测试**：`evaluators/retrieval.py` 规则指标边界；`parser.py` MD 样例；
- **集成测试**：Mock dagent HTTP，跑通 `EvalRunner` 单样本；
- **回归**：固定小数据集 + Judge 模型版本记录在报告中。

---

## 12. 数据库字段字典（详表）

本章列出主要表的字段语义，便于写 SQL 报表、对接 BI 或二次开发。JSON 列在 SQLite 中以 `TEXT` 存储，应用层 `json.loads` 解析。

### 12.1 platform_config

| 字段 | 类型 | 说明 |
|------|------|------|
| id | TEXT PK | UUID hex |
| name | TEXT | 展示名称，如「dagent 生产」 |
| type | TEXT | 默认 `dagent`，预留其他 Adapter |
| base_url | TEXT | 如 `https://dagent.d-robotics.cc` |
| org_id | TEXT | 组织 ID，检索与对话必传 |
| token | TEXT | 可选 Bearer Token |
| created_at | TEXT | ISO 时间戳 |

### 12.2 judge_config

| 字段 | 类型 | 说明 |
|------|------|------|
| embed_base_url | TEXT | 为空则回退 base_url |
| embed_api_key | TEXT | 为空则回退 api_key |
| embed_model | TEXT | 去重与 Answer Relevance 使用 |

### 12.3 eval_sample

| 字段 | 类型 | 说明 |
|------|------|------|
| relevant_chunk_ids | TEXT | JSON 数组，Hit/MRR/NDCG 必需 |
| knowledge_hub_id | TEXT | 样本级 hub，可与任务级叠加 |
| source_file_id | TEXT | 可选，追溯出题文件 |
| metadata | TEXT | 扩展 JSON |

### 12.4 eval_task

| 字段 | 类型 | 说明 |
|------|------|------|
| eval_retrieval | INTEGER | 1/0，与 selected_metrics 二选一逻辑在 RunConfig |
| eval_generation | INTEGER | 1/0 |
| selected_metrics | TEXT | JSON 数组，非空时覆盖上述开关 |
| file_id_list | TEXT | 检索时限制文件范围 |
| concurrency | INTEGER | 默认 3 |
| progress / total | INTEGER | 已完成样本数 / 总样本数 |

### 12.5 eval_result

逐样本存储完整评判：`retrieved_chunks` 为正文数组 JSON；`judge_detail` 为各 LLM 指标原始返回，供 UI 下钻。

### 12.6 single_jump_result

| 字段 | 说明 |
|------|------|
| retrieved | 原始 dagent 返回 JSON 数组，保留 `cosine_distance_1` |
| is_file_hit | 预期 file_id 是否出现在召回列表 |
| is_chunk_hit | expected_chunk_id 是否在 hit_top_k 内 |
| chunk_hit_rank | 命中时排名，从 1 起 |
| raw_chunk_headers | 用于与 qa_gen 的 chunk_headers 对齐展示 |

### 12.7 qa_gen_question

| 字段 | 说明 |
|------|------|
| status | pending / approved / rejected |
| dup_of | 若重复，指向主题库中已有题 id |
| dup_similarity | 向量相似度 |
| embedding | 存 JSON 向量，去重用 |
| chunk_content_preview | 前 500 字，审核时免查库 |

### 12.8 loop_task

累计字段 `total_generated`、`total_approved`、`total_recalled`、`total_file_hit` 等由引擎每轮刷新；`expected_chunk_count` 与分批规划对齐，用于校验从 dagent 拉取的切片数量是否完整。`global_dedup=1` 时去重范围扩大到全部已批准题目。

### 12.9 loop_round

每轮关联 `qa_gen_task_id` 与 `single_jump_task_id`，`status` 跟踪本轮是进行中还是已完成，便于服务重启后从断点阶段继续。

---

## 13. REST API 端点详解

以下按模块列出常用端点；HTTP 方法后的路径均相对于 `/api`。

### 13.1 配置 `/config`

| 方法 | 路径 | 说明 |
|------|------|------|
| GET | `/config/platform` | 列表 |
| POST | `/config/platform` | 创建，body: name, base_url, org_id, token? |
| DELETE | `/config/platform/{id}` | 删除 |
| GET | `/config/judge` | Judge 列表 |
| POST | `/config/judge` | 创建 Judge + Embedding 配置 |

### 13.2 数据集 `/dataset`

| 方法 | 路径 | 说明 |
|------|------|------|
| GET | `/dataset/list` | 所有数据集 |
| GET | `/dataset/{id}` | 含样本列表 |
| POST | `/dataset/create` | name, description |
| POST | `/dataset/sample/add` | 单条样本 |
| POST | `/dataset/import` | multipart JSON 文件 |
| POST | `/dataset/generate` | 触发 LLM 生成，返回 generate_task_id |
| GET | `/dataset/generate/{id}` | 生成进度 |
| GET | `/dataset/chunks-preview` | 预览 hub 下切片规模 |

### 13.3 评测任务 `/task` 与报告 `/report`

| 方法 | 路径 | 说明 |
|------|------|------|
| POST | `/task/run` | 创建并异步执行 eval_task |
| GET | `/task/list` | 任务列表含 status、progress |
| GET | `/report/{task_id}` | 聚合指标 + interpretation |
| GET | `/report/{task_id}/items` | 分页样本明细 |

### 13.4 单跳 `/single-jump`

| 方法 | 路径 | 说明 |
|------|------|------|
| POST | `/single-jump/task` | Form: env_url, org_id, md_file, top_k, agent_id… |
| POST | `/single-jump/task/batch` | 批量文件 |
| GET | `/single-jump/task/{id}/summary` | 汇总指标 |
| GET | `/single-jump/task/{id}/sections` | 章节树 |
| GET | `/single-jump/task/{id}/results` | ?section= 过滤 |
| GET | `/single-jump/task/{id}/export-failed-md` | 导出失败题为 MD |

### 13.5 循环 `/loop`

| 方法 | 路径 | 说明 |
|------|------|------|
| POST | `/loop/task` | Form 创建循环任务 |
| POST | `/loop/task/{id}/pause` | 暂停 |
| POST | `/loop/task/{id}/resume` | 恢复 |
| POST | `/loop/task/{id}/stop` | 停止 |
| GET | `/loop/task/{id}/export` | ?format=md\|json&category=all\|hit\|… |

### 13.6 问题生成 `/qa-gen`

`qa_gen.py` 与 `qa_gen_dagent.py` **共享前缀** `/api/qa-gen`：前者上传 MD/文件列表出题，后者从 dagent 拉取目录树与切片。注意路由注册顺序避免路径冲突。

| 能力 | 端点示例 |
|------|----------|
| dagent 文件树 | GET `/qa-gen/dagent/tree?org_id=` |
| 创建出题任务 | POST `/qa-gen/task/from-dagent` |
| 审核 | POST `/qa-gen/question/{id}/approve` |

---

## 14. 循环引擎深度解析

### 14.1 启动与断点续跑

`run_loop_task` 被 `asyncio.create_task` 调用后立即返回。引擎启动时查询 `loop_round` 最后一条记录：

- 若上一轮 `single_jump` 未完成，则继续等待或重试；
- 若已完成且未达终止条件，则 `current_round += 1` 并新建 `loop_round` 行。

服务崩溃后，`recover_orphaned_loops` 将 `status=running` 改为 `paused`，人工确认后调 resume。

### 14.2 单轮各阶段耗时分布

```mermaid
gantt
    title 典型单轮耗时构成（示意）
    dateFormat X
    axisFormat %s
    section 出题
    拉切片与LLM生成     :a1, 0, 40
    section 去重
    Embedding批量比对   :a2, after a1, 15
    section 召回
    单跳并发检索        :a3, after a2, 30
```

实际占比取决于 `concurrency`、切片数、Judge 模型速度及 dagent 集群负载。组 1 批次 1 在远程环境上常见数千条 approved 题，单轮可能持续数十分钟。

### 14.3 终止条件

| 条件 | 行为 |
|------|------|
| `max_rounds > 0` 且达到 | 正常结束 |
| `max_questions > 0` 且累计 approved 达到 | 正常结束 |
| 连续若干轮无新 approved | 可配置空轮退出（引擎内 consecutive_empty_rounds） |
| 用户 stop | 立即写 stopped |
| 异常 | status=failed，error_message 记录栈信息 |

### 14.4 与单跳模块的协作

循环引擎不直接调用 `SingleJumpTester` 类，而是通过内部函数或 API 层复用「生成 MD → 创建 task → 轮询完成」流程，保证与手动单跳使用同一套解析与命中逻辑，避免统计口径不一致。

---

## 15. 单跳 MD 格式与 FileMapper

### 15.1 MD 结构约定

```markdown
# 第1章 章节展示标题

## path/to/file.md / doc_name
> 原始切片标题: 完整 headers 路径
# 1. doc_name_Document
> 由 LLM 自动生成的问答对

## Q1: 问题正文？

**A1:** 参考答案正文

> chunk_id: abc123...
```

- `# 第N章`：人类可读章节名；
- `##` 行：与 `FileMapper` 键一致，通常为 `file_name / doc_name`；
- `Q`/`A` 编号：解析器正则提取；
- 可选 `chunk_id` 行：用于切片级命中。

`loop_recall_md.py` 与 `single_jump/parser.py` 共用同一套生成规则，保证「循环内导出 → 再导入单跳」不丢字段。

### 15.2 FileMapper 匹配策略

```mermaid
flowchart TD
    SP[section_path 来自 MD] --> E{精确匹配 file_path?}
    E -->|是| OK[file_id]
    E -->|否| C{路径包含?}
    C -->|是| OK
    C -->|否| F[模糊相似度]
    F -->|高于阈值| OK
    F -->|否| MISS[unmatched]
```

未匹配章节仍参与召回测试，但 `is_file_hit` 统计为未命中文件；报告中的「章节匹配率」帮助发现路径规范问题。

---

## 16. LLM Judge 调用链与成本

### 16.1 单样本 Judge 调用次数估算

设回答被拆为 $N$ 条声明，检索上下文分为 $K$ 个 chunk：

| 指标 | 约 LLM 次数 |
|------|-------------|
| Faithfulness | $1 + N$ |
| Groundedness | 1 |
| Context Precision | 1 |
| Context Recall | 1 |
| Answer Correctness | 1 |
| Answer Relevance | 1 + 3 次 embedding |

综合评测全开时，单样本可达 **10+ 次** LLM 调用。批量任务应合理设置 `concurrency` 与 `selected_metrics`，避免 Judge API 限流。

### 16.2 Prompt 语言与 JSON 解析

所有 Prompt 为中文指令，要求模型**仅输出 JSON**。`OpenAICompatibleJudge` 对返回做 `json.loads`，失败时捕获异常并将 raw 文本写入 `judge_detail` 便于排查。生产环境建议选用 JSON 遵循能力较强的模型（如 GPT-4o、DeepSeek-V3）。

### 16.3 Embedding 用途

- **Answer Relevance**：回答 → 生成 3 个假设问题 → 与原始问题做 cosine；
- **循环去重**：approved 题的 question 字段向量与新区块比对；
- 二者共用 `judge_config` 中的 embed 三元组，可与 chat 模型异构部署。

---

## 17. 前端页面交互说明

### 17.1 测试集页

支持三种来源并列：表格手动新增、上传 JSON、侧栏触发「LLM 生成」并轮询 `generate_task`。详情页展示样本字段，可编辑 `relevant_chunk_ids`（JSON 文本框）。

### 17.2 评测任务页

表单字段与 `eval_task` 表一一对应；提交后列表展示进度条 `progress/total`；完成后跳转 Report。删除任务不级联删除 report 时需确认实现（当前以实现为准）。

### 17.3 单跳报告页

左侧章节树，右侧问题列表；支持按 section 筛选、查看每条 retrieved JSON、导出未命中 MD。颜色区分 file_hit / chunk_hit / 空召回。

### 17.4 问题生成页

Tab 区分「文件上传」与「dagent 数据源」；dagent 模式先加载文件树勾选 file_ids；问题表支持 approve/reject、编辑 Q/A；embedding 去重结果展示 dup_similarity。

---

## 18. 故障排查手册

| 现象 | 可能原因 | 处理 |
|------|----------|------|
| 任务长期 running | 后台协程异常退出未写库 | 查 server 日志；手动改 status |
| Judge 全 0 分 | API Key 无效或 JSON 解析失败 | 查 judge_detail 原始返回 |
| Hit Rate 全空 | 未填 relevant_chunk_ids | 补标注或关闭规则指标 |
| 单跳章节全 unmatched | file 路径与知识库不一致 | 检查 MD `##` 行与 dagent 路径 |
| 循环任务暂停无法恢复 | 进程重启后 _loop_controls 丢失 | 仅支持同进程 resume；否则新起任务 |
| SQLite database locked | 并发写冲突 | 已设 busy_timeout；避免多进程写同一库 |
| 导出 OOM | 一次加载百万级 JSON | 使用 export_loop_all_groups 按批次导出 |
| dagent 429 | 并发过高 | 降低 concurrency |

### 18.1 日志位置

开发时 uvicorn 标准输出；历史曾写入根目录 `server*.log`（已清理）。生产建议配置结构化日志到文件或 ELK。

---

## 19. dagent 远程集成实践

### 19.1 环境划分

| 环境 | 用途 |
|------|------|
| dagent-dev | 功能联调 |
| dagent.d-robotics.cc | 14 组循环生产数据所在 |

`platform_config` 与 `loop_task.env_url` 应指向被测环境，避免 dev 数据写入生产库统计。

### 19.2 跨切片模式（cross_chunk）

当前部分 dagent 版本不支持检索 API 的 `file_id_list` 过滤，单跳与循环建议 **cross_chunk=true**，在更大池中检索后再用 `is_file_hit` 判断文件是否正确。这与「限定文件内检索」的理想实验设置不同，报告解读时需注明。

### 19.3 大规模跑数建议

1. 按 [task_groups_plan.json](./task_groups_plan.json) 分批，每批 100 切片；
2. 组间并行度受 Judge 与 dagent 配额限制，建议组内顺序、组间适度并行；
3. 每批完成后执行 `export_loop_all_groups.py` 或 API export 做冷备；
4. `rag_eval.db` 体积膨胀后 VACUUM 需停机维护。

### 19.4 问答集资产用途

`docs/exports/` 下 23 万+ 题可用于：检索离线评测、训练数据构造、Bad Case 分析、版本回归对比。JSON 行内含 `chunk_id` 可回连 dagent 切片。

---

## 20. SDK CLI 与配置参考

### 20.1 命令行

```bash
rag-eval generate --config config.yaml --output dataset.json
rag-eval run --config config.yaml --dataset dataset.json --output report.json
```

`config.yaml` 结构见 `docs/config.example.yaml`：含 `platform`、`judge`、`agent_id`、`knowledge_hub_id`、`top_k`、`concurrency` 等。

### 20.2 编程式调用

Server 与 CLI 均依赖同一 `EvalRunner`，保证指标口径一致。自定义 `progress_cb` 可在 CI 中打印进度条。

```mermaid
sequenceDiagram
    participant CI as CI Pipeline
    participant CLI as rag-eval CLI
    participant RUN as EvalRunner
    participant ADP as Adapter

    CI->>CLI: run dataset.json
    CLI->>RUN: run(config)
    RUN->>ADP: retrieve + chat
    RUN-->>CLI: report.json
    CI->>CI: 阈值门禁 RAG Score > 0.75
```

---

## 21. 多跳召回与多跳出题（技术说明）

### 21.1 多跳问题模型

多跳样本除 `question`、`answer` 外，核心结构为 `hops[]`：每一跳描述一个子问题、期望检索的 `section_path` / `file_id`，以及该跳对最终答案的贡献权重。评测时引擎按跳次顺序调用检索 API，记录每跳 top-K 结果，再合并为 `retrieved` 全集用于兼容旧版统计。

**全链路命中（full_hit）**：所有期望跳的文件或切片均命中；**部分命中（partial_hit）**：至少一跳命中。与单跳相比，多跳更考察知识库跨文档关联能力。

### 21.2 多跳与 Agent 回答

若配置 `agent_id` 与 `judge_config_id`，在分跳检索完成后可调用 Agent 生成最终答案，并由 Judge 评判与标准答案的一致性。该路径同时消耗检索与对话配额，适合端到端 RAG 演示而非纯检索压测。

### 21.3 multi_hop_gen

`multi_hop_gen_task` 支持 `source=file`（上传结构化工单）或 `source=dagent`（按 org 拉目录）。`hops_per_question` 控制每题跳数，`questions_per_group` 控制每组生成数量。生成结果存入 `multi_hop_gen_question`，经人工审核后可导出为多跳 MD 再回流多跳召回测试。

```mermaid
flowchart LR
    GEN[multi_hop_gen] --> MD[多跳 MD]
    MD --> MH[multi_hop 测试]
    MH --> RPT[分跳命中报告]
```

---

## 22. DatasetGenerator 与测试集自动生成

### 22.1 流程

`DatasetGenerator` 接收 `file_id_list`，通过 Adapter 拉取每个文件的切片列表。对每个切片：

1. 将切片正文（及可选图片多模态描述）填入出题 Prompt；
2. 调用 Judge LLM 生成「问题 + 参考答案」；
3. 二次调用质量评估 Prompt，低于 `quality_threshold` 的丢弃；
4. 写入 `eval_sample` 或仅返回内存对象。

### 22.2 与综合评测的衔接

Web UI 的「LLM 自动生成」创建 `generate_task` 异步任务，完成后样本落入指定 `eval_dataset`。用户可人工删改再启动 `eval_task`，形成「半自动」评测流水线。

### 22.3 标注成本对比

| 方式 | 人工成本 | 适合场景 |
|------|----------|----------|
| 全手动 | 高 | 黄金集、合规场景 |
| LLM 生成 + 人工抽检 | 中 | 快速扩容 |
| 循环测试自动生成 | 低 | 覆盖度优先、允许噪声 |

---

## 23. 报告对象模型（EvalReport）

`EvalReport` 由 `EvalRunner._build_report` 构造，包含：

- 任务级聚合：各 `avg_*` 字段、`rag_score`、`hallucination_rate`；
- 样本级列表：`List[SampleResult]`，每条含指标分数字段与 `judge_detail` 字典；
- 序列化：`report.save(path)` 输出 JSON，CLI 与 Server 共用。

Server 额外调用 Judge 生成自然语言 `interpretation`，写入 `eval_report` 表，前端直接展示而无需客户端再调 LLM。

**SampleResult 字段与 UI 映射：**

| 字段 | 报告页展示 |
|------|------------|
| hit_rate, mrr, ndcg | 检索卡片 / 雷达图轴 |
| faithfulness 等 | 生成卡片 |
| judge_detail | Modal JSON |
| error | 红色错误行 |

---

## 24. 并发模型与资源约束

### 24.1 asyncio 语义

Server 主线程运行在 uvicorn 事件循环上。`run_eval_task`、`run_loop_task`、单跳后台任务均为 `asyncio.create_task` 调度的协程，共享同一线程。CPU 密集操作（如大 JSON 解析）应避免阻塞过久，必要时用 `asyncio.to_thread`。

### 24.2 Semaphore

`EvalRunner` 与 `SingleJumpTester` 均使用 `asyncio.Semaphore(concurrency)` 限制同时在飞的 HTTP 请求数。过大并发会导致：

- dagent 返回 429 或超时；
- Judge API 账单激增；
- SQLite 写锁等待。

推荐生产从 3–5 起步，循环大规模任务可提到 10–20 并监控错误率。

### 24.3 连接池

`DagentAdapter` 每次调用新建 `aiohttp.ClientSession`，简单但高并发下开销大。若需优化可改为 Session 复用（注意线程/协程安全）。

---

## 25. 类图：SDK 核心类型

```mermaid
classDiagram
    class RAGAdapter {
        <<abstract>>
        +retrieve()
        +chat()
    }
    class DagentAdapter {
        +base_url
        +org_id
    }
    class LLMJudge {
        <<abstract>>
        +score_faithfulness()
        +score_relevance()
    }
    class OpenAICompatibleJudge {
        +client AsyncOpenAI
    }
    class EvalRunner {
        +adapter
        +judge
        +run()
    }
    class EvalSample {
        +question
        +reference_answer
        +relevant_chunk_ids
    }
    class EvalReport {
        +rag_score
        +results
    }
    RAGAdapter <|-- DagentAdapter
    LLMJudge <|-- OpenAICompatibleJudge
    EvalRunner --> RAGAdapter
    EvalRunner --> LLMJudge
    EvalRunner --> EvalReport
    EvalRunner --> EvalSample
```

---

## 26. 安全、合规与权限（建议）

当前版本为**内网工具**假设：无用户登录、无 RBAC。若对外暴露：

1. 增加 OAuth2 / 公司 SSO，API 带 Bearer；
2. `judge_config.api_key` 改为 KMS 引用或环境变量注入，库内不存明文；
3. 导出接口加审计日志；
4. 按 org 隔离 `platform_config`，防止误测他人知识库。

---

## 27. 版本演进与已知限制

| 限制 | 说明 | 规避 |
|------|------|------|
| 单进程循环控制 | pause/resume 不能跨 uvicorn worker | 单 worker 或 Redis 协调 |
| qa_gen 路由共用前缀 | 两模块同 prefix | 注册顺序、集成测试 |
| README 端口 8003 vs 代码 8021 | 历史文档差异 | 以实际启动参数为准 |
| 超大 SQLite | 循环后 DB 数 GB | 归档 exports、分库 |
| file_id 过滤 | 部分 dagent 不支持 | cross_chunk |

---

## 28. 典型使用场景 walkthrough

### 28.1 场景 A：发版前回归

1. 维护固定 `eval_dataset`（200 条黄金集）；
2. CI 中 `rag-eval run`，`selected_metrics` 仅开 faithfulness + hit_rate；
3. 对比上一版本 `report.json`，RAG Score 下降超过 5% 则失败。

### 28.2 场景 B：新知识库冷启动

1. `qa_gen` 从 dagent 选目录出题；
2. 人工审核 10% 样本；
3. 单跳全库 MD 导出召回报告；
4. 针对 file_miss 章节调整切片策略。

### 28.3 场景 C：远程 4140 切片覆盖

1. 按 `task_groups_plan` 建 42 个 `loop_task`；
2. 每组跑满 `max_rounds=5` 或直至收益递减；
3. `export_loop_all_groups.py` 汇总；
4. 用 exports JSON 训练或分析高频未命中 chunk。

### 28.4 场景 D：多跳文档联调

1. `multi_hop_gen` 生成推理链问题；
2. 导出 MD → `multi_hop` 任务；
3. 查看 `hop_hit_count` 与 `full_hit` 比例，定位薄弱跳次。

---

## 29. 与早期设计文档的关系

[rag-eval-framework-design.md](./rag-eval-framework-design.md) 撰写于框架立项阶段，侧重指标定义与分层理念。本文档（技术规格说明书）对齐**当前代码实现**，补充了循环测试、多跳、qa_gen、SQLite 表结构及运维细节。若两处冲突，以本规格书与源码为准。

---

## 30. 名词索引（中英对照）

| 中文 | 英文 | 代码中的关键符号 |
|------|------|------------------|
| 评测运行器 | Eval Runner | `EvalRunner` |
| 平台适配器 | RAG Adapter | `RAGAdapter` |
| 评判器 | LLM Judge | `LLMJudge` |
| 单跳 | Single-hop | `single_jump` |
| 多跳 | Multi-hop | `multi_hop` |
| 循环任务 | Loop Task | `loop_task` |
| 调和均值 | Harmonic Mean | `rag_score` 计算 |
| 幻觉率 | Hallucination Rate | faithfulness < threshold |
| 切片 | Chunk | `RetrievedChunk` |
| 知识库 | Knowledge Hub | `knowledge_hub_id` |

---

## 31. 检索规则指标实现细节

本节说明 `sdk/rag_eval/evaluators/retrieval.py` 中各函数的行为边界，便于复现论文指标或对接外部评测框架。

### 31.1 Hit Rate@K

对单个问题，若在召回列表前 K 个位置中**至少出现一个** `chunk_id` 属于标注集合 `relevant_chunk_ids`，则该样本 hit=1，否则为 0。数据集层面 Hit Rate 为所有样本 hit 的算术平均。该指标对「只要召回到一个相关文档即可」的场景敏感，无法区分相关结果排名优劣。

### 31.2 MRR@K

取第一个相关 chunk 的排名 rank（从 1 开始），贡献 $1/\text{rank}$；若无相关则贡献 0。数据集 MRR 为样本 MRR 的平均。相比 Hit Rate，MRR 对「相关结果是否靠前」更敏感，适合排序质量评估。

### 31.3 NDCG@K

实现采用二元相关度：相关 chunk 为 1，否则为 0。计算 DCG@K 时使用 $\sum_i \frac{2^{rel_i}-1}{\log_2(i+1)}$，再以理想 DCG 归一化。若标注集中有多个相关 chunk，全部命中可获得更高 NDCG。K 默认与 `RunConfig.top_k` 一致。

### 31.4 与 LLM 检索指标的关系

Hit/MRR/NDCG 依赖**离散的 chunk_id 标注**；Context Precision/Recall 依赖**自然语言参考答案**，可捕捉语义等价但 chunk_id 未标注的情况。生产评测建议两套指标并行：规则指标看排序，LLM 指标看语义覆盖。

---

## 32. Windows 与跨平台注意事项

`server/main.py` 在 `win32` 平台将 stdout/stderr 重定向为 UTF-8，避免控制台 GBK 打印特殊 Unicode（如数学符号）时崩溃。`single_jump/tester.py` 与 `loop_engine.py` 同样调用 `reconfigure(encoding='utf-8')`。

路径上 Server 使用 `Path(__file__)` 定位 `sdk` 与 `frontend/dist`，避免硬编码盘符。运维脚本应避免写死 `d:/project/...`，改用相对路径。

SQLite 在 Windows 上注意：

- 勿将 `rag_eval.db` 放在同步盘（OneDrive）上，易导致锁异常；
- 杀毒软件实时扫描大库文件会拖慢写入，建议排除 `server/data/`。

---

## 33. Docker 与 nginx 配置说明

`docker-compose.yml` 通常定义两个 service：`server` 暴露 API 端口，`frontend` 构建静态资源或由 nginx 托管。`nginx.conf` 将 `/api` 反向代理至 uvicorn，其余路径走静态文件，并配置 `try_files` 支持 React Router 前端路由。

`Dockerfile.server` 安装 `requirements.txt`，复制 `server/` 与 `sdk/`，工作目录设为 `server`，CMD 为 uvicorn。构建上下文应为 `rag-eval` 根目录而非 `server/`，否则找不到 sdk。

镜像内数据库路径需挂载 volume，例如 `- ./server/data:/app/server/data`，防止容器销毁丢数。

---

## 34. 提示词模板（prompt_template）机制

`prompt_template` 表允许用户保存可复用的出题或评判 Prompt 正文。创建 `qa_gen_task` 时可指定模板 id，生成逻辑将基础 Prompt 与模板合并，实现「同一套切片、不同题型」的 A/B。模板 CRUD 通过 `/api/prompt-template` 完成，前端可在问题生成页下拉选择。

设计意图是**将 Prompt 版本从代码中解耦**，使领域专家可在 UI 调整措辞而无需发版 Server。若模板为空则回退代码内默认 Prompt（见 `dataset/generator.py` 与 qa_gen 路由内联字符串）。

---

## 35. 数据导出格式说明

### 35.1 循环导出 JSON 结构

`export_loop_all_groups.py` 产出顶层字段：

- `exported_at`、`environment`、`org_id`；
- `task_groups[]`：每组含 `batches[]`；
- 每 batch 含 `questions[]`，单题含 `question`、`reference_answer`、`chunk_id`、`file_name`、`round`、`quality_score` 等。

该格式适合用 jq/Python 做二次聚合，例如按 `file_name` 统计每文件出题数。

### 35.2 循环导出 MD 结构

与单跳解析器兼容，可直接作为下一轮 `single-jump` 上传文件，形成「生成 → 验证 → 修正 → 再验证」闭环。

### 35.3 综合评测 report.json

CLI `rag-eval run --output report.json` 输出 `EvalReport` 全量序列化，含 `results` 数组。可用于离线绘图或与历史版本 diff。

---

## 36. 质量保障建议（组织级）

1. **黄金集**：维护 100–500 条人工审核样本，任何检索模型变更必跑；
2. **Judge 模型版本冻结**：报告中记录 `judge_config.model`，避免不可比；
3. **定期冷备**：`rag_eval.db` + `docs/exports/` 双轨；
4. **指标看板**：从 `eval_report` 表 ETL 到 Grafana，按日趋势监控 RAG Score；
5. **Bad Case 例会**：单跳 `export-failed-md` 导出未命中集，分配给切片优化负责人。

---

## 37. 读者常见问题（FAQ）

**问：评测任务为何一直 pending？**  
答：若未触发 `create_task` 或进程未启动后台协程，会停留 pending。检查 uvicorn 是否运行、API 是否返回 task_id。

**问：能否只评检索不评生成？**  
答：可以。`eval_retrieval=1`、`eval_generation=0`，或 `selected_metrics` 仅列检索项。

**问：循环任务与 qa_gen 区别？**  
答：qa_gen 单轮出题+审核；循环在多轮中自动串联出题、去重、单跳验证并累计统计。

**问：23 万题导出是否含重复？**  
答：去重后 approved 题；不同轮次可能对同一切片有不同问法，是否语义重复需用 embedding 再滤。

**问：如何对接非 dagent 平台？**  
答：实现 `RAGAdapter`，在 Server 实例化处按 `platform_config.type` 分支。

**问：RAG Score 很低但 Faithfulness 很高？**  
答：调和均值受 Context Precision/Recall 拖累，说明检索上下文质量差而非生成幻觉。

---

## 38. 文档贡献与维护

修改核心流程（如新增指标、表结构变更）时，请同步更新：

1. 本技术规格说明书对应章节；
2. 根目录 `README.md` 功能表；
3. `docs/README.md` 索引；
4. OpenAPI 注解（如有）。

Pull Request 模板可要求勾选「已更新技术文档」。

---

## 39. Server 启动生命周期

```mermaid
sequenceDiagram
    participant U as uvicorn
    participant M as main.py
    participant DB as init_db
    participant R as recover_orphaned_loops

    U->>M: import app
    M->>M: sys.path sdk
    M->>M: include_router × 11
  Note over M: lifespan start
    M->>DB: executeschema + migrations
    M->>R: running loop → paused
    M-->>U: yield app ready
    Note over M: 处理 HTTP 请求
    Note over M: lifespan end
```

应用启动时 `init_db` 执行 `schema.sql` 中 `CREATE TABLE IF NOT EXISTS`，随后 `_run_migrations` 对老库补列。任何 `running` 状态的 `loop_task` 在崩溃后被标记 `paused`，防止 UI 显示「运行中」却无法控制。

静态资源：若存在 `frontend/dist`，`app.mount("/", StaticFiles)` 将 SPA 挂在根路径，API 仍在 `/api` 下，需注意路由匹配顺序（API 路由先注册）。

---

## 40. 单跳 tester 请求载荷说明

`SingleJumpTester` 向 dagent 发起的语义检索 POST 体核心字段：

- `query`：问题正文；
- `org_id`：组织；
- `top_k`：召回数量（展示用，命中判断可能用更小的 `hit_top_k`）；
- `knowledge_hub_id`：若任务指定；
- 可选 `file_id_list`：非 cross_chunk 时限制范围。

响应解析保留每条结果的 `file_id`、`knowledge_md_header_split_id`、`cosine_distance_1`、`headers` 等原始字段写入 `retrieved` JSON，以便报告页展示完整证据链。

错误处理：单条 QA 失败写入 `error` 字段，不中断整任务；summary 统计时排除或单独计数 error 行。

---

## 41. 去重算法（dedup）参数

`service/dedup.py` 对候选题计算 embedding，与库中已批准题做余弦相似度。超过阈值则标记 `dup_of` 指向最相似题 id，并可选自动 reject。

| 参数 | 典型值 | 影响 |
|------|--------|------|
| 相似度阈值 | 0.85–0.92 | 越高越宽松 |
| global_dedup | true/false | 跨 loop_task 比对 |
| 比对字段 | question | 仅问题文本，不含答案 |

全局去重在 14 组大规模跑数时显著增加 SQL 与 embedding 调用，但能有效降低「同一文档重复问法」占比。

---

## 42. 前端 http 客户端与错误处理

`services/http.ts` 基于 axios，`baseURL` 设为 `/api`。响应拦截器统一处理 4xx/5xx，Ant Design `message.error` 提示。文件上传使用 `FormData`，不手动设 Content-Type 以保留 boundary。

长轮询：任务列表页 `setInterval` 刷新 progress，间隔约 2–5 秒；任务完成后清除定时器。大结果集分页：`qa_gen` questions 接口支持 `page`/`page_size`。

---

## 43. 评测指标体系与 RAGAS 对照

本平台指标设计参考 RAGAS、TruLens 等框架的常见定义，但实现为独立中文 Prompt，**数值不可与 RAGAS 官方实现直接划等号**。对照关系如下：

| 本平台 | 相近概念 | 差异 |
|--------|----------|------|
| Faithfulness | faithfulness | 两步 claim 验证 |
| Answer Relevance | answer_relevancy | 反推问题 + embedding |
| Context Precision | context_precision | LLM 判 useful |
| Context Recall | context_recall | 陈述级支持 |
| Groundedness | 部分 attribution | 显式 chunk index |

对外汇报时建议注明「内部评测框架」及 Judge 模型版本。

---

## 44. 性能基准（经验值，非承诺）

在「Judge=gpt-4o、dagent 内网、concurrency=3、样本 100 条、全开指标」条件下，单次 eval_task 约 15–40 分钟，主要耗时在 Faithfulness 与 Context 类 LLM 调用。单跳 1000 题、top_k=10、concurrency=10，约 10–25 分钟，主要受 dagent 检索延迟制约。

循环任务单批 100 切片、5 轮、每切片 5 题量级，总 LLM 调用可达数万次，应安排在非高峰时段并监控配额。

---

## 45. 代码阅读路径（新人 onboarding）

1. `sdk/rag_eval/runner.py` — 理解主流程；
2. `sdk/rag_eval/adapters/dagent.py` — 理解外部依赖；
3. `server/service/task_service.py` — 理解持久化；
4. `server/api/task.py` + `frontend/pages/Task` — 理解端到端；
5. `server/service/loop_engine.py` — 理解最复杂编排；
6. `server/models/schema.sql` — 理解数据全貌。

每模块配有本规格书第 4、6 章交叉引用。

---

## 46. eval_task 创建请求体字段说明

Web UI 提交 `POST /api/task/run` 时，JSON 或表单字段与数据库列映射如下。理解该映射有助于用脚本批量建任务。

| 请求字段 | 必填 | 说明 |
|----------|------|------|
| dataset_id | 是 | 已存在的数据集 |
| platform_config_id | 是 | dagent 连接 |
| judge_config_id | 是 | LLM 评判 |
| agent_id | 是 | 生成层对话用 |
| knowledge_hub_id | 是 | 检索范围 |
| name | 否 | 任务展示名 |
| top_k | 否 | 默认 10 |
| eval_retrieval / eval_generation | 否 | 布尔 |
| selected_metrics | 否 | JSON 数组，覆盖上述布尔 |
| file_id_list | 否 | 限制检索文件 |
| concurrency | 否 | 默认 3 |

创建成功后 Server 立即 `asyncio.create_task(run_eval_task(task_id))`，HTTP 响应不等待评测结束。

---

## 47. 切片质量与评测结果的因果关系链

评测低分往往并非单一环节失败，建议按下列因果链排查：

```mermaid
flowchart TD
    A[切片过长/过短] --> B[检索噪声大]
    B --> C[Context Precision 低]
    A --> D[关键信息未切片]
    D --> E[Context Recall 低]
    E --> F[Agent 缺上下文]
    F --> G[Faithfulness 低或胡编]
    H[Agent Prompt 不当] --> G
    I[Embedding 模型不适配中文] --> B
```

平台提供单跳与循环工具定位 B 段；综合评测定位 C–G；需与知识库工程、Agent 配置协同优化。

---

## 48. 未来架构演进方向（规划，非承诺）

1. **任务队列外置**：Redis + Celery/RQ，支持多 Worker 与任务取消；
2. **PostgreSQL 选项**：替代 SQLite 以支撑多实例写入；
3. **Judge 缓存**：相同 (question, chunks) 哈希复用评判结果；
4. **插件化指标**：`Metric` 接口注册，UI 动态勾选；
5. **权限与租户**：org 级隔离与审计；
6. **标准数据集格式**：导入 RAGAS/HuggingFace 格式。

上述方向来自实际运维痛点，实施优先级由产品决定。

---

## 49. 缩略语表

| 缩略语 | 全称 |
|--------|------|
| RAG | Retrieval-Augmented Generation |
| LLM | Large Language Model |
| SSE | Server-Sent Events |
| WAL | Write-Ahead Logging |
| API | Application Programming Interface |
| SPA | Single Page Application |
| CRUD | Create Read Update Delete |
| ER | Entity-Relationship |
| CI/CD | Continuous Integration / Delivery |
| EVB | 项目内知识库代号 |
| org_id | dagent 组织标识 |

---

## 50. 结语

RAG Eval 平台将**可复现的指标体系**、**贴近 dagent 的工程工具链**与**大规模数据生产能力**整合在同一仓库中。本文档从架构、数据、流程、API、运维五方面描述当前实现，并配有二十余张 Mermaid 图辅助理解。随着代码迭代，请持续更新本文档与根目录 README，保持「文档 — 代码 — 数据导出」三者一致，以便团队在任何时间点都能追溯评测结论的依据。

---

## 附录 A：14 组循环测试与数据资产

大规模远程 dagent 循环测试将 4140 切片划分为 **42 批次 × 14 组**，详见 [循环测试_14组分批规则.md](./循环测试_14组分批规则.md)。全量导出（235,347 题）位于 [exports/](./exports/)。

```mermaid
flowchart TB
    subgraph Chunks["4140 切片 / 207 文件"]
        B1["批次 1-3<br/>组1"]
        B2["批次 4-6<br/>组2"]
        BDOT["…"]
        B14["批次 40-42<br/>组14"]
    end

    Chunks --> LT["loop_task × 42"]
    LT --> QR["qa_gen_question"]
    LT --> SR["single_jump_result"]
    QR --> EXP["docs/exports/ 汇总"]
    SR --> EXP
```

---

## 附录 B：文档修订记录

| 版本 | 日期 | 说明 |
|------|------|------|
| v1.0 | 2026-05-18 | 首版：架构、时序图、数据模型、指标、API、运维与字段字典 |
| v1.1 | 2026-05-18 | 扩充第 12–20 章，满足万字技术规格要求 |

---

*本文档随代码演进更新；若与实现不一致，以仓库源码为准。*