LeRobot + LIBERO 机器人仿真评估全流程：模型下载、环境搭建与踩坑指南

weixin_46200189

393人浏览 · 2026-07-04 21:23:49

weixin_46200189 · 2026-07-04 21:23:49 发布

LeRobot + LIBERO 机器人仿真评估全流程：模型下载、环境搭建与踩坑指南

在具身智能算法开发中，基于 LIBERO 基准评测 VLA（视觉语言动作）模型是验证模型泛化能力的核心环节。本文以 lerobot/pi05_libero_finetuned 模型为例，完整记录从 Windows 端下载模型、Ubuntu 服务器编译依赖、数据集准备，到最终跑通全任务评估的完整流程，并逐一解决过程中遇到的 cmake 编译失败、数据集路径缺失、Gated 模型无权限等典型踩坑问题。

一、整体方案说明

国内直接在 Ubuntu 服务器下载 Hugging Face 模型，普遍存在速度慢、断点续传不稳定、网络波动导致下载失败等问题。最稳妥的方案是：Win10 端通过镜像站高速下载模型与数据，再通过 Samba 共享传输到 Ubuntu 服务器，最后在服务器本地加载运行评估，全程可控且容错性更高。

二、Win10 端：下载 pi05_libero_finetuned 模型

2.1 安装 huggingface-cli 工具

确保本机已配置 Python 环境，打开命令行执行以下命令安装官方下载工具：

pip install -U "huggingface_hub[cli]"

2.2 配置 HF 国内镜像站（加速必备）

根据你使用的终端类型，执行对应命令配置镜像地址：

CMD 命令行：

set HF_ENDPOINT=https://hf-mirror.com

PowerShell：

$env:HF_ENDPOINT="https://hf-mirror.com"

2.3 执行模型下载

指定本地保存路径，执行下载命令，工具支持断点续传：

hf download lerobot/pi05_libero_finetuned --local-dir D:\lerobot_models\pi05_libero_finetuned

下载过程示例：
在这里插入图片描述

下载完成后，务必检查目录内核心文件是否齐全：

config.json 模型配置文件
模型权重文件（model.safetensors / pytorch_model.bin 等）
preprocessor_config.json 预处理配置文件

三、Ubuntu 端：编译依赖与环境安装

这一步是环境搭建的踩坑重灾区，hf-egl-probe 编译失败、cmake 命令找不到、EGL 图形库缺失等问题都集中在此环节。

3.1 安装系统级编译与图形依赖

先安装基础编译工具链和 EGL/OpenGL 开发库，解决无头服务器离线渲染依赖：

sudo apt-get update
sudo apt-get install -y \
  build-essential \
  cmake \
  ninja-build \
  pkg-config \
  libegl1-mesa-dev \
  libgl1-mesa-dev \
  libgles2-mesa-dev \
  libx11-dev \
  libxext-dev \
  libxrandr-dev \
  libxinerama-dev \
  libxcursor-dev \
  libxi-dev

3.2 安装指定版本 cmake（避免版本不兼容）

如果系统自带 cmake 版本过低，会导致编译校验不通过。可通过 pip 将指定版本 cmake 安装到 conda 虚拟环境内：

conda activate lerobot
python -m pip install --no-cache-dir "cmake==3.31.6"

3.3 安装 egl_probe 与 lerobot（含 LIBERO 支持）

重点：必须添加 --no-build-isolation 参数，让构建过程复用当前环境的 cmake，解决隔离环境内找不到 cmake 的问题。

conda activate lerobot
# 安装egl_probe渲染依赖
python -m pip install --no-build-isolation --no-cache-dir "egl_probe==1.0.2"
# 安装带LIBERO支持的lerobot
python -m pip install --no-build-isolation -e ".[libero]"

🚩 踩坑提示：如果直接执行 pip install 不加参数，会出现经典报错 subprocess.CalledProcessError: Command '['cmake', '--version']' returned non-zero exit status 1，本质是 pip 隔离构建环境内无法识别系统/环境内的 cmake。

四、模型文件传输到 Ubuntu

通过 Samba 共享将 Win10 下载好的模型文件夹完整拷贝到 Ubuntu 服务器，例如目标绝对路径：

/home/xxx/pi05_libero_finetuned

对应 Windows 端的网络访问路径：

\\192.168.118.250\xxx\pi05_libero_finetuned

五、LIBERO 数据集下载与目录配置

首次运行评估脚本时，会反复出现 datasets path ... does not exist 警告，这是因为 LIBERO 数据集未放置到程序默认读取路径。

5.1 官方脚本一键下载

进入 LIBERO 仓库根目录，先配置 HF 镜像，再执行官方下载脚本：

cd /home/linux/git_code/Embodied-Artificial-Intelligence/LIBERO
export HF_ENDPOINT=https://hf-mirror.com
python benchmark_scripts/download_libero_datasets.py --use-huggingface

5.2 数据集目录结构校验

下载完成后，确保目录结构与程序期望路径完全一致：

LIBERO/
└── libero/
    └── datasets/
        ├── libero_spatial/
        ├── libero_object/
        ├── libero_goal/
        └── libero_10/

目录结构验证示例：
在这里插入图片描述

六、解决 Gated 模型权限问题

评估过程中加载 google/paligemma-3b-pt-224 时，即使已经登录 HF 账号，仍会报权限错误。这是因为该模型属于 Gated 仓库，需要单独申请访问权限。

6.1 申请模型访问权限

浏览器打开模型官方页面：

https://huggingface.co/google/paligemma-3b-pt-224

使用你的 Hugging Face 账号登录，阅读并同意协议，提交访问申请。

6.2 确认 Token 权限范围

如果你使用的是细粒度 Token（fine-grained token），需要在 Token 权限设置中开启 public gated repositories 访问权限。

权限配置完成页面示例：

七、执行 LIBERO 全任务评估

7.1 评估运行命令

使用本地模型绝对路径，运行 LIBERO 四个任务套件的评估：

lerobot-eval \
  --output_dir=./eval_logs/ \
  --env.type=libero \
  --env.task=libero_spatial,libero_object,libero_goal,libero_10 \
  --eval.batch_size=1 \
  --eval.n_episodes=10 \
  --policy.path=/home/chenxd/pi05_libero_finetuned \
  --policy.n_action_steps=10 \
  --env.max_parallel_tasks=1

📌 注意：--policy.path 必须填写本地模型的绝对路径，不要继续填写 Hugging Face 仓库名，否则会触发联网下载逻辑。

7.2 运行成功结果

正常运行后会依次构建四个任务套件的仿真环境，最终输出完整评估指标，示例结果如下：
在这里插入图片描述

核心指标说明：

pc_success：任务成功率，100.0 代表当前测试集全部任务成功完成
avg_sum_reward：平均累计奖励
eval_ep_s：单回合评估平均耗时

八、常见报错与解决方案汇总

报错信息	根本原因	对应解决方案
`Command '['cmake', '--version']' returned non-zero exit status 1`	pip 隔离构建环境内找不到可用 cmake	安装系统 cmake + 环境内 pip 安装 cmake，编译时添加 `--no-build-isolation` 参数
`ModuleNotFoundError: No module named 'yaml'`	缺少 pyyaml 依赖库	执行 `pip install pyyaml`
`datasets path ... does not exist`	LIBERO 数据集未放到默认读取路径	运行官方下载脚本，严格对齐目录结构
Gated 模型 403 无权限	paligemma 模型需单独申请访问权限	官网提交访问申请，确认 Token 权限范围
模型加载失败、提示文件缺失	下载不完整或路径配置错误	校验核心配置与权重文件，使用绝对路径加载