OpenCompass 评估框架项目文档目录项目概述环境配置文件结构核心组件说明测试用例配置评估流程运行命令测试结果常见问题扩展指南1. 项目概述本项目是 OpenCompass 大模型评估框架的测试部署旨在验证框架的完整功能包括数据集加载支持多种格式JSONL、HuggingFace Dataset等模型推理支持 HuggingFace 模型评估指标准确率等常用指标结果分析预测结果和评估报告技术栈组件版本说明Python3.13编程语言OpenCompass0.5.3评估框架PyTorchlatest深度学习框架Transformers4.46.3HuggingFace 模型库Datasets2.x-3.x数据集库2. 环境配置2.1 虚拟环境# 创建虚拟环境python-mvenv venv# 激活虚拟环境Windowsvenv\Scripts\activate# 激活虚拟环境Linux/macOSsourcevenv/bin/activate2.2 依赖安装# 安装 OpenCompass不安装依赖pipinstallopencompass0.5.3 --no-deps# 安装基础依赖pipinstallnumpy2.0.0 torchtransformers4.46.3 datasets2.12.0,4.0.0 mmengine# 安装额外依赖pipinstallrouge importlib_metadata tqdm requests2.3 环境变量# 设置 PYTHONPATHWindowssetPYTHONPATHE:\project\opencompass# 设置 PYTHONPATHLinux/macOSexportPYTHONPATH/path/to/project/opencompass3. 文件结构E:\project\opencompass\ ├── venv/ # Python 虚拟环境 ├── opencompass_source/ # OpenCompass 源码 │ └── opencompass/ # 核心代码 ├── models/ # 模型文件目录 │ └── Qwen2-0.5B-Instruct/ # Qwen2-0.5B-Instruct 模型 ├── outputs/ # 评估输出目录 │ └── simple_test/ # 测试输出 ├── test_data.jsonl # 测试数据集JSONL格式 ├── simple_test_config.py # 测试配置文件 ├── simple_mcq_postprocess.py # 预测后处理器 ├── download_model.py # 模型下载脚本 ├── test_environment.py # 环境测试脚本 └── PROJECT_DOC.md # 项目文档本文档文件说明文件类型说明test_data.jsonl数据集多项选择题测试数据simple_test_config.py配置OpenCompass 评估配置simple_mcq_postprocess.py脚本提取字母选项的后处理器download_model.py脚本模型下载工具test_environment.py脚本环境验证工具4. 核心组件说明4.1 数据集Dataset使用 JSONL 格式存储每行一个 JSON 对象{question:22?,options:[A. 3,B. 4,C. 5,D. 6],answer:B}字段说明question问题文本options选项列表字符串数组answer正确答案A/B/C/D4.2 模型Model使用 HuggingFaceBaseModel 加载本地模型models[dict(typeHuggingFaceBaseModel,abbrqwen2-0.5b-instruct-hf,pathE:/project/opencompass/models/Qwen2-0.5B-Instruct,max_out_len16,batch_size1,run_cfgdict(num_gpus0),model_kwargsdict(torch_dtypeauto,device_mapcpu),)]4.3 推理器Inferencer使用 GenInferencer 进行生成式推理infer_cfgdict(prompt_templatedict(typePromptTemplate,templateQuestion: {question}\nOptions: {options}\nAnswer:,),retrieverdict(typeZeroRetriever),inferencerdict(typeGenInferencer,max_out_len16),)4.4 评估器Evaluator使用 AccEvaluator 计算准确率eval_cfgdict(evaluatordict(typeAccEvaluator),pred_postprocessordict(typesimple_mcq_postprocess.simple_mcq_postprocess),)5. 测试用例配置5.1 配置文件结构配置文件包含四个核心部分Reader 配置定义数据读取方式Infer 配置定义推理过程Eval 配置定义评估过程Datasets/Models定义数据集和模型列表5.2 完整配置示例# 读取配置simple_reader_cfgdict(input_columns[question,options],output_columnanswer)# 推理配置simple_infer_cfgdict(prompt_templatedict(typePromptTemplate,templateQuestion: {question}\nOptions: {options}\nAnswer:,),retrieverdict(typeZeroRetriever),inferencerdict(typeGenInferencer,max_out_len16),)# 评估配置simple_eval_cfgdict(evaluatordict(typeAccEvaluator),pred_postprocessordict(typesimple_mcq_postprocess.simple_mcq_postprocess),)# 数据集列表datasets[dict(abbrsimple_mcq_test,typeJsonlDataset,pathE:/project/opencompass/test_data.jsonl,reader_cfgsimple_reader_cfg,infer_cfgsimple_infer_cfg,eval_cfgsimple_eval_cfg,)]# 模型列表models[dict(typeHuggingFaceBaseModel,abbrqwen2-0.5b-instruct-hf,pathE:/project/opencompass/models/Qwen2-0.5B-Instruct,max_out_len16,batch_size1,run_cfgdict(num_gpus0),model_kwargsdict(torch_dtypeauto,device_mapcpu),)]# 输出目录work_dir./outputs/simple_test6. 评估流程6.1 完整流程┌─────────────────┐ │ 1. 加载数据集 │ ← JsonlDataset └────────┬────────┘ ▼ ┌─────────────────┐ │ 2. 构建提示 │ ← PromptTemplate └────────┬────────┘ ▼ ┌─────────────────┐ │ 3. 零样本检索 │ ← ZeroRetriever └────────┬────────┘ ▼ ┌─────────────────┐ │ 4. 模型推理 │ ← GenInferencer HuggingFaceBaseModel └────────┬────────┘ ▼ ┌─────────────────┐ │ 5. 后处理 │ ← simple_mcq_postprocess └────────┬────────┘ ▼ ┌─────────────────┐ │ 6. 评估计算 │ ← AccEvaluator └────────┬────────┘ ▼ ┌─────────────────┐ │ 7. 输出结果 │ ← 预测文件 汇总报告 └─────────────────┘6.2 各步骤说明步骤组件说明1JsonlDataset读取 JSONL 文件返回 HuggingFace Dataset2PromptTemplate将数据填充到提示模板中3ZeroRetriever不使用检索直接推理4GenInferencer调用模型生成回答5simple_mcq_postprocess从生成文本中提取字母选项6AccEvaluator计算预测与标准答案的匹配率7OutputWriter保存预测结果和汇总报告7. 运行命令7.1 验证环境python test_environment.py7.2 下载模型python download_model.py7.3 运行评估# 设置 PYTHONPATHsetPYTHONPATHE:\project\opencompass# 运行评估python opencompass_source/opencompass/cli/main.py simple_test_config.py--debug--max-num-workers17.4 命令参数说明参数说明--debug启用调试模式生成详细日志--max-num-workers设置最大工作线程数--dump-eval-details是否保存评估详情默认 True--num-gpus使用的 GPU 数量8. 测试结果8.1 评估报告datasetversionmetricmodeqwen2-0.5b-instruct-hfsimple_mcq_test5da63caccuracygen25.008.2 预测结果示例{0:{origin_prompt:Question: 22?\nOptions: [A. 3, B. 4, C. 5, D. 6]\nAnswer:,prediction: We can solve this problem by adding the numbers together:\n\n\\[2 2,gold:B},1:{origin_prompt:Question: The capital of China is?\nOptions: [A. Shanghai, B. Beijing, C. Guangzhou, D. Shenzhen]\nAnswer:,prediction: B. Beijing\n\nThe capital of China is Beijing...,gold:B}}8.3 结果分析准确率 25%4 道题中答对 1 道正确题目中国首都B错误题目22、最近行星、10-3原因分析模型输出过于冗长后处理器仅提取第一个字母导致数学题答案被忽略9. 常见问题9.1 ModuleNotFoundError: No module named ‘tree_sitter’问题OpenCompass 部分数据集依赖 tree_sitter但该库在 Python 3.13 上安装失败。解决方案修改opencompass/datasets/__init__.py注释掉相关数据集的导入。9.2 模型下载速度慢问题直接从 HuggingFace Hub 下载速度较慢。解决方案使用国内镜像hf-mirror.com或使用download_model.py脚本。9.3 评估器找不到问题配置文件中指定的评估器名称错误。解决方案使用正确的评估器名称如AccEvaluator不是AccuracyEvaluator。9.4 预测结果格式不正确问题模型输出文本而非单个字母导致评估失败。解决方案添加pred_postprocessor从预测文本中提取字母选项。10. 扩展指南10.1 添加新数据集创建 JSONL 文件在配置文件中添加数据集定义配置 reader、infer、eval 参数10.2 添加新模型下载模型到models/目录在配置文件中添加模型定义调整模型参数max_out_len、batch_size 等10.3 添加新评估指标创建评估器类或使用现有评估器在配置文件中指定 evaluator 类型添加必要的后处理器10.4 优化提示模板根据任务类型调整提示模板# 多项选择题templateQuestion: {question}\nOptions: {options}\nAnswer:# 问答任务templateQuestion: {question}\nAnswer:# 分类任务templateSentence: {sentence}\nLabel:附录A. 参考链接OpenCompass 官方文档Qwen2-0.5B-InstructHuggingFace DatasetsB. 版本历史日期版本说明2026-07-27v1.0初始版本完成基础环境配置和测试用例