OpenCompass 任务执行与监控完全指南：从 run.py 启动到 Lark 实时告警

• 模型评测
• 人工智能
• 大模型
• AI 评测

本文围绕 OpenCompass 评测任务的生命周期展开：从run.py的多种启动方式、完整命令行参数解析，到任务在 infer/eval/viz 三阶段中的划分与调度原理，再到基于 Lark 机器人的实时状态上报与outputs/目录结果解读。读完本文，你将掌握如何在本地、Slurm 集群与阿里云 DLC 上正确启动评测任务，并能独立排查与监控大规模评测的完整流程。

一、任务入口：run.py 与评测配置

OpenCompass 评测任务的程序入口是仓库根目录下的 run.py，其核心逻辑极简——直接调用 opencompass/cli/main.py 中的main()函数完成参数解析、配置装配、任务调度与汇总输出。整体用法如下：

python run.py $EXP {--slurm | --dlc | None} [-p PARTITION] [-q QUOTATYPE] [--debug] [-m MODE] [-r [REUSE]] [-w WORKDIR] [-l] [--dry-run] [--dump-eval-details]

其中$EXP即任务配置。配置可以来自三种途径，get_config_from_arg()会按优先级依次解析（对应源码见 opencompass/utils/run.py）：

1. 直接指定配置文件

run.py接受一个 .py 配置文件作为任务参数，该配置必须包含datasets和models字段。典型的 demo 配置可以参考 examples/eval_base_demo.py，它通过read_base()引入 gsm8k、math 两个数据集与两个 HuggingFace 模型，然后聚合出datasets与models：

python run.py configs/eval_demo.py

从源码看，配置文件路径传入后会被Config.fromfile()读取，若配置中带有chatml_datasets字段还会额外拼接 chatml 数据集，并可配合--accelerator（vllm/lmdeploy）将模型一键切换为对应推理加速后端（见get_config_from_arg与change_accelerator的实现）。

2. 用--models/--datasets组合

不提供配置文件时，可以用命令行直接指定模型与数据集，run.py会在configs/datasets、configs/dataset_collections与configs/models等目录中按名称匹配并加载相应配置片段：

python run.py --models hf_opt_350m hf_opt_125m --datasets siqa_gen winograd_ppl

注意数据集名形如siqa_gen（数据集_推理方式），代码会将其拆分为数据集名siqa与后缀_gen，从而只挑选对应推理配置片段（如_gen对应生成式推理、_ppl对应困惑度推理）。若匹配不到或匹配到多个同名配置，match_cfg_file()会抛出带表格提示的报错，并建议使用tools/list_configs.py辅助定位。

3. HuggingFace 参数快速建模

对于 HuggingFace 系模型，还可以直接在命令行中通过一组--hf-*参数快速定义模型，再配合--datasets指定数据集：

python run.py --datasets siqa_gen winograd_ppl --hf-type base --hf-path huggyllama/llama-7b

此时 opencompass/utils/run.py 会根据--hf-type为chat或base分别构造HuggingFacewithChatTemplate或HuggingFaceBaseModel类型的模型字典，其中run_cfg.num_gpus由--hf-num-gpus决定。完整的 HuggingFace 参数说明如下：

补充：旧参数--num-gpus已弃用，opencompass/cli/main.py 中一旦检测到该参数会直接抛出 ValueError 提示改用--hf-num-gpus。此外还有--generation-kwargs、--pad-token-id、--stop-words、--min-out-len等生成相关参数可进一步定制。

二、四种启动方式

根据执行环境的不同，run.py支持四种启动方式：

• 本地直接运行：run.py $EXP，任务由LocalRunner在本机多进程并行执行；
• Slurm 集群：run.py $EXP --slurm -p $PARTITION_name，任务通过srun提交到集群；指定--slurm后-p为必填（parse_args中有断言校验）；
• 阿里云 DLC：run.py $EXP --dlc --aliyun-cfg $AliYun_Cfg，由DLCRunner提交到 PAI-DLC，需要环境预装dlc客户端并指定阿里云配置文件；
• 自定义启动：run.py $EXP，其中$EXP配置内含eval与infer字段，用户可自行定义 Partitioner 与 Runner 策略。

关于第 4 种方式，infer/eval字段分别描述推理阶段与评测阶段的划分（Partitioner）和执行（Runner）策略。以 docs/en/user_guides/evaluation.md 中的示例为参考，可在配置中直接引入SizePartitioner、SlurmRunner、OpenICLInferTask等组件：

from opencompass.partitioners import SizePartitioner, NaivePartitioner from opencompass.runners import SlurmRunner from opencompass.tasks import OpenICLInferTask, OpenICLEvalTask infer = dict( partitioner=dict(type=SizePartitioner, max_task_size=5000), runner=dict( type=SlurmRunner, max_num_workers=64, task=dict(type=OpenICLInferTask), retry=5), ) eval = dict( partitioner=dict(type=NaivePartitioner), runner=dict( type=LocalRunner, max_num_workers=32, task=dict(type=OpenICLEvalTask)), )

需要注意的是：当同时指定--slurm/--dlc且配置中已存在infer/eval字段时，运行时参数会覆盖配置中的对应字段（main.py会打印提示日志）；未提供infer/eval配置时，fill_infer_cfg()与fill_eval_cfg()会自动填充默认策略——推理阶段默认使用NumWorkerPartitioner+ 按启动方式选择的 Runner，评测阶段默认使用NaivePartitioner。

三、核心命令行参数详解

以下参数覆盖了任务调度的主要控制面（默认值与语义均核对自 opencompass/cli/main.py）：

运行-m eval或-m viz模式时必须显式给出-r（或配合--read-from-station与--station-path从结果站读取），否则main.py会直接抛出ValueError提示。

四、整体执行流程：infer → eval → viz

以默认模式-m all为例，整体执行流程如下（对应 opencompass/cli/main.py 的主流程）：

1. 读取配置：get_config_from_arg()解析出模型、数据集、评测器（evaluator）与 summarizer 等配置信息；若--dry-run开启则立即返回；
2. 划分任务并调度：评测任务主要包含三阶段——推理infer、评测eval、可视化viz。配置按mode决定哪些阶段参与：
   • 推理阶段由infer.partitioner（默认NumWorkerPartitioner）将大规模样本切分为子任务，infer.partitioner['out_dir']指向{work_dir}/predictions/；
   • 评测阶段由eval.partitioner（默认NaivePartitioner，即每个「模型-数据集」组合一个任务）产出评测任务，eval.partitioner['out_dir']指向{work_dir}/results/；
   • 单个推理与评测任务分别被抽象为OpenICLInferTask与OpenICLEvalTask，最终交给 Runner（LocalRunner/SlurmRunner/DLCRunner）并行执行；
   • 若评测任务类型为OpenICLEvalWatchTask（守护式评测），main.py会启动HeartBeatManager心跳线程与评测线程，待推理全部完成后停止心跳并汇合线程；
3. 汇总可视化：所有阶段结束后，viz 阶段读取results/中的评测结果，交由 Summarizer（未指定时默认DefaultSummarizer）生成汇总表格；开启--analysis-repeat还会额外输出重复预测分析。

值得注意的细节：每次启动都会以datetime.now()生成形如20230220_183030的时间戳目录，并将解析后的完整配置 dump 到{work_dir}/configs/{time}_{pid}.py后重新加载，以保证序列化的可靠性。

五、任务监控：Lark 机器人实时上报

OpenCompass 支持通过配置飞书（Lark）机器人实现对任务状态的实时监控。LarkReporter的底层实现见 opencompass/utils/lark.py：它通过 Webhook 以text或富文本post消息格式向群聊发送内容，任务启动、结束等关键事件都会由main.py调用LarkReporter(url).post(content)完成推送。

配置方法分三步：

1. 定义 Webhook 地址。在configs/lark.py文件中加入一行：

lark_bot_url = 'YOUR_WEBHOOK_URL'

Webhook 地址一般形如：https://open.feishu.cn/open-apis/bot/v2/hook/xxxxxxxxxxxxxxxxx。创建机器人的方法可参考飞书官方文档中「自定义机器人」的指引。

2. 在完整评测配置中继承该配置。使用mmengine.config的read_base机制：

from mmengine.config import read_base with read_base(): from .lark import lark_bot_url

3. 通过-l开启状态上报。为了避免机器人频繁推送造成打扰，状态上报默认不开启，需要按需显式指定-l（或--lark）：

python run.py configs/eval_demo.py -p {PARTITION} -l

从main.py的源码逻辑看：未指定-l时cfg['lark_bot_url']会被置为None，Runner 不会上报；指定后不仅会在任务启动时发送「任务已启动」通知，还会把lark_bot_url注入infer.runner与eval.runner的配置中，使各阶段的关键状态持续同步到群聊。

六、运行结果目录结构

所有运行结果默认存放在outputs/default/目录下，每个时间戳目录对应一次完整运行，目录结构如下：

outputs/default/ ├── 20200220_120000 ├── ... ├── 20230220_183030 │ ├── configs │ ├── logs │ │ ├── eval │ │ └── infer │ ├── predictions │ │ └── MODEL1 │ └── results │ └── MODEL1

每个时间戳目录内包含四类内容：

• configs/：存放以该时间戳为输出目录的每次运行对应的配置文件（文件名为{时间戳}_{进程ID}.py）；
• logs/：存放推理与评测阶段的输出日志，两个阶段内部再按模型分子目录；
• predictions/：存放推理产出的 json 结果，按模型分子目录；
• results/：存放评测产出的 json 结果，按模型分子目录；在--dump-eval-details（默认开启）时还会包含逐样本正确性等细节。

此外，所有不带时间戳的-r复用操作，都会通过按字典序排序选择最新的文件夹作为复用来源（对应main.py中sorted(dirs)[-1]的逻辑）。

七、结果汇总与后续步骤

评测结果由 Summarizer 组件汇总。默认情况下，main.py在 viz 阶段会使用DefaultSummarizer读取results/下的评测输出并生成可读的汇总表格；对于主观评测，则会按数据集前缀分组后逐个调用对应的主观 summarizer（summarizer配置中带function字段时走主观分支），最终产出带分组得分的汇总。

关于任务划分与执行后端的更深入内容（SizePartitioner、NaivePartitioner、LocalRunner、SlurmRunner、DLCRunner的完整参数与适用场景），可以继续阅读 Efficient Evaluation 获取系统化介绍。

• 模型评测
• 人工智能
• 大模型
• AI 评测