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. 使用注意事项
- torch 推理评测请使用 PRECISION=float32 的转换产物,并在服务侧设 TORCH_SERVE_DTYPE=fp32。开环数值对拍一致性很好的 bfloat16 权重,在闭环控制评测中成功率仍会明显下降。
- RoboTwin 官方 cotrain 权重(RoboTwin-lerobot_v30-aloha_agilex)推理三要素:契约 3 相机(head + 双腕)、norm_mode=quantile、DELTA_ACTION_SPACE=true。缺 delta 还原的典型症状是机械臂几乎不动(模型输出 delta 增量被当作绝对关节角)。
- 显存不足 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 可用。
- 多卡训练环境要求: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(每卡完整模型)。推理服务固定单机单卡。
- 推理服务与转换只接受契约管线 checkpoint(目录内含 model_structure.json 与 assets/norm_stats.json)。官方原始权重需先经 convert(以 CONTRACT_JSON 注入契约)转成契约管线产物。
- 容器内运行不需要外网:HF_HUB_OFFLINE 默认开启,tokenizer 与官方权重均已离线打入。
- 训练数据增广(随机裁剪 / 旋转 / 色彩抖动)在 JAX 0.11 系存在第三方库兼容问题,冒烟可设 OPENPI_DISABLE_AUGMENT=1 关闭;该开关不影响推理。
- 各入口遵循统一收尾协议: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 一致性单测