简介:本文以开源机器人AI框架LeRobot为例,提供环境搭建、数据集制作、训练命令、配置说明、验收清单与故障排查的完整步骤。读完后,你能照做跑通模仿学习任务,并会用损失、评估与回放判断策略是否可用。
本文以开源机器人AI框架 LeRobot 为例,带你在本地跑通一条完整的机器人模仿学习链路:数据采集/准备 → 环境配置 → 参数训练 → 评估指标 → 可视化回放 → 问题排查。
如果你使用其他开源机器人AI框架,例如 robomimic、Isaac Lab 等,具体命令会不同,但流程一致:先确认环境与版本,再校验数据格式,随后做小规模冒烟测试,最后正式训练并验收。
读完本文后,你将能够:
如果你的任务是让机器人从数据中学会“看什么、做什么动作”,例如抓取、放置、装配、插拔、分拣等,那么模仿学习是一个常见且实用的选择。尤其当你已经有人类示教、遥操作轨迹或仿真轨迹时,开源机器人AI框架可以帮助你快速复现策略训练流程。
适合的场景包括:
需要注意:这类框架主要解决“机器人如何从数据中学习动作策略”,它不等同于完整的运动规划、实时控制或底层硬件驱动。实际落地时,通常还需要与仿真环境、传感器、控制接口和硬件安全模块配合。
nvidia-smi、df -h、free -h 检查 GPU、磁盘和内存状态。为了避免依赖冲突,建议先固定版本,再安装。以下是以 LeRobot 教程复现为导向的示例组合,实际版本请以你所用框架官方发布说明为准。
| 组件 | 示例版本 | 说明 |
|---|---|---|
| Python | 3.10 或 3.11 | 兼容性较好;不建议随意使用过新版本 |
| PyTorch | 2.2 或 2.3 | 示例训练引擎;需与 CUDA 版本匹配 |
| CUDA | 12.1 | 示例 GPU 计算版本;CPU 模式可跳过 |
| cuDNN | 8.9 | 若使用 GPU,需与 PyTorch/CUDA 匹配 |
| NVIDIA 驱动 | 535+ | 示例驱动版本,需支持对应 CUDA |
| LeRobot | 以官方 Releases 为准 | 建议使用稳定发布版,不要用未经验证的开发分支 |
如果只需要 CPU 调试,可以不配置 CUDA,但训练速度会明显下降。
你需要准备或选择一个机器人轨迹数据集。数据通常按“观测(observation)+ 动作(action)”组织,观测可能包含相机图像、机器人状态、任务描述,动作则是每一步机器人要执行的控制目标。
建议提前理解:
不要直接在系统默认 Python 环境中安装依赖。建议先创建独立虚拟环境,避免不同项目之间污染依赖。
以 LeRobot 为例,可使用以下命令:
git clone https://github.com/huggingface/lerobot.gitcd lerobot# 示例版本,请替换为官方 Releases 中的稳定标签git checkout v0.3.0python3.10 -m venv .venvsource .venv/bin/activate# Windows 可改为:.venv\Scripts\activatepip install -U pip# 如果使用 GPU,示例安装 CUDA 12.1 对应 PyTorchpip install torch torchvision --index-url https://download.pytorch.org/whl/cu121# 安装框架本体pip install -e .
如果需要硬件扩展,例如夹爪、串口或特定机器人套件,可按官方文档选择可选依赖。例如:
pip install -e ".[feetech]"
安装完成后,检查环境与版本:
python -c "import torch; print(torch.__version__, torch.cuda.is_available())"pip show lerobotlscat pyproject.toml
如果 torch.cuda.is_available() 返回 False,说明 PyTorch 没有识别到 GPU,需要重新检查显卡驱动、CUDA 版本或 PyTorch 安装版本。
建议在源码目录中查看官方文档、示例、依赖清单和配置入口。重点检查:
lscat README.mdcat pyproject.tomlls lerobot
如果你需要复现某篇教程或某个实验,建议记录以下最小版本信息:
这样在出现问题时,可以判断是环境问题、数据问题,还是参数配置问题。
LeRobot 类框架通常使用统一的数据集目录。一个典型结构如下:
dataset_root/meta/info.jsonepisodes.jsonltasks.jsonldata/chunk-000/episode_000000.parquetvideos/chunk-000/observation.images.camera.episode_000000.mp4
其中:
meta/info.json:数据集级信息,例如采样频率、机器人类型、特征定义;meta/episodes.jsonl:每个 episode 的索引和元信息;meta/tasks.jsonl:任务描述;data/:逐帧轨迹数据,通常是参数文件;videos/:相机图像等视频数据。info.json 的示例字段如下:
{"fps": 30,"robot_type": "so100_follower","total_episodes": 1,"total_frames": 300,"features": {"observation.state": {"dtype": "float32","shape": [6]},"observation.images.camera": {"dtype": "image","shape": [480, 640, 3]},"action": {"dtype": "float32","shape": [6]}}}
正式训练前,先用框架提供的数据查看或回放入口做一次检查。例如:
lerobot-visualize-dataset \--dataset.repo_id=your_dataset \--dataset.root=/path/to/dataset
如果你的版本没有该命令,也可以用最小 Python 脚本检查参数文件:
python - <<'PY'import pandas as pdpath = "/path/to/dataset/data/chunk-000/episode_000000.parquet"df = pd.read_parquet(path)print("rows:", len(df))print("columns:", df.columns.tolist())print("null count:")print(df.isna().sum())assert len(df) > 0, "数据为空"assert "action" in df.columns or any("action" in c for c in df.columns), "缺少动作字段"PY
如果你的框架使用嵌套结构或自定义字段,请以框架加载器为准,但基本检查目标不变:
不同框架的参数入口不同。LeRobot 常见方式是通过命令行参数启动训练;如果你希望集中管理参数,可以自己建立配置文件,例如:
configs/act_pusht.yaml
一个自定义示例如下:
dataset:repo_id: your_datasetroot: /path/to/datasetpolicy:type: acttrain:batch_size: 32training_steps: 100000eval_every: 1000output_dir: outputs/train/act_pusht
需要注意:这不是任何框架必须采用的统一格式,具体字段名应以你的框架 --help 或官方文档为准。LeRobot 常见做法是直接传命令行参数,也可以在训练输出目录中查看最终生效配置。
不要一上来就训练十万步。先用极小规模命令跑通流程,确认数据、模型、显存和输出目录都正常。
冒烟测试示例:
lerobot-train \--policy.type=act \--dataset.repo_id=your_dataset \--dataset.root=/path/to/dataset \--batch_size=8 \--training_steps=50 \--output_dir=outputs/smoke/act_demo
如果冒烟测试能顺利结束,并且输出目录中生成日志或检查点,再进入正式训练:
lerobot-train \--policy.type=act \--dataset.repo_id=your_dataset \--dataset.root=/path/to/dataset \--batch_size=32 \--training_steps=100000 \--eval.every=1000 \--output_dir=outputs/train/act_pusht
如果你的版本支持仿真评估,可以追加评估参数,例如 --eval.n_episodes=10。如果没有仿真环境,也可以先依赖验证集指标和轨迹回放来判断。
训练启动后,建议另开终端检查 GPU 占用:
nvidia-smi
Linux 下可循环查看:
watch -n 1 nvidia-smi
如果 GPU 利用率长期接近 0,或者日志显示训练在 CPU 上运行,需要检查 PyTorch 是否使用 CUDA、数据集路径是否正确、数据加载是否成为瓶颈。
以下参数值为通用示例,实际应结合任务规模、显存和收敛情况调整。
| 配置项 | 含义 | 示例值 | 调整建议 |
|---|---|---|---|
| 数据路径 | 训练与验证数据位置 | /path/to/dataset |
先确认可读,再开始训练 |
| 模型类型 | 策略网络结构 | act |
小规模任务可先用简单策略验证 |
| 批大小 | 每次更新使用样本数 | 8 或 32 | 显存不足先降批大小 |
| 学习率 | 优化步长 | 1e-4 |
过大不收敛,过小收敛慢 |
| 训练步数 | 总更新次数 | 100000 | 先用 50 到 500 步冒烟 |
| 评估间隔 | 每隔多少步评估 | 1000 | 太频繁会拖慢训练 |
| 输出目录 | 日志、配置、检查点 | outputs/train/act_pusht |
建议每次实验独立目录 |
配置原则:先保证流程跑通,再优化收敛速度,最后才追求极致性能。顺序颠倒,容易在错误配置上浪费时间。
下面的伪代码仅用于说明训练逻辑,不代表任何具体框架的真实接口。
# 通用训练流程示意(伪代码)config = {"dataset_path": "/path/to/dataset","batch_size": 32,"learning_rate": 1e-4,"train_steps": 100000,"eval_interval": 1000,"model_type": "imitation_policy",}dataset = load_dataset(config["dataset_path"])train_set, val_set = split(dataset, ratio=0.9)model = build_model(config["model_type"])optimizer = create_optimizer(model, lr=config["learning_rate"])for step in range(config["train_steps"]):batch = train_set.sample_batch(config["batch_size"])loss = model.compute_loss(batch)optimizer.step(loss)if step % config["eval_interval"] == 0:metrics = evaluate(model, val_set)log(metrics, step)
要点:数据加载在前,模型构建在中,训练循环在后,评估穿插其中。任何一步缺失,都可能导致报错或训练无效。
不要只看“训练没有报错”。建议从三个层面验收。
| 检查项 | 通过条件示例 | 不通过时的处理 |
|---|---|---|
| 损失曲线 | 前若干步整体下降,长期不再剧烈震荡 | 降低或调整学习率,检查数据质量 |
| 验证指标 | 动作误差持续下降,或任务成功率达到设定阈值 | 检查数据分布、模型容量和批大小 |
| 可视化回放 | 轨迹连续、平滑,无明显越界、抖动或停滞 | 若数值好但回放差,警惕表面拟合 |
| GPU 状态 | GPU 利用率明显上升,显存在合理范围 | 检查 CUDA、批大小和模型规模 |
| 输出目录 | 有日志、配置、检查点或评估记录 | 检查输出目录权限和磁盘空间 |
验收阈值不是固定不变的。不同任务可接受标准不同,但初版建议至少满足:损失整体下降、验证指标不劣于基线、回放轨迹基本合理。三者都通过,才算真正跑通。
原因通常是 Python、PyTorch、CUDA 或框架版本不匹配。
处理建议:
python -Vpip show torchpip show lerobot
建议重建虚拟环境,按官方版本矩阵重新安装。优先解决 GPU 驱动与 PyTorch 的匹配问题。
如果日志出现 CUDA out of memory,可尝试:
可用命令检查残留进程:
nvidia-smips aux | grep python
先不要启动长训练。先用最小命令或脚本单独读取一条数据。检查:
meta/info.json 是否存在;可能原因包括学习率过大或过小、数据质量差、模型容量不匹配。
排查顺序:
机器人训练任务往往时间较长,建议提前做保护:
df -h;定期清理旧日志、旧检查点和缓存;数据集建议单独存放。本文以开源机器人AI框架 LeRobot 为例,把环境搭建、数据准备、训练启动、结果验收和故障排查整理成了一套可执行流程。你可以照做完成从零跑通训练任务:先固定 Python、PyTorch、CUDA 与框架版本,再校验数据集目录和元数据,随后用极小规模冒烟测试验证链路,最后通过损失曲线、验证指标和可视化回放判断模型是否真正学会。掌握这套流程后,你可以继续深入模仿学习算法选择、仿真到真实迁移、多任务训练以及策略部署等方向。