OpenCompass 离线加载本地模型的技术解析与解决方案

问题背景

在使用OpenCompass评估框架时，许多用户会遇到需要离线加载本地模型的情况。特别是在企业内网环境或网络受限的场景下，无法直接连接Hugging Face Hub下载模型文件。本文将以Llama-2-7B模型为例，深入分析离线加载本地模型的技术原理和解决方案。

问题现象

用户尝试通过指定本地路径加载Llama-2-7B模型时，即使设置了HF_HUB_OFFLINE=1环境变量，系统仍然报错提示无法连接到Hugging Face Hub获取config.json文件。这表明系统未能正确识别本地模型路径，仍然尝试从远程仓库获取模型配置。

技术原理分析

OpenCompass基于Hugging Face Transformers库构建模型加载功能。当使用HuggingFaceBaseModel类型加载模型时，系统会执行以下关键步骤：

1. 首先尝试从指定路径加载模型配置文件(config.json)
2. 检查模型权重文件是否存在于指定目录
3. 验证模型架构与配置文件匹配性

在离线模式下，系统会优先检查本地缓存，若找不到相关文件则会报错。关键在于确保本地模型目录结构完整且符合Hugging Face模型仓库规范。

解决方案

方案一：使用run.py命令行工具

OpenCompass提供了更简单的命令行接口来加载本地模型：

python run.py \
--hf-type base \
--hf-path /path/to/your/model \
--datasets dataset_name \
--debug

参数说明：

• --hf-type: 指定模型类型(base或chat)
• --hf-path: 本地模型目录绝对路径
• --datasets: 要评估的数据集名称
• --debug: 可选调试模式

方案二：确保本地模型目录结构完整

若仍需使用配置文件方式，必须确保本地模型目录包含以下必要文件：

• config.json (模型配置文件)
• pytorch_model.bin或类似权重文件
• tokenizer相关文件(tokenizer.json等)

目录结构示例：

/path/to/your/model/
├── config.json
├── pytorch_model.bin
├── tokenizer.json
└── (其他必要文件)

方案三：预下载模型文件

在网络可用时预先下载完整模型：

from transformers import AutoModel, AutoTokenizer

model = AutoModel.from_pretrained("meta-llama/Llama-2-7b-hf", cache_dir="/path/to/save")
tokenizer = AutoTokenizer.from_pretrained("meta-llama/Llama-2-7b-hf", cache_dir="/path/to/save")

最佳实践建议

1. 优先使用run.py命令行工具，它封装了更健壮的本地模型加载逻辑
2. 完整下载模型文件而不仅是权重文件
3. 验证模型目录是否包含所有必要组件
4. 在配置文件中使用绝对路径而非相对路径
5. 对于大型模型，考虑使用符号链接到实际存储位置

总结

OpenCompass支持离线评估本地模型，关键在于确保模型目录结构完整且路径配置正确。通过理解Hugging Face模型加载机制，我们可以有效解决离线环境下的模型评估需求。对于大多数用户，使用run.py命令行工具是最简单可靠的解决方案。