OpenCompass：一站式大模型评估平台核心原理与实战指南-平芜编程栈

1. 项目概述：OpenCompass，你的大模型“体检中心”

如果你正在研究或使用大语言模型，无论是开源的Llama、Qwen，还是闭源的GPT-4、Claude，一个绕不开的核心问题就是：这个模型到底有多强？它的数学推理能力如何？代码生成水平怎样？长文本理解是否过关？面对市面上层出不穷的模型和版本，单靠“感觉”或者零散的测试已经远远不够了。你需要一个系统、全面、可复现的评估体系。

这就是OpenCompass诞生的初衷。简单来说，它就像是大语言模型的“专业体检中心”和“统一高考考场”。它不是一个模型，而是一个一站式的大模型评估平台。它的目标是为业界提供一个公平、开放、可复现的基准测试框架，让任何模型的性能都能被量化、被比较。

我最初接触OpenCompass是因为需要对比几个不同微调版本的InternLM模型在特定任务上的表现。手动编写测试集、设计prompt、处理输出、统计准确率……这套流程不仅繁琐，而且难以保证评估标准的一致性，结果也缺乏公信力。OpenCompass的出现，把我们从这种重复劳动中解放了出来。它预置了海量的评测数据集（从经典的MMLU、C-Eval到前沿的NeedleBench、SciCode），支持从开源到API的各种模型接入，并且用一套优雅的配置系统管理整个评估流程。你可以把它看作是大模型领域的“SPEC CPU”或“3DMark”，只不过测试对象从硬件变成了AI。

对于研究者，你可以用它来客观衡量自己工作的改进；对于开发者，你可以用它来为项目选型，找到最适合的模型；对于学习者，你可以通过复现评估过程，深入理解不同模型的能力边界。接下来，我将以一个实践者的角度，带你从零开始，深入拆解OpenCompass的核心设计、实战用法以及那些官方文档里不会写的“踩坑”经验。

2. 核心设计哲学：为什么是OpenCompass？

在深入命令行之前，理解OpenCompass的设计思路至关重要。这能帮你更好地使用它，甚至在需要时扩展它。它的核心优势可以概括为四个词：全面、高效、灵活、可复现。

2.1 模块化架构：像搭积木一样设计评估任务

OpenCompass的整个评估流程被抽象为几个清晰的模块，这种设计让复杂任务的配置变得直观。

模型 (Model): 这是被评估的对象。OpenCompass通过“Wrapper”来封装不同来源的模型。比如，HuggingFaceModel封装本地HF模型，OpenAI封装GPT系列API，LMDeployModel则对接LMDeploy推理引擎。你不需要关心模型内部如何加载和推理，只需要在配置中指定类型和路径（或API Key）。

数据集 (Dataset): 这是考卷。每个数据集配置定义了如何读取数据、如何构造输入（Prompt）。例如，gsm8k_gen配置会从GSM8K数据集中读取数学应用题，并按照指定的few-shot模板构造出给模型的提问。

评测器 (Evaluator): 这是阅卷老师。它负责将模型输出的答案与标准答案进行比对，并给出分数。最常见的是GenEvaluator（生成式评测），它通过字符串匹配或正则表达式提取模型输出中的关键信息（如选择题的选项字母、数学题的最终数字）来进行评分。对于更复杂、需要主观判断的任务，则可以使用LLMEvaluator，即用另一个大模型（如GPT-4）作为裁判来打分。

运行器 (Runner): 这是考场调度系统。它负责最复杂的部分——任务切分与资源调度。当你评估一个模型在多个数据集上的表现时，会产生成千上万个独立的评测样本。Runner（默认是DLCRunner）会自动将这些样本任务拆分成小块，分配到可用的GPU上进行并行计算，极大地提升了评估效率。

这种“模型-数据-评测”解耦的设计，意味着你可以随意组合。想用GPT-4当裁判来评估Qwen在创意写作上的表现？或者想用vLLM加速InternLM在50个数据集上的评测？只需要在配置文件中像搭积木一样组合相应的模块即可。

2.2 分布式评估：让“大海捞针”变成并行计算

评估大模型，尤其是用大量数据集进行全面测评，是一个计算密集型任务。如果串行执行，可能耗时数天甚至数周。OpenCompass的分布式评估是其杀手锏。

它的核心思想是“数据并行”。假设你要评估一个模型在包含10万条样本的数据集上，你有4张GPU。OpenCompass的Runner会自动将10万个样本分成4个任务包（每个约2.5万条），然后同时提交给4个GPU上的工作进程（Worker）去执行。每个Worker独立地加载模型、推理、评分，最后将结果汇总。

这个过程对用户几乎是透明的。你只需要在命令行通过--max-num-worker指定使用的GPU数量，或者通过配置文件设置runner.max_num_workers。OpenCompass会处理好任务队列、容错重启和结果收集。在我实际测试中，用4卡A100评估一个7B模型在MMLU（约1.4万题）上的表现，从数小时缩短到了不到一小时。

注意：这里的--max-num-worker指的是数据并行的进程数。还有一个参数--hf-num-gpus（或在模型配置中设置num_gpus）用于模型并行，即当单个GPU放不下整个模型时，将其拆分到多个GPU上。两者概念不同，不要混淆。对于大多数7B/13B模型，单卡即可加载，只需使用--max-num-worker进行数据并行加速。

2.3 可复现性：一切皆配置

科研和工程都强调可复现性。OpenCompass通过Python配置文件（通常是.py文件）来记录一次评估的所有细节：用了哪个模型版本、什么参数、哪些数据集、怎样的prompt模板、甚至随机种子。只要你保存了这个配置文件，任何时候、在任何机器上重新运行，理论上都应该得到完全相同的结果。

这彻底改变了以往“写个脚本跑一下，结果自己都忘了怎么来的”的混乱状态。你的每一次评估都是一个完整的实验记录，可以归档、可以分享、可以接受同行检验。OpenCompass社区维护的 CompassRank 排行榜上的结果，都附带了可复现的配置，这极大地增强了其公信力。

3. 从零开始的实战指南

理论说得再多，不如动手跑一遍。我们从一个最简单的评估开始，逐步深入到复杂场景。

3.1 环境搭建：避坑第一站

官方推荐用Conda管理环境，这是非常明智的，可以避免复杂的依赖冲突。

# 创建并激活环境 conda create -n opencompass python=3.10 -y conda activate opencompass

接下来是安装OpenCompass。这里有个关键选择：基础安装还是完整安装？

# 基础安装（核心功能） pip install -U opencompass # 完整安装（支持更多数据集，推荐） pip install -U "opencompass[full]" # 如果你计划使用LMDeploy或vLLM进行加速推理，需要单独安装 # 注意：这些加速框架通常互斥，建议为它们创建独立的环境 pip install -U "opencompass[lmdeploy]" # 或 pip install -U "opencompass[vllm]" # 如果需要评估OpenAI等API模型 pip install -U "opencompass[api]"

我的实操心得：强烈建议初次安装时选择[full]。很多有趣的数据集（如需要代码执行的HumanEval）依赖额外的库，基础安装不包含它们，等到运行时再报错会非常麻烦。另外，LMDeploy和vLLM的安装确实容易有CUDA版本、PyTorch版本冲突，按照官方文档的建议，为它们准备独立的环境是最稳妥的做法。

3.2 数据准备：三种方式，按需选择

评估需要数据。OpenCompass提供了三种数据获取方式：

1. 离线下载（最稳定）：

wget https://github.com/open-compass/opencompass/releases/download/0.2.2.rc1/OpenCompassData-core-20240207.zip unzip OpenCompassData-core-20240207.zip -d data/

这会下载一个核心数据集包到data/目录。优点是稳定、快速，适合内网或网络不佳的环境。缺点是数据包较大（几个GB），且可能不是最新的全部数据集。

2. 运行时自动下载（最方便）：这是OpenCompass 2.0后大力推荐的方式。你不需要手动下载任何数据，在首次运行某个数据集的评估时，OpenCompass会自动从其服务器下载所需文件到缓存目录（通常是~/.cache/opencompass）。只需在命令后加上--dry-run参数，即可触发下载而不真正运行评估。

opencompass --models hf_internlm2_5_1_8b_chat --datasets mmlu_gen --dry-run

注意事项：确保你的网络能够访问相关资源。部分数据集源可能在海外，国内用户可能会遇到下载慢或失败的情况。

3. 使用ModelScope数据集源（适合国内用户）：对于国内用户，ModelScope是一个很好的替代数据源。

pip install modelscope export DATASET_SOURCE=ModelScope

设置环境变量后，OpenCompass会尝试从ModelScope加载数据集。这种方式的好处是通常速度更快，且不占用本地大量存储（按需加载）。但并非所有数据集都已在ModelScope上架。

3.3 你的第一次评估：CLI快速体验

让我们用命令行完成一次最简单的评估，感受一下流程。假设我们想测试internlm2-chat-1.8b这个聊天模型在小学数学题（GSM8K）上的表现。

opencompass --models hf_internlm2_5_1_8b_chat --datasets demo_gsm8k_chat_gen

分解一下这个命令：

--models hf_internlm2_5_1_8b_chat: 指定要评估的模型。hf_前缀表示这是HuggingFace格式的模型，internlm2_5_1_8b_chat是OpenCompass预定义的一个模型配置名，指向internlm/internlm2_5-1_8b-chat这个模型。
--datasets demo_gsm8k_chat_gen: 指定要使用的数据集。demo_gsm8k_chat_gen是一个GSM8K数据集的演示配置，数据量较小，适合快速跑通流程。_gen后缀表示这是一个生成式任务的配置。

运行后，你会看到终端开始输出日志：加载模型、加载数据、任务分割、启动Worker、开始推理、评分……最终，结果会以表格形式打印在终端，并同时保存到outputs/default/目录下的一个以时间戳命名的文件夹中，里面包含详细的评分结果和模型的所有输出。

如果想评估API模型，比如GPT-4，同样简单：

export OPENAI_API_KEY='你的API密钥' opencompass --models gpt-4o-2024-05-13 --datasets demo_gsm8k_chat_gen

3.4 进阶评估：使用Python配置文件

CLI适合简单任务，但真正的力量在于配置文件。通过编写一个.py配置文件，你可以实现极其复杂和定制化的评估流程。我们来看一个标准配置文件的骨架：

# eval_demo.py from opencompass.openicl.icl_prompt_template import PromptTemplate from opencompass.openicl.icl_retriever import ZeroRetriever from opencompass.openicl.icl_inferencer import GenInferencer from opencompass.datasets import GSM8KDataset from opencompass.utils.text_postprocessors import first_capital_postprocess from opencompass.summarizers import GSM8KSummarizer # 1. 定义数据集 gsm8k_reader_cfg = dict(...) # 数据读取配置 gsm8k_infer_cfg = dict( prompt_template=dict( type=PromptTemplate, template=dict(round=[ # 多轮对话prompt模板 dict(role='HUMAN', prompt='Question: {question}\nLet\'s think step by step.'), dict(role='BOT', prompt='Answer:'), ]), ), retriever=dict(type=ZeroRetriever), # 零样本学习 inferencer=dict(type=GenInferencer), # 生成式推理 ) gsm8k_eval_cfg = dict( evaluator=dict(type=GenEvaluator), # 生成式评分器 pred_postprocessor=dict(type=first_capital_postprocess), # 答案后处理 ) gsm8k_datasets = [] for split in ['train', 'test']: gsm8k_datasets.append( dict( type=GSM8KDataset, path='./data/gsm8k', abbr='gsm8k-' + split, reader_cfg=gsm8k_reader_cfg, infer_cfg=gsm8k_infer_cfg.copy(), eval_cfg=gsm8k_eval_cfg.copy(), ) ) # 2. 定义模型 models = [ dict( type=HuggingFaceCausalLM, abbr='internlm2-1.8b-chat-hf', path='internlm/internlm2-chat-1_8b', tokenizer_path='internlm/internlm2-chat-1_8b', model_kwargs=dict(...), batch_size=16, run_cfg=dict(num_gpus=1), # 每份副本用1张GPU ) ] # 3. 运行配置 work_dir = './outputs/' runner = dict( type='DLCRunner', task=dict(type='OpenICLInferTask'), # 推理任务 max_num_workers=4, # 同时使用4个Worker进行数据并行 ) # 4. 汇总器（生成报告） summarizer = dict(type=GSM8KSummarizer)

然后运行这个配置：

opencompass eval_demo.py

通过配置文件，你可以精细控制每一个环节：prompt的措辞、推理的参数（temperature, max_tokens）、批处理大小、甚至自定义的数据后处理逻辑。这是进行严肃研究和对比实验的必备技能。

4. 核心功能深度解析与实战技巧

掌握了基础操作后，我们深入几个核心且实用的功能，这些是提升你评估效率和质量的关键。

4.1 加速推理：LMDeploy与vLLM集成

当评估的模型很大或数据量很多时，推理速度是瓶颈。OpenCompass原生支持集成LMDeploy和vLLM这两个高性能推理框架。

为什么需要它们？

HuggingFace Transformers：通用性强，但推理时为了灵活性牺牲了部分性能，尤其是生成任务中的注意力计算和KV缓存管理不够高效。
LMDeploy：由上海人工智能实验室开发，针对其自家的InternLM系列有深度优化，同时通用性也很好。它支持TurboMind推理引擎，具有极高的吞吐量。
vLLM：由加州大学伯克利分校团队开发，以其高效的PagedAttention算法闻名，特别擅长处理长序列和批量推理，能极大减少内存碎片，提升GPU利用率。

如何使用？首先，确保你在安装了对应加速框架的环境中（如pip install "opencompass[lmdeploy]"）。

方式一：CLI快速切换

# 使用LMDeploy后端 opencompass --models hf_internlm2_5_1_8b_chat --datasets mmlu_gen -a lmdeploy # 或使用vLLM后端 opencompass --models hf_llama3_8b_instruct --datasets mmlu_gen -a vllm

-a或--accelerator参数指定推理后端。

方式二：在模型配置中指定在配置文件的模型定义里，可以显式指定后端：

models = [ dict( type=LMDeployModel, # 或 VLLMModel abbr='internlm2-1.8b-chat-lmdeploy', path='internlm/internlm2-chat-1_8b', engine_config=dict(...), # 传递引擎特有参数，如tp_size（张量并行） gen_config=dict(...), batch_size=32, # 通常可以设置比HF更大的批处理大小 run_cfg=dict(num_gpus=1), ) ]

我的实测对比：在单卡A100上评估InternLM2-7B，使用vLLM后端相比默认的HF后端，在MMLU数据集上的整体吞吐量（tokens/sec）提升了约2-3倍，显存占用也更平稳。对于批量评估任务，加速效果非常明显。

重要提示：不是所有模型都兼容所有后端。例如，一些使用了特殊Attention机制的模型可能在vLLM上需要额外适配。建议先从官方支持的模型列表开始尝试。此外，加速后端可能会对模型输出的精确性有极其微小的影响（源于不同的计算实现），对于追求绝对可复现性的学术研究，需要留意这一点。

4.2 主观与复杂评估：LLM即裁判（LLM-as-a-Judge）

很多能力无法用简单的字符串匹配来评分，比如创意写作、对话质量、安全性、代码可读性等。OpenCompass的LLMEvaluator引入了“大模型当裁判”的范式。

其原理是：准备一个“裁判”模型（通常是能力更强的模型，如GPT-4），将待评估模型的输出和问题一起，按照设计好的评分规则（Rubric）构造prompt，交给裁判模型打分。

配置示例：

from opencompass.openicl.icl_evaluator import LMEvaluator eval_cfg = dict( evaluator=dict( type=LMEvaluator, prompt_template=dict( # 给裁判模型的指令 type=PromptTemplate, template='''请根据以下标准对回答进行评分（1-5分）： 标准：相关性、创造性、流畅性。 问题：{question} 回答：{prediction} 请先输出你的推理过程，最后一行必须为“评分：X”，其中X是1-5的整数。''' ), judge_model=dict( # 裁判模型配置 type=OpenAI, path='gpt-4', key='ENV', # 从环境变量读取API KEY query_per_second=1, # 限速 max_seq_len=2048, ), retry_limit=10, # API调用失败重试次数 ) )

应用场景：

创意写作评估：让GPT-4为不同模型生成的故事在情节、文笔、创意上打分。
安全性评估：构造一些敏感或诱导性问题，用裁判模型判断回答是否安全、合规。
代码竞赛题评估：除了单元测试（pass@k），还可以让裁判模型评估代码的简洁性、可读性。

成本与效率考量：使用GPT-4等商用API作为裁判成本较高。一个折中的方案是使用强大的开源模型（如Qwen-Max、GLM-4）作为裁判，通过OpenCompass的API模型接口接入。虽然效果可能略逊于顶级闭源模型，但成本可控，且整个过程依然可复现。

4.3 长文本评估：NeedleInAHaystack与RULER

大模型的上下文窗口越做越大，从4K、32K到现在的1M甚至更长。如何评估其长文本能力？OpenCompass集成了两个标杆性的长文本评估基准。

1. NeedleInAHaystack（大海捞针）：这个测试的思想非常巧妙。它将一个关键事实（“针”）插入到一篇很长的文档（“干草堆”）中，然后向模型提问这个关键事实。通过改变“针”插入的位置（开头、中间、结尾）和文档的长度，可以系统地测试模型在不同位置、不同长度下的信息提取和记忆能力。 OpenCompass的配置让运行这个测试变得很简单：

opencompass --datasets needle --models hf_your_long_context_model

你需要确保你的模型配置支持长上下文（设置了正确的max_seq_len）。

2. RULER（Rule-based Long-context Evaluation）：这是一个更系统、更全面的长文本评估套件。它不仅仅测试信息检索，还测试多跳推理（需要关联文档中多处信息）、聚合（总结多个信息点）和问答能力。RULER通过一套灵活的配置，可以生成不同难度、不同任务类型的长文本评估样本。

# 运行RULER基准测试 opencompass --datasets ruler --models hf_your_long_context_model

长文本评估的实操要点：

显存警告：评估长文本模型时，显存消耗巨大。即使是7B模型，处理32K长度的序列也可能需要40GB以上的显存。务必根据你的硬件调整批次大小（batch_size）和序列长度。
推理后端选择：vLLM的PagedAttention对长文本推理有显著的性能和内存优化，是此类评估的首选后端。
结果解读：长文本评估的结果通常是一个随着位置和长度变化的性能曲面图。不要只看一个平均分，要分析模型在文档开头、中间、结尾的表现差异，这能揭示其注意力机制的局限性。

4.4 自定义模型与数据集

OpenCompass预置了大量模型和数据集，但总有覆盖不到的情况。添加自定义支持是高级用户的必经之路。

添加一个HuggingFace模型：如果模型已经在HuggingFace Hub上，且架构是AutoModelForCausalLM支持的，那么添加它非常简单。你甚至不需要写配置文件，直接用CLI指定路径即可：

opencompass --datasets mmlu_gen --hf-path username/my-awesome-model --hf-type chat

--hf-type chat表示这是一个聊天模型，OpenCompass会使用其默认的聊天模板。如果是基座模型，则使用--hf-type base。

对于更复杂的自定义，可以在配置文件中定义：

models = [ dict( type=HuggingFaceCausalLM, abbr='my-model', path='./local/path/to/model', # 或HF仓库名 tokenizer_path='./local/path/to/tokenizer', model_kwargs=dict( torch_dtype=torch.bfloat16, device_map='auto', trust_remote_code=True, # 如果模型需要 ), tokenizer_kwargs=dict(padding_side='left'), generation_kwargs=dict(temperature=0.7, do_sample=True), batch_padding=True, batch_size=8, run_cfg=dict(num_gpus=1), ) ]

添加一个自定义数据集：这需要编写一个新的Dataset类，继承自BaseDataset。核心是实现reader_cfg,infer_cfg,eval_cfg。不过，大多数情况下，你可以复用现有数据集的配置，只修改数据加载部分。更简单的方法是，如果你的数据是JSON、JSONL或CSV格式，可以尝试使用NaiveDataset这个通用类，通过指定reader_cfg中的input_columns和output_column来快速适配。

贡献回馈：如果你添加的模型或数据集具有通用价值，非常鼓励你向OpenCompass开源项目提交Pull Request。这能帮助整个社区，也是你技术影响力的体现。

5. 生产级评估：问题排查与性能调优

当你开始大规模、自动化地运行评估时，会遇到各种问题。这里分享一些实战中积累的经验。

5.1 常见错误与解决方案

1. 显存不足（CUDA out of memory）这是最常见的问题。

降低batch_size：这是最直接有效的方法。在模型配置中减小batch_size的值。
启用量化：如果模型支持，可以在model_kwargs中设置load_in_4bit=True或load_in_8bit=True（需要安装bitsandbytes）。
使用加速后端：如前所述，vLLM和LMDeploy通常有更好的显存管理。
检查max_seq_len：过长的序列长度是显存杀手。确保模型配置中的max_seq_len与实际需求匹配，不要无谓地设置得过大。
使用--max-num-worker 1：先确保单卡能跑通，再增加并行数。

2. 下载数据集失败或超时

切换数据源：尝试设置export DATASET_SOURCE=ModelScope使用国内源。
手动下载：对于自动下载失败的数据集，根据错误日志中的URL，尝试用浏览器或下载工具手动下载，并放置到~/.cache/opencompass目录下对应的位置。
使用离线数据包：回归最稳定的方式，下载官方发布的数据集压缩包。

3. API调用失败（频率限制、超时）

设置query_per_second：在API模型配置中，加入限速参数，例如query_per_second=1表示每秒最多1次查询，避免触发频率限制。
设置retry_limit：配置重试次数和延迟，例如retry_limit=5, retry_delay=30。
使用代理：对于某些API，可能需要配置网络代理。这通常在初始化API客户端时设置，具体取决于你使用的封装。

4. 结果不一致或分数异常低

检查Prompt模板：不同的模型对Prompt格式非常敏感。确保你使用的prompt_template适合当前模型。例如，ChatML格式、Alpaca格式、LLaMA的指令格式都不同。一个常见的错误是给聊天模型用了基座模型的Prompt。
检查答案后处理（Post-processor）：评分前，需要从模型生成的一大段文本中提取出答案（例如，选择题的“A”，数学题的“42”）。first_capital_postprocess（提取第一个大写字母）或first_number_postprocess（提取第一个数字）是常用后处理器。如果提取逻辑不对，分数就会全错。对于复杂输出，可能需要自定义后处理函数。
检查模型加载版本：确认你加载的模型文件是否正确（例如，是chat版本还是base版本）。一个base模型去回答需要指令遵循的chat问题，效果会很差。

5.2 性能调优指南

1. 最大化GPU利用率

调整batch_size：这是最重要的参数。太小，GPU算力闲置；太大，会爆显存。通过nvidia-smi观察GPU利用率，逐步增加batch_size直到利用率稳定在80%以上或接近显存上限。不同模型和数据集的最佳批次大小不同，需要实验。
使用--max-num-worker：充分利用多卡。设置为你的可用GPU数量。注意，这是进程数，每个进程会加载一份模型副本。确保总显存足够。
使用TurboMind/LMDeploy或vLLM：如前所述，它们能显著提升吞吐量。

2. 优化I/O与缓存

将数据和模型放在SSD上：尤其是当数据集很大时，硬盘读取速度会成为瓶颈。NVMe SSD能极大改善数据加载速度。
使用内存盘（Ramdisk）：对于超大规模评估，如果服务器内存足够，可以将频繁读取的缓存目录（如~/.cache/huggingface,~/.cache/opencompass）挂载到内存盘上。
预加载模型：对于需要反复评估同一个模型的情况，可以编写脚本先加载模型到显存并预热，然后让OpenCompass的Worker复用这个已加载的模型，避免每次任务都重复加载。这需要对Runner的工作机制有更深的理解和定制。

3. 任务管理与监控

使用--debug模式：在正式大规模运行前，加上--debug参数，它只会处理前几条数据，快速验证整个流程（模型加载、数据读取、推理、评分）是否正确。
理解输出目录结构：outputs/下的每次运行都有一个独立文件夹，里面包含：
- configs/: 本次运行的完整配置备份。
- predictions/: 每个模型在每个数据集上的原始输出。
- results/: 评分后的汇总结果（CSV格式）。
- summary/: 最终的报告文件（通常是一个txt或json）。
利用TensorBoard或自定义日志：对于长时间运行的任务，可以修改代码添加更详细的进度日志和性能指标（如每秒处理样本数），方便监控和发现问题。