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

305 lines
19 KiB
Markdown
Raw Permalink Blame History

This file contains ambiguous Unicode characters

This file contains Unicode characters that might be confused with other characters. If you think that this is intentional, you can safely ignore this warning. Use the Escape button to reveal them.

# 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 供算子联动脚本读取):
```bash
./build_docker.sh # 训练/推理镜像 (default builder, --push)
```
训练镜像容器布局:入口在 /app/entry/,业务代码在 /app/src/ (pi_pipeline, ws_common, openpi 副本),官方权重固定在 /app/src/openpi_weights/pi05_base。运行时无 ENTRYPOINT,由调用方指定入口脚本:
```bash
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 模型参数(契约字段)
```json
{
"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。
```bash
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 仿真评测客户端联调:
```bash
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 一致性单测
```