# 模型评测功能总结

本项目（基于 LLaMA-Factory 的微调训练平台）包含 **4 套相对独立** 的模型评测能力，分别面向不同的使用场景：

| 能力 | 入口/目录 | 评测类型 | 打分方式 |
| --- | --- | --- | --- |
| 1. 学术 Benchmark 评测 | `llamafactory/eval/` | 选择题式基准（类 MMLU/C-Eval） | 选项匹配 + few-shot |
| 2. 评估工作台 | `backend/app/api/v1/eval/` | 生成式问答（指令跟随） | BLEU / ROUGE / ExactMatch + 可选 LLM 评审 |
| 3. 平台评估系统 | `backend/app/api/v1/evaluation/` | 基于评估数据集的问答 | 判卷模型（judge model）打分（0–5 分） |
| 4. 训练时验证评估 | `backend/app/services/task_runner.py` | 训练验证集 | loss 指标 |

下面分别说明。

---

## 1. 学术 Benchmark 评测（LLaMA-Factory 原生）

面向标准学术选择题基准（如 MMLU、C-Eval 等），复用 LLaMA-Factory 原生的评测框架。

**核心文件**
- `llamafactory/eval/evaluator.py`：`Evaluator` 类 + `run_eval()` 入口
- `llamafactory/eval/template.py`：评测 prompt 模板（中/英，含 few-shot 示例构建）
- `llamafactory/hparams/evaluation_args.py`：`EvaluationArguments` 配置类

**工作流程**
1. 按 `task`（benchmark 名称）加载数据集，按科目（subject）拆分。
2. 每个样本构造 few-shot 提示词（`n_shot` 控制示例数，由 `lang` 决定中/英模板），将题干与候选选项拼入 prompt。
3. 调用模型推理得到预测，与标准答案比对，统计每个科目及整体的 `accuracy`。
4. 结果写入 `save_dir`，打印各科目与平均准确率。

**关键参数（`EvaluationArguments`）**
- `task`：基准数据集名
- `batch_size` / `n_shot` / `lang` / `save_dir` / `seed`
- `model_name_or_path`、`template`、`trust_remote_code` 等模型相关参数

> 该能力属于框架底层，本平台前端未直接提供操作入口，主要通过配置文件/脚本调用。

---

## 2. 评估工作台（生成式评测 + 指标计算）

后端路由位于 `backend/app/api/v1/eval/__init__.py`，前端称为「评估工作台」。**适用于评测模型的指令跟随与生成质量**，并支持 LLM 作为裁判（LLM-as-a-Judge）。

**API 端点**
- `GET  /evaluation/tasks`：列出评测任务（`frontend/src/api/evaluation.ts:listTasks`）
- `POST /evaluation/run`：提交一次评测（`runEval`）
- `GET  /evaluation/report/{task_id}`：拉取评测报告（`getReport`）
- `DELETE /evaluation/tasks/{task_id}`：删除任务（`deleteTask`）

**评测流程（`run_eval`）**
1. 通过 **LLaMA-Factory 数据管道**（`get_dataset`) 加载数据集，支持 `subset` 与抽样（`eval_sample`）。
2. 用 **原生 transformers** 加载模型在本地做生成推理（单进程顺序生成，便于展示样本）。
3. 计算客观指标（`compute_score`）：
   - `BLEU`（sacrebleu）
   - `ROUGE-1 / ROUGE-2 / ROUGE-L`（rouge-score）
   - `Exact Match`
4. **可选 LLM 评审**（judge）：当配置了 `judge_model` / `judge_api_base` / `judge_api_key` 时，调用 OpenAI 兼容接口对每条样本打分（10 分制），并输出 4 个维度与理由：
   - 核心事实正确性 `factual`
   - 信息完整性 `completeness`
   - 无幻觉 `no_hallucination`
   - 格式合规性 `format`
   - 综合分 `score` + `reason`
5. 任务状态持久化在后端 `eval_tasks.json`（支持 running/completed/failed/stopped），前端轮询进度。

**前端页面**
- `frontend/src/views/evaluation/EvaluateTask.vue`：任务列表、创建评测对话框（选模型、数据集、指标、可选 judge 配置）
- `frontend/src/views/evaluation/EvaluateReport.vue`：报告页，展示综合得分、BLEU、ROUGE-L、各维度指标及「参考答案 vs 模型预测 vs LLM 评审」对比样例

---

## 3. 平台评估系统（基于评估数据集 + 判卷模型）

后端路由位于 `backend/app/api/v1/evaluation/__init__.py`，是平台业务层自研的评测体系。通过「评估数据集」组织题目，可一次性对 **多个被测模型 + 指定判卷模型** 进行批量评分。

**核心概念（数据模型 `backend/app/models/models.py`）**
- `EvalDataset`（`models.py:131`）：评估数据集，从项目问答对（`Question`/`Chunk`）中按 `question_type`（mixed/fact/reasoning）选题构建，状态 `pending/running/completed/failed`。
- `EvalResult`（`models.py:147`）：单条评测结果，含 `judge_score`（0–5 分）、`is_correct`（true/false/partial）、`feedback`、`expected_answer` 等。
- `Task`（`models.py:184`）：后台任务，`task_type="model-evaluation"`，记录进度与 `model_info`（存放平均分等汇总）。

**评测流程（`process_evaluation_task`，`backend/app/services/task_processor.py:336` 起）**
1. 加载评估数据集关联的题目，可选带入 `chunk` 上下文（RAG 场景）。
2. 对每道题，先用 `build_eval_prompt` 组合「上下文 + 题目 + 参考答案」，调用 **判卷模型**（`call_model`，temperature=0.3）生成评分。
3. `parse_eval_result` 解析出 `score`(0–5)、`is_correct`、`feedback`，写入 `EvalResult`。
4. 逐题提交进度（`completed_count` / `progress`），支持中途 `stopped`。
5. 汇总：`avg_score = 总分/有效数 × 20`（换算百分制），`avg_score_5 = 总分/有效数`（5 分制），存入 `task.model_info`。判定规则：得分 **≥3 视为正确**。

**特点**
- 判卷与被测模型解耦：被测模型给出答案，判卷模型（judge）独立评分，降低自评偏差。
- 支持失败隔离：单题异常写入 `evaluation_status: failed` 记录而不中断整体任务。

---

## 4. 训练时验证评估

在微调训练任务执行期间，由 `backend/app/services/task_runner.py` 的 `do_eval` 触发：

- 在训练过程中对验证集（validation set）计算 `eval_loss`，用于监控过拟合。
- 结果回填到 `Task` 的 `loss_info` / `detail`，前端绘制 loss 曲线。
- 属于训练配套的轻量评估，不参与上述 1–3 的业务评测。

---

## 附属：前端评测相关页面

| 文件 | 作用 |
| --- | --- |
| `frontend/src/views/evaluation/EvaluateTask.vue` | 评估工作台：任务列表 + 创建评测 |
| `frontend/src/views/evaluation/EvaluateReport.vue` | 评估报告：指标卡 + 维度标签 + 对比样例 |
| `frontend/src/api/evaluation.ts` | 评估工作台接口封装 |
| 平台评估系统入口 | 评估数据集管理 + 评估任务（model-evaluation）创建与结果查看 |

---

## 小结

- **想要学术榜单式准确率** → 用能力 1（LLaMA-Factory `eval/`）。
- **想要开放式生成质量（BLEU/ROUGE + LLM 评审）** → 用能力 2（评估工作台 `/evaluation/run`）。
- **想要基于自有问答数据、用判卷模型批量打分** → 用能力 3（平台评估系统 `model-evaluation` 任务）。
- **训练过程监控** → 能力 4（`do_eval` 验证集 loss）。

三种业务评测（1/2/3）相互独立，可并存于同一平台；数据模型（`EvalDataset`/`EvalResult`/`Task`）主要服务于能力 3，而能力 2 使用独立的 `eval_tasks.json` 文件持久化。