用 OpenCompass 配置并运行一次 GSM8K 模型评测

OpenCompass 是一个面向大语言模型的评测框架，它把「模型接入」「数据集加载」「推理执行」「指标计算」这几件事拆成可组合的配置项，让同一套评测设置可以被保存、复用和版本管理。它适合需要定期对比多个模型表现、或者要把评测流程固化进研发流水线的团队；如果你只是想临时看一眼某个模型在某份数据上的得分，它同样提供了命令行入口。本文以 GSM8K 演示数据集为例，完整走一遍从配置密钥到读取结果的过程，涉及的评测对象与数据集名称均以仓库中已有的配置为准。站内也有对应的工具条目可供参考：OpenCompass。

需要先说明一点：本文讲的是「怎么把一次评测跑起来并读懂产物」，不是「哪个模型更强」。评测结果高度依赖数据集版本、提示模板、采样参数和并发设置，任何跨文章的分数对比都要谨慎。

准备工作

环境与仓库

开始之前需要完成安装与环境配置，并进入 OpenCompass 仓库根目录。后续所有命令都假定当前工作目录是仓库根目录，配置文件路径、数据集路径和工具脚本路径都是相对这个根目录解析的。如果不在根目录执行，最常见的报错就是找不到配置模块或数据集文件。

本文的示例通过 API 调用模型，因此不需要本地 GPU。但运行环境必须能够访问对应的 API 服务，账号凭据也必须对该服务有效。此外，首次运行通常需要从网络下载数据集，网络不通或下载被拦截时会卡在数据准备阶段。

配置 API 密钥

示例使用的模型配置文件位于 opencompass/configs/models/openai/gpt_6_astra.py。打开它之后，密钥有两种写法。

方式一：直接写在模型配置里。适合本地临时测试，缺点是密钥会进入配置文件，一旦提交到版本库就会泄露。

from opencompass.models import OpenAISDKResponse

models = [
    dict(
        type=OpenAISDKResponse,
        abbr='gpt-6-astra-response',
        path='gpt-6-astra',
        key='your-api-key',  # 其余参数保持不变
    )
]

方式二：从环境变量读取。这是更推荐的做法。先在 shell 中设置变量：

export OPENCOMPASS_API_KEY="your-api-key"

然后在模型配置中读取该变量：

import os
from opencompass.models import OpenAISDKResponse

models = [
    dict(
        type=OpenAISDKResponse,
        abbr='gpt-6-astra-response',
        path='gpt-6-astra',
        key=os.getenv('OPENCOMPASS_API_KEY'),  # 其余参数保持不变
    )
]

两种写法只改 key 这一项，其余字段保持原样。示例中的 abbr 是这次评测中模型的简称，会出现在结果目录和汇总表里，建议取一个能区分模型与接入方式的名字。

操作步骤

第一步：编写评测配置文件

仓库已经提供了模型配置和 GSM8K 演示数据集配置，把它们组合起来即可。新建 quick_start_eval.py：

# quick_start_eval.py
from mmengine.config import read_base

with read_base():
    from opencompass.configs.datasets.demo.demo_gsm8k_chat_gen import \
        gsm8k_datasets
    from opencompass.configs.models.openai.gpt_6_astra import \
        models as gpt6_astra_models

datasets = gsm8k_datasets
models = gpt6_astra_models

这里的关键是 read_base() 上下文：它负责把被导入模块里的配置项合并进来，然后在上下文之外用 datasets 和 models 两个变量指向合并后的结果。这种写法让「引用现成配置」和「在本地覆盖参数」可以共存——你可以在 with 块之后继续修改 models 里的字段，而不必复制整份配置。

为什么优先用配置文件而不是命令行？因为配置文件本身就是一份可存档的评测记录：它保留了这次评测用的模型、数据集、提示模板和采样参数，可以纳入版本控制，下次复现时直接重跑同一个文件即可。命令行更适合快速试一下。

第二步：用 --dry-run 预检

在真正调用模型之前，先做一次配置解析检查：

opencompass quick_start_eval.py --dry-run

--dry-run 不会执行模型推理，它只验证配置文件能否被正确解析，并展示推理任务将如何被切分。这一步能提前暴露导入路径错误、配置项拼写错误、数据集与模型不匹配等问题，避免等到真正跑起来才在推理中途失败。任务切分信息也值得看一眼：它决定了后续并发执行时的任务粒度。

第三步：运行完整评测

配置检查通过后，执行完整流程：

opencompass quick_start_eval.py \
    --work-dir outputs/quick_start_config \
    --debug

--work-dir 指定输出根目录，每次运行都会在其中新建一个带时间戳的子目录。--debug 的作用是让任务在当前进程内顺序执行，并把日志直接打印到终端。它适合初次排查问题，因为所有输出都在眼前，不需要去翻日志文件。正式的批量评测通常不需要加这个参数——顺序执行会显著拉长总耗时。

第四步（可选）：直接用命令行跑同一套评测

如果不想创建配置文件，也可以用命令行参数直接指定模型和数据集。配置名取自 opencompass/configs/models 和 opencompass/configs/datasets 下的文件名，去掉 .py 后缀，分别传给 --models 和 --datasets：

opencompass \
    --models gpt_6_astra \
    --datasets demo_gsm8k_chat_gen \
    --work-dir outputs/quick_start_cli \
    --debug

不确定配置名怎么写时，用列表脚本查询：

python tools/list_configs.py gpt_6_astra gsm8k

这个脚本会按关键字匹配并列出可用的配置名，比手动翻目录可靠。命令行方式适合快速验证，但遇到以下情况就应该改用配置文件：需要组合多个模型与多个数据集、需要调整模型并发数或具体请求参数、需要自定义执行策略。这些细粒度控制在命令行里表达起来既冗长又容易出错。

一个完整示例

下面把上面的步骤串成一次可复现的最小流程。假设已经完成安装、进入仓库根目录，并且 shell 中已设置好 OPENCOMPASS_API_KEY。

1. 确认密钥已生效。

echo $OPENCOMPASS_API_KEY

输出非空即说明变量已设置。若为空，重新执行 export 命令，或检查是否在新开的终端窗口里丢失了变量。

2. 确认模型配置读取的是环境变量。打开 opencompass/configs/models/openai/gpt_6_astra.py，确认 key 字段写的是 os.getenv('OPENCOMPASS_API_KEY')，而不是硬编码的字符串。

3. 创建 quick_start_eval.py，内容与上文第一步给出的代码一致。

4. 预检配置。

opencompass quick_start_eval.py --dry-run

观察输出中解析出的模型列表与数据集列表是否符合预期，以及任务切分是否合理。这一步不产生任何 API 调用费用。

5. 正式运行。

opencompass quick_start_eval.py \
    --work-dir outputs/quick_start_config \
    --debug

首次运行会下载数据集，耗时取决于网络状况。终端会持续输出推理进度。

6. 查看结果。进入 outputs/quick_start_config，找到最新创建的时间戳目录，按下一节说明的四个子目录逐一检查。

结果目录里有什么

每次运行都会在 --work-dir 下生成一个时间戳目录，其中主要包含四类产物：

子目录	内容	用途
`configs/`	本次运行实际生效的配置快照	复现与审计，确认这次到底用了哪些参数
`predictions/`	逐样本的模型输出	人工抽查模型回答，定位异常样本
`results/`	评测器计算出的指标与明细	查看分数构成，而不只是一个总分
`summary/`	CSV、Markdown 等格式的最终汇总	直接用于报告或表格对比

排查问题时，建议的顺序是：先看 summary/ 确认评测是否正常完成，再看 results/ 确认指标是否合理，最后到 predictions/ 抽查具体样本。如果怀疑配置写错了，回到 configs/ 里的快照，它记录的是实际生效的值，而不是你以为生效的值。

注意事项

执行失败时先看终端输出。如果加了 --debug，日志直接打在终端；否则去时间戳目录里找日志文件。多数失败集中在三类原因：密钥无效或环境变量未生效、网络无法访问 API 服务或无法下载数据集、配置导入路径写错。
--debug 不是正式评测的默认选项。它让任务在当前进程内顺序执行，便于观察，但会牺牲吞吐。确认流程跑通后，正式批量评测应去掉该参数。
命令行方式有适用边界。它适合快速验证，不适合需要细粒度控制的场景。多模型多数据集组合、并发调整、请求参数定制、执行策略自定义，都应写进配置文件。
密钥不要硬编码进版本库。直接写在配置里的方式仅限本地临时测试；需要提交或共享的配置一律走环境变量。
首次运行依赖网络。数据集需要下载，API 服务需要可达。离线环境或受限网络下，需要提前准备好数据与网络通路。
模型名称、数据集版本、接口参数与配额可能随版本变化，具体以 OpenCompass 仓库与所接入服务商的当前信息为准。本文示例中的配置名与字段请以你本地仓库的实际内容核对后再使用。

跑通这一页之后，下一步值得读的是工作流与核心概念部分，理解配置是如何被组装、任务是如何被调度、评测器是如何被选中的；再往后可以学习如何用配置文件组织一次完整的、可复现的评测流程，把单次试跑扩展成可重复执行的评测方案。