Being-H-EDU实战教程:SO101机械臂pick_cube_plate任务从数据处理到本地部署全流程
Being-H-EDU实战教程:SO101机械臂pick_cube_plate任务从数据处理到本地部署全流程
Being-H-EDU 是开源项目 Being-H 提供的教育版教程工作区,基于 Being-H0.5 VLA(视觉-语言-动作)模型代码库构建。本教程带你用 SO101 机械臂完成 pick_cube_plate(把方块放进盘子)任务,跑通「SO101 机器人数据处理 → 模型后训练 → 本地推理部署」的完整闭环,是新手入门 VLA 机械臂后训练最友好的路径之一。
🧭 你将学到什么
| 阶段 | 内容 | 关键文件 |
|---|---|---|
| 环境准备 | 一键脚本搭建 Python 3.10 + PyTorch 环境 | scripts/setup_beingh_env.sh |
| 数据处理 | 下载 LeRobot 格式 SO101 数据集,转换为 delta 动作 | docs/so101_data_processing.md |
| 模型训练 | 用 Being-H0.5 检查点多卡后训练 SO101 策略 | examples/so101/train_so101_beingh.sh |
| 本地部署 | 启动推理服务并连接真实 SO101 机械臂 | examples/so101/run_server_so101.sh |
整体流程可概括为:安装环境 → 下载并转换数据集 → 配置训练 YAML → 后训练 → 启动推理服务 → 客户端接真机。每一步都有官方脚本兜底,跟着做即可。
📦 环境准备:3 条命令完成安装
首先需要获取代码仓库:
git clone https://gitcode.com/gh_mirrors/be/Being-H.git
然后进入 Being-H-EDU 目录,用一条脚本创建虚拟环境(已验证 Python 3.10 + PyTorch 2.5.x):
cd tutorials/Being-H-EDU
bash scripts/setup_beingh_env.sh .venv
source .venv/bin/activate
export PYTHONPATH=$PWD:$PYTHONPATH
⚠️ 小提示:如果
flash-attn编译失败,先加环境变量跳过:INSTALL_FLASH_ATTN=0 bash scripts/setup_beingh_env.sh .venv,之后再手动安装与你的 PyTorch/CUDA 匹配的flash-attn轮子包即可,详见 environment_setup.md。
训练/推理前还需要 3 个模型检查点,通过环境变量指定本地路径:
PRETRAIN_MODEL:InternVL/Qwen 视觉语言模型检查点,如InternVL3_5-2BEXPERT_MODEL:Qwen 专家模型检查点,如Qwen3-0.6BRESUME_PATH:Being-H0.5 官方检查点,作为后训练起点
📥 获取 pick_cube_plate 数据集:选择正确的变体
SO101 数据集 BeingBeyond/Being-H-EDU_SO101 以 LeRobot 格式发布,任务指令为 Pick the cube into the plate.。使用 huggingface-cli 下载到本地可写目录:
cd tutorials/Being-H-EDU
export DATA_ROOT=${DATA_ROOT:-$HOME/datasets}
mkdir -p "$DATA_ROOT"
huggingface-cli download BeingBeyond/Being-H-EDU_SO101 \
--repo-type dataset \
--local-dir "$DATA_ROOT/Being-H-EDU_SO101"
export SO101_DATASET="$DATA_ROOT/Being-H-EDU_SO101/pick_cube_plate_trimmed"
仓库包含 4 种数据集变体,推荐使用 pick_cube_plate_trimmed(已做质量过滤并裁剪静止帧,189 条轨迹、35006 帧):
| 目录 | 轨迹数 | 帧数 | 用途 |
|---|---|---|---|
pick_cube_plate |
210 | 51,987 | 原始合并数据,用于审计或自定义过滤 |
pick_cube_plate_filtered |
189 | 45,001 | 质量过滤后的数据集 |
pick_cube_plate_trimmed ✅ |
189 | 35,006 | 推荐的 Being-H-EDU 训练集 |
pick_cube_plate_v3.0 |
210 | 51,987 | LeRobot v3.0 布局,适配新版工具链 |
可用以下命令快速校验路径是否为合法的 LeRobot 数据集根目录:
test -f "$SO101_DATASET/meta/info.json"
test -d "$SO101_DATASET/data"
test -d "$SO101_DATASET/videos"
🔁 关键一步:把绝对动作转换成 delta 动作
Being-H 的统一动作空间要求:前 5 维关节动作必须是相对于 observation.state 的增量(delta),最后的夹爪维度保持绝对值。公开数据集存的是绝对动作目标,所以需要在本地副本上执行一次性转换:
python examples/so101/convert_so101_actions_to_delta.py "$SO101_DATASET"
该脚本会原地更新 parquet 文件、重算 meta/stats.json 与 meta/episodes_stats.jsonl,并写入 meta/action_delta_conversion.json 作为标记——已有标记时会拒绝重复执行,想重跑需加 --force。
💡 映射关系定义在 configs/data_config.py 中:
observation.state<a href="https://link.gitcode.com/i/d3aa5860786799d26a52f51983764a8c" target="_blank">0:6]→ 关节/夹爪状态,action[0:5]→ 5 维 delta 关节动作,action[5:6]→ 绝对夹爪动作。更多细节见 [unified_action_space.md。
🚀 配置训练 YAML 并启动后训练
第一步是把示例配置复制成本地配置,并将占位路径替换为你的 SO101_DATASET:
cp configs/posttrain/so101/so101_example.yaml configs/posttrain/so101/so101_local.yaml
编辑 so101_local.yaml,核心字段只需确认这几处:
so101_posttrain:
dataset_names:
- so101.pick_cube_plate
dataset_path_overrides:
so101.pick_cube_plate: /你的本地路径/Being-H-EDU_SO101/pick_cube_plate_trimmed
data_config_names:
- "so101"
embodiment_tags:
- "so101"
数据集键名保持默认的
so101.pick_cube_plate即可,它必须与 configs/dataset_info.py 中的注册键一致;只有注册多个任务时才需要新增键。
然后启动训练,以 4 卡、20000 步为例:
PRETRAIN_MODEL=/path/to/InternVL3_5-2B \
EXPERT_MODEL=/path/to/Qwen3-0.6B \
RESUME_PATH=/path/to/being-h05-checkpoint \
bash examples/so101/train_so101_beingh.sh \
--dataset-config configs/posttrain/so101/so101_local.yaml \
--gpus 4 \
--steps 20000
常用参数速查:--lr 学习率、--save-steps 保存间隔、--action-chunk-length 动作块长度、--wandb 开启 W&B 日志。输出默认写入 outputs/<run-name>/,TensorBoard 日志在 logs/tensorboard/。完整参数说明见 training.md。
🖥️ 启动本地推理服务
训练完成后,用一行命令拉起 Being-H SO101 推理服务器:
MODEL_PATH=/path/to/so101-checkpoint \
bash examples/so101/run_server_so101.sh
服务默认配置:端口 8080、数据配置 so101、NUM_INFERENCE_TIMESTEPS=4、启用 MPG(USE_MPG=True)。可通过环境变量覆盖,例如换端口:
SERVER_PORT=8081 \
MODEL_PATH=/path/to/so101-checkpoint \
bash examples/so101/run_server_so101.sh
若检查点训练时使用了命名变体,显式传入
METADATA_VARIANT=so101.pick_cube_plate。更多选项见 inference.md。
🤖 连接真实 SO101 机械臂:参考客户端
client_so101.py 是一个自包含的参考客户端,依赖 LeRobot 的 SO101 硬件驱动,通过 ZMQ 与推理服务器通信,数据流为:读取双摄像头图像与关节状态 → 发送到服务器 → 接收动作 → 执行控制。
export PYTHONPATH=/path/to/lerobot/src:$PYTHONPATH
python examples/so101/client_so101.py \
--server-host localhost \
--server-port 8080 \
--robot-port /dev/ttyUSB0 \
--camera-external 0 \
--camera-wrist 2 \
--task "Pick the cube into the plate."
注意 --server-port 要与服务端 SERVER_PORT 保持一致,--robot-port、--camera-external、--camera-wrist 按实际接线修改。
✅ 训练前自检清单与常见问题
按 so101_data_processing.md 的校验清单逐项确认:
meta/info.json中 LeRobotcodebase_version为v2.1meta/tasks.jsonl包含指令Pick the cube into the plate.meta/action_delta_conversion.json已存在(说明 delta 转换完成)data/chunk-000/*.parquet包含action、observation.state、task_index等字段videos/chunk-000/下外置与腕部摄像头视频与 episode 一一对应
常见问题:
- flash-attn 装不上:用
INSTALL_FLASH_ATTN=0建环境后,再手动安装匹配 PyTorch/CUDA 的轮子包。 - 提示路径是占位符:训练/推理脚本会校验
PRETRAIN_MODEL、EXPERT_MODEL、RESUME_PATH、MODEL_PATH,必须指向真实存在的本地路径。 - 想处理自己的 SO101 数据:tools/so101_processing/ 提供
merge_datasets.py(合并多段数据)、trim_static.py(裁剪静止帧)、analyze_stillness.py(静止分析)三个工具,流程详见 PIPELINE.md。
🎯 总结
至此,你已经完整走通 Being-H-EDU 的 SO101 教学闭环:环境安装 → pick_cube_plate 数据集处理(LeRobot 格式 + delta 动作转换)→ Being-H0.5 后训练 → 本地推理服务 → 真机客户端控制。更多进阶内容可继续阅读 SO101 快速上手 与 Being-H-EDU 总览,祝你训练顺利!
