Spaces:
Sleeping
Sleeping
| # ELBench 架构说明 | |
| 本文档描述 ELBench 的工程设计：注册表、provider 抽象、执行模型，以及如何扩展框架。基准与排行榜的总览见顶层 [README](../README.zh-CN.md)。 | |
| ELBench 不是临时脚本，而是按正式工程维护的评测系统。当前仓库在一个统一框架下承载四个模块： | |
| - `安全可信` / Safety & Trustworthiness | |
| - `高阶育人` / High-Level Educational Cultivation | |
| - `基本教育` / Basic Education | |
| - `通用模型` / General Capability | |
| `基本教育` 已作为 ELBench 的正式模块接入。它的 benchmark 数据放在 `data/benchmark_root/基本教育/`，多轮执行由项目内部的 `basic_education_runtime` 模块负责，代码位于 `src/elbench/basic_education_runtime/`。这个内部运行时来源于 ELMES 项目，但现在已经按 ELBench 的内部模块方式接管和维护。 | |
| ## 设计原则 | |
| - 评测流程由注册表和配置驱动，不在主流程里写死文件逻辑 | |
| - 模型调用统一走 provider adapter，不让厂商差异污染主 runner | |
| - 客观题优先规则判分 | |
| - 主观和开放式任务采用 `LLM-as-a-Judge` | |
| - 稳定的机器可读输出、日志、检查点与汇总 | |
| - 中断后支持续跑 | |
| - 可配置并发，默认全局上限 `100` | |
| ## 当前实际接入的内容 | |
| ### 已注册的 benchmark 文件 | |
| `configs/file_registry.yaml` 当前解析以下文件： | |
| - `安全拒答.jsonl` | |
| - `安全引导.jsonl` | |
| - `安全回答.jsonl` | |
| - `SATAs.xlsx` | |
| - `adversarial_prompts.xlsx` | |
| - `高阶育人-edu.jsonl` | |
| - `高阶育人-omni.jsonl` | |
| - `knowledge.yaml` | |
| - `question.yaml` | |
| - `cross.yaml` | |
| - `config_guided_task.yaml` | |
| - `mmlu_pro_sampled.jsonl` | |
| - `ceval_sampled.jsonl` | |
| - `ifeval_sampled.jsonl` | |
| - `math_500_sampled.jsonl` | |
| - `aime24_sampled.jsonl` | |
| - `aime25.jsonl` | |
| - `aime26.jsonl` | |
| - `gsm8k_sampled.jsonl` | |
| 文件只有在注册之后才会被视为有效的 benchmark 输入。没有出现在 `configs/file_registry.yaml` 中的数据文件，不属于可运行基准的一部分。 | |
| ### 当前判分策略 | |
| 客观题用规则或参考答案匹配： | |
| - `SATAs.xlsx` | |
| - `高阶育人-omni.jsonl` | |
| - `mmlu_pro_sampled.jsonl` | |
| - `ceval_sampled.jsonl` | |
| - `ifeval_sampled.jsonl` | |
| - `math_500_sampled.jsonl` | |
| - `aime24_sampled.jsonl` | |
| - `aime25.jsonl` | |
| - `aime26.jsonl` | |
| - `gsm8k_sampled.jsonl` | |
| 主观或开放式任务用 `LLM-as-a-Judge`： | |
| - `安全拒答.jsonl` | |
| - `安全引导.jsonl` | |
| - `安全回答.jsonl` | |
| - `adversarial_prompts.xlsx` | |
| - `高阶育人-edu.jsonl` | |
| 仓库把外部 provider 接入设计为可插拔。内置 `mock.default` 和 `mock.judge`，可在没有真实 API 的情况下本地验证完整流水线。 | |
| ## 仓库结构 | |
| ```text | |
| . | |
| ├── configs/ | |
| │ ├── app.yaml | |
| │ ├── basic_education.yaml | |
| │ ├── field_mappings.yaml | |
| │ ├── file_registry.yaml | |
| │ ├── judges.yaml | |
| │ ├── models.yaml | |
| │ ├── module_registry.yaml | |
| │ └── providers.yaml | |
| ├── data/ | |
| │ └── benchmark_root/ | |
| │ ├── 安全可信/ | |
| │ ├── 高阶育人/ | |
| │ ├── 基本教育/ | |
| │ └── 通用/ | |
| ├── docs/ | |
| │ └── TEAM_MAINTENANCE_GUIDE.zh-CN.md | |
| ├── results/ | |
| ├── scripts/ | |
| │ └── run_benchmark.py | |
| ├── src/ | |
| │ └── elbench/ | |
| │ ├── basic_education_runtime/ | |
| │ ├── cli.py | |
| │ ├── config/ | |
| │ ├── execution/ | |
| │ ├── judges/ | |
| │ ├── loaders/ | |
| │ ├── persistence/ | |
| │ ├── providers/ | |
| │ ├── registry/ | |
| │ ├── schemas/ | |
| │ ├── summary/ | |
| │ └── utils/ | |
| └── tests/ | |
| ``` | |
| `scripts/run_benchmark.py` 刻意只是一个薄入口，真正的评测逻辑都在 `src/elbench/` 下。 | |
| ## 核心架构 | |
| ### 注册表与 schema 适配 | |
| - `configs/file_registry.yaml` 把文件映射到模块、子集、任务、loader 与规范名。 | |
| - `configs/field_mappings.yaml` 把原始数据集字段映射进 ELBench 的统一内部 schema。 | |
| - JSONL、XLSX、基本教育 YAML 输入都被规范化为同一个 `Sample` 结构。 | |
| ### 统一的 sample/result schema | |
| 加载后的记录被规范化为稳定 schema，字段包括： | |
| - `sample_id` | |
| - `source_file` | |
| - `module` | |
| - `subset` | |
| - `task` | |
| - `dimension` | |
| - `prompt` | |
| - `reference` | |
| - `metadata` | |
| 执行输出包括： | |
| - `provider_name` | |
| - `model_id` | |
| - `model_name` | |
| - `model_response` | |
| - `judge_result` | |
| - `score` | |
| - `judge_reason` | |
| - `judge_metadata` | |
| - `latency_ms` | |
| - `retry_count` | |
| - `timestamp` | |
| ### Provider 抽象 | |
| - `ModelClient` 是模型执行的统一接口。 | |
| - 厂商 API 差异都隔离在 `src/elbench/providers/` 下。 | |
| - 一旦 adapter 存在，主 runner 不关心模型来自 OpenAI、Anthropic、Gemini 还是其他厂商。 | |
| ### 执行、并发与恢复 | |
| runner 支持： | |
| - 全局并发控制 | |
| - provider/模型级并发上限 | |
| - 指数退避重试 | |
| - 失败日志 | |
| - 基于检查点的续跑 | |
| - 原始响应持久化 | |
| - 判分结果持久化 | |
| - 汇总生成 | |
| `configs/app.yaml` 中默认全局最大并发为 `100`。 | |
| ### 基本教育运行时 | |
| `基本教育` 与其他模块的差别只在执行方式，不在数据治理： | |
| - benchmark 数据仍放在 `data/benchmark_root/基本教育/` | |
| - 文件发现仍走 `configs/file_registry.yaml` | |
| - 运行时执行由 `src/elbench/execution/basic_education.py` 负责 | |
| - 内部运行时实现位于 `src/elbench/basic_education_runtime/` | |
| ## 输出结构 | |
| ```text | |
| outputs/ | |
| ├── raw_responses/ | |
| ├── judged_results/ | |
| ├── summaries/ | |
| └── logs/ | |
| ``` | |
| 这些目录是运行时产物，刻意被 Git 忽略。整理后的排行榜与审计汇总提交在 `results/` 下。 | |
| ## 配置面 | |
| ### `configs/models.yaml` | |
| 具体的被测模型与裁判模型实例，含超时、重试、限速与 provider 参数。 | |
| ### `configs/providers.yaml` | |
| provider adapter 注册表与默认 provider 能力。当前内置 adapter： | |
| - `mock` | |
| - `openai_compatible` | |
| ### `configs/judges.yaml` | |
| 任务到裁判的路由： | |
| - `rule` | |
| - `llm` | |
| ### `configs/basic_education.yaml` | |
| 基本教育内部运行时的场景级设置。该文件不替代注册表，而是对其补充。 | |
| ## 扩展 ELBench | |
| ### 新增 provider | |
| 1. 在 `src/elbench/providers/` 下实现 adapter。 | |
| 2. 在 `configs/providers.yaml` 中注册。 | |
| 3. 在 `configs/models.yaml` 中加入具体模型。 | |
| ### 新增 benchmark 文件 | |
| 1. 把数据文件放到 `data/benchmark_root/` 下。 | |
| 2. 在 `configs/file_registry.yaml` 中注册。 | |
| 3. 在 `configs/field_mappings.yaml` 中加字段映射。 | |
| 4. 在 `configs/judges.yaml` 中路由判分。 | |
| 5. 新增或复用测试。 | |
| ### 新增未来模块 | |
| ELBench 已为更多模块预留空间，预期路径仍是： | |
| 1. 加模块注册 | |
| 2. 加文件注册 | |
| 3. 加字段映射 | |
| 4. 加裁判路由 | |
| 5. 仅当配置无法表达行为时才加任务专属逻辑 | |
| 不需要重写主 runner。 | |
| ## 维护 | |
| 权威的团队维护指南是 [`docs/TEAM_MAINTENANCE_GUIDE.zh-CN.md`](TEAM_MAINTENANCE_GUIDE.zh-CN.md)，它说明每个维护目录的用途、哪些路径仅运行时、以及哪些该提交哪些不该提交。 | |
| ## 状态 | |
| 已实现： | |
| - 配置系统 | |
| - 文件注册表 | |
| - JSONL/XLSX/YAML loader | |
| - 统一 sample/result schema | |
| - provider 抽象 | |
| - 并发 runner | |
| - 重试与检查点续跑 | |
| - 原始/判分/汇总/日志输出 | |
| - 客观题规则裁判 | |
| - 主观题 `LLM-as-a-Judge` 执行路径 | |
| - 基于内部运行时模块的基本教育桥接 | |
| 仍刻意未完成： | |
| - 面向每个外部厂商的生产级 adapter | |
| - 最终化的主观裁判 rubric 与 prompt | |
| - 超出当前已注册文件的完整未来模块接入 | |