81 lines
12 KiB
Markdown
81 lines
12 KiB
Markdown
# 自定义训练与前视射线避障
|
||
|
||
1. 启动仓库本地训练服务，在「控制台 → 强化学习任务」输入令牌并连接。
|
||
2. 选择「前视射线避障导航」，设置地形、种子、障碍物参数、FOV、探测/安全距离及避障奖励权重，发起训练。界面显示进度、最近价值/策略/熵损失和原始日志。
|
||
3. 可选的「检查当前场景地图」从全部**已应用**实例的已编译MuJoCo静态碰撞几何导出权威 `custom_boxes/boxes-v1`，支持多实例、平移/旋转、工程地图路径及嵌套body。不重新运行随机预设，不同步未应用草稿。面板不再显示或编辑出生/目标坐标：系统从连通栅格自动选择满足障碍/边界净空0.55m且相距至少2m的参考点；训练每个episode仍独立随机采样。点击训练或打开调参时会从当前已应用碰撞场景自动重新编译并校验，不依赖旧同步快照；绝不删除或移动障碍来腾出安全区。
|
||
4. 训练完成后，先导入并加载有对应12个关节的Go2模型（Go2-W仅为非同构实验）。点击「导入策略」会校验作业配置与ONNX内嵌部署契约，在候选场景中完成真实ORT初始化、graph与机器人绑定检查后才事务替换当前**物理**地形、复位到出生点，启动策略与仿真。当前编辑器地图保留，重新加载模型恢复它。失败保留原场景、策略、物理状态及原暂停/播放状态。旧Flat无配套地形时仍按原方式加载后手动启用；新服务的默认Flat作业允许旧外部训练器无metadata导出，但真实graph必须固定47→12；显式自定义地图/避障不允许此降级。
|
||
5. 避障任务自动导航到配套目标，目标半径0.5m内停止速度指令。摄像头PiP自动打开，可单独隐藏；「显示避障射线」可切换红色命中/绿色未命中线段。
|
||
|
||
## 交互式导航目标与训练趋势
|
||
|
||
- 避障策略加载后，主视口显示青色呼吸目标信标，按当前训练碰撞地形的顶部高度落位。ONNX 面板显示当前目标坐标及水平剩余距离。
|
||
- 点击「设定目标」，再在主视口地形单击：目标限制在地图边缘内缩0.5m的区域，并自动退出设定模式。Esc/取消可退出；空白、拖动及摄像头PiP不会更新目标。模式使用捕获阶段拦截输入，不选择刚体或操纵地图Gizmo。
|
||
- 暂停或停用策略时也可更改目标，但不会自动启动仿真或策略。「复位目标点」只恢复训练地图默认目标；「重置仿真」同时恢复默认目标与出生状态。换目标不修改部署JSON、不重建ONNX会话，下一次观测仍保持该策略的81或97维。信标仅表示目标位置，不保证该点可到达或路径无障碍。
|
||
- 训练卡片中的「训练指标趋势」可折叠，提供价值/策略损失及综合页；综合页的熵、平均奖励、平均回合长度各用独立纵轴。复用自调参工作台的轻量Canvas图表，EMA系数0.4仅用于曲线，悬停图例和摘要保留原始值，支持缩放。
|
||
- 按日志中的 `Learning iteration` 合并指标，重复轮询不重复入点，同迭代分批日志可补全；内存最多保留最近500个有指标的迭代。换作业/清除作业会清空。服务器仅保留日志尾部，断线重连不能恢复已丢失历史；没有迭代标题或已知重叠上下文的孤立指标会跳过，不猜测step。缺失指标不显示，原始日志仍可展开。
|
||
|
||
## 自定义场景导出边界
|
||
|
||
- 使用实际碰撞几何而非Three装饰包围盒；box的世界AABB半尺寸为abs(R)×halfsize，sphere/capsule/ellipsoid/cylinder有精确解析bounds。mesh/hfield暂明确拒绝，其他未声明静态碰撞也报错，不能漏掉。既有工程地图include导入限制不变。
|
||
- **AABB会膨胀旋转/非box形状，底板标准化可能填补支撑面之间空白**；custom总是approximation=true，仅保证训练和浏览器部署相同boxes，不保证原OBB/原场景几何同构。仅明确命名且顶面z≈0的水平支撑归并为floor z=[-.2,0]；地下/坑底、倾斜或非零高度plane拒绝，不静默填坑。
|
||
- 固定floor加最多256障碍，超量报错不截断。保持世界坐标、覆盖范围8–24m，超出时明确拒绝，不clamp/平移障碍。所有半尺寸须严格正值；统一friction=.2–2且其余摩擦分量为.005/.0001，混合摩擦需先在地图中显式统一。
|
||
- 服务和训练入口都验证完整JSON白名单、尺寸/位置、标准floor、count/approximation一致性及起终点安全区；`terrainPreset=custom_boxes`配套`customTerrainBoxes`布局全程传入任务JSON/deployment/ONNX，不降级预设。旧服务无custom_boxes能力时同步按钮报升级提示。
|
||
|
||
## 明确边界
|
||
|
||
- 默认32条水平前向物理射线；显式multi模式为3×16=48条（pitch 0/-20/-45度），**不是真实camera_depth或RGB视觉策略**。PiP是观察窗口，不作为网络输入。低障碍、跌落与切片外障碍存在感知盲区。
|
||
- 配套`boxes-v1`布局直接来自训练器，使用相同世界坐标、半尺寸、摩擦、出生点和目标；`rough/wave/pyramid_stairs`明确为训练专用box近似，不等于编辑器同名高度场。
|
||
- 浏览器对**编译后的**静态训练box `geom_xpos/geom_xmat/geom_size`做解析slab求交，包括地板。它与MuJoCo box几何求交等价；完整机身姿态旋转射线，按命名与group2仅选训练地形，排除整个机器人。不接受额外无限plane、未声明静态几何或非box训练地形。地图组合先用`mj_saveLastXML`展开include，避免原地面残留。
|
||
- 使用原47维本体观测+32归一化距离+2目标误差，共81维；multi改为47+48+2=97维。保持单in-flight、50Hz异步held-action，不阻塞WASM子步。不另加动态观测归一化。导出器Actor内已有归一化。
|
||
- 原Go2自定义地图部署按`go2_constants.py`补齐hip/thigh/calf armature=0.01/0.01/0.02、零关节阻尼/摩擦损失、非足端condim1/priority0、足端condim3/priority1/solimp宽度0.023，碰撞contype1/conaffinity0关闭自碰撞；足端摩擦使用配套地形。旧无自定义地图的Flat路径不覆盖这些参数。
|
||
- 初始关节姿态写入`MjData.qpos`，不改变模型`qpos0`的关节参考角；重置会恢复出生位姿、初始关节、零速度/历史动作及步态时间。
|
||
- 浏览器评测在20秒、机身高度低于0.12m或越界时停止并报错，需重置后重新启用；**不是训练端的接触/姿态终止自动reset**。到达目标不会强制结束episode。
|
||
- 旧`Unitree-Go2-Rough`的234维观测未在浏览器实现，可训练但禁止一键导入。原Flat、Go2-W速度策略、Python控制器、Flat自调参工作台保持兼容。
|
||
- 模型拓扑及PD配置校验不等于动力学完全一致。短PPO和零动作fixture只能验证链路，不能证明避障收敛或Sim2Sim导航成功。
|
||
|
||
## 验证入口
|
||
|
||
```bash
|
||
npm run typecheck
|
||
npm run check
|
||
npm run test:e2e -- web_platform/e2e/obstacle.spec.ts
|
||
# 可选：加载后端1iteration实际导出的模型（无需复制模型进仓库）
|
||
GO2_SMOKE_POLICY=/tmp/go2-obstacle-train-smoke/policy.onnx npm run test:e2e -- web_platform/e2e/obstacle.spec.ts
|
||
```
|
||
|
||
`src/rl/fixtures/obstacleRayGolden.json`保存CPU MuJoCo `mj_ray`参考距离；单测覆盖yaw/pitch/roll、地板命中、box内部/表面/平行/边缘、range边界、miss；真实WASM单测编译Go2碰撞/惯量模型并逐元素验证32条射线。E2E默认模型为`fixtures/obstacle/zero-action.onnx`（测试专用Constant零动作，非训练策略），检查真实浏览器WASM+ORT、地图联动、PiP、射线开关、metadata不一致拒绝。
|
||
|
||
完整后端字段定义见[部署契约](../training_server/OBSTACLE_AVOIDANCE.md)。
|
||
|
||
## Obstacle 自调参
|
||
|
||
自调参工作台新建Session可选Flat或Obstacle，选择Obstacle自动绑定四个专属标量/范围和五项固定客观权重（success .4/time .2/clearance .2/smooth .1/no-fall .1）。目标速度位于`params.target_velocity`，是导航command而非奖励。Approval/Automatic及运行时切换、护栏revision保持兼容，Loss看板不变。
|
||
|
||
从训练面板打开工作台时传递当前任务、seed、terrain/sensor；custom_boxes会先从当前已应用场景自动重新编译并验证，未应用草稿不发送凭据或配置。独立打开时可直接选任务，在“避障场景配置JSON”输入与训练API同构的terrain/sensor配置；服务再次严格验证。自定义地图明确为同一权威地图/自动参考起终点上的三个固定seed重复评估，不冒充三地形。Agent上下文按32/48ray实际模式描述侧后、层间与高度盲区、目标导航、擦碰/绕行/动作抖动约束。
|
||
|
||
Obstacle最佳策略通过ONNX内嵌metadata事务导入，导航速度随部署契约应用（.3–1.2），旧81维.6m/s模型与Flat导入保持原行为。客观评分、成功/碰撞/跌倒定义及3seed串行隔离评估详见[部署契约](../training_server/OBSTACLE_AVOIDANCE.md#obstacle-deepseek-自调参obstacle-v1)。小GPU smoke只验证链路和指标，不代表学会导航。
|
||
|
||
## 多层射线与性能（阶段5）
|
||
|
||
避障高级设置的“传感器模式”可选默认水平32ray/81obs或显式三层48ray/97obs。旧服务未公布multi能力时选项禁用；加载策略以后按metadata动态分配PiP射线，不截断到32条。前47维及heading/π符号不变，Click-to-Navigate目标/面板、Loss曲线、custom_boxes、Obstacle调参速度与Flat保留。旧81 graph不能通过97部署shape校验。
|
||
|
||
**不是局部高程图**：尚无网格/用途定义，本阶段未实现。下倾仍可能漏掉层间矮物、遮挡及坑；标准地图底板会填内部空洞。floor真实命中进入观测，只有multi近障奖励使用已验证标准底板顶面的10微米几何分类过滤，不把floor测距伪装成miss。与floor顶面共面的其他几何无法区分。完整字段、公式和分类限制见[多层契约](../training_server/OBSTACLE_AVOIDANCE.md#显式多层射线阶段5不是局部高程图)。
|
||
|
||
`multiRingGolden.json`来自CPU mj_ray，覆盖全部48条完整姿态、5cm低障碍、有界地板跌落边缘和层序；真实WASM绑定逐元素比对。`multi-zero-action.onnx`为测试Constant零动作97维fixture，非训练策略。真实短训模型可用：
|
||
|
||
```bash
|
||
GO2_MULTI_SMOKE_POLICY=/tmp/go2-multi-ring-stage5/train/policy.onnx npm run test:e2e -- web_platform/e2e/multiRing.spec.ts
|
||
```
|
||
|
||
`src/rl/tasks/raycastBenchmark.ts`导出`benchmarkForwardRays()`：每帧真实调用生产sampleForwardRays与slab，预计算方向/静态box，包含完整48ray全部box求交、姿态旋转和depth/线段分配；不测单ray、不用平均值代替尾延迟。默认25box和257box的16×16最坏数量布局分别warmup3000帧、采样10000帧，逐帧改变姿态/位置，不缓存命中结果。仅报告数量最坏布局，不声称穷尽所有空间排布或整浏览器帧耗时。
|
||
|
||
本机Intel i7-14700F/Ubuntu24.04，Node24.19：25box p50/p95约.019/.020ms，257box约.169/.187ms；HeadlessChromium151（同机，cross-origin-isolated高精度计时）约.015/.020ms与.160/.165ms，测得均低于完整48ray .2ms目标。初版通用旋转slab的257box p95≈.219ms未达标；优化为严格单位旋转快速slab后达标，保留原日志。不隔离浏览器计时分辨率约.1ms，p95量化为.2ms，不能用该读数证明严格小于目标；高精度基准不改变生产隔离/时序配置。
|
||
|
||
结果随硬件、GC、浏览器调度变化，不是实时保证；只测解析感知，不含渲染/ORT/物理步。复现打包脚本、Node/浏览器原始分位数与硬件说明位于`/tmp/go2-multi-ring-stage5/run_benchmark.mjs`及`perf-*.json`；日志与独立阶段incremental.diff同目录，后续review可直接读取。
|
||
|
||
## 复审修复：preset与导航拖动
|
||
|
||
Flat奖励菜单只展示服务根据来源session确认`taskId=Unitree-Go2-Flat`的preset；Obstacle及未声明身份项不展示。历史Flat的任务身份由服务恢复并完整验证schema，跨任务/损坏preset在创建作业前返回400，不推迟到训练器失败。旧服务没有返回任务身份时需升级服务才能使用这些preset；不增加Obstacle普通训练preset入口。
|
||
|
||
设定导航目标时超过5px即永久标记本次手势为拖动，即使返回起点也不会设置目标；画布外的同pointer移动也记录。pointercancel、Esc、失焦、退出模式、clear/dispose会清空手势。取消后旧pointerup不生效，重新按下的正常点击仍可设定。
|