Files
SkillFactory/docs/leg_interface.md
T
chenlin 7f39abb613 release: SkillFactory v0.0.1
Add declarative single-leg import, fixed-anchor benchmark, masked shared-policy PPO prototype, regression tests, and consolidated documentation.
2026-10-10 09:58:30 +08:00

110 lines
10 KiB
Markdown
Raw 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.
# 单腿接口与验收
## 1. 实现范围
```text
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 学习 → 冻结低层与高层复用 → 单独评估移动基座/整机协调。
研究参考:[URMA](https://arxiv.org/html/2409.06366v2)、[ModSkill](https://arxiv.org/html/2502.14140v1)。本项目是固定支座单腿工程改编,不是原论文全身模仿或零样本迁移复现。