openpi π₀ 项目部署运行逻辑（四）——机器人主控程序 main.py — aloha_real

π₀ 机器人主控脚本都在 examples 中：

可以看到包含了多种类机器人适配

此笔记首先记录了 aloha_real 部分

aloha_real 中，main.py 是 openpi ALOHA 平台上“主控执行入口”，负责：

• 建立与推理服务器（serve_policy.py，WebSocket服务）的通信
• 启动实际的机器人环境交互回路（包括视觉、动作、状态反馈）
• 循环执行策略推理与动作下发，控制机器人完成任务

目录

1 库引用

2 参数定义

3 主流程 main

4 流程逻辑

5 使用方法总结

---

1 库引用

import dataclasses    # 用于创建结构化参数对象
import logging        # 用于日志输出，便于调试和运行记录# 导入 openpi_client 相关模块，用于动作下发与策略服务器通信
from openpi_client import action_chunk_broker
from openpi_client import websocket_client_policy as _websocket_client_policy
from openpi_client.runtime import runtime as _runtime
from openpi_client.runtime.agents import policy_agent as _policy_agent
import tyro           # 更现代的命令行参数解析库# 导入当前目录下的 env.py，包含真实机器人环境封装
from examples.aloha_real import env as _env

2 参数定义

# 命令行参数结构体定义
@dataclasses.dataclass
class Args:host: str = "0.0.0.0"                  # 策略服务端的IP地址或主机名，默认监听所有地址（本地）port: int = 8000                       # 策略服务端口号，默认8000action_horizon: int = 25               # 每次下发给机器人的连续动作片段长度num_episodes: int = 1                  # 总共要运行多少个完整任务回合（episode）max_episode_steps: int = 1000          # 每个任务允许的最大动作步数（防止卡死）

• host, port：推理服务器（策略服务端）的地址端口
• action_horizon：每次规划/推理的连续动作片段长度
• num_episodes：循环任务的数量（实验集大小，通常=1）
• max_episode_steps：每个任务最大步骤数（超限自动终止）

3 主流程 main

def main(args: Args) -> None:# 实例化WebSocket策略客户端，与策略服务器建立通信ws_client_policy = _websocket_client_policy.WebsocketClientPolicy(host=args.host,port=args.port,)# 打印推理服务器返回的模型元信息，帮助调试logging.info(f"Server metadata: {ws_client_policy.get_server_metadata()}")metadata = ws_client_policy.get_server_metadata()# 构建机器人运行时回路对象，包括环境、Agent等runtime = _runtime.Runtime(environment=_env.AlohaRealEnvironment(reset_position=metadata.get("reset_pose")  # 从服务器元数据获取初始重置位姿),agent=_policy_agent.PolicyAgent(# 使用ActionChunkBroker，支持批量连续动作推理，减少通讯延迟policy=action_chunk_broker.ActionChunkBroker(policy=ws_client_policy,action_horizon=args.action_horizon,)),subscribers=[],             # 可扩展的观测/日志/可视化订阅者，目前为空max_hz=50,                  # 主循环最大频率（Hz），实际受通信/硬件影响num_episodes=args.num_episodes,               # 任务回合数max_episode_steps=args.max_episode_steps,     # 单回合最大动作步数)runtime.run()   # 启动机器人任务主循环if __name__ == "__main__":logging.basicConfig(level=logging.INFO, force=True)  # 全局设置日志级别tyro.cli(main)   # 使用tyro自动从命令行解析参数并运行main()

具体流程如下：

1. 建立一个 WebSocket 客户端，连接远端策略推理服务

2. 获取服务器的模型元数据（包括是否需要语言提示、动作空间信息等）

3. 构建机器人回路的“运行时对象” Runtime，内含多个关键组件：

• environment：物理环境交互接口，这里是实际的 ALOHA 机器人（重置姿态等参数从 server metadata 获取）
• agent：决策主体，这里是通过 PolicyAgent 封装、带有“连续 chunk 动作预测能力”的 policy
• subscribers：订阅者/观察器（可扩展，用于实时数据流转或远程监控）
• max_hz：主循环最大频率
• num_episodes、max_episode_steps：回合数与最大步长

ActionChunkBroker 实现了高效的“分块推理”，一次请求多个动作 chunk，减少通信和延迟

4. 开始回路，实际控制机器人感知、推理、动作执行和反馈的全流程

4 流程逻辑

+-------------------+    WebSocket    +---------------------+
|   main.py         | <-------------> | serve_policy.py     |
|  (机器人主控)     |                 | (策略推理服务)      |
+-------------------+                 +---------------------+|                                       v                                       控制机器人硬件

5 使用方法总结

目前给的几个机器人样例还是很详细的，对于 aloha_real 来说，记一下详细的流程笔记：

基本流程思路如下：

1. 创建一个隔离的 Python 3.10 虚拟环境
2. 安装项目所需的依赖（包括第三方库和本地开发的包）
3. 运行机器人程序的主模块（examples.aloha_real.main）

1. 创建虚拟环境

# Create virtual environment
uv venv --python 3.11 examples/aloha_real/.venv

使用 uv 在指定路径下创建一个隔离的 Python 环境，避免与系统或其他项目的依赖冲突

PS：此处建议为了依赖问题安装 Python 版本 ≥3.11

2. 激活虚拟环境

source examples/aloha_real/.venv/bin/activate

3. 同步依赖

uv pip sync examples/aloha_real/requirements.txt

使用 uv pip 安装 requirements.txt 中列出的所有依赖包

4. 以可编辑模式安装本地包

uv pip install -e packages/openpi-client

• -e：可编辑模式，允许直接修改包代码而无需重新安装
• packages/openpi-client：本地包的路径

5. 运行机器人程序

# Run the robot
python -m examples.aloha_real.main

• -m：以模块形式运行

修改主机 ip：

    host: str = "192.168.1.20"

最后，运行连接

python -m examples.aloha_real.main