내비게이션은 로봇이 인지 능력과 운동 능력을 유용한 자율성으로 전환할 수 있도록 지원합니다. 안정적인 이동 자체를 생성하는 보행(Locomotion)과 달리, 내비게이션은 목표 지점에 안전하게 도달하기 위해 로봇의 위치를 지속적으로 추정하고, 변화하는 주변 환경을 해석하며, 경로를 선택하고, 장애물을 회피해야 합니다.
이러한 기능을 새로운 로봇이나 씬(Scene)에 적용하려면 새로운 데이터, 시뮬레이션 자산, 로봇 인터페이스, 학습, 진단, 평가 작업이 수반될 수 있습니다. 로봇과 씬 조합이 바뀌시마다 이 과정을 반복하는 것은 비용이 많이 들고 재현하기도 어렵습니다.
에이전트 기반 워크플로우는 이러한 부담을 줄여줍니다. 개발자가 로봇, 씬 소스, 내비게이션 목표를 정의하면, 코딩 에이전트는 리포지토리 스킬을 사용하여 종속성을 검증하고, 자산을 준비하며, 스모크 테스트를 실행하고, 학습을 개시하며, 오류를 진단하고, 체크포인트를 비교합니다. 개발자의 승인 단계를 통해 씬 채택, 단일 환경 스모크 테스트, 체크포인트 최종 승인을 제어합니다.
본 튜토리얼은 Spot을 레퍼런스 로봇으로 사용하여 에이전트 기반 COMPASS 워크플로우를 내장 씬 및 SAGE-10K 씬에 적용하는 방법을 설명하며, NVIDIA Omniverse NuRec이 캡처된 환경을 어떻게 지원하는지 함께 소개합니다. 스모크 테스트, 잔차 학습(Residual training), 체크포인트 평가, 그리고 오도메트리 옵션을 포함한 런타임 통합에 이르기까지 정책 워크플로우 전반을 다룹니다.
COMPASS란 무엇인가?
COMPASS(Cross-Embodiment Mobility Policy via Residual RL and Skill Synthesis)는 단일 임바디먼트의 전문가 시연 데이터를 활용해 확장 가능한 크로스 임바디먼트 이동성을 구현하는 통합 프레임워크입니다. 이 프레임워크는 사전 학습된 NVIDIA X-Mobility 정책의 내비게이션 동작을 재사용합니다. 처음부터 내비게이션을 다시 학습하는 대신, 선택한 로봇과 환경에 맞게 기본 동작을 보정하는 강화학습(RL) 정책인 잔차 전문가(Residual specialist)를 학습시킵니다. 추후 여러 전문가로부터 수집된 데이터는 하나의 공유 크로스 임바디먼트 정책으로 증류(Distill)될 수 있습니다.
에이전트 기반 워크플로우가 학습 및 평가하는 COMPASS 정책 아키텍처는 그림 1에 제시되어 있습니다.
COMPASS는 이러한 개발 워크플로우를 리포지토리 스킬로 패키지화합니다. 본 튜토리얼에서는 개발 과정에 Codex를 활용합니다. 학습을 마친 정책과 로봇 컨트롤러는 코딩 에이전트 없이 런타임 환경에서 내비게이션을 수행합니다.
레퍼런스 워크플로우 개요
레퍼런스 워크플로우는 Boston Dynamics의 사족 보행 로봇 Spot을 사용합니다. 내장된 물류창고 씬은 재현 가능한 기본 경로로 사용되며, SAGE-10K는 이를 생성된 씬으로 확장하고, NVIDIA Omniverse NuRec은 재구성된 타깃 환경을 위한 선택적 경로를 제공합니다. CUDA 가속 비주얼 오도메트리 및 SLAM 라이브러리인 NVIDIA cuVSLAM은 로봇이 호환 가능한 오도메트리와 변환(Transform) 데이터를 제공하지 않을 때 배포용 오도메트리를 제공할 수 있습니다.
다른 환경을 구성하려면 리포지토리에 고정된 COMPASS 소프트웨어 스택과 다음 하드웨어 지침을 참고하십시오:
- 최소 32GB RAM, 최소 16GB VRAM을 갖춘 RTX 지원 NVIDIA GPU, Isaac Sim 6.0 검증 버전에 해당하는 Linux driver 580.95.05가 설치된 Ubuntu 22.04 또는 24.04 시스템. Isaac Sim 6.0의 최소 레퍼런스 GPU는 GeForce RTX 4080입니다. 설치 전 Isaac Sim 호환성 검사기를 실행해 확인하시기 바랍니다.
- NVIDIA Container Toolkit이 포함된 Docker Engine 24 이상 버전.
- nvidia/COMPASS 및 nvidia/X-Mobility Hugging Face 리포지토리에 접근 권한이 있는 Hugging Face 계정 및 읽기 토큰.
- 검증된 튜토리얼 스택: NVIDIA Isaac Sim 6.0 기반 NVIDIA Isaac Lab 3.0.
1단계: COMPASS 에이전틱 워크플로우 설정
씬 관련 작업을 시작하기 전, 리포지토리를 준비하고 코딩 에이전트에 명확한 워크플로우 계약을 부여합니다. 접근 권한이 제한된 자산을 다운로드하고, COMPASS 스킬을 Codex에서 탐색할 수 있도록 설정하며, 스택 검사를 실행한 후 단일 환경 승인 게이트에서 대기합니다. 모든 $compass 블록은 쉘 명령어가 아닌 COMPASS 리포지토리 루트의 Codex 채팅용 복사 가능 프롬프트입니다. Claude Code에서는 동일한 워크플로우에 /compass를 사용합니다.
Codex의 경우 먼저 .agents/skills에 리포지토리 스킬을 노출한 뒤 /skills로 COMPASS를 선택하거나 프롬프트에서 $compass를 언급합니다. Codex는 심볼릭 링크 스킬 디렉토리를 지원하므로 현재 리포지토리 스킬을 기존 위치에 그대로 유지할 수 있습니다. Claude Code에서는 /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 읽기 토큰을 생성한 뒤 계정에서 사용할 수 있는 공개 제한 리포지토리를 읽을 수 있는지 확인합니다. 토큰은 현재 쉘에만 노출하고, 에이전트 프롬프트에 붙여넣거나 소스 제어에 커밋하지 마십시오.
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을 디버깅하기 전에 인증을 먼저 해결하십시오.
각 단계는 다음 단계가 시작되기 전에 검토 가능한 증거를 생성합니다:
- 검증: 소프트웨어 및 자산 목록, 환경 보고서, 스모크 테스트 로그
- 씬 준비: 등록된 씬 구성, 점유 지도(Occupancy map), 육안 검사 증거
- 학습: 고정된 명령어 및 구성, 로그, 원격 측정 데이터, 주기적 체크포인트
- 평가: 일치하는 프로토콜, 표준 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단계: 내비게이션 씬 선택 및 준비
이 섹션에서는 내장 COMPASS 물류창고, 생성된 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.
경로 2: SAGE-10K 씬 사용
SAGE-10K 데이터셋은 50개 방 유형에 걸친 1만 개의 생성된 실내 씬을 포함합니다. 이는 정책이나 시뮬레이터가 아닌 씬 데이터셋입니다. 각 씬은 형상, 재질, 레이아웃 메타데이터, 미리보기를 제공합니다. 거실과 물류창고 씬은 동일한 준비 과정을 거치므로 전체 데이터셋을 다운로드하는 대신 적합한 후보 하나를 선택합니다.
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 경로는 렌더링된 씬을 등록하고, 제공된 점유 지도와 원점 규격을 검증하며, 로봇의 이격 공간(Clearance)을 검사한 후 학습 전 단일 환경 스모크 테스트를 실행합니다.
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이 유효한 위치에 생성되는지, 카메라 관측 데이터를 활용할 수 있는지, 로봇이 핑트림(Clipping), 낙하, 해결되지 않은 시뮬레이션 오류 없이 정책 명령에 반응하는지 확인합니다.
코딩 에이전트에 명령하여 미리보기 로그와 시각적 증거를 요약하고, 차단 요인(Blocker)을 식별하며, 개발자 승인을 위해 정지하도록 합니다. 씬, 로봇, 관측 데이터, 액션 인터페이스가 예상대로 함께 작동하는 것을 확인한 후에만 잔차 학습으로 진행합니다.
4단계: 잔차 전문가 학습
이 섹션에서는 COMPASS가 사전 학습된 X-Mobility 정책을 선택한 로봇과 씬에 적응시키는 방법을 설명합니다. 잔차 강화학습을 개시하고, 실행 과정을 모니터링하며, 후보 체크포인트를 저장하고, 평가에 필요한 증거를 보존합니다.
잔차 학습 개시
단일 환경 스모크 테스트가 승인되면 코딩 에이전트는 표준 잔차 RL 워크플로우를 개시할 수 있습니다. 다음 명령어는 Spot과 내장 물류창고를 사용합니다. 생성된 씬 경로를 따르는 경우 환경 키를 등록된 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단계: 체크포인트 최종 승인 전 평가
이 섹션에서는 잔차 체크포인트가 승인(Promotion)할 준비가 되었는지 판단하는 방법을 설명합니다. 동일 조건하에서 사전 학습된 베이스 정책과 잔차 후보를 비교하는 방법, 표준 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 토픽을 통해 전진 선속도 및 각속도 명령을 발행합니다. 순환 상태(Recurrent state)와 이전 액션은 추론 구현 내부의 요소이며, 외부 ROS 통합 입력이 아닙니다. 타깃 배포 환경에 대해 좌표계, 업데이트 주기, 정규화, 명령어 제한, 정지 동작, 물리 로봇 컨트롤러를 검증하십시오.
필요시 cuVSLAM 오도메트리 추가
배포된 로봇이 GPS가 차단되거나 불안정한 환경에서 카메라 기반 상태 추정이 필요하고, 호환 가능하며 검증된 오도메트리 및 변환 데이터를 제공하지 않는 경우 cuVSLAM 라이브러리를 사용합니다. cuVSLAM의 오도메트리는 COMPASS 내비게이터를 지원할 수 있지만, 해당 지도가 내비게이션 정책의 입력으로 사용되는 것은 아닙니다.
cuVSLAM은 COMPASS 정책 학습의 일부가 아니며 에이전트 스킬이 필요하지 않습니다. 버전에 맞는 별도의 ROS 2 컴포넌트로 실행하고, 오도메트리 출력을 /chassis/odom에 연결하거나 리매핑하며, 필요한 odom-to-base_link 변환을 제공하고, 캘리브레이션, 타임스탬프, 토픽 이름, 좌표계 규격을 검증하십시오. 선택 사항인 $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가 개발자에게 로봇 구성, 환경 등록, 액션 매핑, 단일 환경 시각적 스모크 테스트 과정을 안내합니다. 새로운 임바디먼트를 온보딩하는 것은 기존 로봇을 위한 전문가를 학습시키는 것과는 별개의 엔지니어링 작업이지만, 동일한 검증 및 승인 패턴을 사용합니다.
본 튜토리얼은 체크포인트 평가 단계에서 마무리됩니다. ONNX, JIT, TensorRT로의 엑스포트, ROS 2 통합, 물리 하드웨어 배포는 타깃 로봇과 런타임에 대한 별도의 검증이 필요합니다. 씬 품질, 학습 시간, 체크포인트 성능은 임바디먼트, 환경, 보상 설계, 사용 가능한 연산 자원에 따라 달라지므로 워크플로우에서 단일한 성공 기준을 정의하지는 않습니다.
COMPASS 시작하기
레퍼런스 경로로 시작한 뒤 한 번에 하나의 컴포넌트씩 확장해 보십시오:
- 레퍼런스 환경 설정: COMPASS 리포지토리를 복제하고, COMPASS 핸드북의 빠른 시작 안내를 따르며, 모델 이용 약관에 동의하고, COMPASS 시뮬레이션 자산 및 X-Mobility 체크포인트를 다운로드합니다.
- 에이전틱 워크플로우 실행: 지원되는 로봇 및 내장 씬을 지정하여 Codex에서
$compass를 호출하고, 스모크 테스트 후 승인 단계를 거쳐 동일 조건하에서 전문가를 학습 및 평가합니다. - 신중한 확장 및 패키징: 미등록 로봇에는
$compass-newembodiment를 사용합니다. 다음 엔지니어링 의사결정에 필요한 구성, 체크포인트, 로그, 동일 조건의 평가 결과, 비디오를 저장합니다.
본 워크플로우를 재현하고 확장하려면 다음 리소스를 확인하십시오:
- 생성된 실내 씬을 위한 SAGE-10K 데이터셋
- 캡처된 씬 재구성 및 내비게이션 정책 학습을 위한 Omniverse NuRec developer page, COMPASS NuRec workflow, Isaac Lab NuRec guide
- 시뮬레이션 및 로봇 학습 스택을 위한 NVIDIA Isaac Sim 및 NVIDIA Isaac Lab 설명서
- 배포용 선택적 cuVSLAM 기반 오도메트리를 위한 Isaac ROS Visual SLAM 설명서
