OpenPi_POC_Dev/README.md
2026-10-09 16:41:13 +08:00

19 KiB
Raw Blame History

OpenPi_Dev — Pi0.5 训练 / 转换 / 推理镜像工程

本项目将 openpi(Pi0.5, Physical Intelligence 开源实现)封装为一条数据流水线:输入 LeRobot v3 数据集,完成模型训练(JAX / PyTorch 双栈)、JAX 到 PyTorch 的权重转换、XPolicyLab 协议推理服务。

LeRobot v3 数据集 (RoboTwin2_Dev 产出或自备)
    │
    ├─ train_jax / train_torch ──► checkpoint (含 model_structure.json 契约快照)
    │                                  │
    │                                  ├─ convert ──► torch 权重 (model.safetensors)
    │                                  └─ serve_jax / serve_torch ──► XPolicyLab ws 协议服务
    │                                                                    └─ RoboTwin 仿真评测客户端
    └─ norm_stats (独立统计, 训练入口缺文件时也会自动补算)

全部功能由环境变量超参驱动,每个功能一个入口脚本,适配算子平台运行;也可以脱离平台直接 docker run 使用。

0. 当前已验证状态 (2026-09-08)

远端平台已通过简化套件 T1-T5 判定的发布物,与本地代码的对应关系:

项 值
镜像 tag ccr-29eug8s3-pub.cnc.bj.baidubce.com/public/openpi_train_inference:da7ce8b-20260908-2
openpi 副本 commit da7ce8b (基于官方 15a9616, 见 openpi/ 内 git log)
源码清单 releases/manifest_da7ce8b-20260908-2.txt (构建上下文逐文件 sha256)
平台算子 JAX 训练 operator-9b489829810b7b59db63f30081fa0a07 / torch 训练 operator-848270666764d6ce59991129492ed7fa / norm_stats operator-d6ec15d9574813d2c47f3b716ce47dd6 (均 version 1.2.0, image 同上 tag)
平台工作流 workflow-cf61aefd254f0283327e1f9ec45e7dfa (project-3990926c0623c46d0f5942ff8febde23, OpenPi 平台测试项目)
套件结果 T1 jax 4cam / T2 torch 4cam / T3 norm_stats / T4 jax 1cam / T5 多数据集 4 库混合 全部 completed, run 依次 f36b9f5e / 4b7dcfe0 / 1ee7afb2 / 0bf63fb5 / 165fb507
套件驱动 .local_dev/platform_test/platform_run.py + cases_t.json + cases_t5.json (复跑方法见 releases/RELEASES.md)

本表之下的正文描述的是当前代码的功能语义(与该发布物一致)。重建该发布物:按 releases/RELEASES.md 的步骤构建并推送镜像即可,构建上下文即本目录当前状态。

1. 镜像

镜像 承载功能 说明
openpi_train_inference 训练 / 转换 / 推理 / 统计 基于 CUDA 12.8 + Python 3.12, 内置官方 JAX pi05_base 权重, 离线运行

构建(在本目录执行,tag 自动取 openpi 副本 git 短hash-日期并直推 CCR,同时写入 ~/tmp_daa_reg/cur_tag 供算子联动脚本读取):

./build_docker.sh                    # 训练/推理镜像 (default builder, --push)

训练镜像容器布局:入口在 /app/entry/,业务代码在 /app/src/ (pi_pipeline, ws_common, openpi 副本),官方权重固定在 /app/src/openpi_weights/pi05_base。运行时无 ENTRYPOINT,由调用方指定入口脚本:

docker run --rm --gpus all \
  -e OUTPUT_DIR=/out \
  -e DATASET_PATH=/data/my_lerobot_v3 \
  -v $PWD/my_dataset:/data/my_lerobot_v3:ro \
  -v $PWD/out:/out \
  ccr-29eug8s3-pub.cnc.bj.baidubce.com/public/openpi_train_inference:<tag> \
  sh /app/entry/train_jax.sh

2. 配置体系:模型参数与非模型参数

本项目的全部可配置项分为两类,理解这个划分是正确使用的前提:

  • 模型参数:配置完成后,模型中每一个权重和激活对应的形状就已经确定。模型参数全部集中在契约 (CONTRACT_JSON) 里,训练 / 转换 / 推理全链路消费同一份契约,并被序列化进 checkpoint 的 model_structure.json 作为结构锚点。改模型参数意味着得到一个结构不同的模型,与既有 checkpoint 不兼容(action_dim 例外,官方权重 resume 时可自动 tile 适配)。
  • 非模型参数:模型参数确定之后才生效的运行配置,包括训练过程、训练行为、恢复与产物管理。改非模型参数不影响任何权重形状,同类 checkpoint 之间可以自由更换。

2.1 模型参数(契约字段)

{
  "cameras": ["cam1", "cam2", "cam3", "cam4"],
  "state": {"dim": 14, "inject": true},
  "language": {"enabled": true, "max_token_len": 200},
  "action": {"dim": 14, "horizon": 10},
  "norm_mode": "min_max",
  "key_map": {
    "observation.images.cam_high": ["cam1"],
    "observation.images.cam_third_view": ["cam2"],
    "observation.images.cam_left_wrist": ["cam3"],
    "observation.images.cam_right_wrist": ["cam4"],
    "observation.state": "state",
    "action": "actions",
    "task": "prompt"
  }
}
模型参数 决定的形状
cameras 相机槽位数量与拼接顺序, 决定视觉 token 总数与 prefix 结构; 槽名 cam1..camN, 理论上无上限 (受显存约束); key_map 中一个外部图像键可映射多个槽 (一对多复用)
画面比例 固定 1:1: 224x224, 16x16 网格, 每路 256 token; 非 1:1 比例 (4:3/16:9 及 pos_emb 行切片) 已移除, 模型代码还原为官方状态, 旧契约出现 aspect_ratio 非 1:1 取值时非 0 退出
state.dim 与 state.inject 状态投影维度与是否注入 prefix; inject=false 时模型不接收状态输入
action.dim 动作维度, 决定 action_in_proj / action_out_proj 权重形状; 官方权重 action_dim=32, 与契约不一致时 resume 自动循环 tile 适配 (日志以 resume-adapt 标注)
action.horizon 动作序列长度, 决定流匹配目标的时间维
language.max_token_len 语言指令 token 上限, 决定 prompt 激活宽度
norm_mode 归一化模式: min_max (默认, 有界到 -1..1)、mean_std、vision_only (等价 state.inject=false)、quantile (官方 pi05 语义); mean_std/min_max/quantile 互切不改形状, 仅数值分布不同
LORA=true (环境变量) 切换到低秩参数化, 权重集合与形状改变 (gemma_2b_lora + gemma_300m_lora), 冻结非 LoRA 参数并关闭 EMA

key_map 校验失败(槽位冲突、槽位未映射、图像值非列表)会以非 0 退出并给出可读报错。不设 CONTRACT_JSON 时使用内置 RoboTwin 四相机默认契约(presets/robotwin_default_contract.json 等价)。

2.2 非模型参数(环境变量)

训练过程类(不改变模型结构,只影响训练如何进行):

参数 默认 说明
BATCH_SIZE 8 全局批大小; 多卡数据并行时须被数据并行度整除
NUM_TRAIN_STEPS 20000 训练步数
LR_WARMUP_STEPS / LR_PEAK / LR_DECAY_STEPS 1000 / 2.5e-5 / 30000 学习率日程
EMA_DECAY 0.99 EMA 衰减系数; LORA=true 时自动关闭
SEED 0 随机种子
NUM_WORKERS 4 数据加载进程数
FSDP_DEVICES 1 JAX 专属: 参数切分设备数, 1 为纯数据并行
NPROC_PER_NODE 1 torch 专属: DDP 进程数, 大于 1 时入口自动以 torchrun 启动

训练行为类(冻结与精度,只动可训性与数值类型):

参数 说明
FREEZE_BACKBONE torch 专属: 冻结 Paligemma 主干, 只训 action_in_proj / action_out_proj / time_mlp 头, 低显存路径
TRAIN_PRECISION torch 专属: bfloat16 (默认) 或 float32
OPENPI_DISABLE_AUGMENT 置 1 关闭数据增广 (见注意事项)

恢复与产物管理类:

参数 默认 说明
RESUME false true 为断点续训, 从实验 checkpoint 目录的最新 step 恢复
RESUME_CKPT 空 (镜像内置官方权重) JAX 专属: 外部权重目录, 指向 checkpoint 内的 params 目录 (如 .../99/params), 传 step 目录会报 item_metadata 错误
PYTORCH_WEIGHT_PATH 空 torch 专属: torch 起点权重 (convert 产物), 空则随机初始化 (仅冒烟用)
NORM_STATS_PATH 空 归一化统计文件; 空 = 自动统计 (存在即跳过, 幂等)
OUTPUT_DIR / EXP_NAME 必填 / pi05_contract 产物目录与实验名
SAVE_INTERVAL / KEEP_PERIOD 1000 / 5000 保存与长期保留节奏
LOG_INTERVAL 100 日志打印间隔
OVERWRITE false true 时覆盖既有实验目录

3. 数据集要求

输入是标准 LeRobot Dataset v3.0 目录(含 meta/info.json、data/chunk-xxx/*.parquet、videos/),与 RoboTwin2_Dev 镜像的 data2lerobot 产物直接对接。数据格式差异会被自动处理,不需要预先转换:

  • 视频帧 float32 (0,1) CHW 布局自动转 uint8 HWC(官方数据管线语义)
  • 图像 letterbox 缩放对齐 PIL golden(含抗锯齿),四舍五入取整
  • 多任务数据集(v3 tasks 索引)按帧的任务文本作为语言指令

数据集输入根支持两种形态(多数据集聚合):

  • 根自身是数据集(有 meta/info.json):单数据集训练,行为与传统一致
  • 根是父目录:其下每个含 meta/info.json 的子目录都是一个数据集,按目录名排序全部聚合训练(共享同一契约 transforms 与同一份混合 norm_stats,norm_stats 的资产目录名为 mix<N>-<hash>);多数据集必须共父目录(LeRobot 本地读取的 HF_LEROBOT_HOME 唯一),违例非 0 退出

平台运行时,位于 workspace PVC 下的输入根会被自动暂存到节点本地盘(/tmp/pi-stage/<pid>/)再训练——这是平台形态的内生行为,不暴露超参;本地直跑(输入不在 $WORKSPACE_ROOT 下)不暂存。

4. 功能一:JAX 训练 (train_jax.sh)

功能:契约驱动的 JAX 全参 / LoRA 微调,产出 checkpoint(权重 + train_state + norm_stats + model_structure.json 契约快照)。

配置:模型参数全部通过 CONTRACT_JSON 注入(即上文契约字段表);非模型参数全部环境变量注入,均可省略使用默认值。

镜像:openpi_train_inference。

docker run --rm --gpus '"device=0,1"' --shm-size=16g \
  -e OUTPUT_DIR=/out -e DATASET_PATH=/data/my_lerobot_v3 \
  -e CONTRACT_JSON='{"cameras":["cam1","cam2","cam3"],"state":{"dim":14,"inject":true},"language":{"enabled":true,"max_token_len":200},"action":{"dim":14,"horizon":10},"norm_mode":"min_max","key_map":{"observation.images.cam_high":["cam1"],"observation.images.cam_left_wrist":["cam2"],"observation.images.cam_right_wrist":["cam3"],"observation.state":"state","action":"actions","task":"prompt"}}' \
  -e LORA=true -e NUM_TRAIN_STEPS=5000 \
  -v $PWD/my_dataset:/data/my_lerobot_v3:ro -v $PWD/out:/out \
  ccr-.../openpi_train_inference:<tag> sh /app/entry/train_jax.sh

多卡(JAX):可见 GPU 数须被 FSDP_DEVICES 整除,mesh 为 (数据并行度, 参数切分度),BATCH_SIZE 须被数据并行度整除:

FSDP_DEVICES 语义 适用
1 纯数据并行, 每卡完整模型, batch 按卡数均分 单卡装得下模型时扩展吞吐
2 / 4 N 卡装一个模型 (参数沿特征维切分), 剩余卡数做数据并行 单卡装不下时降低单卡显存

已验证组合:2 卡 (FSDP=1/2)、4 卡 (FSDP=1/2/4)。

显存路线参考:

路线 参考占用 说明
LORA=true (JAX) 单卡约 15GB 冻结主干转 bfloat16, 最省
FREEZE_BACKBONE=1 (torch) 单卡约 10GB (batch 2) 只训练头部投影
全参微调 (JAX 多卡) FSDP_DEVICES=2/4 分摊 实测 4x32GB (FSDP=4, BATCH_SIZE=1) 仍 OOM, 需 80GB 级卡; 32GB 卡建议 LoRA
全参微调 (单卡) 需 80GB 级显卡 官方默认配置

5. 功能二:PyTorch 训练 (train_torch.sh)

功能:与 JAX 入口同一契约、同一非模型参数面的 torch 训练;多卡为 DDP(每卡完整模型 + 梯度 all-reduce),由 NPROC_PER_NODE 大于 1 时自动 torchrun 启动。

配置:模型参数同契约;非模型参数在公共面之外多四个:PYTORCH_WEIGHT_PATH(起点权重)、TRAIN_PRECISION(bf16/fp32)、FREEZE_BACKBONE(冻结主干)、NPROC_PER_NODE(DDP 进程数)。已验证 DDP 组合:2 / 4 进程。

镜像:openpi_train_inference。

torch 训练建议从 convert 产物起步:先用 JAX 训练(或官方权重转换)得到 torch 权重,再设 PYTORCH_WEIGHT_PATH 续训;随机初始化仅用于链路冒烟。

6. 功能三:归一化统计 (norm_stats.sh)

功能:对数据集统计归一化参数,输出 norm_stats.json(含 mean/std/q01/q99/min/max),统计空间与训练管线一致(repack + 数据变换后)。训练入口发现缺失时也会自动补算;NORM_STATS_PATH 显式指定优先级最高。

配置:DATASET_PATH(必填)、CONTRACT_JSON、OUTPUT_DIR。无需 GPU。

镜像:openpi_train_inference。

7. 功能四:权重转换 (convert.sh)

功能:JAX checkpoint 转 torch model.safetensors,作为 torch 训练起点与 torch 推理的交接格式。附带能力:

  • 结构判定读 checkpoint 内 model_structure.json(不依赖目录名);外部权重没有契约快照时用 CONTRACT_JSON 注入
  • 转换后自动做 JAX 与 torch 前向数值对拍(余弦相似度阈值 0.95),结果写入 convert_metadata.json
  • 产物附 paligemma_tokenizer.model

配置:CHECKPOINT_PATH(必填)、CONTRACT_JSON(外部权重时必填)、PRECISION(bfloat16 默认 / float32)、OUTPUT_DIR。GPU 可选。

镜像:openpi_train_inference。

转换 RoboTwin 官方 cotrain 权重(aloha_agilex)时,契约需要与官方训练配置对齐:3 相机(cam_high + 左右手腕,无第三视角)、action.dim=32、norm_mode=quantile。

8. 功能五:推理服务 (serve_jax.sh / serve_torch.sh)

功能:XPolicyLab websocket 协议动作服务(单客户端串行,动作 chunk 整块返回),与 RoboTwin2_Dev 镜像的 eval_client 直接联调。协议相机键经契约 key_map 逆映射到内部槽位;评测侧多出的相机自动忽略并记日志,契约要求但缺失的相机补零图并置 mask。

配置:

参数 默认 说明
CHECKPOINT_PATH 必填 契约管线 checkpoint 目录 (含 model_structure.json 与 assets/norm_stats)
CONTRACT_JSON 空 外部权重无契约快照时注入
SERVE_HOST / SERVE_PORT 0.0.0.0 / 19000 监听地址
DELTA_ACTION_SPACE false true = 模型输出为 delta joint (臂增量 + 爪绝对), 自动加回当前状态; 官方 aloha cotrain 权重必须开启
TORCH_SERVE_DTYPE bf16 torch 服务精度; 设 fp32 时跳过 bfloat16 转换
ACTION_TYPE joint joint 或 ee

观测输入格式(XPolicyLab 协议):

obs["vision"][cam]["color"]       uint8 RGB 图像 (H,W,3), cam 为对外键
                                    (cam_head / cam_third_view / cam_left_wrist / cam_right_wrist)
obs["state"]["{left,right}_{arm,ee}_joint_state"]   关节状态, 拼接序 [左臂6,左爪1,右臂6,右爪1]
obs["instruction"]                 语言指令

镜像:openpi_train_inference(单机单卡,docker run -p 暴露端口)。

与 RoboTwin 仿真评测客户端联调:

docker run --rm --gpus '"device=1"' \
  -e NVIDIA_DRIVER_CAPABILITIES=all \
  -e VK_ICD_FILENAMES=/etc/vulkan/icd.d/nvidia_icd.json \
  -e OUTPUT_DIR=/out -e POLICY_SERVER_IP=<宿主IP> -e POLICY_SERVER_PORT=19000 \
  -e TASK_NAME=beat_block_hammer -e TEST_NUM=5 -e SAVE_VIDEO=true \
  -v $PWD/eval_out:/out \
  ccr-29eug8s3-pub.cnc.bj.baidubce.com/public/robotwin2_data_debug:<tag> \
  sh /app/entry/eval_client.sh

9. 产物结构

训练产物(两个训练入口同构):

$OUTPUT_DIR/
├── checkpoints/<exp>/<step>/     模型参数 + train_state + assets/norm_stats.json
│                                   + model_structure.json (契约快照, serve/convert 的锚点)
├── train_report.json             loss 摘要与契约快照
└── .artifacts.json               产物清单 (算子平台协议)

convert 产物:

$OUTPUT_DIR/checkpoint_torch/
├── model.safetensors             torch 权重
├── model_structure.json          契约透传或注入契约生成
├── convert_metadata.json         数值对拍结果 (cosine / max_abs)
└── paligemma_tokenizer.model     tokenizer 随行

10. 使用注意事项

  1. torch 推理评测请使用 PRECISION=float32 的转换产物,并在服务侧设 TORCH_SERVE_DTYPE=fp32。开环数值对拍一致性很好的 bfloat16 权重,在闭环控制评测中成功率仍会明显下降。
  2. RoboTwin 官方 cotrain 权重(RoboTwin-lerobot_v30-aloha_agilex)推理三要素:契约 3 相机(head + 双腕)、norm_mode=quantile、DELTA_ACTION_SPACE=true。缺 delta 还原的典型症状是机械臂几乎不动(模型输出 delta 增量被当作绝对关节角)。
  3. 显存不足 32GB 的卡优先走 LoRA(JAX)或 FREEZE_BACKBONE(torch)路线;JAX 全参微调实测 4x32GB(FSDP=4、BATCH_SIZE=1)仍 OOM,需 80GB 级卡;torch LoRA 实测 32GB 单卡(含 BATCH_SIZE=1)与双卡 DDP 均超出显存,32GB 卡 torch 路线只有 FREEZE_BACKBONE 可用。
  4. 多卡训练环境要求:NCCL 不低于 2.29.7(2.27.x 的 AllToAll 在 sm_120/虚拟化环境会报 unhandled system error),镜像内已内置;容器运行需足够共享内存(docker 默认 64MB 的 /dev/shm 会导致 NCCL 报 No space left on device,多卡训练须加 --shm-size=16g)。GPU 间跨 PCIe root(SYS 拓扑)时需设 NCCL_P2P_DISABLE=1(train_jax.sh 已内置默认值 1)。JAX 侧多卡支持 FSDP_DEVICES 数据并行与参数切分的任意整除组合,torch 侧为 DDP(每卡完整模型)。推理服务固定单机单卡。
  5. 推理服务与转换只接受契约管线 checkpoint(目录内含 model_structure.json 与 assets/norm_stats.json)。官方原始权重需先经 convert(以 CONTRACT_JSON 注入契约)转成契约管线产物。
  6. 容器内运行不需要外网:HF_HUB_OFFLINE 默认开启,tokenizer 与官方权重均已离线打入。
  7. 训练数据增广(随机裁剪 / 旋转 / 色彩抖动)在 JAX 0.11 系存在第三方库兼容问题,冒烟可设 OPENPI_DISABLE_AUGMENT=1 关闭;该开关不影响推理。
  8. 各入口遵循统一收尾协议:stdout 逐 step 打印 DROBOTICFLOW_PROGRESS 进度行,产物清单写 .artifacts.json,业务文件不占用 result.json 等平台保留文件名。

11. 目录结构(构建上下文)

OpenPi_Dev/
├── Dockerfile                    训练/推理镜像 (CUDA 12.8 + Python 3.12)
├── build_docker.sh               训练镜像构建编排 (XPolicyLab 就位 / SDK wheels 暂存 / CCR 推送)
├── entry/                        七个功能入口脚本 (train / convert / serve / norm_stats)
├── pi_pipeline/                  业务包: contract / train_runner / train_torch_runner
│                                   serve_xpolicylab / convert_runner / norm_stats_runner
├── openpi/                       openpi 副本 (@da7ce8b, 基于官方 15a9616), 深层改动唯一发生地, 文件头标注改动点
├── presets/                      默认契约模板
├── ws_common/                    与 RoboTwin2_Dev 同源的共享层 (输入定位 / 收尾协议)
├── releases/                     发布记录与构建清单 (RELEASES.md + 源码 sha256 manifest)
├── src-externals/XPolicyLab/     serve 协议实现 (构建期从 reference 拷入)
└── tests/                        契约校验 / letterbox golden 一致性单测