LeRobot 的依赖库设计遵循“AI 原生 硬件解耦”原则核心栈高度收敛于 PyTorch 与 Hugging Face 生态仿真/硬件依赖按需可选避免传统机器人框架常见的“依赖地狱”。以下按功能域分类说明附版本约束、安装策略与避坑指南。 一、依赖库全景分类基于pyproject.toml与官方文档类别核心依赖包必选/可选版本约束在 LeRobot 中的作用 计算与学习引擎torch,torchvision✅ 必选2.1.0(推荐 2.4)张量计算、自动微分、视觉骨干网络、torch.compile加速einops✅ 必选0.7.0多维张量重组ACT/Diffusion Policy 核心依赖 HF 生态栈datasets✅ 必选2.19.0机器人数据集加载/版本管理/流式训练transformers✅ 必选4.40.0VLA 模型加载、Tokenizer、多模态对齐accelerate✅ 必选0.30.0分布式训练、混合精度、设备调度safetensors,huggingface_hub✅ 必选最新稳定版安全模型序列化、HF 模型仓库交互 数据与序列化h5py,pyarrow,pandas,numpy✅ 必选numpy2.0(暂不兼容).hdf5/.parquet数据集读写、状态/动作表格化处理️ 视觉与多模态opencv-python,Pillow✅ 必选兼容 PyTorch 版本图像解码/增强/可视化timm✅ 必选0.9.0预训练视觉 backbone (ResNet/ViT/EVA) 仿真与环境gymnasium✅ 必选0.29.0统一 RL/IL 环境接口替代旧版gymdm_control,mujoco⚙️ 可选 ([sim])mujoco3.1.0MuJoCo 物理仿真、接触动力学、传感器模拟robosuite,pybullet⚙️ 可选/社区按需安装替代仿真后端非官方默认 训练与追踪wandb,tqdm,matplotlib,pyyaml✅ 必选最新稳定版实验记录、进度条、轨迹可视化、配置解析 部署与推理onnx,onnxruntime⚙️ 可选 ([deploy])onnxruntime1.16模型导出、CPU/边缘端加速推理tensorrt⚙️ 可选匹配 CUDA 版本Jetson/服务器 GPU 低延迟推理需手动安装 硬件 SDKlerobot[hardware_aloha],lerobot[hardware_so100]等⚙️ 按需安装独立版本仅在使用对应实体机器人时安装默认不打包️ 二、官方推荐安装方式1. 基础安装仅训练/推理无仿真/硬件pip install lerobot[core] # 或 pip install lerobot2. 完整开发环境含仿真pip install lerobot[sim] # 会自动安装 gymnasium, dm_control, mujoco, robosuite(可选)3. 带部署优化ONNX/TensorRTpip install lerobot[deploy] # 注意TensorRT 需按 NVIDIA 官方指南单独安装pip 仅装 Python 绑定4. 硬件支持以 SO-100 为例pip install lerobot[hardware_so100] # 内部会拉取 lekiwi、dynamixel-sdk 等硬件通信库重要提示LeRobot 采用Extras 依赖隔离避免“装一个框架带崩整个环境”。生产部署建议按需安装并通过pip freeze锁定版本。⚠️ 三、高频依赖冲突与解决方案问题现象根本原因解决方案numpy导入报错ValueError: numpy.dtype size changednumpy2.0与旧版 C 扩展不兼容pip install numpy2.0或使用pip install lerobot --no-deps后手动指定版本mujoco编译失败缺少 C 编译器或libglfw3-devsudo apt install build-essential libglfw3-dev libglew-dev后pip install mujocotorch与onnxruntimeCUDA 版本不匹配系统 CUDA / PyTorch / ORT 版本割裂统一 CUDA 版本如 12.1使用pip install onnxruntime-gpu1.17.0gymnasium与gym冲突旧项目残留gym包pip uninstall gymLeRobot 已全面迁移至gymnasium多模态模型加载内存溢出transformers未启用device_mapauto训练时用accelerate自动分片推理时加torch_dtypetorch.float16 四、架构级依赖设计哲学AI 栈收敛所有策略网络均通过torch.nn.Module实现依赖einops替代自定义张量操作保证可编译性与可读性。数据层标准化强制使用 HFdatasets格式.hdf5/.parquet内置ChunkDataset与StateAction抽象杜绝私有二进制格式。硬件解耦SDK 通过lerobot[hardware_*]独立分发核心框架仅依赖抽象接口如RobotEnv避免绑定特定厂商协议。部署友好提供export_policy()一键导出 ONNX推理节点可脱离 PyTorch 运行仅依赖onnxruntime或tensorrt。 五、验证安装是否成功import lerobot print(lerobot.__version__) # 应 2.0.0 # 验证核心依赖 import torch, datasets, transformers, einops, gymnasium print(fPyTorch: {torch.__version__} | Datasets: {datasets.__version__}) # 验证策略加载以 ACT 为例 from lerobot.common.policies.act.modeling_act import ACTPolicy print(✅ ACT Policy 加载成功) 附生产环境requirements.lock建议片段torch2.4.0 torchvision0.19.0 datasets2.20.0 transformers4.44.0 accelerate0.33.0 safetensors0.4.3 einops0.8.0 gymnasium0.29.1 mujoco3.1.6 dm_control1.0.18 opencv-python4.10.0.84 timm0.9.16 numpy1.26.4 onnx1.16.1 onnxruntime-gpu1.18.0