ms-swift模型评测指南：用OpenCompass评估性能

ms-swift模型评测指南：用OpenCompass评估性能

在大模型微调与部署实践中，训练只是起点，科学、全面、可复现的模型评测才是验证效果的关键环节。ms-swift作为覆盖训练、推理、量化、部署全链路的轻量级微调框架，不仅支持600+文本模型与300+多模态模型的高效训练，更深度集成了EvalScope评测后端，并原生兼容业界权威评测平台——OpenCompass。本文不讲抽象理论，不堆参数配置，而是以一线工程师视角，手把手带你完成一次真实、完整、可落地的模型性能评测闭环：从环境准备、评测任务配置、OpenCompass数据集选择，到结果解析与横向对比，全程聚焦“怎么用、为什么这么用、容易踩什么坑”。

你不需要是分布式系统专家，也不必熟读OpenCompass源码。只要你会运行一条命令、能看懂终端输出、关心“我的微调模型到底强在哪、弱在哪”，这篇文章就能帮你建立一套属于自己的、可复用的模型能力评估方法论。

1. 为什么必须用OpenCompass做评测

很多开发者在微调完成后，习惯性地用几个简单问题手动测试一下模型输出，就认为“效果不错”。这种做法看似快捷，实则存在三个致命盲区：

• 主观偏差大：你选的5个问题，很可能恰好是模型最擅长的领域，而它在逻辑推理、数学计算或中文长文本理解上的短板完全被掩盖；
• 缺乏横向标尺：你无法回答“比基线模型提升多少？”“在行业标准榜单上排第几？”这类关键问题；
• 结果不可复现：没有统一评测流程和固定数据集，不同时间、不同人跑出的结果无法对比，团队协作和模型迭代失去依据。

OpenCompass正是为解决这些问题而生。它由上海人工智能实验室主导开发，已成国内大模型评测事实标准，具备三大不可替代优势：

• 100+权威数据集全覆盖：涵盖MMLU（大学学科知识）、CMMLU（中文多学科）、ARC（科学推理）、CEval（中文综合考试）、BBH（复杂推理）、Gaokao-Bench（高考题）等硬核 benchmark，每个数据集都经过严格清洗与标准化处理；
• 多维度能力画像：不只给一个总分，而是拆解为“语言理解”“逻辑推理”“数学能力”“代码生成”“中文素养”等子项得分，精准定位模型强项与瓶颈；
• 开箱即用的公平评测协议：统一prompt模板、统一few-shot示例、统一采样策略（如greedy decoding或temperature=0.3），确保所有模型在完全相同条件下比拼，杜绝“调参赢比赛”的水分。

ms-swift通过--eval_backend OpenCompass参数，将整个评测流程无缝接入，让你无需离开熟悉的命令行环境，就能获得一份媲美论文级的专业评测报告。

2. 环境准备与OpenCompass依赖安装

ms-swift镜像本身已预装核心依赖，但OpenCompass需额外安装其Python包及评测数据集。以下步骤在Docker容器内执行（基于你提供的镜像标签swift3.5.3）：

2.1 进入容器并升级pip

docker exec -it <container_name> /bin/bash pip install --upgrade pip

2.2 安装OpenCompass（推荐v1.2.0稳定版）

pip install opencompass==1.2.0

验证安装：运行opencompass --help，若显示帮助信息则安装成功。
注意：不要使用最新dev版本，其API可能与ms-swift当前集成层不兼容；v1.2.0经官方文档与ms-swift源码交叉验证，稳定性最佳。

2.3 下载评测数据集（自动触发）

首次运行OpenCompass评测时，它会自动从HuggingFace或ModelScope下载所需数据集。为避免评测中途卡顿，建议提前拉取核心数据集：

# 下载中文核心数据集（CMMLU, CEval, Gaokao-Bench等） opencompass download --dataset cmmlu ceval gaokao-bench # 下载英文核心数据集（MMLU, ARC, BBH等） opencompass download --dataset mmlu arc bbh

该命令会将数据集缓存至~/.cache/opencompass/目录，后续评测直接复用，无需重复下载。

2.4 验证ms-swift OpenCompass集成

运行以下命令检查ms-swift是否识别OpenCompass后端：

swift eval --help | grep "eval_backend"

输出中应包含--eval_backend {OpenCompass,EvalScope}选项，确认集成无误。

3. 评测全流程实战：从单模型到多模型对比

本节以Qwen2.5-7B-Instruct微调模型为例，演示完整评测流程。所有命令均可直接复制粘贴执行，我们聚焦“做什么”和“为什么这么做”，而非罗列所有参数。

3.1 基础单模型评测：快速获取能力全景图

假设你已完成LoRA微调，权重保存在./output/qwen25-lora/checkpoint-1000。现在要对其进行全面评测：

CUDA_VISIBLE_DEVICES=0 swift eval \ --model Qwen/Qwen2.5-7B-Instruct \ --adapters ./output/qwen25-lora/checkpoint-1000 \ --eval_backend OpenCompass \ --eval_dataset cmmlu ceval mmlu arc \ --infer_backend vllm \ --vllm_max_model_len 8192 \ --max_new_tokens 512 \ --temperature 0 \ --num_gpus 1 \ --work_dir ./eval_results/qwen25_lora_1000

关键参数解析：

• --model：指定基础模型ID，ms-swift据此加载tokenizer与模型结构；
• --adapters：指向LoRA权重路径，ms-swift自动注入适配器并合并推理；
• --eval_dataset：指定评测数据集，支持空格分隔多个数据集，此处选取中英文双语核心benchmark；
• --infer_backend vllm：启用vLLM加速推理，显著提升评测吞吐（尤其对长上下文数据集如CEval）；
• --work_dir：评测结果与中间日志的存储根目录，便于后续分析与归档。

执行后你将得到：

• 每个数据集的详细结果文件（如./eval_results/qwen25_lora_1000/outputs/cmmlu/20240615_1423/results.json）；
• 自动生成的汇总报告./eval_results/qwen25_lora_1000/summary/20240615_1423/summary.json，含各数据集准确率、平均分等；
• 可视化HTML报告（需额外生成，见4.2节）。

小技巧：首次评测建议先用小数据集（如cmmlu#100）快速验证流程，避免等待过久。确认无误后再跑全量。

3.2 多模型横向对比：科学评估微调收益

微调的价值，必须通过与基线模型的对比来体现。ms-swift支持一键评测多个模型，自动生成对比表格：

CUDA_VISIBLE_DEVICES=0 swift eval \ --model Qwen/Qwen2.5-7B-Instruct \ --adapters ./output/qwen25-lora/checkpoint-1000 \ --eval_backend OpenCompass \ --eval_dataset ceval cmmlu \ --infer_backend vllm \ --work_dir ./eval_results/comparison \ --model_alias "Qwen2.5-7B-Base" "Qwen2.5-7B-LoRA" \ --base_model Qwen/Qwen2.5-7B-Instruct \ --base_adapters "" \ --base_model_alias "Qwen2.5-7B-Base"

新增参数说明：

• --model_alias：为每个被评测模型指定易读别名，用于最终报告标题；
• --base_model&--base_adapters：显式声明基线模型（无adapter即原始模型）；
• --base_model_alias：基线模型别名。

执行完毕后，ms-swift会在./eval_results/comparison/summary/下生成comparison_report.md，内容类似：

这份报告直击核心：你的微调带来了多少真实提升？提升集中在哪些能力维度？为后续迭代提供明确方向。

3.3 自定义评测任务：聚焦业务场景

OpenCompass支持自定义数据集评测，这对业务场景至关重要。例如，你微调了一个电商客服模型，想验证其在“退换货政策解读”上的专业度：

1. 准备JSONL格式数据集（ecommerce_policy.jsonl）：

{"question": "我收到的商品有划痕，可以退货吗？", "options": ["A. 不可以", "B. 可以，7天无理由", "C. 可以，需提供照片证明"], "answer": "C"} {"question": "订单已发货，还能取消吗？", "options": ["A. 不能", "B. 能，联系客服拦截", "C. 能，自行在APP操作"], "answer": "B"}

2. 注册并评测：

swift eval \ --model Qwen/Qwen2.5-7B-Instruct \ --adapters ./output/ecommerce-lora \ --eval_backend OpenCompass \ --custom_dataset ecommerce_policy.jsonl \ --custom_dataset_type multiple_choice \ --work_dir ./eval_results/ecommerce

--custom_dataset_type指定数据格式（multiple_choice/generation/scoring），ms-swift自动匹配OpenCompass对应评测器，让业务指标真正可量化。

4. 结果深度解析与实用建议

评测不是终点，而是新洞察的起点。本节教你如何从OpenCompass输出中提炼高价值信息。

4.1 理解核心结果文件结构

ms-swift调用OpenCompass后，结果按以下层级组织：

./eval_results/ └── qwen25_lora_1000/ ├── outputs/ │ ├── cmmlu/ # CMMLU数据集原始输出 │ │ └── 20240615_1423/ │ │ ├── predictions.jsonl # 模型每题预测结果 │ │ └── results.json # 汇总统计（准确率、各学科分） │ └── ceval/ # CEval同理 └── summary/ └── 20240615_1423/ ├── summary.json # 全部数据集总览 └── detail.csv # 各数据集详细指标（可导入Excel分析）

重点关注summary.json中字段：

• "score"：该数据集最终得分（通常为准确率百分比）；
• "num_few_shot_examples"：评测使用的few-shot样本数（影响结果可比性）；
• "metric"：评分方式（accuracy/exact_match/bleu等），确认是否符合预期。

4.2 生成可视化HTML报告（强烈推荐）

OpenCompass自带报告生成工具，可将枯燥数字转化为直观图表：

cd ./eval_results/qwen25_lora_1000 opencompass report --config ./summary/20240615_1423/summary.json --html

生成report.html，打开后可见：

• 雷达图：直观展示模型在CMMLU（人文）、CEval（理工）、MMLU（英文）等维度的能力分布；
• 学科细分条形图：如CMMLU下“历史学”得分为58%，而“计算机科学”达79%，提示微调数据需加强人文领域覆盖；
• 错误案例分析：点击某题，查看模型原始输出与标准答案，快速定位典型失败模式（如混淆概念、忽略否定词）。

4.3 常见问题与避坑指南

• 问题1：评测卡在“Loading dataset...”不动
  原因：网络问题导致HuggingFace数据集下载失败。
  解法：手动下载数据集到本地，用--dataset_path /path/to/local/dataset指定；或配置HF镜像源export HF_ENDPOINT=https://hf-mirror.com。

• 问题2：vLLM报错“OutOfMemoryError”
  原因：--vllm_max_model_len设置过大，或batch size超限。
  解法：降低--vllm_max_model_len（如从8192→4096），或添加--per_device_eval_batch_size 1强制单卡单样本。

• 问题3：CEval得分远低于预期（如<40%）
  原因：CEval要求5-shot prompt，而ms-swift默认使用0-shot。
  解法：显式指定--few_shot_num 5参数，确保与标准评测协议一致。

• 问题4：多GPU评测结果不一致
  原因：OpenCompass默认启用数据并行，但ms-swift的adapter加载未同步。
  解法：评测时固定单卡（CUDA_VISIBLE_DEVICES=0），或改用--infer_backend pt（PyTorch原生）保证确定性。

5. 超越分数：构建可持续的模型评估体系

一次评测只能反映模型在特定时刻、特定数据上的表现。真正的工程化实践，需要将评测融入研发闭环：

5.1 建立评测基线库

为每个重要模型版本（如qwen25-base-v1,qwen25-sft-v2,qwen25-dpo-v3）保存其完整评测报告与summary.json。当新版本上线，自动运行对比脚本，仅输出差异项：

# 伪代码：diff_summary.py old = load_json("qwen25-sft-v2/summary.json") new = load_json("qwen25-dpo-v3/summary.json") for dataset in ["ceval", "cmmlu"]: diff = new[dataset]["score"] - old[dataset]["score"] print(f"{dataset}: {old[dataset]['score']:.1f}% → {new[dataset]['score']:.1f}% ({diff:+.1f}%)")

让每一次迭代的价值一目了然。

5.2 将评测嵌入CI/CD流水线

在GitHub Actions或GitLab CI中添加评测Job：

test-model: stage: test script: - swift eval --model $MODEL_ID --adapters $ADAPTER_PATH --eval_dataset ceval#100 --work_dir ./ci_eval - python -c "import json; r=json.load(open('./ci_eval/summary/latest/summary.json')); assert r['ceval']['score'] > 60.0, 'CEval score too low!'"

模型PR合并前必须通过核心指标门槛，从源头保障质量。

5.3 用评测驱动数据优化

当发现模型在“法律常识”子项得分偏低（CMMLU-law=42%），立即反向分析：

• 检查微调数据集中法律相关样本数量与质量；
• 人工编写100条高质量法律问答，加入下一轮微调；
• 专项评测验证改进效果。

评测不再是“交差式”的终点，而成为连接数据、训练、业务需求的主动神经。

6. 总结：评测是微调的“最后一公里”

ms-swift的OpenCompass评测能力，绝非一个简单的命令开关。它是一套完整的、工业级的模型能力验证基础设施：

• 它把模糊的“效果好”变成精确的“CEval提升3.5%”，让技术决策有据可依；
• 它把孤立的单次训练，串联成可追溯、可对比、可自动化的持续演进过程；
• 它让工程师从“调参者”升级为“模型能力架构师”，用数据定义什么是真正的好模型。

记住，没有评测的微调，就像没有地图的远征——你可能走了很远，却不知身在何处。而ms-swift与OpenCompass的结合，正为你提供了这张清晰、权威、随时可用的地图。

现在，就打开终端，运行第一条评测命令吧。你的模型，值得被世界公正地看见。

--- > **获取更多AI镜像** > > 想探索更多AI镜像和应用场景？访问 [CSDN星图镜像广场](https://ai.csdn.net/?utm_source=mirror_blog_end)，提供丰富的预置镜像，覆盖大模型推理、图像生成、视频生成、模型微调等多个领域，支持一键部署。