chenlin
f5d84e26f6
新增专家轨迹诊断、原视频估计相机入口和状态参考ACT数据门禁/训练链路；更新版本与进度文档。 验证：120项CPU/USD回归和4步synthetic CPU smoke通过；1333帧默认GUI历史回放PASS。原视频相机完整回放超时124，策略GPU E2E未执行，完整pre-commit工具缺失。 兼容性：HDF5、Cartpole、USD和控制阈值保持不变。本提交为实验进度快照，不宣称完整发布验收通过；数据、视频和权重不纳入。
223 lines
15 KiB
Markdown
223 lines
15 KiB
Markdown
# L20 状态输入 ACT：训练准备与运行
|
||
|
||
**v0.1.3 更新**：最新汇总见 [`PROGRESS_v0.1.3.md`](PROGRESS_v0.1.3.md)。本轮120项回归及新的4步CPU smoke通过。
|
||
已收到1333帧同源轨迹和估计相机；这不构成新的独立采集组或实测尺度审查。
|
||
默认展示相机参考回放已有PASS，原视频相机完整运行超时；ACT策略GPU E2E仍NOT_RUN。
|
||
下文环境安装、118项测试和“未升级/未提交”等描述是初次ACT准备阶段的历史记录，不是v0.1.3提交状态。
|
||
|
||
## 当前交付范围
|
||
|
||
路线A：**腕手参考轨迹模仿 → 仿真评估 → 后续PPO refinement**。
|
||
当前提供可执行的状态输入ACT-style CVAE Transformer、数据门禁、离线训练/保存/加载/留出评估，
|
||
以及已有Isaac Lab受限回放入口的可选闭环策略分支。
|
||
|
||
- **PASS**：本机CPU依赖、editable安装、synthetic短训练→保存→加载→离线预测链路及回归测试。
|
||
- **BLOCKED**：真实专家训练，目前只有单条示例，且独立坐标/尺度审查未闭合；不能自动批准。
|
||
- **NOT_RUN**：新策略分支的GPU仿真E2E、真实专家训练/质量评测、GUI策略回放。
|
||
历史75/80倍参考回放PASS不等于新策略回放PASS。
|
||
- 没有创建L20 Gym/RL任务、奖励、物体场景、PPO、视觉模型或硬件驱动；Cartpole任务及checkpoint保留。
|
||
本页的“训练可运行”指离线参考模仿，不是抓取训练就绪或Sim2Real验收。
|
||
|
||
## 1. 本机环境
|
||
|
||
继续使用已有Isaac Sim Python，**不更换它的PyTorch/CUDA**。
|
||
本次实测：Python3.12.13、PyTorch2.10.0+cu128、numpy2.5.1、h5py3.16.0，
|
||
Isaac Sim6.0.1-rc.7；Isaac Lab可发现。本轮没有初始化CUDA训练或启动Kit。
|
||
|
||
从仓库根目录运行：
|
||
|
||
```bash
|
||
# 本机默认使用 ~/isaacsim/python.sh；不同安装位置由调用者显式设置。
|
||
# export ISAACSIM_PYTHON=/path/to/isaacsim/python.sh
|
||
bash scripts/imitation.sh doctor
|
||
|
||
# 本机已实际执行：仅安装项目，不访问索引、不安装/升级依赖。
|
||
~/isaacsim/python.sh -m pip install --no-index --no-deps --no-build-isolation -e source/dex_workbench
|
||
```
|
||
|
||
`setup.py`已收录`dex_workbench_imitation`包及`imitation`可选依赖。
|
||
本机旧installed metadata为0.1.0，本次重新安装后与源码0.1.2一致；**未修改源码版本号**。
|
||
不要在Isaac Python里盲目执行`pip install --upgrade torch`或复制另一机器的CUDA wheel。
|
||
新节点须先安装兼容的Isaac Sim/Lab和已核验依赖，再执行上述本地安装与doctor。
|
||
右手USD目前仅本地存在，存储/再分发许可尚未闭合；离线训练只消费HDF5与清单，
|
||
新节点仿真评估另需合法取得同哈希资产并重建prepared层，不保证干净克隆直接可回放。
|
||
可选 `doctor --cuda`仅检查CUDA可用性，不是GPU容量或仿真验收。
|
||
|
||
包装脚本设置本仓库`PYTHONPATH`，不改变调用者cwd；输入/输出相对路径仍相对于调用目录。
|
||
不要求激活系统Python或下载额外模型，也不会自动搜索“最新checkpoint”或自动开始训练。
|
||
|
||
## 2. HDF5补齐后还需要哪些输入
|
||
|
||
沿用 [`l20_tracking_v1`](HDF5_REQUIREMENTS.md)，不新增伪造观测/力矩字段，不改变现有回放契约。
|
||
训练前需要三个实际文件及同版模型清单：
|
||
|
||
1. **HDF5**：经过同版模型绑定，全部使用一侧L20与同一校准；各episode全有效，单位/时间/顺序/限位/联动正确。
|
||
不能直接把原始交付的暂定资产哈希替换成当前清单哈希。
|
||
2. **划分文件**：参照 `configs/imitation/splits.example.json`，在仓库外填写实际episode与采集来源。
|
||
3. **数据审查文件**：参照 `configs/imitation/data_review.example.json`，在独立复核后由负责人填写。
|
||
|
||
### 划分与来源
|
||
|
||
- 至少 **两个独立采集组**才可进行训练+验证，建议另有独立test组；这只是最小接口门槛，不是数据充足标准。
|
||
- 每个episode必须且只能属于train/validation/test中的一个。不能随机按帧划分。
|
||
- 同一原始录制的切片、慢放、重采样或重复导出，必须使用同一`episode_groups`值且落在同一分区。
|
||
- 自动拒绝跨分区同group及几何数组逐值重复的轨迹（忽略时间，捕获改名/慢放副本）。
|
||
不能自动识别所有重采样、裁剪或旋转等价副本；仍需负责人核对真实采集来源。
|
||
- `episode_groups`不是自动生成的独立性证据，示例中的占位名称必须替换。
|
||
- HDF5中所有episode必须明确划分，不静默忽略文件里的额外轨迹。
|
||
|
||
### 审查文件不是绕过门禁的开关
|
||
|
||
填写**实际HDF5文件SHA256**和资产包SHA，记录`reviewer`与`evidence`，明确：
|
||
|
||
- `coordinate_and_scale_reviewed`：坐标变换、SLAM尺度与同步已经独立复核；
|
||
- `reference_state_targets_accepted`：同意把未来参考状态作为这一实验的目标代理，而非宣称实测动作；
|
||
- `capture_groups_reviewed`：数据来源与跨分区泄漏已人工审核。
|
||
|
||
示例默认false/空值，**刻意不能通过训练门禁**。程序只检查声明与文件绑定，不能替代人的真实审查。
|
||
当前已收到估计相机SE3，但尺度与独立数据审查仍未闭合，不能把标记自动改为true来启动。
|
||
|
||
### 速度和时间
|
||
|
||
- 配置控制频率30Hz；保留数据物理时间，按线性位置/关节插值及shortest-arc SLERP重采样。
|
||
- episode末时刻须落在控制频率网格上；只处理浮点舍入，不静默裁去尾帧或改变时长。
|
||
- 保留既有参考上限：腕平移0.05m/s、腕旋转0.5rad/s、所有状态关节0.5rad/s。
|
||
默认实验工作半径0.8m，与先前扩范围回放一致。
|
||
- **训练准备不自动慢放、缩放、平滑、重居中或跨无效帧插值**。超限时明确失败，由数据方另出可追溯版本。
|
||
- 单文件读取上限2GiB，重采样总帧数默认500000；大数据须明确分片/扩展，不自动放大资源预算。
|
||
|
||
## 3. 观测/动作契约：`l20_goal_reference_act_v1`
|
||
|
||
这是**状态参考模仿基线**，不是完整Canonical Skill Space或全项目DexSchema实现。
|
||
共享几何使用相对episode初始根link的腕部位姿；构型特有的关节顺序、主从映射与限幅封装在Adapter中。
|
||
不把21状态关节或16个目标硬编码为所有手型接口，也不把模型独立目标数当作硬件电机数。
|
||
|
||
| 项目 | 定义 |
|
||
| --- | --- |
|
||
| 当前状态 | 初始根坐标系中的当前腕位置3维、旋转6D（旋转矩阵前两列）、清单全部J个状态关节 |
|
||
| 条件目标 | 同坐标系下的episode终点腕位姿、终点M个模型独立关节姿态 |
|
||
| 时间条件 | 归一化phase及episode时长（秒）；用于指定此参考的时间参数，不是奖励 |
|
||
| 观测维数 | `20 + J + M`（当前已核验右手为57） |
|
||
| 输出 | 未来chunk的腕位置/旋转6D与M个独立`q_target`代理，维数`9 + M`（当前右手25） |
|
||
| 训练输入来源 | HDF5的参考状态；没有声称这是执行后传感器观测 |
|
||
| 仿真输入来源 | 实际当前root-link pose/q，加预先给定终点目标、phase和时长；不喂未来中间参考帧 |
|
||
|
||
当前状态→未来状态目标不是已测量的动作因果对。训练中teacher-forced参考状态与部署时受扰状态存在分布差异；
|
||
多条路径也可能共享相同起终点。这是需要真实仿真评估和后续示教/残差策略研究的风险，不因loss降低而消失。
|
||
不向网络输入完整未来参考轨迹来假装闭环成功。
|
||
|
||
### 模型与loss
|
||
|
||
- 状态输入ACT-style CVAE：训练时Transformer posterior编码观测及未padding的未来动作块，
|
||
得到高斯latent；decoder根据观测+latent与chunk queries预测未来目标。
|
||
- masked normalized L1 + KL；padding既不参与reconstruction loss，也被posterior attention mask排除。
|
||
- 推理固定latent=0，不使用训练posterior的未来目标；无dropout，CPU推理确定。
|
||
- 不是官方ACT仓库/权重兼容实现；没有视觉ResNet或Diffusion分支。
|
||
- normalization仅由训练分区的非padding帧拟合，验证/test数据不参与统计。
|
||
- best checkpoint仅按validation选择；test不参与优化或checkpoint选择。
|
||
|
||
默认 `configs/imitation/l20_right_act.json`：chunk16、每次执行前4个目标再规划、30Hz目标频率，
|
||
Transformer宽128/2层/4heads/latent32、batch32、seed42、最多1000更新且600秒。
|
||
这是**有界起始配置，不是已调优或保证收敛的超参**。600秒是训练/验证循环的内部预算，
|
||
不包含此前的数据预检；命令另设外部进程超时。预算耗尽记FAIL/未完成，不伪装成完成训练。
|
||
|
||
## 4. 数据到位后的命令
|
||
|
||
下面变量由调用者指向审核后的文件；`OUT`必须是新的仓库外目录。
|
||
当前示例数据不会通过这些正式训练门禁，这属于预期BLOCKED，不是安装失败。
|
||
|
||
```bash
|
||
MANIFEST=assets/robots/dex_hand/linkerhand_g20_right/tracking_manifest.json
|
||
CONFIG=configs/imitation/l20_right_act.json
|
||
# DATA=/approved/path/demonstrations.hdf5
|
||
# SPLITS=/approved/path/splits.json
|
||
# REVIEW=/approved/path/data_review.json
|
||
# OUT=/external/artifacts/l20-act-run-001
|
||
|
||
# 先只做CPU数据预检；父目录须存在，输出JSON必须为新文件。
|
||
bash scripts/imitation.sh preflight --hdf5 "$DATA" --manifest "$MANIFEST" \
|
||
--config "$CONFIG" --splits "$SPLITS" --data-review "$REVIEW" --output "$OUT-preflight.json"
|
||
|
||
# 审核数据与资源预算后再由用户启动；不传--execute会拒绝。
|
||
# CUDA是显式选择；不可用时报错，不静默换CPU，也不安装替代CUDA依赖。
|
||
timeout --kill-after=15s 660s bash scripts/imitation.sh train --hdf5 "$DATA" --manifest "$MANIFEST" \
|
||
--config "$CONFIG" --splits "$SPLITS" --data-review "$REVIEW" \
|
||
--device cuda --execute --output "$OUT"
|
||
|
||
# 按完整test分区做离线预测评测（CPU）；这不是仿真rollout或任务成功率。
|
||
bash scripts/imitation.sh evaluate --checkpoint "$OUT/best.pt" --hdf5 "$DATA" \
|
||
--manifest "$MANIFEST" --split test --output "$OUT-test.json"
|
||
```
|
||
|
||
`train`默认device为CPU；不要省略CUDA选择后误以为已用GPU。修改`max_updates/max_seconds`等资源预算应先确认。
|
||
训练输出为`run.json`、逐更新`metrics.jsonl`、`best.pt`、`last.pt`、`result.json`；
|
||
受控异常输出`failure.json`，不写成功result；进程硬超时/中断可能只留下部分制品，缺少result不能算PASS。
|
||
已有目录拒绝使用，不自动覆盖历史实验。
|
||
同一新run内best/last通过临时文件原子发布；记录配置、数据/Adapter、split/review、源模块哈希与依赖版本。
|
||
|
||
checkpoint使用tensor-only加载，绑定contract、资产/Adapter及normalization。
|
||
本版本支持**推理加载，不提供优化器resume**；不要把另一次新训练冒充恢复同一优化状态。
|
||
同一checkpoint的评估必须使用同一HDF5哈希；新评测数据需要显式评估接口扩展，不靠改metadata冒充原评测集。
|
||
|
||
## 5. 仿真策略评估入口（已实现，GPU E2E为NOT_RUN）
|
||
|
||
新增可选 `scripts/tracking/track_l20.py --policy-checkpoint`，默认不传时保留参考目标回放逻辑。
|
||
PASS日志增加`control_source`与`policy_checkpoint_sha256`字段；不改变HDF5 schema。
|
||
只接受训练数据中明确属于validation/test的episode，拒绝train episode；要求完整回合回放。
|
||
运行前仍检查source/prepared USD、PhysX后端、参考速度/范围及所有旧门禁。
|
||
|
||
策略在控制步读取实际状态，执行chunk前4个目标后重规划；每个240Hz物理步均经过Adapter：
|
||
|
||
- 将6D旋转恢复为合法旋转；退化/非有限输出明确失败，不能静默给单位姿态。
|
||
- 限制起点相对工作半径、目标平移/转动速度；关节按主从约束交集限位。
|
||
- 独立关节限速还考虑mimic倍率，确保派生状态关节目标也满足参考速度上限。
|
||
- 只发master `q_target`及既有根部wrench PD；从动关节由物理耦合响应，不独立驱动。
|
||
- 两轮分别清空policy chunk、时间计数及限幅器状态；只有原有reset路径写物理状态。
|
||
- 保留原有动态误差/限位/速度/mimic/非零运动及reset、位姿/速度重复性检查。
|
||
策略未训练好时应该FAIL，不用参考轨迹替代网络输出来通过。
|
||
|
||
确认无其他GPU/Kit作业，并**另行批准单次仿真预算后**才运行：
|
||
|
||
```bash
|
||
export PYTHONPATH="$PWD/source/dex_workbench${PYTHONPATH:+:$PYTHONPATH}"
|
||
# EPISODE必须属于validation/test，STEPS必须等于该回合秒数*240，且100<=STEPS<=32000。
|
||
# TIMEOUT_S须覆盖已批准预算；外部终止宽限15秒，不自动重试。
|
||
timeout --kill-after=15s "$TIMEOUT_S" ~/isaacsim/python.sh scripts/tracking/track_l20.py \
|
||
assets/robots/dex_hand/linkerhand_g20_right/tracking.usda --manifest "$MANIFEST" \
|
||
--hdf5 "$DATA" --episode "$EPISODE" --steps "$STEPS" --full-episode \
|
||
--workspace-radius 0.8 --policy-checkpoint "$OUT/best.pt" --execute-experimental --headless
|
||
```
|
||
|
||
策略与运行时控制参数必须与checkpoint绑定值一致；不允许临时扩大范围或阈值来通过。
|
||
日志使用独立标记`bounded_reference_act_rollout`，记录checkpoint SHA、推理次数和目标限幅步数。
|
||
目标限幅计数**不是**真实wrench/力矩饱和统计。
|
||
完整轨迹、非零运动和误差门禁仍可能限制部分静止/局部手指episode的仿真验收；
|
||
这些数据可以用于离线训练，不得为了满足诊断而添加伪运动。
|
||
|
||
## 6. 本次测试证据与剩余工作
|
||
|
||
本机证据位于 `../dex_workbench-evidence/l20-act-setup-M9Y0OX/`，不随代码分发。
|
||
|
||
```bash
|
||
# 已执行：只生成明确synthetic的三条不同解析轨迹，4次小CPU更新；不启动Kit。
|
||
bash scripts/imitation.sh smoke --manifest assets/robots/dex_hand/linkerhand_g20_right/tracking_manifest.json \
|
||
--output "$NEW_EXTERNAL_SMOKE_DIRECTORY"
|
||
|
||
PYTHONPATH=source/dex_workbench ~/isaacsim/python.sh -m unittest discover \
|
||
-s source/dex_workbench/tests -p 'test_*.py' -v
|
||
```
|
||
|
||
- 依赖/安装PASS：项目editable安装成功，无依赖下载/升级；CPU doctor及`doctor --cuda`可用性探测成功。
|
||
另在仓库外、清除PYTHONPATH后验证安装包可导入；CUDA可用不代表本轮执行过GPU训练或仿真。
|
||
- CPU smoke PASS：真实反向传播4次、有限loss、保存非空checkpoint、tensor-only重新加载；
|
||
重新加载预测最大差0；独立test分区离线预测有限。仅为管线验证，不宣称收敛。
|
||
- 全部118项回归PASS，无跳过（包含20项新增模仿学习测试）；覆盖坐标/半周旋转、coupling/rate限幅、
|
||
数据划分/分组/重复轨迹、训练统计隔离、padding mask、CVAE梯度、checkpoint身份、预算失败、
|
||
拒绝覆盖、held-out策略时钟/reset，以及旧tracking回归。
|
||
- 新仿真策略分支E2E、当前修改后的默认参考回放GPU回归、真实数据训练为NOT_RUN；
|
||
没有沿用上一轮已消耗的600秒GPU授权。完整pre-commit工具仍缺失，不宣称全量发布门禁通过。
|
||
- 后续：补齐数据审查与独立episode → 批准小规模真实训练预算 → 新checkpoint仿真闭环验收；
|
||
之后才设计PPO refinement或视觉/物体任务。尚无任务成功率、Sim2Real或SkillBundle交付声明。
|
||
- 本轮新增包/配置/文档，扩展可选策略入口；原始数据、USD、控制增益与物理阈值未改，
|
||
不升级包版本或改变Cartpole任务。未暂存、提交、推送。
|