Add declarative single-leg import, fixed-anchor benchmark, masked shared-policy PPO prototype, regression tests, and consolidated documentation.
10 KiB
单腿接口与验收
1. 实现范围
LegSpec JSON → URDF 子树/资源/许可 → USD 与映射
→ 固定支座环境 → 形态/状态 tokens → 共享 actor/critic → PPO
- 已实现真实 Go2 FL、Go1 FL 导入、CUDA 批量仿真、indexed reset、目标条件共享 PPO 短更新。
- 支持独立 bounded revolute 树、显式辅助 fixed 支链、一个足端、sphere/box 间隙探针;mimic、prismatic/continuous、闭链、柔性结构和 mesh 足底近似明确不支持。
- 未实现 ModSkill 式学习 latent、跨部件协调、冻结 SkillBundle、高层调用及真实留出形态泛化。人工 goal、URMA 内部 action intent、保存 checkpoint 都不等于已学得可复用 Skill。
- Go2/Go1 都是 3 DoF;生成的 1/2/4 DoF 夹具验证接口,不代替真实不同 DoF 或迁移实验。
2. 资产与物理契约
公共入口:SkillFactory.legs.LegSpec / JointSpec、legs.urdf.extract_leg、legs.spec.load_bundle。示例 configs/legs/{go2_fl,go1_fl}.json。
| 声明 | 含义 |
|---|---|
| source_root / urdf / package_name / license_file / license_id | 来源、资源解析及许可 |
| mount_joint / auxiliary_root_joints | 切口与保留支链;辅助 roots 必须 fixed 且共用源 parent |
| joints | 受控关节的声明顺序、q_default、action_scale、Kp/Kd |
| foot_body / foot_collision_index | 独立传感 body 与用于 gap 的碰撞体 |
| soft_limit_factor / physics_dt / decimation | 软限位与物理/控制时间步 |
提取按树而非名称前缀;全部 moving joints 必须受控,保留足端/rotor/固定碰撞辅助。合成 anchor_base 无碰撞、质量 1 kg、惯性对角 0.001 kg·m²;固定安装座,不冻结 hip。anchor frame 为安装关节零位 frame,源 parent 到 anchor 的变换保存在 manifest.mount,供未来装配使用。
输出:leg.urdf、asset manifest v2、完整资源、LICENSE、分层 USD、conversion.json。加载校验 URDF/资源/许可 hash、执行顺序、转换 manifest hash、独立 body/joint 映射、固定支座及层依赖;拒绝逃逸路径、输出覆盖源目录及越界 symlink。改描述/重提取后必须重转换,资产目录整体迁移。
真实 Unitree 资产保留 BSD-3-Clause 许可,不修改原文件。有源惯性保留完整 tensor 并检验正定;Go2 FL_calflower/FL_calflower1 缺少惯性,PhysX 实测估算质量约 0.0247086/0.0226430 kg,不能冒充厂家数据。质量尺度为源已知惯性质量和,排除 anchor 和未知估算质量;有效导入 body masses 随运行报告保存。
默认显式 Ideal PD,示例 Kp=25、Kd=0.5,导入器 drive 关闭;限矩/限速取 URDF,目标为 q_default + action_scale * clamp(action,-1,1),再按软范围裁剪。Go2 默认 [0,0.8,-1.5] rad、scale=0.25;限矩 [23.7,23.7,45.43] N·m、限速 [30.1,30.1,15.7] rad/s。物理 0.002 s / 控制 0.01 s。
新任务用本地 legs/resources/ground.usda(z=0、静/动摩擦 0.8/0.6、恢复系数 0);旧基准地面保持原配置。足端显式启用 contact reporter;运行入口验证 ground collider 和传感器唯一映射。
3. 通用任务 SkillFactory-LegSkill-v0
Kit 启动后构造 LegEnvCfg(bundle_dir=..., max_joints=8) 并 gym.make(...)。默认悬空高度为保守足端路径长度 +0.1 m;ReachCommand 对实际动作范围内姿态做 FK,生成运动学可达的足端 link 位置目标。reward 为归一化 tracking、effort 与 action-rate 惩罚,不保证目标动态可行或已学到步态。
obs['policy'] 字典:浮点 CUDA float32、mask bool;anchor 坐标、米/弧度/SI;四元数 xyzw、世界 z 向上。完整字段顺序/归一化由 legs.tokens.FEATURE_SCHEMA 定义,并存入 checkpoint。
| 字段 | 形状 |
|---|---|
| joint_description / joint_observation / joint_mask | [B,Jmax,25] / [B,Jmax,3] / [B,Jmax] |
| effector_description / effector_observation / effector_mask | [B,1,16] / [B,1,11] / [B,1] |
| context / goal | [B,10] / [B,3] |
- joint description 含 nominal 轴/位置、范围/控制规格、source child mass、COM 惯性及偏移;COM/inertia 转到 anchor nominal frame,不做 fixed-subtree 复合惯性聚合。
- joint observation:
(q-q_nominal)/scale、dq/limit、最后已施加动作(ActionManager.action)。 - effector:link 原点位置/线速度、ground-filtered 法向力、接触标志(>1 N)、选定碰撞体 gap。不是切向摩擦力、实测电机扭矩或六维 wrench;其他碰撞体的全脚掌最小 gap 未实现。
- context 保留重力、dt、地面相对高度、长度/已知质量、限矩对重力力矩比、绝对限速、缺失惯性标志,避免归一化擦掉物理差异。
- 当前必需传感器,无噪声/DR;未来随机化物理属性必须同步描述,不能沿用静态缓存。
mdp.state(env).snapshot() 返回新 token 视图;跨 step/reset 保存须 clone。state(env).actions([B,Jmax]) 去 padding 后再调用 env.step([B,N]);Gym action space 是实际 N。虚拟槽不驱动,也不参与路由/log-prob/entropy/梯度。
reset(env_ids=...) 支持全量、索引、空集合 no-op;拒绝负/越界/重复/非整数索引及空 reset reseed。复位清理目标、动作/历史、episode;不重建 stage、不推进物理时间,不改变未选实例。非法原生动作在 ActionManager 改历史前拒绝。timeout 使用 reset 前的 terminal tokens bootstrap,真 termination 不 bootstrap。
4. 训练与失败语义
LegActorCritic:静态描述 MLP 的逐 latent 特征 softmax 路由动态状态、共享核心、共享逐关节高斯 decoder。不是大型 Transformer 或完整 ModSkill 复现。
不同拓扑按独立同构 worker 采样,只在 PPO 层合并,不能认为 replicate_physics=True 支持任意拓扑混装。各资产等量采样、共用采样权重/optimizer,必须同 physics/control dt;device 显式传给 worker。保存未裁剪动作的 log-prob,实际执行再裁剪。更新前检验概率一致性;GAE/旧 rollout 梯度分离,拒绝空/非有限输入。
当前每轮重启 Kit、CPU 文件交换,仅适合短测试,不适合直接长训或吞吐结论。checkpoint 仍标 trained_skill=false。
运行报告先写 passed=false/status=running,环境成功关闭后才提交成功;JSON 原子替换并拒绝 NaN/Inf。关闭异常/子进程失败/critical log 均保留非零退出码,检查 error/fatal/contact buffer overflow,不能只看进程退出 0。优化按字段读取观测,不缓存跨 reset 状态;FK 常量与 box 投影复用/向量化。
5. 保留基准 SkillFactory-SingleLegAnchor-Go2-v0
接口不变:CUDA float32 actions [B,3],policy [B,19]:
| 切片 | 字段 |
|---|---|
| 0:3 / 3:6 | q-q_default [rad] / dq [rad/s] |
| 6:9 / 9:12 | foot link 位置 [m] / 线速度 [m/s],anchor frame |
| 12:15 / 15:16 | ground 法向力 [N] / contact float 0/1 |
| 16:19 | ActionManager.prev_action(旧接口历史语义,区别于新任务) |
旧默认支座高度 0.344598 m、足球 r=0.022 m / local offset=(-0.002,0,0);默认 timeout 10 s,验收禁用。旧空 reset 在验证调用端做 no-op;不要假设底层普通 ManagerBasedRLEnv 支持空索引。诊断 single_leg_anchor.mdp.observations.diagnostics 包含 q/dq/目标、限幅前后命令 torque、gap、anchor pose、[B,5,1,3] 历史;torque 非实测、reaction_wrench=None/valid=False。
6. 验收证据与限制
第一周历史完整验收:logs/week1_anchor/acceptance/result.json,passed=true/milestone_complete=true;原 Go2 URDF SHA256 7d19fe48e2e689ee1a032ab99f2a4a8b671d87e73de48d3e65811682a5b48b9e,源提交 daadf41ee9afce8f90fdc09a98506012691fa122。
| 项目 | 实测 | 保留阈值 |
|---|---|---|
| B=1/16/64 接口 | [B,19] CUDA、顺序/有限性通过 |
shape/order/finite 匹配 |
| 悬空 60 s + 2 s warmup,0.1 rad / 0.5 Hz | RMS [0.043313,0.017097,0.009654] rad,根漂移/转角 0 |
RMS≤0.10,根≤1e-4 m/1e-3 rad,硬限位容差0.01 rad、torque不越界 |
| 20 次抬脚/压地 | 离地 0 N;最小稳定平均 Fz 31.3321 N | gap≥1 cm/力<0.1 N,压地>1 N |
| 接触响应/穿透 | 延迟0控制周期、最大1.40e-6 m | ≤1周期 / ≤5 mm |
| 独立1 kg小球标定 | 9.810026 N | m·g误差≤20% |
| 耐久 | 64×600 s、60,000控制/300,000物理步 | 完整时长、无非有限/意外reset/限位异常 |
| reset隔离 | 1,334操作=1,001非空+333no-op;误差0、prim数2384不变 | ≥1000真reset,q/dq≤1e-5、未选≤1e-6、历史清零、不重建 |
| 资源 | device used 3,814,981,632 B前后不变 | warmup后增长≤5% |
历史墙钟 576.748 s(约6,658环境控制步/s)、reset均值/最大1.785/4.620 ms;没有墙钟实时门槛。显存包含 Warp/PhysX,不能只报 Torch 分配。固定支座承担载荷,足端力不等于腿重量。
本次代码复验放在 logs/code_review/,不覆盖历史验收:
- 全部定向测试 43 passed(含旧任务 B=1/16/64 Kit 集成),全仓库 Ruff /
git diff --check通过。 go2_64、go1_contact_64、fixture2_16:原生/token动作、快照一致性、任意轴/box、索引/空reset与接触复验通过。train_mixed_smoke:三组各16环境、32步、1次共享PPO,概率与checkpoint一致性通过;trained_skill=false。anchor_debug:缩短的旧full套件通过,明确milestone_complete=false;最终运行日志无error/fatal/buffer overflow。
缩短时长的通过不等于重做600 s验收;生成夹具或一次 PPO 更新不证明真实泛化/收敛。
生成缓存与证据不入库,迁移机器需重建复验。后续顺序:常驻采样与训练/留出评估 → reference/goal-to-latent 学习 → 冻结低层与高层复用 → 单独评估移动基座/整机协调。