基于 openpi 的 ALOHA 真实机器人部署实战指南【免费下载链接】openpi项目地址: https://gitcode.com/GitHub_Trending/op/openpiopenpi 仓库的examples/aloha_real示例提供了在真实 ALOHA 双臂机器人平台上运行 pi0 视觉-语言-动作VLA模型推理的完整参考实现。本文将以 examples/aloha_real/README.md 为核心结合仓库中的环境封装、Docker 编排、策略服务与数据转换源码系统讲解从硬件准备、双模式部署Docker / 非 Docker、三种预训练 Checkpoint 的场景布置到使用自定义 ALOHA 数据集微调训练的完整链路帮助你在自己的真实机器人上复现「取吐司」「叠毛巾」「开保鲜盒」等任务。一、背景ALOHA 平台与 openpi 示例定位ALOHAA Low-cost Open-source Hardware System for Bimanual Teleoperation是一套低成本开源双臂遥操作系统。openpi 仓库通过examples/aloha_real示例将 pi0 策略与 ALOHA 真实硬件打通其要点包括仓库使用 ALOHA 仓库的一个fork 版本与上游相比仅做了极少修改核心改动是使用 Intel RealSense 相机替代原有相机方案fork 代码位于仓库的 third_party/aloha 目录随 Docker 构建一并编译进 ROS Noetic 工作空间推理链路采用「远程策略服务器 机器人端轻量客户端」的架构策略模型运行在有 GPU 的机器上机器人端通过 WebSocket 请求动作块action chunk详见 docs/remote_inference.md。从源码结构看该示例由以下几个相互协作的模块组成文件职责examples/aloha_real/main.py机器人端运行时入口组装环境、策略 Agent 与 ActionChunkBrokerexamples/aloha_real/env.py将真实 ALOHA 环境适配为 openpi-client 的Environment接口examples/aloha_real/real_env.py底层真实硬件封装机械臂、夹爪、关节状态、图像采集主要复制自 ACT 项目examples/aloha_real/robot_utils.pyROS 订阅/发布工具包括四路相机的ImageRecorder与关节Recorderexamples/aloha_real/constants.pyALOHA 关节与夹爪的标定常量、归一化/反归一化函数examples/aloha_real/compose.yml一键启动整套系统的 Docker Compose 编排examples/aloha_real/Dockerfile基于 ROS Noetic 的镜像构建含 Python 3.10、Interbotix 驱动、ALOHA fork二、前置条件与硬件准备1. 硬件安装按 ALOHA 仓库的 hardware installation instructions 完成硬件安装。ALOHA 双臂通常包含两组各 6 自由度机械臂一组主臂用于遥操作采集、一组从臂用于执行加上夹爪和相机。2. 修改相机序列号由于本仓库使用 RealSense 相机需要修改 fork 中的发布脚本将相机序列号替换为你自己的设备序列号third_party/aloha/aloha_scripts/realsense_publisher.py每个 RealSense 相机都有唯一的序列号脚本会按序列号区分cam_high高处全景与cam_low低处全景等相机而腕部相机cam_left_wrist、cam_right_wrist通常通过 USB 端口号识别。必须将序列号改为你实际设备的序列号否则相机节点无法发布图像。3. 环境依赖说明非 Docker 方式运行需要 Python 3.10 虚拟环境依赖由 examples/aloha_real/requirements.txt 锁定由 requirements.in 通过uv pip compile生成关键依赖包括pyrealsense2RealSense 相机驱动rospkg、pyyamlROS 工具链依赖dm_control、mujoco基于 MuJoCo 的仿真控制栈modern_robotics、pyquaternion机器人运动学与姿态计算msgpack、websockets与策略服务器通信的序列化与传输tyro命令行参数解析main.py 与转换脚本均使用。三、部署方式一Docker 一键启动Docker 方式由 examples/aloha_real/compose.yml 编排四个服务一条命令拉起整套系统export SERVER_ARGS--env ALOHA --default_prompttake the toast out of the toaster docker compose -f examples/aloha_real/compose.yml up --buildCompose 编排的四个服务服务镜像职责ros_masterros:noetic-robot启动roscore作为 ROS 主节点aloha_ros_nodesaloha_real本地构建执行roslaunch aloha ros_nodes.launch启动机械臂与相机 ROS 节点openpi_serveropenpi_server本地构建由 scripts/docker/serve_policy.Dockerfile 构建运行uv run scripts/serve_policy.py加载 pi0 模型并提供策略服务runtimealoha_real本地构建运行 examples/aloha_real/main.py即机器人端运行时需要重点理解的关键配置SERVER_ARGS环境变量通过environment字段透传给openpi_server服务控制策略服务器加载哪个环境--env ALOHA以及默认任务提示词--default_prompt。修改default_prompt即可切换执行的任务详见下文 Checkpoint 指南中的提示词。OPENPI_DATA_HOME默认挂载宿主机~/.cache/openpi到容器内/openpi_assets策略 Checkpoint 与归一化统计资产norm stats从这里加载可通过OPENPI_DATA_HOME环境变量覆盖宿主机侧缓存目录。network_mode: hostprivileged: true机器人 ROS 通信roscore/话题、WebSocket 策略请求以及 USB/串口硬件访问都需要宿主机网络与设备权限/dev被挂载进aloha_ros_nodes服务$PWD挂载到/app以便直接运行仓库代码。GPU 资源预留openpi_server服务通过deploy.resources.reservations.devices声明需要 1 块 NVIDIA GPU如果没有 GPU 则需注释掉这段 deploy 配置模型推理将无法进行但编译仍可完成。init: truetty: true以 PID 1 方式运行并分配 TTY保证roslaunch与运行时进程能正确接收信号。docker compose up会按依赖顺序启动ros_master→aloha_ros_nodes/openpi_server→runtime最终由runtime服务执行python3 /app/examples/aloha_real/main.py进入回合循环见 examples/aloha_real/Dockerfile 的CMD。四、部署方式二不使用 Docker三个终端窗口不依赖 Docker 时需要手动准备环境并分别启动 ROS 节点、策略服务器与机器人运行时。终端窗口 1创建虚拟环境并运行机器人# 创建 Python 3.10 虚拟环境 uv venv --python 3.10 examples/aloha_real/.venv source examples/aloha_real/.venv/bin/activate # 安装锁定依赖与 openpi-client 客户端包 uv pip sync examples/aloha_real/requirements.txt uv pip install -e packages/openpi-client # 运行机器人端运行时默认连接 localhost:8000 的策略服务器 python -m examples.aloha_real.main终端窗口 2启动 ROS 节点roslaunch aloha ros_nodes.launch该命令需要在已 source ALOHA fork 工作空间third_party/aloha编译产物的环境中执行负责拉起机械臂驱动、RealSense 相机发布与夹爪控制等 ROS 节点。终端窗口 3启动策略服务器uv run scripts/serve_policy.py --env ALOHA --default_prompttake the toast out of the toasterscripts/serve_policy.py会根据--env ALOHA自动选择pi0_baseCheckpoint对应gs://openpi-assets/checkpoints/pi0_base并加载对应环境的输入/输出变换对 ALOHA 而言是 src/openpi/policies/aloha_policy.py 中的AlohaInputs/AlohaOutputs在默认端口8000上提供 WebSocket 策略服务。--default_prompt指定当前回合使用的自然语言指令。机器人端运行时的工作机制对照 examples/aloha_real/main.py运行时启动流程为创建WebsocketClientPolicy连接host默认0.0.0.0与port默认8000上的策略服务器并打印服务器元数据含reset_pose复位姿态用服务器下发的reset_pose构造AlohaRealEnvironment将策略包装进ActionChunkBrokeraction_horizon25即每次推理预测 25 步动作块组装Runtime以max_hz5050 Hz 控制频率运行支持num_episodes、max_episode_steps参数控制回合数与每回合最大步数。其中ActionChunkBroker位于 packages/openpi_client/src/openpi_client/action_chunk_broker.py负责将策略预测的动作块按步序切分下发——模型并非每步都推理而是每action_horizon步推理一次中间各步开环执行预测的动作块。观测与动作空间从 examples/aloha_real/real_env.py 的类注释可以明确动作/观测的维度结构动作空间14 维[左臂关节角 (6), 左夹爪归一化位置 (1), 右臂关节角 (6), 右夹爪归一化位置 (1)]夹爪 0 表示闭合、1 表示张开观测空间qpos14 维关节角 夹爪、qvel14 维角速度 夹爪速度、effort力矩以及四路相机图像cam_high、cam_low、cam_left_wrist、cam_right_wrist均为 480×640×3 的 uint8 图像。在 examples/aloha_real/env.py 的get_observation中图像会先删除深度通道再经image_tools.resize_with_pad缩放填充到224×224并转为 uint8最后重排为[C, H, W]送入策略动作则从策略输出中取出actions字段直接执行。reset()会通过real_env依次重启夹爪电机、复位关节到reset_pose、执行「先闭合再张开」的夹爪复位该顺序与原始 ALOHA 相反是为了匹配 pi 内部数据采集时的夹爪初始状态并减少电机故障。策略服务器与客户端的完整链路服务端与客户端的协议细节可参考 docs/remote_inference.md服务端uv run scripts/serve_policy.py --env ALOHA等价于执行uv run scripts/serve_policy.py policy:checkpoint --policy.configpi0_fast_aloha --policy.dirgs://openpi-assets/checkpoints/pi0_base之类的底层命令——--env只是快捷方式你也可以为自己训练的 Checkpoint 显式指定policy:checkpoint与config/dir参数来启动服务器客户端openpi-client包提供websocket_client_policy.WebsocketClientPolicy(host, port)机器人端只需构造{observation/image: ..., observation/wrist_image: ..., observation/state: ..., prompt: ...}观测字典调用client.infer(observation)[actions]即可拿到形状为(action_horizon, action_dim)的动作块。proprioceptive 的state可以传未归一化的原始值归一化在服务器端完成图像建议在客户端先resize_with_pad到 224×224 并convert_to_uint8以降低带宽与延迟。五、ALOHA Checkpoint 使用指南pi0_base模型可以在 ALOHA 平台上零样本完成简单任务此外官方额外提供两个微调 Checkpoint可完成更进阶的任务。需要强调的是零样本运行仍是实验性功能不保证在你的机器人上一定成功官方推荐的使用方式是用目标机器人的数据微调pi0_base。Checkpoint任务Prompt路径pi0_base简单任务零样本视任务而定gs://openpi-assets/checkpoints/pi0_basepi0_aloha_towel把毛巾折成八折fold the towelgs://openpi-assets/checkpoints/pi0_aloha_towelpi0_aloha_tupperware打开保鲜盒并把食物倒到盘子上open the tupperware and put the food on the plategs://openpi-assets/checkpoints/pi0_aloha_tupperware这些微调配置在 src/openpi/training/config.py 中均有对应定义pi0_aloha_towel、pi0_aloha_tupperware它们都基于pi0模型数据侧使用LeRobotAlohaDataConfig并指定assetsAssetsConfig(asset_idtrossen)加载 Trossen 机器人的归一化统计同时把default_prompt预设为任务指令、在policy_metadata中给出复位姿态[0, -1.5, 1.5, 0, 0, 0]。以下为各任务的经验性场景布置建议——策略曾在多套 ALOHA 工位上、未见过的条件下工作但这些建议是为了最大化成功概率而总结的。1. 吐司任务Toast Task机器人需要从烤面包机中取出两片吐司并放到盘子上。Checkpoint 路径gs://openpi-assets/checkpoints/pi0_basePrompttake the toast out of the toaster所需物体两片吐司、一个盘子、一台标准烤面包机物体分布经验真吐司与橡胶仿真吐司均可兼容标准双槽烤面包机各种颜色的盘子均可。场景布置建议烤面包机放在工作区左上象限两片吐司初始时位于烤面包机内且至少 1 cm 的面包露出顶部便于抓取盘子大致放在工作区中下方自然光与合成光均可但不要让场景过暗例如不要放在封闭空间或窗帘下。2. 毛巾任务Towel Task机器人将一条小毛巾约手巾大小对折成八折。Checkpoint 路径gs://openpi-assets/checkpoints/pi0_aloha_towelPromptfold the towel物体分布经验各种纯色毛巾均可纹理复杂或条纹毛巾上表现较差。场景布置建议毛巾摊平并大致放在桌面中央选择与桌面颜色反差明显的毛巾避免融为一体。3. 保鲜盒任务Tupperware Task机器人打开装有食物的保鲜盒并把内容物倒到盘子上。Checkpoint 路径gs://openpi-assets/checkpoints/pi0_aloha_tupperwarePromptopen the tupperware and put the food on the plate所需物体保鲜盒、食物或类食物物品、盘子物体分布经验各种仿真食物均可如仿真鸡块、薯条、炸鸡兼容不同盒盖颜色与形状的保鲜盒方形带角掀盖的保鲜盒表现最佳策略见过各种纯色盘子。场景布置建议保鲜盒与盘子都大致放在工作区中央附近时表现最好相对位置保鲜盒在左盘子在其右方或下方保鲜盒的掀盖朝向盘子。六、使用自定义 ALOHA 数据集微调训练官方强烈推荐的方式是采集目标机器人的数据微调pi0_base。整个流程分两步第一步将数据集转换为 LeRobot v2.0 格式仓库提供转换脚本 examples/aloha_real/convert_aloha_data_to_lerobot.py把 ALOHA 采集的 HDF5 数据转换为 LeRobot dataset v2.0 格式uv run examples/aloha_real/convert_aloha_data_to_lerobot.py \ --raw-dir /path/to/raw/data \ --repo-id org/dataset-name官方示例是将 BiPlay 仓库的aloha_pen_uncap_diverse_raw原始数据集转换后上传到 HuggingFace Hub得到physical-intelligence/aloha_pen_uncap_diverse。该脚本的关键行为与源码对应读取原始 HDF5遍历episode_*.hdf5文件从/observations/qpos、/action读取状态与动作若存在/observations/qvel、/observations/effort则一并读取为速度/力矩特征通过has_velocity/has_effort自动检测图像处理固定读取cam_high、cam_low、cam_left_wrist、cam_right_wrist四路相机自动忽略 depth 深度通道对压缩存储的图像用 OpenCV 逐帧解码并转 RGB特征结构14 个电机左右各 6 关节 夹爪对应observation.state与action图像为(3, 480, 640)数据集以50 FPS、robot_typealoha--is-mobile时用mobile_aloha创建模式选择--mode video|image决定图像以视频还是单帧存储默认脚本入口为image上传默认push_to_hubTrue会把转换结果推送到 HuggingFace Hub本地转换可传--push-to-hub false其他参数--task任务描述默认DEBUG、--episodes选择部分 episode、--raw-repo-id当本地目录不存在时直接从 Hub 下载原始数据。第二步定义使用自定义数据集的训练配置参考 src/openpi/training/config.py 中的pi0_aloha_pen_uncap配置即可定义使用自定义数据集的新训练配置。具体训练命令请参照仓库根目录 README.md 中关于如何用新配置运行训练的说明。重要归一化统计norm stats的匹配基础 Checkpoint 中包含了多种常见机器人配置的归一化统计。当用自定义数据集微调基础 Checkpoint 时如果该数据集来自这些配置之一建议使用基础 Checkpoint 中自带的对应归一化统计而不是重新计算。在示例配置中这一做法通过AssetsConfig指定asset_id指定为对应机器人配置如trossen同时提供预训练 Checkpoint 的资产目录路径assets_dir。例如来自 src/openpi/training/config.py 中AssetsConfig的文档示例AssetsConfig( assets_dirgs://openpi-assets/checkpoints/pi0_base/assets, asset_idtrossen, )该机制在源码中的语义是AssetsConfig决定数据管线使用的资产如 norm stats的加载位置这些资产会被复制到 Checkpoint 的assets/asset_id目录下从而在微调时复用与预训练一致的归一化范围避免因统计不匹配导致的训练不稳定或效果退化。七、故障排查与注意事项策略无法连接确认openpi_server已就绪且端口 8000 未被占用Docker 方式下runtime服务依赖openpi_server但实际推理请求发生在运行时启动之后模型加载可能需要较长时间首次需下载gs://openpi-assets/checkpoints/pi0_base等 Checkpoint请保证网络可达 GCS。相机无图像检查realsense_publisher.py中的序列号是否与rs-enumerate-devices输出一致Docker 方式确认/dev已挂载且容器为 privileged 模式。ROS 通信失败所有服务或三个终端必须共享同一 ROS masterDocker 方式已统一使用network_mode: host。复位姿态差异pi0_aloha系列配置在policy_metadata中定义reset_pose[0, -1.5, 1.5, 0, 0, 0]与 examples/aloha_real/real_env.py 中的默认值DEFAULT_RESET_POSITION[0, -0.96, 1.16, 0, -0.3, 0]不同——运行时以服务器下发的reset_pose为准若更换 Checkpoint 请留意复位姿态的变化。零样本不稳定正如文档强调零样本运行是实验性功能。若任务失败率偏高优先按第五节中的场景布置建议调整物体位置、光照与初始状态或采集数据走微调路线。GPU 缺失非 Docker 方式确保运行serve_policy.py的机器有可用 GPUDocker 方式注释掉 compose 中的 GPUdeploy段仅用于完成构建实际推理仍需 GPU。八、总结本文完整梳理了 openpi 在真实 ALOHA 平台上从零到一部署 pi0 策略的路径硬件准备与相机序列号配置、Docker 与手动双模式启动、ActionChunkBroker WebSocket 策略服务器的推理架构、三个预训练 Checkpoint 的场景布置经验以及用convert_aloha_data_to_lerobot.py转换自定义数据集并微调训练的完整流程。相关可深入阅读的仓库资源包括运行时入口与参数examples/aloha_real/main.py环境适配与真实硬件封装examples/aloha_real/env.py、examples/aloha_real/real_env.py关节/夹爪标定常量examples/aloha_real/constants.py远程策略服务器与客户端协议docs/remote_inference.mdALOHA 策略输入输出变换src/openpi/policies/aloha_policy.py数据转换与训练配置examples/aloha_real/convert_aloha_data_to_lerobot.py、src/openpi/training/config.py整体训练说明README.md【免费下载链接】openpi项目地址: https://gitcode.com/GitHub_Trending/op/openpi创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考 基于 openpi 的 ALOHA 真实机器人部署实战指南
基于 openpi 的 ALOHA 真实机器人部署实战指南【免费下载链接】openpi项目地址: https://gitcode.com/GitHub_Trending/op/openpiopenpi 仓库的examples/aloha_real示例提供了在真实 ALOHA 双臂机器人平台上运行 pi0 视觉-语言-动作VLA模型推理的完整参考实现。本文将以 examples/aloha_real/README.md 为核心结合仓库中的环境封装、Docker 编排、策略服务与数据转换源码系统讲解从硬件准备、双模式部署Docker / 非 Docker、三种预训练 Checkpoint 的场景布置到使用自定义 ALOHA 数据集微调训练的完整链路帮助你在自己的真实机器人上复现「取吐司」「叠毛巾」「开保鲜盒」等任务。一、背景ALOHA 平台与 openpi 示例定位ALOHAA Low-cost Open-source Hardware System for Bimanual Teleoperation是一套低成本开源双臂遥操作系统。openpi 仓库通过examples/aloha_real示例将 pi0 策略与 ALOHA 真实硬件打通其要点包括仓库使用 ALOHA 仓库的一个fork 版本与上游相比仅做了极少修改核心改动是使用 Intel RealSense 相机替代原有相机方案fork 代码位于仓库的 third_party/aloha 目录随 Docker 构建一并编译进 ROS Noetic 工作空间推理链路采用「远程策略服务器 机器人端轻量客户端」的架构策略模型运行在有 GPU 的机器上机器人端通过 WebSocket 请求动作块action chunk详见 docs/remote_inference.md。从源码结构看该示例由以下几个相互协作的模块组成文件职责examples/aloha_real/main.py机器人端运行时入口组装环境、策略 Agent 与 ActionChunkBrokerexamples/aloha_real/env.py将真实 ALOHA 环境适配为 openpi-client 的Environment接口examples/aloha_real/real_env.py底层真实硬件封装机械臂、夹爪、关节状态、图像采集主要复制自 ACT 项目examples/aloha_real/robot_utils.pyROS 订阅/发布工具包括四路相机的ImageRecorder与关节Recorderexamples/aloha_real/constants.pyALOHA 关节与夹爪的标定常量、归一化/反归一化函数examples/aloha_real/compose.yml一键启动整套系统的 Docker Compose 编排examples/aloha_real/Dockerfile基于 ROS Noetic 的镜像构建含 Python 3.10、Interbotix 驱动、ALOHA fork二、前置条件与硬件准备1. 硬件安装按 ALOHA 仓库的 hardware installation instructions 完成硬件安装。ALOHA 双臂通常包含两组各 6 自由度机械臂一组主臂用于遥操作采集、一组从臂用于执行加上夹爪和相机。2. 修改相机序列号由于本仓库使用 RealSense 相机需要修改 fork 中的发布脚本将相机序列号替换为你自己的设备序列号third_party/aloha/aloha_scripts/realsense_publisher.py每个 RealSense 相机都有唯一的序列号脚本会按序列号区分cam_high高处全景与cam_low低处全景等相机而腕部相机cam_left_wrist、cam_right_wrist通常通过 USB 端口号识别。必须将序列号改为你实际设备的序列号否则相机节点无法发布图像。3. 环境依赖说明非 Docker 方式运行需要 Python 3.10 虚拟环境依赖由 examples/aloha_real/requirements.txt 锁定由 requirements.in 通过uv pip compile生成关键依赖包括pyrealsense2RealSense 相机驱动rospkg、pyyamlROS 工具链依赖dm_control、mujoco基于 MuJoCo 的仿真控制栈modern_robotics、pyquaternion机器人运动学与姿态计算msgpack、websockets与策略服务器通信的序列化与传输tyro命令行参数解析main.py 与转换脚本均使用。三、部署方式一Docker 一键启动Docker 方式由 examples/aloha_real/compose.yml 编排四个服务一条命令拉起整套系统export SERVER_ARGS--env ALOHA --default_prompttake the toast out of the toaster docker compose -f examples/aloha_real/compose.yml up --buildCompose 编排的四个服务服务镜像职责ros_masterros:noetic-robot启动roscore作为 ROS 主节点aloha_ros_nodesaloha_real本地构建执行roslaunch aloha ros_nodes.launch启动机械臂与相机 ROS 节点openpi_serveropenpi_server本地构建由 scripts/docker/serve_policy.Dockerfile 构建运行uv run scripts/serve_policy.py加载 pi0 模型并提供策略服务runtimealoha_real本地构建运行 examples/aloha_real/main.py即机器人端运行时需要重点理解的关键配置SERVER_ARGS环境变量通过environment字段透传给openpi_server服务控制策略服务器加载哪个环境--env ALOHA以及默认任务提示词--default_prompt。修改default_prompt即可切换执行的任务详见下文 Checkpoint 指南中的提示词。OPENPI_DATA_HOME默认挂载宿主机~/.cache/openpi到容器内/openpi_assets策略 Checkpoint 与归一化统计资产norm stats从这里加载可通过OPENPI_DATA_HOME环境变量覆盖宿主机侧缓存目录。network_mode: hostprivileged: true机器人 ROS 通信roscore/话题、WebSocket 策略请求以及 USB/串口硬件访问都需要宿主机网络与设备权限/dev被挂载进aloha_ros_nodes服务$PWD挂载到/app以便直接运行仓库代码。GPU 资源预留openpi_server服务通过deploy.resources.reservations.devices声明需要 1 块 NVIDIA GPU如果没有 GPU 则需注释掉这段 deploy 配置模型推理将无法进行但编译仍可完成。init: truetty: true以 PID 1 方式运行并分配 TTY保证roslaunch与运行时进程能正确接收信号。docker compose up会按依赖顺序启动ros_master→aloha_ros_nodes/openpi_server→runtime最终由runtime服务执行python3 /app/examples/aloha_real/main.py进入回合循环见 examples/aloha_real/Dockerfile 的CMD。四、部署方式二不使用 Docker三个终端窗口不依赖 Docker 时需要手动准备环境并分别启动 ROS 节点、策略服务器与机器人运行时。终端窗口 1创建虚拟环境并运行机器人# 创建 Python 3.10 虚拟环境 uv venv --python 3.10 examples/aloha_real/.venv source examples/aloha_real/.venv/bin/activate # 安装锁定依赖与 openpi-client 客户端包 uv pip sync examples/aloha_real/requirements.txt uv pip install -e packages/openpi-client # 运行机器人端运行时默认连接 localhost:8000 的策略服务器 python -m examples.aloha_real.main终端窗口 2启动 ROS 节点roslaunch aloha ros_nodes.launch该命令需要在已 source ALOHA fork 工作空间third_party/aloha编译产物的环境中执行负责拉起机械臂驱动、RealSense 相机发布与夹爪控制等 ROS 节点。终端窗口 3启动策略服务器uv run scripts/serve_policy.py --env ALOHA --default_prompttake the toast out of the toasterscripts/serve_policy.py会根据--env ALOHA自动选择pi0_baseCheckpoint对应gs://openpi-assets/checkpoints/pi0_base并加载对应环境的输入/输出变换对 ALOHA 而言是 src/openpi/policies/aloha_policy.py 中的AlohaInputs/AlohaOutputs在默认端口8000上提供 WebSocket 策略服务。--default_prompt指定当前回合使用的自然语言指令。机器人端运行时的工作机制对照 examples/aloha_real/main.py运行时启动流程为创建WebsocketClientPolicy连接host默认0.0.0.0与port默认8000上的策略服务器并打印服务器元数据含reset_pose复位姿态用服务器下发的reset_pose构造AlohaRealEnvironment将策略包装进ActionChunkBrokeraction_horizon25即每次推理预测 25 步动作块组装Runtime以max_hz5050 Hz 控制频率运行支持num_episodes、max_episode_steps参数控制回合数与每回合最大步数。其中ActionChunkBroker位于 packages/openpi_client/src/openpi_client/action_chunk_broker.py负责将策略预测的动作块按步序切分下发——模型并非每步都推理而是每action_horizon步推理一次中间各步开环执行预测的动作块。观测与动作空间从 examples/aloha_real/real_env.py 的类注释可以明确动作/观测的维度结构动作空间14 维[左臂关节角 (6), 左夹爪归一化位置 (1), 右臂关节角 (6), 右夹爪归一化位置 (1)]夹爪 0 表示闭合、1 表示张开观测空间qpos14 维关节角 夹爪、qvel14 维角速度 夹爪速度、effort力矩以及四路相机图像cam_high、cam_low、cam_left_wrist、cam_right_wrist均为 480×640×3 的 uint8 图像。在 examples/aloha_real/env.py 的get_observation中图像会先删除深度通道再经image_tools.resize_with_pad缩放填充到224×224并转为 uint8最后重排为[C, H, W]送入策略动作则从策略输出中取出actions字段直接执行。reset()会通过real_env依次重启夹爪电机、复位关节到reset_pose、执行「先闭合再张开」的夹爪复位该顺序与原始 ALOHA 相反是为了匹配 pi 内部数据采集时的夹爪初始状态并减少电机故障。策略服务器与客户端的完整链路服务端与客户端的协议细节可参考 docs/remote_inference.md服务端uv run scripts/serve_policy.py --env ALOHA等价于执行uv run scripts/serve_policy.py policy:checkpoint --policy.configpi0_fast_aloha --policy.dirgs://openpi-assets/checkpoints/pi0_base之类的底层命令——--env只是快捷方式你也可以为自己训练的 Checkpoint 显式指定policy:checkpoint与config/dir参数来启动服务器客户端openpi-client包提供websocket_client_policy.WebsocketClientPolicy(host, port)机器人端只需构造{observation/image: ..., observation/wrist_image: ..., observation/state: ..., prompt: ...}观测字典调用client.infer(observation)[actions]即可拿到形状为(action_horizon, action_dim)的动作块。proprioceptive 的state可以传未归一化的原始值归一化在服务器端完成图像建议在客户端先resize_with_pad到 224×224 并convert_to_uint8以降低带宽与延迟。五、ALOHA Checkpoint 使用指南pi0_base模型可以在 ALOHA 平台上零样本完成简单任务此外官方额外提供两个微调 Checkpoint可完成更进阶的任务。需要强调的是零样本运行仍是实验性功能不保证在你的机器人上一定成功官方推荐的使用方式是用目标机器人的数据微调pi0_base。Checkpoint任务Prompt路径pi0_base简单任务零样本视任务而定gs://openpi-assets/checkpoints/pi0_basepi0_aloha_towel把毛巾折成八折fold the towelgs://openpi-assets/checkpoints/pi0_aloha_towelpi0_aloha_tupperware打开保鲜盒并把食物倒到盘子上open the tupperware and put the food on the plategs://openpi-assets/checkpoints/pi0_aloha_tupperware这些微调配置在 src/openpi/training/config.py 中均有对应定义pi0_aloha_towel、pi0_aloha_tupperware它们都基于pi0模型数据侧使用LeRobotAlohaDataConfig并指定assetsAssetsConfig(asset_idtrossen)加载 Trossen 机器人的归一化统计同时把default_prompt预设为任务指令、在policy_metadata中给出复位姿态[0, -1.5, 1.5, 0, 0, 0]。以下为各任务的经验性场景布置建议——策略曾在多套 ALOHA 工位上、未见过的条件下工作但这些建议是为了最大化成功概率而总结的。1. 吐司任务Toast Task机器人需要从烤面包机中取出两片吐司并放到盘子上。Checkpoint 路径gs://openpi-assets/checkpoints/pi0_basePrompttake the toast out of the toaster所需物体两片吐司、一个盘子、一台标准烤面包机物体分布经验真吐司与橡胶仿真吐司均可兼容标准双槽烤面包机各种颜色的盘子均可。场景布置建议烤面包机放在工作区左上象限两片吐司初始时位于烤面包机内且至少 1 cm 的面包露出顶部便于抓取盘子大致放在工作区中下方自然光与合成光均可但不要让场景过暗例如不要放在封闭空间或窗帘下。2. 毛巾任务Towel Task机器人将一条小毛巾约手巾大小对折成八折。Checkpoint 路径gs://openpi-assets/checkpoints/pi0_aloha_towelPromptfold the towel物体分布经验各种纯色毛巾均可纹理复杂或条纹毛巾上表现较差。场景布置建议毛巾摊平并大致放在桌面中央选择与桌面颜色反差明显的毛巾避免融为一体。3. 保鲜盒任务Tupperware Task机器人打开装有食物的保鲜盒并把内容物倒到盘子上。Checkpoint 路径gs://openpi-assets/checkpoints/pi0_aloha_tupperwarePromptopen the tupperware and put the food on the plate所需物体保鲜盒、食物或类食物物品、盘子物体分布经验各种仿真食物均可如仿真鸡块、薯条、炸鸡兼容不同盒盖颜色与形状的保鲜盒方形带角掀盖的保鲜盒表现最佳策略见过各种纯色盘子。场景布置建议保鲜盒与盘子都大致放在工作区中央附近时表现最好相对位置保鲜盒在左盘子在其右方或下方保鲜盒的掀盖朝向盘子。六、使用自定义 ALOHA 数据集微调训练官方强烈推荐的方式是采集目标机器人的数据微调pi0_base。整个流程分两步第一步将数据集转换为 LeRobot v2.0 格式仓库提供转换脚本 examples/aloha_real/convert_aloha_data_to_lerobot.py把 ALOHA 采集的 HDF5 数据转换为 LeRobot dataset v2.0 格式uv run examples/aloha_real/convert_aloha_data_to_lerobot.py \ --raw-dir /path/to/raw/data \ --repo-id org/dataset-name官方示例是将 BiPlay 仓库的aloha_pen_uncap_diverse_raw原始数据集转换后上传到 HuggingFace Hub得到physical-intelligence/aloha_pen_uncap_diverse。该脚本的关键行为与源码对应读取原始 HDF5遍历episode_*.hdf5文件从/observations/qpos、/action读取状态与动作若存在/observations/qvel、/observations/effort则一并读取为速度/力矩特征通过has_velocity/has_effort自动检测图像处理固定读取cam_high、cam_low、cam_left_wrist、cam_right_wrist四路相机自动忽略 depth 深度通道对压缩存储的图像用 OpenCV 逐帧解码并转 RGB特征结构14 个电机左右各 6 关节 夹爪对应observation.state与action图像为(3, 480, 640)数据集以50 FPS、robot_typealoha--is-mobile时用mobile_aloha创建模式选择--mode video|image决定图像以视频还是单帧存储默认脚本入口为image上传默认push_to_hubTrue会把转换结果推送到 HuggingFace Hub本地转换可传--push-to-hub false其他参数--task任务描述默认DEBUG、--episodes选择部分 episode、--raw-repo-id当本地目录不存在时直接从 Hub 下载原始数据。第二步定义使用自定义数据集的训练配置参考 src/openpi/training/config.py 中的pi0_aloha_pen_uncap配置即可定义使用自定义数据集的新训练配置。具体训练命令请参照仓库根目录 README.md 中关于如何用新配置运行训练的说明。重要归一化统计norm stats的匹配基础 Checkpoint 中包含了多种常见机器人配置的归一化统计。当用自定义数据集微调基础 Checkpoint 时如果该数据集来自这些配置之一建议使用基础 Checkpoint 中自带的对应归一化统计而不是重新计算。在示例配置中这一做法通过AssetsConfig指定asset_id指定为对应机器人配置如trossen同时提供预训练 Checkpoint 的资产目录路径assets_dir。例如来自 src/openpi/training/config.py 中AssetsConfig的文档示例AssetsConfig( assets_dirgs://openpi-assets/checkpoints/pi0_base/assets, asset_idtrossen, )该机制在源码中的语义是AssetsConfig决定数据管线使用的资产如 norm stats的加载位置这些资产会被复制到 Checkpoint 的assets/asset_id目录下从而在微调时复用与预训练一致的归一化范围避免因统计不匹配导致的训练不稳定或效果退化。七、故障排查与注意事项策略无法连接确认openpi_server已就绪且端口 8000 未被占用Docker 方式下runtime服务依赖openpi_server但实际推理请求发生在运行时启动之后模型加载可能需要较长时间首次需下载gs://openpi-assets/checkpoints/pi0_base等 Checkpoint请保证网络可达 GCS。相机无图像检查realsense_publisher.py中的序列号是否与rs-enumerate-devices输出一致Docker 方式确认/dev已挂载且容器为 privileged 模式。ROS 通信失败所有服务或三个终端必须共享同一 ROS masterDocker 方式已统一使用network_mode: host。复位姿态差异pi0_aloha系列配置在policy_metadata中定义reset_pose[0, -1.5, 1.5, 0, 0, 0]与 examples/aloha_real/real_env.py 中的默认值DEFAULT_RESET_POSITION[0, -0.96, 1.16, 0, -0.3, 0]不同——运行时以服务器下发的reset_pose为准若更换 Checkpoint 请留意复位姿态的变化。零样本不稳定正如文档强调零样本运行是实验性功能。若任务失败率偏高优先按第五节中的场景布置建议调整物体位置、光照与初始状态或采集数据走微调路线。GPU 缺失非 Docker 方式确保运行serve_policy.py的机器有可用 GPUDocker 方式注释掉 compose 中的 GPUdeploy段仅用于完成构建实际推理仍需 GPU。八、总结本文完整梳理了 openpi 在真实 ALOHA 平台上从零到一部署 pi0 策略的路径硬件准备与相机序列号配置、Docker 与手动双模式启动、ActionChunkBroker WebSocket 策略服务器的推理架构、三个预训练 Checkpoint 的场景布置经验以及用convert_aloha_data_to_lerobot.py转换自定义数据集并微调训练的完整流程。相关可深入阅读的仓库资源包括运行时入口与参数examples/aloha_real/main.py环境适配与真实硬件封装examples/aloha_real/env.py、examples/aloha_real/real_env.py关节/夹爪标定常量examples/aloha_real/constants.py远程策略服务器与客户端协议docs/remote_inference.mdALOHA 策略输入输出变换src/openpi/policies/aloha_policy.py数据转换与训练配置examples/aloha_real/convert_aloha_data_to_lerobot.py、src/openpi/training/config.py整体训练说明README.md【免费下载链接】openpi项目地址: https://gitcode.com/GitHub_Trending/op/openpi创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考