导航使机器人能够将感知和运动转化为有目的的自主性。与产生稳定运动的运动不同，导航必须用于不断定位机器人、解读不断变化的环境、选择路线，并避开障碍物以安全到达目标。
将此功能迁移到新的机器人或场景可能需要新的数据、仿真资产、机器人接口、训练、诊断和评估。为每个机器人场景对重复这项工作不仅成本高昂，而且难以重现。
智能体驱动的工作流可减轻这种负担。开发者定义机器人、场景源和导航目标。编码智能体使用存储库技能来验证依赖项、准备素材、运行烟雾测试、启动训练、诊断故障和比较检查点。人类审批门控制场景接受度、单一环境烟雾测试和检查点推广。
此博文教程使用 Spot 作为参考机器人，将代理驱动的 COMPASS 工作流应用于内置场景和 SAGE-10K 场景，同时展示了 NVIDIA Omniverse NuRec 如何支持捕获的环境。它通过烟雾测试、残差训练、检查点评估和运行时集成 (包括可选的测距) 来遵循策略工作流。
COMPASS 是什么？
COMPASS (通过残差 RL 和技能合成实现的跨具身移动性策略) 是一个统一的框架，可通过单个具身的专家演示实现可扩展的跨具身移动性。它重复使用预训练的 NVIDIA X-Mobility 策略中的导航行为。它训练残差专家，这是一种 强化学习 (RL) 策略，用于纠正选定机器人和环境的基本动作，而不是从一开始就重新学习导航。来自多个专家的数据稍后可以蒸到共享的跨具身策略中。
图 1 显示了此智能体驱动工作流训练和评估的 COMPASS 策略架构。
COMPASS 将此开发工作流程打包成资源库技能。本教程在开发期间使用 Codex。经过训练的策略和机器人控制器在运行时执行导航，而无需编码代理。
参考工作流程概述
参考工作流使用 Boston Dynamics Spot 四足模型。内置仓库是可重现的主要路径，SAGE-10K 将其扩展到生成的场景，而 NVIDIA Omniverse NuRec 为重建的目标环境提供了可选路径。NVIDIA cuVSLAM 是一个由 CUDA 加速的视觉测距以及同步定位和地图构建库，可在机器人尚未提供兼容的测距和变换时提供部署测距。
对于其他环境，请使用存储库固定的 COMPASS 软件堆栈和以下硬件指南：
- 至少 Linux 驱动程序 580.95.05 的 Ubuntu 22.04 或 24.04 系统、至少 16 GB VRAM 的支持 RTX 的 NVIDIA GPU 以及 Linux 驱动程序 580.95.05 (该版本已针对 Isaac Sim 6.0 进行测试) 。Isaac Sim 6.0 的最低参考 GPU 是 GeForce RTX 4080。安装前运行 Isaac Sim 兼容性检查器。
- 配备 NVIDIA 容器工具包的 Docker Engine 24 或更高版本。
- A Hugging Face 账户和读取令牌，以及对 NVIDIA/ COMPASS 和 NVIDIA/ X-Mobility Hugging Face 资源库的访问权限。
- 测试教程堆栈：采用 NVIDIA Isaac Sim 6.0 的 NVIDIA Isaac Lab 3.0。
第 1 步：设置 COMPASS 智能体工作流
首先，在开始场景工作之前，准备资源库并为编码代理提供清晰的工作流程合同。您将下载门控素材，在 Codex 中发现 COMPASS 技能，运行堆栈检查，并在 one-environment 审批门处停留。所有 $compass 块都是 COMPASS 库根目录下 Codex 聊天的可复制提示，而非 shell 命令。在克劳德代码中，为同一工作流使用 /compass。
对于 Codex，首先在 .agents/skills 下展示存储库技能，然后选择 COMPASS with /skills 或在提示词中提及 $compass。Codex 支持符号链接技能目录，因此当前资源库技能可以保留在其维护的位置。对于克劳德代码，请使用 /compass 调用相同的工作流。
mkdir -p .agents/skills
ln -s ../../.claude/skills/compass .agents/skills/compass
ln -s ../../.claude/skills/compass-doctor .agents/skills/compass-doctor
ln -s ../../.claude/skills/compass-newembodiment .agents/skills/compass-newembodiment
编码智能体可以克隆、构建、下载非机密资产，并验证堆栈。开发者必须接受门控存储库条款，并在聊天外部输入 Hugging Face 令牌。智能体不应在日志中请求、显示或存储令牌。
安装 COMPASS 并下载素材
克隆COMPASS 存储库，并按照COMPASS 手册的要求使用存储库固定容器快速入门。在首次运行之前，接受对门控nvidia/ COMPASS和nvidia/ X-Mobility Hugging Face 资源库的访问权限，创建Hugging Face 读取令牌，并确认其可以读取您账户可用的公共门控资源库。仅在当前 shell 中显示令牌。请勿将其粘贴到智能体提示词中，或将其提交至源控制。
export HF_TOKEN=hf_xxx
./docker/run.sh assets
./docker/run.sh build
source ./docker/activate
“Assets” (素材) 步骤会将已注册的模拟素材下载到 ./assets/usd/，并将预训练的 X-Mobility 检查点文件 下载到 ./assets/x_mobility.ckpt。401 或 403 响应通常表示存储库访问或令牌范围不完整。在调试 Isaac Lab 之前解析身份验证。
在下一阶段开始之前，每个阶段都会产生可审查的证据：
- 验证： 软件和资产库存、环境报告和烟雾测试日志
- 场景准备：已注册的场景配置、占用地图和视觉检查证据
- 训练： 固定命令和配置、日志、遥测和定期检查点
- 评估：匹配协议、标准 COMPASS 指标、视频和促销推荐
- 软件包： 已批准的检查点、配置、评估记录和构件清单
审批标准因项目而异，但每个门都应该回答同一个问题：是否存在所需的输入、是否出现预期的输出、是否存在未解决的错误，以及是否有足够的证据可以继续？
调用 COMPASS 技能
容器激活后，打开存储库根的编码代理，并描述机器人、场景、导航结果和审批门。对于基准工作流，请将此提示复制到智能体聊天中：
$compass Validate the COMPASS environment for Spot. Confirm the pinned
repository revision, container, GPU, Isaac Lab and Isaac Sim versions,
simulation assets, and pretrained X-Mobility checkpoint. Run a one-environment
smoke test, save the validation report, and stop for approval.
$compass 技能会根据资源库检查请求的工作流程，并运行相关验证步骤。如果运行失败，$compass-doctor 将执行只读运行状况检查并报告可能的原因，而不会悄无声息地改变环境。
第 2 步：选择并准备导航场景
本节将介绍如何选择和准备三种场景源之一：内置 SAGE-10K 场景或使用 Omniverse NuRec 渲染的已捕获环境。您将了解每条路径的用途，以及在训练之前必须完成哪些注册、占用地图和审批检查。
路径 1：使用内置仓库
从已注册的 combined_multi_rack 仓库开始，获得最快的可复制基准。机器人、场景和占用地图均已注册，因此这是在引入新场景之前验证安装的最佳路径。
将以下提示复制到编码代理以运行基准，并在烟雾测试后暂停：
$compass Train and evaluate Spot in the built-in combined_multi_rack warehouse.
Stop after the one-environment smoke test for approval.
combined_multi_rack 仓库中导航路径 2：使用 SAGE-10K 场景
SAGE-10K 数据集包含 50 种房间类型生成的 10000 个室内场景。它是一个场景数据集，而非策略或模拟器。每个场景都提供几何图形、材质、布局元数据和预览。客厅和仓库场景遵循相同的准备路径，因此请选择一个合适的候选项，而不是下载整个数据集。
SAGE-10K 路径包括两个人工审批门。首先，在 NVIDIA Isaac Sim 中检查转换后的 USD，并在注册前确认几何图形、材质、比例和碰撞网格。完成注册和占用地图生成后，在进行完整训练之前批准单一环境预览。占用地图可识别有效机器人启动和导航目标的可用空间和阻塞空间。
将以下提示复制到编码代理中，以将场景入围，并在两个门处暂停：
$compass Find suitable SAGE-10K living-room or warehouse scenes for Spot and show the best candidates.
After I approve a scene, convert and register it, generate and verify its occupancy map, and stop for inspection.
After I approve the scene and map, run a one-environment smoke test and stop again before full training.
路径 3：使用 NuRec 介绍已捕获的环境
当目标是在预期部署环境的重建中微调和评估 COMPASS 时，请使用 Omniverse NuRec。NuRec 通过对齐的视觉几何图形、碰撞网格和可选的场景增强，将立体 RGB 截取转换为支持 Isaac Sim 的重建。所记录的 COMPASS 路径可注册渲染的场景，验证其提供的占用地图和起源规范，检查机器人间隙，并在训练前运行单一环境烟雾测试。
就本文而言，NuRec 是可选路径。实践训练流程将继续使用 SAGE-10K，以便教程遵循从准备到评估的一个场景。对于已捕获的环境，请使用 COMPASS NuRec 工作流 和 NVIDIA Isaac Sim NuRec 指南 (包括 客厅示例) 进行场景准备、训练、评估、导出和 ROS 2 部署。
将以下提示复制到编码代理中，以准备已注册的 NuRec 场景，并在训练前暂停：
$compass Prepare the registered NuRec Real2Sim scene <scene_name> for <supported_robot>.
Verify the supplied occupancy map and origin convention, inspect collisions and robot clearance,
run a one-environment smoke test, and stop for approval before training.
第 3 步：验证机器人场景集成
将所选场景提供给 COMPASS 后，在扩展训练之前运行单环境预览。对于 SAGE-10K 场景，请先完成早期视觉检查和场景注册审批门。确认 Isaac Sim 已启动、场景已加载、Spot 已在有效位置生成、摄像头观察结果可用，且机器人对策略命令做出响应，且不会出现裁剪、掉落或未解决的仿真错误。
指示编码智能体总结预览日志和视觉证据，识别任何障碍，并停止等待人类批准。只有在场景、机器人、观察结果和动作界面按预期协同工作后，才能继续进行残差训练。
第 4 步：训练残差专家
本节将介绍 COMPASS 如何根据所选机器人和场景调整预训练的 X-Mobility策略。您将启动残差强化学习、监控运行、保存候选检查点，并保留评估所需的证据。
启动残差训练
在单一环境烟雾测试获得批准后，编码智能体可以启动标准的残差 RL 工作流。以下命令使用 Spot 和内置仓库。在遵循生成的场景路径时，将环境密钥替换为已注册的 SAGE-10K 场景。
烟雾测试获得批准后，编码智能体可以启动标准残差 RL 工作流。以下示例运行内置仓库基准。继续生成场景路径时，将环境密钥替换为已注册的SAGE-10K场景。
python run.py \
-c configs/train_config.gin \
-o ./outputs/spot_combined_multi_rack \
-b ./assets/x_mobility.ckpt \
--enable_cameras \
--embodiment spot \
--environment combined_multi_rack
管理训练过程
残差训练是一个漫长的过程。编码代理应在持久会话或托管调度程序中运行，将日志和检查点写入配置的输出目录，并在不保持交互式会话打开状态的情况下报告进度。
训练前，请记录命令、存储库修订、场景关键帧、配置、检查点间隔和停止标准。如果运行被中断，请验证最新的检查点是否已完成，并确认支持的恢复选项，然后再继续。
监控训练并保存检查点
根据可用的 GPU 显存设置 --num_envs，仅使用一个环境进行烟雾测试。在训练期间，监控奖励组件、目标进度、接触和跌倒、情节终止、吞吐量和 GPU 显存。
保存定期检查点，并在匹配的条件下对其进行评估，而不是假设最终迭代为最佳。COMPASS 还支持分布式多 GPU 训练，以实现更大规模的运行。训练时间因硬件、场景复杂性、环境数量和停止标准而异。
诊断故障并保留证据
在更改环境或训练配置之前，使用 COMPASS 诊断工作流调查故障。将身份验证错误路由到 Hugging Face 访问检查，将场景加载或碰撞错误路由到场景准备，将摄像头或动作接口错误路由到烟雾测试阶段，将内存错误路由到环境计数或多 GPU 配置。
保留训练配置、命令、存储库修订版、场景注册、占用地图、烟雾测试证据、日志、检查点和构件清单。在更改依赖项、场景素材、奖励或训练设置之前，需要获得开发者批准。
第 5 步：在推广检查点之前进行评估
本节将介绍如何确定残差检查点是否可用于推广。您将了解如何在匹配条件下比较预训练的基础策略和候选残差，解释标准 COMPASS 指标，标记任何衍生证据，并在打包前获得人工批准。
评估任务性能和安全性。标准 COMPASS 评估报告目标达到率、下降率和行程时间。其他证据，如目标进度、接触行为、超时或命令稳定性，应标记为衍生分析或自定义仪器。只有在匹配的证据满足项目的导航和安全要求，并且包装得到人工批准后，才能推广检查点。
以下提示就是一个示例。根据工作流程所需的机器人、场景、检查点和证据进行调整：
$compass Compare the pretrained X-Mobility base policy with the available Spot
residual checkpoints in the selected scene under matched seeds, goals, initial states,
rollout length, and active terminations. Report the standard COMPASS evaluation metrics,
save matched videos and the exact evaluation command, clearly label any derived evidence,
and stop for human approval before promoting or packaging a checkpoint.
第 6 步：将策略连接到机器人运行时
本节将解释如何在开发完成后将经过训练的策略连接到机器人运行时。您将学习参考策略输入和输出、何时 cuVSLAM 可以提供部署里程计，以及何时未注册的机器人需要 新的具身工作流。编码智能体负责协调开发和验证；它不会在运行时控制机器人。
了解策略的输入和输出
COMPASS 素材步骤下载用于烟雾测试和残差训练的预训练 X-Mobility 检查点。训练会为所选机器人和场景创建残差检查点。导出和部署将经过训练的策略打包用于推理；它们不会将基础和残差公开为开发者必须手动连接的两个 ROS 2 组件。
在参考 ROS 2 集成中，compass_inference可将前置摄像头图像、导航目标或路线以及根据测距得出的机器人速度转换为导出的策略输入。它在/cmd_vel上发布前向线性和角速度命令。循环状态和先前操作是推理实现的内部操作，而非外部 ROS 集成输入。验证目标部署的坐标帧、更新率、归一化、命令限制、停止行为和物理机器人控制器。
需要时添加 cuVSLAM 测距
如果部署的机器人需要在 GPS 拒绝或 GPS 间歇环境中进行基于摄像头的状态估计，并且尚未提供兼容、经过验证的测距和变换，则可使用 cuVSLAM 库。其里程计可以支持 COMPASS 导航器，但其地图不是导航策略的输入。
cuVSLAM 不是 COMPASS 策略训练的一部分，不需要智能体技能。将其作为单独的、版本匹配的 ROS 2 组件运行，将其里程计输出连接或重新映射到 /chassis/odom，提供所需的 odom-to-base_link transform，并验证校准、时间、主题名称和帧约定。可选的 $cuvslam-onboard 和 $cuvslam-troubleshoot 技能有助于在开发期间配置和诊断此状态估计组件。
示例提示：
$cuvslam-onboard Configure cuVSLAM as the odometry source for the COMPASS
navigator on <robot and camera rig>. Select a compatible release and tracking mode,
validate calibration and timestamps, connect odometry and TF to the expected COMPASS
interfaces, and stop for approval before enabling navigation.
将工作流程扩展到另一个机器人
对于未注册的机器人，$compass-newembodiment 可指导开发者完成机器人配置、环境注册、动作映射和单环境视觉烟雾测试。引入新的具身是一项单独的工程任务，不同于为现有机器人训练专家，但它使用相同的验证和批准模式。
本教程将在“Checkpoint” (检查点) 评估阶段结束。导出到 ONNX、JIT 或 TensorRT、ROS 2 集成和物理硬件部署需要针对目标机器人和运行时进行单独验证。场景质量、训练时长和检查点性能因实施、环境、奖励设计和可用计算而有所不同，因此该工作流并未定义通用的成功值。
开始使用 COMPASS
从参考路径开始，然后一次扩展一个组件：
- 设置参考环境。克隆COMPASS 资源库，遵循COMPASS 手册快速入门，接受门控模型术语，并下载COMPASS 模拟资源和X-Mobility 检查点。
- 运行代理式工作流。使用支持的机器人和内置场景在 Codex 中调用
$compass，在烟雾测试后保留批准，并在匹配的条件下训练和评估专家。 - 刻意扩展和打包。对未注册的机器人使用
$compass-newembodiment。保存下一个工程决策所需的配置、检查点、日志、匹配的评估结果和视频。
要重现和扩展工作流程，请查看以下资源：
