解决 OpenCompass 评估中的 PyTorch 与 Transformers 版本冲突问题

在使用 OpenCompass 进行大语言模型评估时，经常会遇到 PyTorch 和 Transformers 版本兼容性问题。本文将详细介绍如何快速搭建 OpenCompass 环境并解决常见的版本冲突错误。

问题背景

最近在使用 OpenCompass 对 Qwen2.5-3B 模型进行评估时，遇到了以下错误：

AttributeError: module 'torch.utils._pytree' has no attribute 'register_pytree_node'. Did you mean: '_register_pytree_node'?

这个错误是由于 PyTorch 与 Transformers 版本不兼容导致的。在较新的 PyTorch 版本中，register_pytree_node 方法已被重命名为 _register_pytree_node，但旧版本的 Transformers 仍在尝试调用旧的方法名。

完整解决方案

步骤 1：创建 Conda 环境

# 创建名为 opencompass 的 Python 3.10 环境
conda create --name opencompass python=3.10 pytorch torchvision pytorch-cuda -c nvidia -c pytorch -y

# 激活环境
conda activate opencompass

重要提示：OpenCompass 要求 PyTorch 版本 >= 1.13。如果需要自定义 PyTorch 版本或 CUDA 版本，请参考 PyTorch 官方文档。

步骤 2：安装 OpenCompass

# 克隆 OpenCompass 仓库
git clone https://github.com/open-compass/opencompass.git
cd opencompass

# 安装 OpenCompass（可编辑模式）
pip install -e .

步骤 3：解决版本冲突问题

当运行评估命令时：

python run.py \
    --datasets demo_gsm8k_chat_gen \
    --hf-type chat \
    --hf-path Qwen/Qwen2.5-3B-Instruct \
    --debug

如果遇到 register_pytree_node 错误，需要降低 Transformers 版本：

# 降级 Transformers 到兼容版本
pip install transformers==4.41.0

步骤 4：验证安装

# 测试环境是否正常
python -c "
import torch, transformers, opencompass
print(f'PyTorch 版本: {torch.__version__}')
print(f'Transformers 版本: {transformers.__version__}')
print('✅ 所有库导入成功！')
"

错误原因深度分析

根本原因

这个兼容性问题的根源在于：

1. PyTorch 2.x+ 版本：将 register_pytree_node 重命名为 _register_pytree_node
2. Transformers 旧版本：仍然调用旧的 API 名称
3. 版本不匹配：新 PyTorch + 旧 Transformers = API 调用失败

版本兼容性矩阵

PyTorch 版本	Transformers 版本	兼容性
2.0+	4.41.0	✅ 推荐
2.0+	>4.41.0	⚠️ 可能有问题
<2.0	4.41.0	✅ 兼容
<2.0	>4.41.0	✅ 兼容

替代解决方案

如果不想降级 Transformers，也可以考虑升级 PyTorch 配置：

方案 A：使用更新的 PyTorch 和 Transformers

# 卸载当前版本
pip uninstall torch transformers -y

# 安装兼容的最新版本
pip install torch>=2.1.0 transformers>=4.37.0

方案 B：创建版本锁定文件

创建 requirements.txt 文件确保环境一致性：

torch>=2.0.1,<2.2.0
transformers==4.41.0
datasets>=2.14.0
accelerate>=0.27.0

完整测试流程

环境配置完成后，可以运行完整的模型评估：

# 测试基础功能
python run.py \
    --datasets demo_gsm8k_chat_gen \
    --hf-type chat \
    --hf-path Qwen/Qwen2.5-3B-Instruct \
    --debug

# 测试更多数据集
python run.py \
    --datasets gsm8k_gen cmmlu_gen \
    --hf-type chat \
    --hf-path Qwen/Qwen2.5-3B-Instruct \
    --debug

常见问题排查

1. 如果仍然遇到版本问题

# 检查具体版本
pip list | grep -E "(torch|transformers)"

# 强制重新安装
pip install --force-reinstall transformers==4.41.0

2. 如果遇到 CUDA 相关问题

# 检查 CUDA 可用性
python -c "import torch; print(f'CUDA available: {torch.cuda.is_available()}')"

# 安装对应 CUDA 版本的 PyTorch
pip install torch torchvision torchaudio --index-url https://download.pytorch.org/whl/cu121

3. 如果遇到内存不足

# 减少批次大小
python run.py \
    --datasets demo_gsm8k_chat_gen \
    --hf-type chat \
    --hf-path Qwen/Qwen2.5-3B-Instruct \
    --batch-size 2 \
    --debug

总结

通过本文的步骤，你可以：

1. ✅ 快速搭建 OpenCompass 评估环境
2. ✅ 解决 PyTorch 与 Transformers 版本冲突
3. ✅ 成功运行大语言模型评估任务
4. ✅ 掌握环境问题排查方法

记住关键点：当遇到 register_pytree_node 错误时，降级 Transformers 到 4.41.0 版本是最直接的解决方案。

这种版本冲突问题在 AI 工具链中很常见，掌握环境配置和问题排查技能对于顺利进行模型评估至关重要。