psi0-brainco

项目说明

本项目提供了 Psi0 算法在 Unitree G1 29 自由度教育版、BrainCo Revo1 触觉版右手与 DECXIN 摄像头组合上的训练和推理部署实现。

<video controls playsinline preload="metadata" width="40%" src="https://huggingface.co/yuzaiyangy/psi0-brainco/resolve/main/demo-web.mp4"></video>

观看或下载演示视频

目录

1. 系统组成与设备分工
2. 环境复现
3. 训练及训练数据要求
4. 40k 训练日志
5. 测试及测试数据要求
6. 设备通信与控制频率
7. 部署启动与退出流程
8. 已知限制、上游来源与许可证

系统组成与设备分工

本项目由三个公开仓库组成：

代码仓库不重复存放数据和权重。40k 权重从已训练 5k 的 action header 初始化后新增训练 40k；former heldout 不是独立测试集。

摄像头链接是设备参考，不作为性能验收依据；本仓库的图像规格以驱动和模型配置为准。BrainCo 的“触觉版”描述硬件型号，当前 Psi0 观测使用手部位置反馈，未将触觉阵列作为模型输入。

链路如下：

DECXIN ──USB/UVC──> pc2 ──ZMQ / JPEG + 时间戳──> 本机推理客户端
BrainCo <─串口Modbus─> pc2 <──DDS 状态/目标/回执──> 本机推理客户端
G1 <────以太网 / Unitree DDS────> 本机 SONIC/WBC
                                      │ 身体反馈与启动状态（ZMQ）
                                      ▼
                                本机推理客户端
                                      ⇅ WebSocket
                                本机 Psi0 模型服务
                                      │
                      token64 → WBC；手部目标 → pc2

当前适配客户端从 WBC 的 ZMQ 遥测取得身体实测状态，WBC 自身通过 Unitree DDS 接收 G1 状态；客户端并非另开一条独立的 G1 DDS 状态链路。

相对原生 Psi0，本项目适配了 DECXIN 右目、BrainCo 状态与六维目标、跨机时间对齐、采集 initial token、推理启动门控及首段动作检查；保留 Psi0 模型服务和 SONIC token 控制的基本结构。

环境复现

环境记录

依赖清单记录安装状态，包含本地源码安装的包，不应将所有条目都视为可直接从 PyPI 安装。pc2 的上述两个补充包原先装在独立服务依赖目录中。

在新副本中准备训练环境的入口：

git clone https://huggingface.co/yuzaiyangy/psi0-brainco
cd psi0-brainco
bash reproducibility/install-training-env.sh

该安装脚本不启动训练，尚未在全新机器上完成安装验收。原 uv.lock 与实际安装版本记录应共同参考，详见 reproduction.json。

需要另外准备的资源

• 预训练 VLM、5k action-header 初始化权重，以及部署所用 40k 权重。
• 与训练一致的数据、冻结归一化统计及 initial token 文件。
• SONIC encoder、decoder、planner 权重和参考运动数据。
• WBC 构建依赖，包括 TensorRT、ONNX Runtime、CUDA、Unitree SDK 原生库。
• 所用机器人或仿真场景需要的第三方资源；本地缺失的网格列在 external_mesh_assets.json。

发布代码中的 /opt/psi0、/opt/sonic-runtime、/opt/brainco-workspace、设备路径及 203.0.113.* 均为部署示例，必须按实际环境配置。不要直接将文档示例地址作为机器人地址使用。

训练及训练数据要求

模型输入和输出

body29 使用弧度，顺序必须和采集适配器、WBC 定义以及宇树关节顺序一致。不能只检查向量长度。

本项目约定 canonical_right6 = [thumb, thumb, index, middle, ring, pinky]，第二通道跟随第一通道。它是项目约定，不表示硬件的 thumb_aux 与 thumb 天然耦合。mean1 是六个 canonical 通道按冻结统计归一化后的均值；不能用六维原始值的均值代替。手部物理目标范围为 [0,1]，0 对应打开。

完整定义见 Contract。归一化统计必须保持与训练一致，不能在测试数据上重算；也不能对已归一化数据再做一次归一化。

数据组织要求

• 使用当前数据适配器兼容的 LeRobot episode 结构，包含图像、状态、动作、任务、帧时间和元数据。
• 每帧图像、身体状态及手部实测反馈需要对应同一观测时刻；保留时间戳、连续段标识及缺失信息。
• 整段 episode 适配器使用 continuity_id 和 padding mask，未来标签不得跨越采集间断或 episode 边界。
• 手部监督使用未来实测位置，不能悄悄改成发送过的串口目标。
• initial token 必须匹配采集时的 SONIC 权重和初始姿态约定。它用于部署起点，不是额外的 state43 输入字段，也不会自动约束模型的首个预测。

预处理和数据校验代码位于 dataset_adapter，整段标签逻辑见 whole_episode_config.py。

本次 40k 训练配置

这条权重谱系是“5k 初始化 + 新增 40k”，不是从随机初始化训练 40k。former heldout 已参与训练，不能作为独立测试集报告。

训练配置、原始调用参数和历史控制器分别保存在 run_config、argv 和 training_recipe。历史控制器含固定存储检查、受保护源码哈希及历史评估依赖，脱敏后不能直接宣称一条命令即可复现；需先配置资源路径和审计前提。

40k 训练日志

在线查看完整日志 · 下载日志

日志对应 batch 96 的 trainval40k_attempt0_b96，包含 40000/40000 和 Happy Ending! 完成标记。末条进度如下：

Training steps: 100%|██████████| 40000/40000 [61:40:14<00:00,  5.55s/it, loss=0.163, lr=0.0e+00]

0.163 是最终进度条显示的训练 loss，不是全程平均值或独立测试指标。发布副本仅将私人绝对路径脱敏、移除 ANSI 控制符，并将进度条回车转为换行；原训练日志未修改。处理说明与哈希。

测试及测试数据要求

同一个客户端通过互斥参数选择测试层级，不能把 --hand-only-policy 或 --enable-brainco-live 当作只读测试。测试入口见 run_psi0_rtc_sonic_brainco.py。

离线测试必须采用未参与梯度更新的独立数据。手部命令被 pc2 接收或写入，只能证明传输或写入完成，不能证明手指已经达到目标；还需检查后续实测状态。模型离线误差较小也不等于机器人轨迹不会碰撞。

发布整理阶段完成了源码语法、相关 shell 语法、敏感信息检查及上传文件核对，记录见 static_validation.json。本次发布没有重新运行训练、推理或真机测试，未提供可复核的全链路性能基准。

设备通信与控制频率

以下是发布代码的配置目标或调度上限。采集、网络传输、模型推理、控制循环和电机物理响应是不同指标，不能互相替代；本次发布未重新测量实际频率。

代码依据：WBC、模型服务、客户端、手部服务、相机驱动。

时间对齐

客户端以右目图像的 pc2 时间戳为观测锚点，保留身体和手部历史，按对齐规则选取反馈。两机通过相机服务的时钟探测建立单调时钟偏移估计，并记录误差界；不是把两台机器的时间戳直接相减。

图像时间戳是 pc2 主机读帧返回时间，不是硬件曝光时间。身体状态在客户端使用接收时间映射，DDS 手部消息同时携带采样和发布信息，因此这些时间戳仍包含采集与传输的不确定性。该方案是软件对齐，不是相机与电机的硬件同步触发。

运行时可查看 BRAINCO_CLIENT_SUMMARY 中的对齐计数、拒绝原因、回执延迟及观测年龄统计。评估时应分别报告有效图像 FPS、有效对齐观测 Hz、模型耗时、手部实测读取 Hz、实际写入 Hz 和回执延迟。

部署启动与退出流程

以下描述现有五服务流程。先在独立部署环境完成路径、设备、网络、模型和 WBC 构建配置，再启动对应程序；发布副本中的示例默认值不能直接用于真实机器人。

pc2 的程序从 pc2/SONIC_psi0_release/ 运行，各终端先激活其对应环境。SESSION 必须在 pc2 和客户端一致；DDS domain 与网络配置也要匹配。

# 从已配置好的发布项目根目录运行；以下变量须由操作者设置。
export SONIC_PYTHON=/path/to/client-env/bin/python
bash real/scripts/deploy_psi0-sonic-rtc-client.sh \
  --host 127.0.0.1 --port 8014 \
  --camera-address "tcp://${PC2_IP}:5558" \
  --network "${WORKSTATION_NIC}" \
  --instruction 'Pick up black ball with right hand' \
  --command-session "${SESSION}" \
  --enable-brainco-live --seconds 600

WBC 先保持采集 initial token，模型预热结果被丢弃。客户端打印 POLICY READY 后，操作者在 WBC 按 Enter 请求启动；模型用新鲜观测生成正式首段动作，WBC 的首段检查通过后才启用执行。按 Enter 不等于无条件开始运动。首段被拒绝时应检查日志，不应仅为了通过检查而提高阈值。

首次切换失败时保持 initial-token 控制，不额外引入“首段超阈值就切阻尼”的方案；其他运行异常仍需按现有 WBC 状态处理。该启动检查不能保证后续轨迹无碰撞。

正常结束时，先在 WBC 按 Enter 关闭流式执行并返回参考控制，再停止客户端和手部服务；确认身体有支撑且可以退出控制后，在 WBC 按 O。摄像头和模型服务分别停止。O 是现有 WBC 退出/停止键，不应描述为独立的硬件急停装置。600 秒客户端时限不自动完成全部退出步骤，手部也不会自动全开。

已知限制、上游来源与许可证

• 本仓库提供源码快照与复现入口，不包含权重、训练数据、完整运行依赖和所有第三方资源。
• 全新环境安装、训练复现、实际通信速率以及全身闭环性能尚未在本次发布中重新验收。
• 软件时间对齐存在时钟估计、曝光时刻未知和反馈传输延迟，不能声称硬件级同步。
• 首段检查不等于连续碰撞检测；模型预测、手部跟踪和 WBC 行为需要分层评估。
• 触觉硬件当前只使用位置反馈；没有训练触觉输入分支。
• 修改内容属于本项目适配，不代表上游 Psi0 或设备厂商对本组合的验收。

上游项目：Psi0、官方 SONIC 部署说明、GR00T-WholeBodyControl。

Psi0 代码许可证见根目录 LICENSE。第三方代码、SDK 辅助代码与资源继续遵循各自许可证；Model card 的 Apache-2.0 标签不覆盖第三方的独立授权条件。相关声明见 SONIC legal 和 BrainCo SDK LICENSE。