yuzaiyangy/psi0-brainco

项目说明

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

观看或下载演示视频

目录

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

系统组成与设备分工

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

仓库	内容与关系
本代码仓库	定义训练、预处理、本机与 pc2 推理及 WBC 部署实现
训练数据集	83 段、31,806 帧预处理数据；train 和 former heldout 都用于本次 40k 训练
40k 推理权重	由上述数据训练得到，包含完整模型参数及配置、Tokenizer/Processor；运行需本代码仓库

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

组件	职责	文档或设备参考
本机工作站	Psi0 训练、模型服务、观测对齐、推理客户端、SONIC/WBC 身体控制	本仓库
机器人 pc2	摄像头采集、BrainCo 串口读写、手部 DDS 服务	pc2/
Unitree G1 29 自由度教育版	提供关节反馈并执行 WBC 关节控制指令	宇树关节电机顺序
BrainCo Revo1 触觉版右手	提供手部位置反馈并执行六维目标位置	BrainCo Revo1 介绍
DECXIN 摄像头	pc2 采集双目拼接画面，取右目 RGB 作为模型视觉输入	设备购买参考

摄像头链接是设备参考，不作为性能验收依据；本仓库的图像规格以驱动和模型配置为准。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 状态链路。

目录	关键内容
src/psi/、scripts/	Psi0 模型、训练与模型服务
training_recipe/	此次训练的启动控制器、数据转换与整段 episode 适配器
real/SONIC/	BrainCo 适配、观测对齐、全身推理客户端及测试入口
pc2/SONIC_psi0_release/	摄像头与 BrainCo DDS 服务
pc2/collection/	复用的 DECXIN 和 BrainCo 采集驱动
pc2/brainco-hand-sdk/	BrainCo SDK Python 辅助代码及许可证
runtime_source/GR00T-WholeBodyControl/	修改版 SONIC/WBC 源码
reproducibility/	三套环境记录、40k 配置、发布清单及验证范围

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

环境复现

环境记录

环境	版本记录	补充要求
本机训练/模型服务	training.json、依赖清单	Python 3.10；Torch 2.7.0 + CUDA 12.8；需匹配 GPU、驱动和 FlashAttention
本机推理客户端	workstation_client.json、依赖清单	SONIC 客户端、CycloneDDS 等
pc2	pc2.json、依赖清单	ARM64；另需 cyclonedds==0.10.2、bc-stark-sdk==2.0.2

依赖清单记录安装状态，包含本地源码安装的包，不应将所有条目都视为可直接从 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.* 均为部署示例，必须按实际环境配置。不要直接将文档示例地址作为机器人地址使用。

训练及训练数据要求

模型输入和输出

项目	本项目定义
图像	单路右目 RGB，键为 observation.images.egocentric；pc2 输出 H×W×C = 600×800×3；40k 配置的 resize/crop 为 240×320
语言	与任务对应的文本指令
当前状态	state43 = body29 + zero_left7 + canonical_right6 + mean1
动作标签	未来 t+1 … t+30 的 action78 = token64 + zero_left7 + canonical_right6 + mean1
时间轴	30 Hz，30 步预测窗口对应约 1 秒
身体动作	SONIC 的 64 维 latent token，由 WBC 解码控制；不是直接预测的 29 个关节角
手部动作	未来实测手部位置监督，反归一化后转换成 BrainCo 六维位置目标

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 训练配置

参数	配置
初始 action header	已训练 5k 的权重
本次新增更新	40,000；新 optimizer、scheduler 和 global step
Batch size	96
精度	BF16
学习率	1e-4
VLM	冻结
训练器	SonicTrainer
数据划分	train 与 former heldout 合并参与训练

这条权重谱系是“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 控制符，并将进度条回车转为换行；原训练日志未修改。处理说明与哈希。

测试及测试数据要求

测试层级	输入要求	检查内容	是否会控制设备
静态/接口检查	源码、依赖；部分测试需冻结统计	语法、导入、维度和手部映射	导入检查 --check 不打开硬件或网络
观测链路	实时右目 RGB、WBC 身体反馈、有效 BrainCo 反馈	能否形成对齐观测，年龄、时钟误差和丢弃原因	--check-inputs 不发送动作；已有 WBC 仍由操作者负责
DDS 目标链路	pc2 --mode record 与相同 session	本机目标发送、pc2 接收和回执匹配	--check-dds 不写手部电机
离线模型评估	独立 episode、训练同构字段与冻结统计、对应 checkpoint	未来动作误差、连续性、手部映射；按动作分量分别报告	不需要真机执行
真实模型记录	完整观测、模型服务、pc2 record 服务	模型输出及目标回执	使用 --record-policy，pc2 必须为 record 模式
仅手部闭环	完整实时观测、模型服务、pc2 live 服务	根据更新观测执行手部目标与反馈闭环	--hand-only-policy 会动手；不发布身体 token
全身闭环	完整服务、匹配 initial token、启动检查通过	WBC 与手部共同执行、异常及退出行为	--enable-brainco-live 会控制身体和手部

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

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

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

设备通信与控制频率

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

链路/阶段	协议与方向	配置频率或速率	含义与实测限制
G1 身体反馈	G1 → 本机 WBC，Unitree DDS	源码预期 500 Hz	接收回调频率由机器人和网络决定，需实测
WBC 输入轮询	本机 ZMQ 输入 → WBC	100 Hz	轮询频率，不是 Psi0 每秒预测 100 次
WBC 控制计算	SONIC 解码/控制 → 29 关节目标	50 Hz	每 20 ms 一次控制计算
G1 关节命令	WBC → G1，Unitree DDS	500 Hz	每 2 ms 发布命令，使用最近控制结果
SONIC planner 线程	WBC 内部	10 Hz	planner 调度频率，不是 Psi0 推理频率
摄像头采集	DECXIN → pc2，USB/UVC	30 FPS 配置	原始双目 1600×600，右目 800×600；实际 FPS 需测量
RGB 跨机传输	pc2 → 本机，ZMQ 请求/应答	按请求发送最新帧，观测循环目标不超过 30 Hz	JPEG quality 80；重复帧被丢弃，没有独立固定的网络推送频率
BrainCo 状态采样	手 → pc2，Modbus 串口	默认目标 20 Hz，115200 baud	串口读写、恢复及超时会降低实际频率；baud 不等于状态频率
BrainCo 状态跨机	pc2 → 本机，DDS	随采样/状态事件发布	不存在独立的 100 Hz 手部实测反馈保证
模型观测发送	本机客户端 → 模型服务，WebSocket	循环目标 30 Hz	有效输入、对齐等待和网络阻塞会降低频率
Psi0 动作时间轴	模型服务 → 客户端	30 Hz，预测窗口 30 步	CTRL_PERIOD_SEC=1/30；整块推理耗时和重规划频率需另外统计
身体 token 与手部目标路由	客户端 → WBC 的 ZMQ / pc2 的 DDS	随动作执行回调，目标时间轴 30 Hz	可能被启动门控、陈旧状态检查或停止状态拦截
BrainCo 电机写入	pc2 → 手，Modbus 串口	默认上限 10 Hz	保留最新目标，变化量/心跳判断减少写入；不是逐条积压执行所有 30 Hz 目标
BrainCo 回执	pc2 → 本机，DDS	事件触发	报告记录、写入或拒绝等结果，不代表物理到位

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

时间对齐

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

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

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

部署启动与退出流程

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

顺序	位置	入口	就绪条件
1	pc2	python realsense_server.py --collection-root /path/to/pc2/collection --bind tcp://*:5558	CAMERA_READY DECXIN right 800x600
2	pc2	python brainco_dds_service.py --mode live --command-session SESSION --network PC2_NIC --device HAND_DEVICE --collection-root /path/to/pc2/collection --sdk-root /path/to/pc2/brainco-hand-sdk	BRAINCO_DDS_READY
3	本机	设置 CHECKPOINT_DIR、CHECKPOINT_STEP=40000，运行 bash scripts/deploy/serve_psi0-rtc-sonic.sh	Application startup complete
4	本机	bash real/scripts/deploy_psi0-sonic-rtc-robot.sh real	确认部署，等待 Init Done，单独按 ]，稳定在采集 initial token 姿态；先不按 Enter
5	本机	下方全身客户端命令	POLICY READY 后，才在 WBC 终端按 Enter 请求开始

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。