大模型评测框架 OpenCompass 本地部署保姆级教程：从安装到跑通 C-Eval 基准（含依赖冲突修复与判分避坑）

写作时间 ：2026 年 10 月（OpenCompass 0.5.4 / Python 3.12 / torch 2.14 CPU 版，版本迭代快，遇到差异以官方文档为准）

本文环境 ：Ubuntu 22.04+ / 无 GPU 普通开发机 / Python 3.12.3

全部命令与配置实测通过，依赖冲突和判分坑都是笔者真实踩出来的，不是编译文档。

前言：为什么你需要一个大模型评测框架

把大模型跑起来（Ollama、vLLM 等）只是第一步。真正的问题很快会来：

量化后的模型到底"变笨"了多少？
升级了推理引擎/驱动，输出质量有没有劣化？
自己部署的模型和官方跑分差多少？

这些问题靠肉眼聊天感受不出来，需要标准化的基准评测：固定题库（C-Eval、MMLU、GSM8K...）、固定参数、规则判分、输出可比的分数。OpenCompass（上海AI实验室开源）就是目前中文生态最主流的评测框架。

但新手装它容易卡在三处：

依赖冲突：装完 import 就报错（pyarrow 和 numpy 互相打架）；
配置系统：OpenCompass 用 mmengine 配置体系，写法特殊，一个环境变量写错位置就崩；
判分坑 ：跑通了，但分数莫名偏低------本文第六节用一组实测数据告诉你，评测配置写不对，同一个模型能差 8 个百分点。

完成本文你将获得：一个能对任意 OpenAI 兼容端点（本地 Ollama / vLLM / 各家 API）执行标准化评测的环境，并避开上面所有坑。

一、先搞懂架构：OpenCompass 是"考官"不是"考生"

复制代码

评测数据集(C-Eval等)          被测模型(Ollama/vLLM/任何API)
      │                              │
      ▼                              ▼
┌───────────────────────────────────────────┐
│ OpenCompass（装在你的开发机上，无需GPU）      │
│ 组卷 → 发请求(OpenAI兼容API) → 判分 → 分数表 │
└───────────────────────────────────────────┘

三个关键认知：

OpenCompass 只出题和判分，不做推理------所以装在普通 CPU 开发机上就够，不占 GPU 资源；
被测模型通过 API 接入------本地 Ollama、公司部署的服务、任何 OpenAI 兼容端点都行，换被测对象只需改两行配置；
规则判分，不依赖裁判模型------不像某些评测框架要再调一个 GPT-4 当裁判，OpenCompass 判选择题对字母、数学题对数值，完全可离线、可复现。

二、环境检查（30 秒）

整段复制进终端：

bash 复制代码

python3 --version          # 需要 ≥ 3.10
df -h $HOME | tail -1      # 磁盘需要 ≥ 5G 可用
timeout 10 curl -sI https://pypi.org/simple/ -o /dev/null -w "PyPI官方源:%{http_code}\n" || echo "PyPI官方源:不通"
timeout 10 curl -sI https://download.pytorch.org/whl/cpu/ -o /dev/null -w "PyTorch源:%{http_code}\n" || echo "PyTorch源:不通"
timeout 10 curl -sI https://hf-mirror.com -o /dev/null -w "HF镜像:%{http_code}\n" || echo "HF镜像:不通"

达标线：Python ≥ 3.10、磁盘 ≥ 5G、三个源至少 PyPI 和 HF 镜像可达（PyPI 不通就先配国内 pip 镜像；HF 镜像不通见第七节问题 5，数据集要用它下载）。

一个反直觉经验：笔者机器上清华 tuna 镜像返回 403，PyPI 官方源反而畅通------别迷信"国内一定快"，先探测再选源。

三、安装（三步，约 10 分钟）

3.1 创建独立虚拟环境

系统 Python 直接 pip 装包会被 Ubuntu 的 externally-managed-environment 保护机制拒绝，而且 OpenCompass 依赖多且版本敏感，独立环境最干净、删掉即卸载：

bash 复制代码

python3 -m venv ~/.venvs/opencompass
~/.venvs/opencompass/bin/pip install --upgrade pip -q
echo "虚拟环境创建成功"

报 ensurepip is not available？sudo apt install python3-venv 解决（仅此处需要权限）。

3.2 先装 CPU 版 torch（省 2GB 的关键顺序）

OpenCompass 依赖 torch，默认 pip 会装带 CUDA 库的 GPU 版（2GB+），但我们只当考官不推理，CPU 版（约 200M）完全够：

bash 复制代码

~/.venvs/opencompass/bin/pip install torch --index-url https://download.pytorch.org/whl/cpu -q

本机就有 GPU、想直接评测本地模型权重的读者，跳过这步直接 3.3（默认装 GPU 版）。

3.3 安装 OpenCompass

bash 复制代码

~/.venvs/opencompass/bin/pip install opencompass -q
~/.venvs/opencompass/bin/python -c "import opencompass; print('opencompass', opencompass.__version__)"

能打印版本号说明安装成功。但大概率还有一颗雷------接着看第四节，那是本教程的必修课。

四、必修课：修复 numpy / pyarrow 依赖冲突

4.1 现象

bash 复制代码

~/.venvs/opencompass/bin/python -c "import opencompass"
# ImportError: pyarrow requires NumPy 2.0 or newer, found 1.26.4

4.2 原因

包	版本要求
pyarrow 26.x（被依赖链拉进来的）	numpy ≥ 2.0
opencompass 0.5.4 官方声明	numpy < 2.0

两个要求互斥。

4.3 错误解法（很多人第一反应）

把 numpy 升到 2.x------import 确实能过，但 opencompass 的代码在 numpy 2 下运行时可能踩到已移除的 API（np.float_ 之类），评测跑到一半暴雷，比装不上更难查。

4.4 正确解法（照抄）

numpy 保持 1.26.4，pyarrow 降到支持 numpy 1.x 的 16.x：

bash 复制代码

~/.venvs/opencompass/bin/pip install "numpy==1.26.4" "pyarrow==16.1.0" -q

三条验证全过才算修好：

bash 复制代码

~/.venvs/opencompass/bin/pip check                                    # 期望: No broken requirements found.
~/.venvs/opencompass/bin/python -c "import opencompass; print('OK')"   # 期望: OK
~/.venvs/opencompass/bin/opencompass --help > /dev/null && echo "CLI OK"  # 期望: CLI OK

以后勿动：不要随手 pip install -U numpy，冲突会复发；装新包若提示 numpy 冲突，回这节重刷一遍即可。

五、跑通第一次评测：对本地 Ollama 跑 C-Eval

前提：本地有任意 OpenAI 兼容服务在跑（以 Ollama + qwen2.5:7b 为例，其他端点同理）。

5.1 配置数据集镜像

OpenCompass 的评测数据托管在 HuggingFace，国内直连不通，设镜像（一劳永逸写进 bashrc）：

bash 复制代码

echo 'export HF_ENDPOINT=https://hf-mirror.com' >> ~/.bashrc
source ~/.bashrc

数据集首次运行自动下载 到 ~/.cache/opencompass/（C-Eval 仅 3.9M），之后离线可用。

5.2 写最小评测配置

创建 my_first_eval.py，内容照抄（只需按需改 path 和 openai_api_base 两行）：

python 复制代码

from mmengine.config import read_base

with read_base():
    from opencompass.configs.datasets.ceval.ceval_gen import ceval_datasets
from opencompass.models import OpenAI

models = [
    dict(
        type=OpenAI,
        path='qwen2.5:7b',                                   # 被测模型名
        key='ENV',                                           # 从环境变量 OPENAI_API_KEY 读取
        openai_api_base='http://127.0.0.1:11434/v1/chat/completions',  # 注意：必须写完整端点！
        query_per_second=1,                                  # 本地 CPU 建议 1
        max_seq_len=16384,
        temperature=0,                                       # 基准评测固定 0，保证可复现
        max_out_len=512,                                     # 勿低于 512（原因见第六节）
        retry=3,
    ),
]

# 冒烟只跑 2 个科目；全量 52 科删掉下面这行过滤即可
datasets = [d for d in ceval_datasets if d['name'] in {'computer_network', 'operating_system'}]

运行：

bash 复制代码

export OPENAI_API_KEY=ollama    # Ollama 不校验 key，但必须设；对接其他平台填真实 key
~/.venvs/opencompass/bin/opencompass my_first_eval.py --debug

看到 Starting inference process... 和进度条就说明链路通了。结果在 ./outputs/default/summary/ 下，形如：

复制代码

| dataset                  | version | metric   | mode | qwen2.5:7b |
| ceval-computer_network   | db9ce2  | accuracy | gen  |    63.16   |
| ceval-operating_system   | 1c2571  | accuracy | gen  |    78.95   |

本节最大的坑 ：openai_api_base 必须写完整端点（含 /chat/completions） ！写习惯性的 http://.../v1 会得到一排 404 page not found，报错信息完全看不出是 URL 的锅------这是 OpenCompass 与 openai SDK 的行为差异，新手必踩。

另一个坑：配置里不要写 import os 读环境变量 ，mmengine 会把配置 dump 成文件再重读，模块对象写进去直接 SyntaxError。读 API key 用本文的 key='ENV' 模式。

5.3 换被测对象

改两行配置即可，环境零改动：

python 复制代码

path='deepseek-r1:7b',                                       # 换模型
openai_api_base='http://your-vllm-host:8000/v1/chat/completions',  # 换平台（vLLM/自建服务/云API）

六、进阶避坑：为什么你的分数可能虚低 8 个百分点

这是笔者认为本文最值钱的一节。同样的模型、同样的题，仅评测配置不同，总分能差 7.9 个百分点。

笔者用 Ollama + Qwen2.5-7B 跑 C-Eval 四个科目（76 题）做过对照实验，先看结果：

配置	判分后处理	总正确率	无效输出
V1：max_tokens=128	`first_capital_postprocess`	75.0%	10 题
V2：max_tokens=512	`first_option_postprocess`	82.9%	0 题

两个坑分别拆解：

坑 1：max_tokens 太小，把推理截断了

7B 级别的模型遇到计算题（TCP 滑动窗口、RTT 计算这类）会自发进行长推理（CoT），128 token 根本写不完，答案还没输出就被掐断。逐题检查发现 7 题的输出结尾是这样的：

复制代码

...未被确认的字节数，即8500 + 300 =     ← 到这里被截断

结论：max_out_len 一律 ≥ 512。

坑 2：判分后处理被协议缩写污染

C-Eval 默认的 first_capital_postprocess 是"取输出中第一个大写字母"。但模型遇到不会的题会写解题过程，于是：

模型输出"对于UDP 协议，应该..." → 取到 U，标准答案 D
模型输出"TCP 连接的发送窗口..." → 取到 T
最冤的一题，模型明明答对了："所以正确答案是：D. 应用层"，但 U 开头先出现 → 判错

解法：换成 first_option_postprocess，它按优先级匹配"答案是X/正确答案是X/故选X"等显式模式，找不到才回退裸字母。在配置里加两行：

python 复制代码

from opencompass.utils.text_postprocessors import first_option_postprocess

# 加载数据集后，覆盖默认判分后处理
for d in datasets:
    d['eval_cfg']['pred_postprocessor'] = dict(type=first_option_postprocess, options='ABCD')

注意上面代码片段中 for d in datasets 要接在你的 datasets = [...] 定义之后。

实用自检方法：盯住"无效输出率"

逐题结果在 outputs/default/results/<模型名>/<科目>.json，每题有 origin_prediction（原始输出）和 predictions（提取的答案）。提取后不在 ABCD 里就是"无效输出"，无效输出率 > 5% 说明判分链路有问题，先修判分再相信分数------否则你做的版本对比，差异可能来自评测系统而不是模型。

七、常见问题排查表（全部实测）

#	现象	原因	解决
1	`ImportError: pyarrow requires NumPy 2.0 or newer`	依赖冲突	第四节 4.4
2	`pip check` 报 opencompass requires numpy<2	numpy 被升到 2.x	回退 numpy1.26.4 + pyarrow16.1.0
3	请求全部 `404 page not found`	`openai_api_base` 没写到 `/chat/completions`	补全端点 URL
4	`ValueError: OpenAI API key is not set`	未设环境变量	`export OPENAI_API_KEY=xxx`（Ollama 也得设）
5	数据集下载卡住	HF 被墙	确认 `HF_ENDPOINT=https://hf-mirror.com`；仍不通就拷贝 `~/.cache/opencompass/`
6	配置内 `import os` 后运行报 SyntaxError	mmengine dump/re-read 机制	key 用 `'ENV'` 模式；动态值文本替换生成配置
7	对 Ollama 评测中途 kill 后，请求一直超时	Ollama 残留请求排队	`pkill -x ollama` 后重启 `ollama serve`
8	分数莫名偏低	见第六节两大坑	max_out≥512 + first_option_postprocess
9	想看模型每题到底答了什么	-	`results/<模型>/<科目>.json` 的 details 字段

八、常用命令与数据集速查

bash 复制代码

# 跑评测（-w 自定义结果目录，--debug 冒烟，-r 断点续跑）
~/.venvs/opencompass/bin/opencompass my_first_eval.py -w ~/oc_results

# 看内置数据集（238 个）
ls ~/.venvs/opencompass/lib/python3.12/site-packages/opencompass/configs/datasets/

# 彻底卸载
rm -rf ~/.venvs/opencompass ~/.cache/opencompass

换评测集只改配置里的 import 行：

基准	import 路径	测什么
C-Eval	`ceval.ceval_gen`	中文综合 52 科
CMMLU	`cmmlu.cmmlu_gen_c13365`	中文综合 67 科
GSM8K	`gsm8k.gsm8k_0shot_v2_gen_17d799`	数学推理
MMLU	`mmlu` 目录	英文综合
HumanEval	`humaneval.humaneval_gen`	代码生成（需沙箱）

判分方式随数据集而异（选择题对字母/数学题抽数值/代码跑测试），各数据集自带 eval 配置，一般不用改。

总结

本文完整走通了"裸机 → 可用的大模型评测环境"：

安装顺序有讲究：venv → CPU 版 torch（省 2GB）→ opencompass；
依赖冲突是必修课 ：numpy1.26.4 + pyarrow16.1.0 是目前 verified 的组合，别升 numpy 2.x；
两个配置大坑 ：openai_api_base 要写完整端点；配置里不能 import os；
判分坑最隐蔽 ：max_tokens≥512 + first_option_postprocess，否则分数虚低------实测差 7.9 个百分点；
一个健康度指标：无效输出率 >5% 时先修判分再谈分数。

如果这篇帮你跑通了第一次大模型基准评测，点赞收藏关注一键三连。评论区欢迎贴出你的评测分数和机器配置------下一篇计划写「用 OpenCompass 对 Qwen/DeepSeek 全家桶做横向对比」，关注不迷路。

参考链接

OpenCompass 官方文档：https://opencompass.readthedocs.io
OpenCompass GitHub：https://github.com/open-compass/opencompass
C-Eval 官网：https://cevalbenchmark.com
HF 镜像站：https://hf-mirror.com

转载请注明出处。写作于 2026-10，软件版本迭代较快，如与最新版本有出入，以官方文档为准。