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 环境打开命令行执行以下命令安装官方下载工具pipinstall-Uhuggingface_hub[cli]2.2 配置 HF 国内镜像站加速必备根据你使用的终端类型执行对应命令配置镜像地址CMD 命令行set HF_ENDPOINThttps://hf-mirror.comPowerShell$env:HF_ENDPOINThttps://hf-mirror.com2.3 执行模型下载指定本地保存路径执行下载命令工具支持断点续传hf download lerobot/pi05_libero_finetuned--local-dirD:\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 开发库解决无头服务器离线渲染依赖sudoapt-getupdatesudoapt-getinstall-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-dev3.2 安装指定版本 cmake避免版本不兼容如果系统自带 cmake 版本过低会导致编译校验不通过。可通过 pip 将指定版本 cmake 安装到 conda 虚拟环境内conda activate lerobot python-mpipinstall--no-cache-dircmake3.31.63.3 安装 egl_probe 与 lerobot含 LIBERO 支持重点必须添加--no-build-isolation参数让构建过程复用当前环境的 cmake解决隔离环境内找不到 cmake 的问题。conda activate lerobot# 安装egl_probe渲染依赖python-mpipinstall--no-build-isolation --no-cache-diregl_probe1.0.2# 安装带LIBERO支持的lerobotpython-mpipinstall--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/LIBEROexportHF_ENDPOINThttps://hf-mirror.com python benchmark_scripts/download_libero_datasets.py --use-huggingface5.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 权限范围如果你使用的是细粒度 Tokenfine-grained token需要在 Token 权限设置中开启public gated repositories访问权限。权限配置完成页面示例七、执行 LIBERO 全任务评估7.1 评估运行命令使用本地模型绝对路径运行 LIBERO 四个任务套件的评估lerobot-eval\--output_dir./eval_logs/\--env.typelibero\--env.tasklibero_spatial,libero_object,libero_goal,libero_10\--eval.batch_size1\--eval.n_episodes10\--policy.path/home/chenxd/pi05_libero_finetuned\--policy.n_action_steps10\--env.max_parallel_tasks1 注意--policy.path必须填写本地模型的绝对路径不要继续填写 Hugging Face 仓库名否则会触发联网下载逻辑。7.2 运行成功结果正常运行后会依次构建四个任务套件的仿真环境最终输出完整评估指标示例结果如下核心指标说明pc_success任务成功率100.0 代表当前测试集全部任务成功完成avg_sum_reward平均累计奖励eval_ep_s单回合评估平均耗时八、常见报错与解决方案汇总报错信息根本原因对应解决方案Command [cmake, --version] returned non-zero exit status 1pip 隔离构建环境内找不到可用 cmake安装系统 cmake 环境内 pip 安装 cmake编译时添加--no-build-isolation参数ModuleNotFoundError: No module named yaml缺少 pyyaml 依赖库执行pip install pyyamldatasets path ... does not existLIBERO 数据集未放到默认读取路径运行官方下载脚本严格对齐目录结构Gated 模型 403 无权限paligemma 模型需单独申请访问权限官网提交访问申请确认 Token 权限范围模型加载失败、提示文件缺失下载不完整或路径配置错误校验核心配置与权重文件使用绝对路径加载九、总结本文完整复现了 LeRobot LIBERO 评估环境从 0 到 1 的搭建流程核心经验可总结为三点国内下载 Hugging Face 模型优先使用hf-mirror.com镜像Win10 下载后传输到服务器稳定性远高于服务器直接下载EGL 相关包编译必须提前配齐系统图形依赖并用--no-build-isolation参数确保 cmake 可被构建环境调用LIBERO 数据集路径与 Gated 模型权限是两大隐形卡点提前准备可大幅减少调试耗时。
LeRobot + LIBERO 机器人仿真评估全流程：模型下载、环境搭建与踩坑指南
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 环境打开命令行执行以下命令安装官方下载工具pipinstall-Uhuggingface_hub[cli]2.2 配置 HF 国内镜像站加速必备根据你使用的终端类型执行对应命令配置镜像地址CMD 命令行set HF_ENDPOINThttps://hf-mirror.comPowerShell$env:HF_ENDPOINThttps://hf-mirror.com2.3 执行模型下载指定本地保存路径执行下载命令工具支持断点续传hf download lerobot/pi05_libero_finetuned--local-dirD:\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 开发库解决无头服务器离线渲染依赖sudoapt-getupdatesudoapt-getinstall-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-dev3.2 安装指定版本 cmake避免版本不兼容如果系统自带 cmake 版本过低会导致编译校验不通过。可通过 pip 将指定版本 cmake 安装到 conda 虚拟环境内conda activate lerobot python-mpipinstall--no-cache-dircmake3.31.63.3 安装 egl_probe 与 lerobot含 LIBERO 支持重点必须添加--no-build-isolation参数让构建过程复用当前环境的 cmake解决隔离环境内找不到 cmake 的问题。conda activate lerobot# 安装egl_probe渲染依赖python-mpipinstall--no-build-isolation --no-cache-diregl_probe1.0.2# 安装带LIBERO支持的lerobotpython-mpipinstall--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/LIBEROexportHF_ENDPOINThttps://hf-mirror.com python benchmark_scripts/download_libero_datasets.py --use-huggingface5.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 权限范围如果你使用的是细粒度 Tokenfine-grained token需要在 Token 权限设置中开启public gated repositories访问权限。权限配置完成页面示例七、执行 LIBERO 全任务评估7.1 评估运行命令使用本地模型绝对路径运行 LIBERO 四个任务套件的评估lerobot-eval\--output_dir./eval_logs/\--env.typelibero\--env.tasklibero_spatial,libero_object,libero_goal,libero_10\--eval.batch_size1\--eval.n_episodes10\--policy.path/home/chenxd/pi05_libero_finetuned\--policy.n_action_steps10\--env.max_parallel_tasks1 注意--policy.path必须填写本地模型的绝对路径不要继续填写 Hugging Face 仓库名否则会触发联网下载逻辑。7.2 运行成功结果正常运行后会依次构建四个任务套件的仿真环境最终输出完整评估指标示例结果如下核心指标说明pc_success任务成功率100.0 代表当前测试集全部任务成功完成avg_sum_reward平均累计奖励eval_ep_s单回合评估平均耗时八、常见报错与解决方案汇总报错信息根本原因对应解决方案Command [cmake, --version] returned non-zero exit status 1pip 隔离构建环境内找不到可用 cmake安装系统 cmake 环境内 pip 安装 cmake编译时添加--no-build-isolation参数ModuleNotFoundError: No module named yaml缺少 pyyaml 依赖库执行pip install pyyamldatasets path ... does not existLIBERO 数据集未放到默认读取路径运行官方下载脚本严格对齐目录结构Gated 模型 403 无权限paligemma 模型需单独申请访问权限官网提交访问申请确认 Token 权限范围模型加载失败、提示文件缺失下载不完整或路径配置错误校验核心配置与权重文件使用绝对路径加载九、总结本文完整复现了 LeRobot LIBERO 评估环境从 0 到 1 的搭建流程核心经验可总结为三点国内下载 Hugging Face 模型优先使用hf-mirror.com镜像Win10 下载后传输到服务器稳定性远高于服务器直接下载EGL 相关包编译必须提前配齐系统图形依赖并用--no-build-isolation参数确保 cmake 可被构建环境调用LIBERO 数据集路径与 Gated 模型权限是两大隐形卡点提前准备可大幅减少调试耗时。
