189 lines
22 KiB
Markdown
189 lines
22 KiB
Markdown
# Go2 前视射线避障部署契约 v1
|
||
|
||
## API
|
||
|
||
默认任务白名单：`Unitree-Go2-Flat`、`Unitree-Go2-Rough`、`Unitree-Go2-ObstacleAvoidance`。
|
||
`GET /api/training/health` 的 `tasks` 保持字符串列表，新增 `taskMetadata`：每项含 `id/name/browserCompatible/terrainPresets/terrainParameters/sensorTypes/sensorParameters/mapSyncScope`。参数元数据含 `min/max/default`，计数含 `integer:true`。
|
||
|
||
`POST /api/training/jobs` 保留原参数，并接受：
|
||
|
||
```json
|
||
{
|
||
"taskId": "Unitree-Go2-ObstacleAvoidance",
|
||
"numEnvs": 1024,
|
||
"maxIterations": 1000,
|
||
"seed": 42,
|
||
"runName": "obstacle-navigation",
|
||
"device": "gpu",
|
||
"gpuIds": [0],
|
||
"wandbMode": "offline",
|
||
"terrainPreset": "discrete_obstacles",
|
||
"terrainParams": {
|
||
"size": 12,
|
||
"obstacle_count": 24,
|
||
"obstacle_height_min": 0.2,
|
||
"obstacle_height_max": 0.6,
|
||
"spacing": 1.2,
|
||
"friction": 0.8
|
||
},
|
||
"sensorType": "raycast",
|
||
"sensorCfg": { "fov": 90, "maxDistance": 4, "safetyDistance": 0.5, "avoidanceWeight": 2 }
|
||
}
|
||
```
|
||
|
||
只实现 `raycast`，**不是 RGB 或真实深度相机**；`camera_depth` 明确拒绝。`sensorCfg.type` 可选但只能是 `raycast`。默认观测数量32；显式multi模式固定48，不接受任意数量（见文末多层契约）。预设与字段严格白名单校验，布尔、非有限、超范围值拒绝。地形 `size` 8–24m、障碍物数1–100，实际数量受 `spacing` 容量限制。全部可选参数与范围见 `task_config.py`。普通训练的奖励 preset 仍仅允许 Flat；Obstacle专属自调参见文末。
|
||
|
||
创建和查询 job 返回 `deployment`，即该作业的确定性部署配置；列表中的 job 也携带此字段。不新增端点；ONNX 下载仍为 `/api/training/jobs/{id}/artifacts/policy.onnx`。自定义配置由服务写入作业目录 `training_config.json`，以参数数组 `--task-config <server-owned-path>` 传入训练器，绝不使用 shell。训练器再次校验配置与seed。
|
||
|
||
`policy.onnx` 的 `platform_deployment` metadata 字符串是同一对象的JSON编码，旁边同时导出 `deployment.json`。ONNX中包含Actor观测归一化，不要在前端再套一层运行均值/方差。其他标准 mjlab metadata 保留。旧 Rough 实际 Actor 为234维（47+17×11 downward height scan），`browserCompatible:false`；前端必须禁用一键加载，不能按 Flat 处理。没有新配置的旧 Flat/tuning 保持原环境行为。
|
||
|
||
## 地图：精确碰撞布局，不是同名编辑器高度场
|
||
|
||
`deployment.terrain` 为 `boxes-v1`：`size/friction/boxes/spawn/spawnQuaternion/target/actualObstacleCount/approximation`。
|
||
|
||
- 单块正方形地图，世界原点在地图中心，+X前、+Y左、+Z上，米/弧度。每个 box 的 `pos` 是世界中心，`size` **为半尺寸**，`yaw=0`。底板占 `z=[-0.2,0]`。无额外无限地面/边墙。
|
||
- 直接用导出的boxes构造碰撞几何，**不要重新运行浏览器的同名地形生成器**。`rough/wave` 为16×16有界box离散化，`pyramid_stairs` 为四层box；`approximation:true` 必须在UI标识训练专用近似布局。
|
||
- 障碍物坐标由 `random.Random(seed)` 对确定性格点洗牌；宽深均0.4m、高度按范围随机，实际数量受spacing与地图容量限制。两端保留平坦出生/目标条带。无需在JS复刻Python RNG，布局本身是权威结果。最多257个boxes。
|
||
- `spawn=[-size/2+1,0,0.32]`、四元数 `wxyz=[1,0,0,0]`、目标 `[size/2-1,0]` 是部署及固定评估的参考起终点。训练时每个episode在同一连通自由区域内重新采样起终点（障碍/边界净空>0.55m、间距>=2m）并随机化初始yaw，初始速度为0；不会跨不可通行墙体抽取目标。MuJoCo地形原点仍为参考spawn，随机复位直接写入世界坐标。
|
||
- mjlab采用1×1 patch，同一张地图用于多个互相独立的Warp环境世界；env origin就是出生点而非地图中心。目标在每个env中用 `env_origin.xy+[size-2,0]`，不是错误地再加地图中心。
|
||
- terrain摩擦为 `[friction,0.005,0.0001]`，priority=1、condim=3；足端startup滑动摩擦固定为相同值。浏览器应保持匹配的摩擦及足端接触配置。
|
||
- “同步当前场景地图”导出已应用场景的 `custom_boxes` 权威布局，细则见下节；预设生成模式仍保持原行为。
|
||
|
||
## 已应用场景 → custom_boxes
|
||
|
||
请求使用 `terrainPreset: "custom_boxes"`、`customTerrainBoxes: <完整boxes-v1对象>`；`terrainParams` 可省略，若提供则只能是与布局完全一致的 `{size, friction}`。服务和训练入口均重新验证，不读取客户端路径或XML，不运行地形RNG、不降级预设。作业目录task JSON、deployment JSON及ONNX metadata中的terrain使用同一布局。health的terrainPresets公布能力。
|
||
|
||
- 浏览器从成功编译的全部sceneMaps静态碰撞 `geom_xpos/geom_xmat/geom_size` 提取，包括工程地图路径、重复实例和嵌套body变换；不使用Three装饰包围盒、编辑器RNG或不完整XML。动态机器人、无碰撞装饰排除；未声明地图身份的其他静态碰撞报错，不能漏障碍。
|
||
- box世界半尺寸为 `abs(R)*halfsize`；sphere、capsule、ellipsoid、cylinder使用解析精确世界AABB。**旋转box与非box转换会扩大碰撞占据区域**。mesh/hfield明确拒绝；项目地图原有include导入限制不变，已经编译模型的include变换不重新解析。
|
||
- 固定floor为中心 `[0,0,-.1]`、半尺寸 `[size/2,size/2,.1]`。仅明确命名floor/ground/flat的朝上水平z=0 plane，以及顶面z≈0的水平支撑box归并。地下/坑底/非零高度或倾斜plane拒绝，不能静默填坑。其他障碍原坐标保留。底板覆盖整个正方形范围，可能填补支撑面间空白；UI明确说明标准化，不保证与原场景几何同构。
|
||
- 最多256障碍+1底板，超量报错不截断；世界原点不变，尺寸8–24m，取覆盖应用地图/几何的正方形，不clamp或平移几何。XY必须在floor内，Z界限[-.2,12]，所有半尺寸严格>0（包括拒绝负零），有限数值。摩擦必须统一为 `[f,.005,.0001]` 且f为.2–2，混合值报错要求用户先显式统一，不能静默覆盖。
|
||
- `approximation` 对custom必须为true（AABB及标准底板转换）；`actualObstacleCount` 必须等于boxes数减一。字段严格白名单，不信任声明值。floor必须标准。面板不显示或编辑出生/目标坐标；场景编译器从连通自由栅格自动选取障碍/边界净空>0.55m且间距>=2m的确定性参考点，出生z固定.32，四元数取成功加载时真实初始浮动基座姿态。启动训练和打开调参时均自动重新编译当前已应用碰撞场景。
|
||
- 出生及目标中心必须距边界>=.5m；与每个非底板障碍XY AABB的最近距离必须严格>.5m（圆形安全区，包括切触拒绝），不能删除或移动障碍以修复。四元数必须有限且归一化。后端env origin、初始化姿态、目标偏移和越界中心按自定义spawn计算。
|
||
- 同步/提交均拒绝未应用草稿、训练部署替换后的场景、加载中或已过时场景；提交前再次比较当前编译布局。HTTP `MAX_REQUEST_BYTES` 与训练JSON上限均128KiB，足够257个double-precision boxes且有界；ONNX部署metadata上限仍100KB。
|
||
|
||
## 81维观测/12维动作
|
||
|
||
Actor顺序（float32）：
|
||
|
||
| slice | 内容 |
|
||
| ----- | --------------------------------------------------------- |
|
||
| 0:3 | `robot/imu_ang_vel`，本体坐标角速度rad/s |
|
||
| 3:6 | 本体坐标重力单位向量（静止 `[0,0,-1]`） |
|
||
| 6:9 | 下述目标导航速度命令 `[vx,0,wz]` |
|
||
| 9:11 | sin/cos(2π×episodeTime/0.6)；命令范数<0.1时均为0 |
|
||
| 11:23 | 相对默认关节位置 |
|
||
| 23:35 | 关节速度，无缩放 |
|
||
| 35:47 | 上一原始12维动作，不是力矩或位置目标 |
|
||
| 47:79 | 32条前向测距，miss→1，否则clamp(distance/maxDistance,0,1) |
|
||
| 79:81 | `[headingError/π, clamp(goalDistance/size,0,1)]` |
|
||
|
||
关节顺序FL/FR/RL/RR，每腿hip/thigh/calf；默认角 `[-.1,.9,-1.8, .1,.9,-1.8, -.1,.9,-1.8, .1,.9,-1.8]`。
|
||
位置目标 `defaultJointPosition+0.25*rawAction`；kp每腿 `[20,20,40]`，kd `[1,1,2]`，力矩限幅 `[23.5,23.5,45]`。后端物理dt=.005，decimation=4，策略50Hz；浏览器仍可更小物理dt并采用single-in-flight/held-action。Go2-W轮式模型不是此任务的同构训练机器人，不应声称动力学严格等同。
|
||
|
||
### 射线
|
||
|
||
安装在 `base_link`。对 i=0..31：
|
||
|
||
- `angle=(-fov/2+i*fov/31)*π/180`，局部direction=`[cos(angle),sin(angle),0]`。
|
||
- 局部offset=`[.3,0,.05]`，origin=`baseWorldPosition+Rbase*offset`，directionWorld=`Rbase*direction`。采用**完整body姿态**，不可只用yaw。采样从右到左且包括两端；无恰好0°的中间射线。
|
||
- 后端地形group0、机器人visual group2/collision group3，include_geom_groups=(0,)排除整个机器人。浏览器必须语义等价地仅射向地形（如其group2），不能照搬group0或只排除base_link。包含地面；倾斜时地面命中也构成感知数据。miss或超过range归一化为1。
|
||
- 前向扇形只能在一个高度切片感知；矮障碍物/跌落/盲区并不保证可检测，不能称安全导航保证。
|
||
|
||
### 导航及episode
|
||
|
||
`delta=target.xy-basePosition.xy`；distance=hypot(delta)；yaw由base wxyz计算；headingError=`atan2(sin(atan2(dy,dx)-yaw),cos(...))`。未到达时 `vx=navigation.speed*max(0,cos(headingError))`（缺省.6，调参可.3–1.2）、vy=0、wz=clamp(headingError,-1,1)。distance<.5m到达后command全0、headingError=0，distance observation仍保留实际距离；不重采样新目标，不因到达施加失败惩罚。移动机器人离开半径后自然恢复导航。
|
||
|
||
训练episode20s，超时重置；跌倒、非足端接触force>10N、机器人中心越过地图边界内0.3m终止并重置。训练复位随机选择同一连通自由区域的起终点和初始yaw，恢复初始关节姿态及零速度，并清phase/上一动作；固定评估仍使用deployment声明的参考起终点以保持版本间可比。浏览器episode若不自动重置必须明确自己的评测行为；到达至少要停命令而非无限推进。奖励保留速度跟踪/平滑/姿态/非法接触终止惩罚，并增加朝目标世界速度投影及归一化近障平方惩罚。
|
||
|
||
## 验证
|
||
|
||
```bash
|
||
.venv/bin/python -m unittest discover -s training_server/tests
|
||
.venv/bin/python -m ruff check training_server
|
||
GO2_RUN_MJLAB_SMOKE=1 MUJOCO_GL=egl .venv/bin/python -m unittest discover -s training_server/tests -p test_obstacle_env.py
|
||
WANDB_MODE=disabled .venv/bin/python training_server/rl/scripts/train.py Unitree-Go2-ObstacleAvoidance --env.scene.num-envs=4 --agent.max-iterations=1 --gpu-ids '[0]' --output-dir /tmp/go2-obstacle-train-smoke
|
||
```
|
||
|
||
GPU smoke对比真实mjlab/Warp与MuJoCo `mj_ray`距离、检查多env出生点/关节顺序/81维有限obs。1iteration只验训练/导出管线，**不证明策略已学会避障或Sim2Sim行为收敛**。
|
||
|
||
## Obstacle DeepSeek 自调参（obstacle-v1）
|
||
|
||
`POST /api/tuning/sessions` 新支持 `taskId=Unitree-Go2-ObstacleAvoidance`。
|
||
沿用 automatic/approval、运行时双向切换、稀疏patch、最多4项/单轮0.5–2倍、工程护栏与revision CAS；Flat完整schema、奖励应用与相对基线六维评分不变。
|
||
可携带与训练相同的顶层terrain/sensor字段，或单独`taskConfig`对象（不能混用）；场景/seed仅创建时确定。所有字段/范围、NaN/Inf、跨任务patch/护栏拒绝；旧revision返回409且不修改配置/审计/待审批项。
|
||
|
||
| JSON路径 | 范围；默认 | 真实环境映射 |
|
||
| --------------------------- | -------------------------------- | -------------------------------------------------------------------------- |
|
||
| `weights.avoidance_weight` | .5–5；2（创建时可取sensorCfg值） | `obstacle_proximity.weight=-value` |
|
||
| `params.target_velocity` | .3–1.2；.6 m/s | `NavigationCommandCfg.speed`，**不是奖励权重** |
|
||
| `weights.collision_penalty` | -10–-.5；-5 | `obstacle_collision`：同illegal_contact函数/参数，非足端地形接触>10N指示量 |
|
||
| `weights.action_smoothness` | -.05–-.001；-.05 | `action_rate_l2.weight` |
|
||
|
||
保留原is_terminated等非白名单项，collision_penalty额外独立惩罚非法接触，不用它替代客观碰撞统计。服务写每trial独立reward/task JSON，以`--reward-config/--task-config` argv传入真实训练器和评估器；训练入口先应用场景再应用调参。导出ONNX/deployment的navigation.speed与sensorCfg.avoidanceWeight反映实际配置，浏览器仍81→12且使用配套速度。旧无调参模型保持.6。奖励Preset在普通训练面板仍仅Flat可选；Obstacle可从调参工作台直接导入最佳带metadata策略，不把Obstacle preset混入Flat训练。
|
||
|
||
### 固定客观评估与安全门槛
|
||
|
||
- 固定seed **101/202/303**、每seed **1000策略步×.02s=20s**；每env仅统计reset后的**第一个episode**。提前终止后仍运行完整horizon，但不将自动reset后新episode混入首episode；剩余步数不能带来平滑/净距奖励。各seed先按env等权均值，再三seed等权。evalNumEnvs创建时固定（所有trial相同），Agent不能改seed、horizon、权重、场景、传感器、起终点。
|
||
- 固定评估按三个seed分别构造布局，非随机预设不保证三张不同地图；评估关闭训练期随机起终点。custom严格保持上传的同一地图及验证过的参考spawn/target，标记`fixed-custom-map`，**不是三个随机地形**。保留任务原有reset_joint/startup随机化并用seed复现；若轨迹相同仅是确定性重复试验，不能当作泛化证据。
|
||
- 读取真实checkpoint Actor网络及其`obs_normalizer`统计，strict加载；没有零动作/假策略fallback，不读取训练reward作为指标。不同地图CUDA编译隔离：三个seed顺序启动同一Python解释器子进程（非fork/非并行），共享不可变checkpoint快照并核对SHA256；父进程使用独立临时目录，worker继承父进程组，现有session取消会终止worker，每seed超时1200s即整轮失败。任意seed失败、缺失、错身份、样本不足、非有限或协议不一致整轮fail closed，不用部分结果凑均值。
|
||
- hook在termination manager计算后、`_reset_idx`之前捕获包括**首terminal**的物理量。与mjlab终止判断一致，派生pose最多滞后一个.005s物理子步；接触force history覆盖全部4子步。每步读取目标水平距离、前视射线命中比例、非底板障碍净距、实际action差分、接触/跌倒标志。前视ray_hit可包含地板，仅作为感知诊断，不直接评分。
|
||
- **擦碰/碰撞**：任一机器人（含足端）与非底板障碍的实际接触力幅值>1N，或非足端与任意地形（含地面）>10N。使用编译terrain_1…几何的独立contact sensor（maxforce+4子步history），排除terrain_0标准底板；不是用ray命中推测碰撞。1N以下触碰不计，不能称零接触安全保证。
|
||
- **跌倒**：base高度<.12m或姿态倾角>70°（projected_gravity.z > -cos70°）。**到达**：水平距离<.5m。**成功**：episode内到达，且整段首episode无碰撞、无跌倒；先到达后擦碰/跌倒也失败。未成功时间项必为0，不因提前跌倒取短时间高分。
|
||
|
||
固定五项0–1分量：`success`为成功指示；`time`成功时`1-firstArrivalStep/1000`，否则0；`clearance`每步`clamp((baseXY到非底板box XY AABB距离-.3m)/.5m,0,1)`，按1000步求均值（终止后补0，任何跌倒整项0，无障碍时每有效步1）；`smooth`每步`1-clamp(mean((action_t-action_t-1)^2),0,1)`，初始action=0，按1000步求均值（终止后补0）；`no_fall`为无跌倒指示。净距是保守圆形机身足迹代理，并非全机身mesh最近距离，地板不作为障碍、躺地不当安全。
|
||
|
||
绝对总分=`.4*success+.2*time+.2*clearance+.1*smooth+.1*no_fall`。例如两步简化fixture，第二步无碰撞到达，净距均.25m、action差分MSE均.5，得分`.4+0+.1+.05+.1=.65`。固定1000步实际协议不接受fixture horizon。
|
||
|
||
相对初始baseline的硬门槛：`fall_rate<=baseline+.02`且`success>=baseline-.02`（边界包含；1e-12浮点容差）。不通过eligible=false且score=-1，不能用其他高分绕过。baseline也用完整客观绝对评分，不默认指标为0。result记录完整协议/场景布局、seed结果、样本数、checkpoint SHA256、各项均值，candidate必须与baseline协议完全一致。
|
||
|
||
## 显式多层射线（阶段5；不是局部高程图）
|
||
|
||
`sensorCfg.sensorMode` 是唯一模式字段：缺省/`single_ring_raycast` 保持旧32ray/81obs及旧proximity奖励行为；显式 `multi_ring_raycast` 为3×16=48ray/97obs。`sensorType/type`仍为`raycast`。health新增`sensorModes`，UI可选择；不是任意自定义扫描图案。没有局部高程图网格、用途或输入定义，本阶段**未实现高程图**。
|
||
|
||
任务JSON、deployment JSON及ONNX metadata规范化导出以下字段（FOV仍叫`fov`）：
|
||
|
||
```json
|
||
{
|
||
"sensorMode": "multi_ring_raycast",
|
||
"rayCount": 48,
|
||
"pitchAngles": [0, -20, -45],
|
||
"yawCount": 16,
|
||
"yawAngles": [-45, -39, -33, -27, -21, -15, -9, -3, 3, 9, 15, 21, 27, 33, 39, 45],
|
||
"fov": 90,
|
||
"angleUnit": "deg",
|
||
"rayOrder": "layer-major"
|
||
}
|
||
```
|
||
|
||
旧single规范化为pitch `[0]`、yawCount/rayCount=32。所有yaw为`-fov/2+i*fov/(yawCount-1)`含两端，从右到左，无0度中心ray。只允许两种固定组合；显式矛盾字段/未知字段/不支持的模式拒绝，不静默覆盖。旧metadata缺新增字段可规范化后与新job语义匹配；旧81 graph绝不冒充97。
|
||
|
||
局部direction=`[cos(pitch)*cos(yaw),cos(pitch)*sin(yaw),sin(pitch)]`，先一层16yaw再下一pitch层；origin仍为`basePosition+Rbase*[.3,0,.05]`，direction乘**完整base姿态**。后端实际RayCastSensorCfg使用同一pattern；浏览器预计算局部direction并缓存每个已编译静态box世界变换，解析slab求交；只对精确单位旋转用轴对齐快速路径，无变换近似。
|
||
|
||
97维slice：基础`0:47`完全不变，真实测距`47:95`，目标误差`95:97`仍为原有符号的heading/π与距离归一化。miss/超range→1，地板命中保留真实距离；调参`target_velocity`继续传入真实command与导出navigation.speed。原single-in-flight、held-action、事务导入和资源释放协议不变。三seed评估仍是顺序独立解释器；advisor按实际32/48模式说明盲区。
|
||
|
||
### 地板与奖励
|
||
|
||
仅multi的`obstacle_proximity`排除标准底板顶面：首次计算用CPU编译模型验证**唯一**与首box相符的静态world-weld/group0 box（世界中心`[0,0,-.1]`、半尺寸`[size/2,size/2,.1]`、单位世界旋转），再核实生成器名称`terrain_0`，失败关闭；不是只根据名称。真实编译terrain为固定body而非bodyid=0，使用weld身份。
|
||
|
||
当前mjlab RayCastData没有hit geom ID，因此是**几何分类过滤**：必须finite实际命中，hit世界XY在floor范围（容差1e-5m），`abs(hit.z)<=1e-5m`，normal与+Z逐分量误差<=1e-5。每个Warp环境是独立同坐标地图，hit不额外加env_origin。容差为float32的10微米，不把5cm低障碍抹除。低box顶面、侧面不滤；全floor/miss惩罚0且finite，其余仍用最近有效距离的原平方归一化。观测数据不原地修改。与底板顶面共面的几何无法凭此分类区分，不能声称等价命中geom ID；台阶/非零高度表面不是标准地板。
|
||
|
||
下倾层改善部分低障碍/有界地板边缘感知，但层间、侧后方、遮挡和有限range仍有盲区；标准boxes-v1底板本身会填补内部空洞，不能声称已解决坑探测或安全导航。
|
||
|
||
### 阶段5复现
|
||
|
||
```bash
|
||
.venv/bin/python training_server/tests/generate_multi_ring_golden.py
|
||
GO2_RUN_MULTI_SMOKE=1 MUJOCO_GL=egl .venv/bin/python -m unittest discover -s training_server/tests -p test_multi_ring.py
|
||
WANDB_MODE=disabled MUJOCO_GL=egl .venv/bin/python training_server/rl/scripts/train.py Unitree-Go2-ObstacleAvoidance --env.scene.num-envs=4 --agent.max-iterations=1 --gpu-ids '[0]' --task-config /tmp/go2-multi-ring-stage5/task.json --output-dir /tmp/go2-multi-ring-stage5/train
|
||
```
|
||
|
||
真实4env/1iteration新97策略仅验训练、归一化Actor导出和浏览器ORT链路，不是旧81 checkpoint改metadata，不证明导航成功。CLI子进程`--help`回归分别验证Flat/Rough/Obstacle的任务注册；修复前直接CLI仅注册mjlab内建任务，原错误日志保留。
|
||
|
||
事务重导入回归确认97→97、97→81→97合法graph/metadata成功；伪97metadata+81graph与缺失ORT算子均在预期阶段报具体错误并保留旧会话。曾看到“模型编译失败”是App只转抛diagnostic.summary遮蔽了原detail，并非实际MJCF编译失败；已改为detail优先，未改事务资源/rollback。
|
||
|
||
### 复审修复：奖励preset任务归属
|
||
|
||
公共preset仍可保存Obstacle调参结果，但`save/get/list`均从来源session的`config.taskId`恢复权威任务归属并验证完整reward schema；列表和单项返回`taskId`。历史session仅缺`taskId`时按既有Flat默认解释，且必须通过完整Flat schema。来源缺失/损坏、显式未知或空taskId、损坏preset均失败关闭（列表不返回部分可信结果）；不相信客户端声明，也不凭奖励字段猜任务。
|
||
|
||
普通本地训练的`rewardPresetId`入口仍仅支持Flat；resolver核对来源任务与请求任务，服务再次验证完整schema，跨任务/损坏preset返回400且不创建job。UI仅展示服务明确标记Flat的preset，旧服务无身份字段时不展示，而不是默认为Flat。Obstacle preset UI未扩展；Obstacle调参最佳策略配套导入、Approval/Automatic均保持原协议。
|