第 10 章 案例与排障¶
两条端到端链路把前九章的机制串起来，再沉淀一份"装不上、跑不动、训不对、迁不过去"时按序排查的清单。两个案例走 Newton/MJWarp 后端 + RSL-RL 这条链路；排障条目按症状分类，并标出哪些边界需要完整 Isaac Sim 才能触及。
1. 端到端案例（一）：摆杆到收敛并导出¶
一条把建模、训练、评估、导出、部署时延打通的完整线，每段都对应前面章节给出的接口与判据：
| 阶段 | 命令要点 | 产物 |
|---|---|---|
| 自检 | 导入 + physics=newton_mjwarp 起一代仿真（第 1 章） |
后端可用、场景构建无异常 |
| 训练 | isaaclab train --task Isaac-Cartpole-Direct-v0 --num_envs 1024 --max_iterations 300 --viz none（第 5 章） |
回报随迭代上升、episode 长度涨到上限、成功率收敛 |
| 评估 | isaaclab play --checkpoint model_299.pt --num_envs 256 --viz none（第 8 章） |
载入 checkpoint 并持续 rollout |
| 导出 | play 内触发，写 exported/policy.{pt,onnx}（第 8 章） |
TorchScript 与 ONNX 两份推理产物 |
| 部署时延 | torch.jit.load 单环境前向（第 8 章） |
单步前向远小于 50–500 Hz 控制周期 |
链路的价值在于每段的输入输出都有明确出处：换 Isaac-Cartpole-Direct-v0 为任一内置任务，命令链完全同构，只是任务配置换文件。
2. 端到端案例（二）：四足平地行走起步¶
四足速度跟踪是 Isaac Lab 的招牌任务。在不装 Isaac Sim 的 Newton/MJWarp 后端上，isaaclab train --rl_library rsl_rl --task Isaac-Velocity-Flat-Unitree-Go2-v0 --num_envs 64 --max_iterations 1 --viz none physics=newton_mjwarp 能正常起步：资产（Unitree Go2）经 S3 自动拉取、环境搭建完成，一代内即输出回报与速度误差指标（error_vel_xy / error_vel_yaw）。
Manager-Based 的 locomotion 任务因此不必先装完整 Isaac Sim 就能离屏训练，后端切换不改变任务配置的写法。
要训到能走，需把 num_envs 提到第 4 章预算内的规模、迭代数拉长，并按第 6 章配好奖励项与（粗糙地形版的）地形课程 Isaac-Velocity-Rough-*。四足训到稳定行走的完整收敛曲线耗时较长，属可扩展项。
3. 版本与安装错配排障¶
装不上，绝大多数是配对与环境，不是代码：
- 导入即报模块不存在 / 扩展加载失败：优先查版本配对。Isaac Lab 3.0.0 只配 Isaac Sim 6.2.0.0，5.1 及更早不受支持（第 1 章）。跨小版本混装（如 2.x 的
isaaclab.sh --conda老流程配 6.x）会让包路径与扩展布局对不上。 --extra isaacsim装不上 / 大 wheel 反复超时：files.pythonhosted、pypi.nvidia.com直连吞吐可能极低，uv对大文件不续传。解法是配可达代理并同时设大小写两组代理环境变量（HTTPS_PROXY与https_proxy），否则uv仍可能走直连（第 1 章）。- 驱动/系统下限：isaacsim 轮子要 GLIBC 2.35+（Ubuntu 22.04 恰好满足）；文档推荐 Linux x86_64 驱动 595.58.03，但 PyTorch cu130 对 Blackwell 的有效下限更低，580 系列驱动上 Newton 路径可用（第 1 章）。显卡驱动安装与 GPU 观测手段见
linux-note第 5 章「桌面、显示与显卡驱动」 与 第 8 章「性能观测工具链」。 - conda 与 uv 混用：3.0 默认
uv管环境，isaaclab.sh已降为转发到isaaclabCLI 的薄壳（第 1 章）；把老的 conda 建环境流程硬套到 3.0 上易踩解释器/环境变量冲突。
判据：跨后端先对约定
重力、单位、关节顺序与执行器符号是迁移时最常见的静默错位；换后端或从别的仿真器迁入，先逐项对约定再谈训练。
4. 运行时与显存排障¶
- CUDA out of memory：先降
num_envs，再看是不是相机/点云观测在吃显存——带相机的任务单环境足迹大，num_envs上调空间远小于无相机任务（第 4 章的预算式：每环境足迹 × num_envs ≤ 可用显存）。 - 首代巨慢、之后才快：第一代含 CUDA graph 编译与 kernel 预热，吞吐读数要看稳态代而非首代（第 4 章）。
- 训练中途 reward 变 NaN/Inf：向量化下一处发散污染全批（第 4 章）——查
sim.dt是否过大、有无穿透深碰撞或未限幅的关节速度，从源头设界而非逐环境检查。
4.1 NaN 的定位顺序¶
单个 NaN 就能吞掉整批统计，这是向量化训练的常态而非罕见：批均值与标准差在出现一个非有限值后整体变成 nan，有限值占比则只从 100% 略微下降——统计量已经失效，却看不出是哪一路量出的事。
| 状态 | 批均值 | 批标准差 | 有限值占比 |
|---|---|---|---|
| 健康批次 | 收敛值 | 收敛值 | 100% |
| 出现一个非有限值 | nan |
nan |
略低于 100% |
bad_env = np.where(~np.isfinite(reward).all(axis=1))[0] # 先按环境维筛出污染环境
first_step = np.argmax(~np.isfinite(reward[bad_env[0]])) # 再沿步维定位首个非有限步
判据：每代做一次有限性检查并记录（环境、步、量名）三元组。少数环境出错就足以让整批 loss 变成 nan，而逐环境打印在向量化规模下不可行——先按环境维定位、沿步维回溯物理量，是唯一可行的顺序。
单个 NaN 的定位与恢复顺序：
flowchart TD
bad["批统计突变：均值/标准差变 nan"] --> isf["isfinite 掩码<br/>按环境维筛出失效环境"]
isf --> back["沿步维回溯<br/>首个非有限步的动作与接触"]
back --> rec["记录（环境、步、量名）三元组"]
rec --> reset["按环境单独 reset<br/>不整批重启"]坑：NaN 定位按环境维再按步维
单个 NaN 就能让整批统计失效；先 isfinite 掩码按环境筛出污染项，再沿步维回溯首个非有限步的动作与接触，最后只 reset 坏环境。
5. 建模与约定坑¶
跨后端、从别的仿真器迁移时，最容易静默出错的是约定不一致：
- 四元数顺序：Isaac Lab 3.0 用 (x, y, z, w)，identity 是
(0, 0, 0, 1)（w 在末位）。从 wxyz 习惯（如老版本或某些工具）平移时若不换算，初始姿态会莫名翻转——第 2 章的init_state.rot即按此序。 - 单位：关节角、角速度一律弧度制；URDF 里以度标注的关节限位导入要确认已转弧度。
scale/use_default_offset决定动作是"相对默认角的增量"还是绝对目标（第 3 章），配错会让策略动作整体偏移。 - 资产路径与命名空间：随环境克隆的实体必须挂
{ENV_REGEX_NS}，全局实体才挂/World（第 2 章）；远程资产经 S3 提供自动拉取。URDF Importer 3.0 已移除convert_mimic_joints_to_normal_joints等旧选项，沿用会告警。 - 后端属性类不通用：物理属性覆写类分
PhysxRigidBodyPropertiesCfg/NewtonRigidBodyPropertiesCfg/MujocoRigidBodyPropertiesCfg，physics=换后端要换对应类，挂错静默失效（第 4 章）；随机化字段同理（第 6 章：Newton 仅单一摩擦系数）。 - 观测顺序/尺度：真机部署拼观测向量必须与训练期
policy组逐维同序同尺度，错位即失灵（第 9 章）。
6. 要点¶
- 两条端到端链路：cartpole-direct 走完"训练→评估→导出→推理时延"全程（回报收敛、两份推理产物、单步前向远低于控制周期）；四足 go2 平地速度任务在 Newton 后端可离屏起步（无需先装 Isaac Sim）。
- 装不上先查配对（Isaac Sim ≤5.1 不支持、GLIBC 2.35、uv+代理双大小写变量），显卡驱动与 GPU 观测回引 linux-note 第 5、8 章。
- 跑不动查显存预算（相机是主因）与首代编译预热；reward 变 NaN 从
sim.dt/限幅在源头设界，勿逐环境查。 - 约定坑以"静默失效"为特征：四元数 (x,y,z,w) 序、弧度单位、
{ENV_REGEX_NS}与资产路径、后端属性类不通用、观测逐维同序——迁移前逐项核对。 - 四足完整收敛曲线、PhysX 路径的仿真表现与 ROS 2 / LEAPP 的端到端部署，按各自版本的文档与发布说明核对；覆盖范围是 Newton + RSL-RL 这条链路。