Being-H-EDU实战教程:SO101机械臂pick_cube_plate任务从数据处理到本地部署全流程

原创2026-10-13 09:55:001,635 阅读

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

Being-H-EDU SO101机械臂VLA教程:Being-H0.5模型家族标识

整体流程可概括为:安装环境 → 下载并转换数据集 → 配置训练 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-2B
  • EXPERT_MODEL:Qwen 专家模型检查点,如 Qwen3-0.6B
  • RESUME_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 的校验清单逐项确认:

  1. meta/info.json 中 LeRobot codebase_version 为 v2.1
  2. meta/tasks.jsonl 包含指令 Pick the cube into the plate.
  3. meta/action_delta_conversion.json 已存在(说明 delta 转换完成)
  4. data/chunk-000/*.parquet 包含 action、observation.state、task_index 等字段
  5. 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 总览,祝你训练顺利!

登录后查看全文
Being-H