NVIDIA Isaac GR00T (N1.7)

요약

NVIDIA Isaac GR00T는 GR00T 계열 VLA의 공식 레퍼런스 구현이자 N1.7 GA 릴리스의 배포처다. 3B 규모 베이스 체크포인트, 벤치마크별 fine-tuning 체크포인트 4종, 다운로드 없이 바로 실행되는 demo 데이터셋 6종, 학습과 추론과 서빙 CLI, ONNX와 TensorRT export, 플랫폼별 설치 스크립트가 한 저장소에 들어 있다.

GA는 General Availability의 약어로, 상용 배포와 지원, 안정성 보장이 명시된 릴리스 단계를 뜻한다. 실험용 프리뷰가 아니라 제품에 넣어도 되는 단계라는 의미이며, README는 검증된 벤치마크 전체와 pull request 기여 수용도 함께 명시한다.

이 페이지는 저장소가 제공하는 자원과 사용 절차에 집중한다. 모델 아키텍처의 내부 구성과 실험 수치는 원 논문 페이지(GR00T N1: An Open Foundation Model for Generalist Humanoid Robots)와 한국어 해설(03-13. Groot N1 - 모두의 로보틱스 - VLA 입문, 03-14. Groot N1.5 - 모두의 로보틱스 - VLA 입문)이 다룬다.

배경

GR00T N1.7은 다양한 로봇 데이터로 학습한 cross-embodiment VLA다. 양팔 로봇, semi-humanoid, 대규모 humanoid 데이터를 섞어 학습했고, 언어와 이미지를 입력으로 받아 여러 환경에서 manipulation 과제를 수행한다. manipulation은 팔과 손으로 물체를 다루는 과제 영역을 말한다.

저장소가 안내하는 사용 흐름은 다섯 단계다. 이 순서가 문서 전체의 뼈대이기도 하다.

성능 수치를 찾는 목적이라면 이 저장소는 맞는 자료가 아니다. N1.6 대비 성능은 comparable이라는 한 단어가 전부이고, RoboCasa, RoboCasa GR1 탁상 과제, SimplerEnv, 실제 G1 기기 평가로 범위를 넓혔다고만 적을 뿐 성공률은 각 벤치마크 하위 README로 넘긴다.

핵심 개념

policy는 현재 observation을 받아 다음 action을 정하는 함수를 말한다. observation은 매 timestep에 policy가 받는 센서 입력이고, action은 policy가 출력하는 제어 명령이다.

embodiment tag는 어떤 로봇의 데이터인지 가리키는 문자열 키다. 모델이 state와 action 배열을 어떻게 해석할지 정하는 modality config를 이 키가 고른다. 추론이든 fine-tuning이든 모든 명령에 --embodiment-tag가 필요하고 대소문자는 구분하지 않는다.

modality config는 하나로 이어붙인 state와 action 배열의 어느 구간이 x, y, z, gripper인지, 어떤 video key가 있는지를 적은 설정이다. 데이터셋 쪽에서는 meta/modality.json 파일이, 학습 쪽에서는 --modality-config-path 인자가 이 설정을 전달한다.

relative EEF action space는 action을 절대 목표 pose가 아니라 현재 pose로부터의 변화량으로 적는 표현이다. EEF는 end-effector의 약어이며, end-effector는 로봇 팔 끝에서 물체와 접촉하는 부분을 가리킨다. N1.7은 이 표현을 로봇과 사람 데이터에 공통으로 적용해 cross-embodiment 성능을 끌어올린 핵심 요인으로 지목한다.

execution horizon은 예측한 action 중 policy 호출 한 번에 실제로 실행하는 개수다. N1.7의 모델 action horizon은 40이지만 예제 명령은 대개 8이나 16을 실행한다.

N1.6에서 달라진 점

신경망의 큰 틀은 유지된다. vision-language foundation model이 앞에 서고 연속 action을 denoise하는 diffusion transformer head가 뒤에 붙으며, action head는 여전히 flow matching 방식의 DiT다. flow matching은 noise에서 데이터로 향하는 vector field를 학습해 샘플을 만드는 생성 기법이고, DiT는 diffusion 모델의 denoising 신경망을 Transformer로 구현한 구조를 말한다.

바뀐 것은 그 안을 채우는 부품과 숫자다.

tune_top_llm_layers가 4에서 0으로 내려간 변화가 눈에 띈다. N1.6은 backbone 상단 4개 층을 함께 학습했지만 N1.7은 backbone을 전부 얼린다. 즉 backbone을 통째로 교체하면서 원래 모델의 일반화 능력은 건드리지 않는 쪽을 택했다. 새 backbone은 해상도가 유연해 이미지를 padding 없이 원래 화면비 그대로 인코딩한다.

차원이 29에서 132로 네 배 넘게 커지고 action horizon이 16에서 40으로 늘어난 것은 whole-body control까지 한 인터페이스에 담으려는 조치로 읽힌다. whole-body control은 균형과 이동을 포함해 몸 전체를 함께 제어하는 문제인데, 다리와 손가락까지 포함하면 29차원으로는 부족하다.

모델 밖의 변화도 세 가지 적혀 있다.

• fine-tuning이 여러 데이터셋 경로를 받고 ds_weights_alpha로 mixture 비중을 조절할 수 있게 됐다.
• 전 구간 ONNX와 TensorRT export가 추가돼 데스크톱 GPU와 edge 플랫폼 사이의 배포 일관성이 맞춰졌다.
• rollout CLI 인자가 --action-horizon에서 --execution-horizon으로 개명됐다. 모델이 예측하는 action 개수와 실제로 실행하는 개수가 다르다는 점을 이름으로 드러낸 것이다.
• policy 서빙, rollout 기록, 평가, 설정 검증 경로가 보강돼 오류 진단이 쉬워졌다.

N1.7 자체의 학습 측 기여는 두 가지로 압축된다. 하나가 위에서 설명한 relative EEF action space이고, 다른 하나가 EgoScale 사람 영상 2만 시간을 로봇 시연 데이터와 나란히 pre-training에 넣은 human video pre-training이다. 상대 표현이 사람과 로봇 양쪽에서 같은 의미를 갖기 때문에 사람 영상에서 배운 manipulation 사전 지식이 로봇 제어로 바로 전이된다.

따라서 두 기여는 사실상 하나로 묶인다. 상대 표현이 먼저 있어야 사람 영상이 학습 데이터로 쓸모가 생기기 때문이다.

체크포인트와 데이터

체크포인트

체크포인트마다 파일 구조가 달라 다루는 방법이 나뉜다. DROID나 SimplerEnv처럼 평평한 구조는 HuggingFace 모델 ID를 --model-path에 그대로 넘기면 되지만, LIBERO처럼 하위 폴더에 모델 파일이 들어 있으면 HuggingFace가 중첩 경로를 지원하지 않아 hf download로 먼저 내려받아야 한다.

demo 데이터셋

demo 데이터셋 6종이 저장소에 함께 들어 있어 별도 다운로드 없이 바로 실행할 수 있다. episode는 과제 시작부터 종료까지의 한 실행 단위를 말한다.

DROID episode가 더 필요하면 scripts/download_droid_sample.py --num-episodes 10으로 추가 생성한다. 베이스 모델은 droid_sample에서 fine-tuning 없이 바로 동작한다.

데이터 포맷

데이터 형식은 LeRobot v2 데이터셋 형식에 meta/modality.json 한 파일을 더한 것이다. 디렉토리 구성은 다음과 같다.

자기 데이터를 쓰려면 위 형식으로 변환한다. LeRobot v3에서 넘어오는 경우에는 scripts/lerobot_conversion 아래의 convert_v3_to_v2.py를 별도 가상환경에서 실행한다.

설치와 하드웨어 요구사항

하드웨어

플랫폼별로 요구하는 CUDA와 Python 조합이 다르다. dGPU는 CUDA 12.8과 Python 3.12, Jetson Thor와 Orin은 JetPack 7.2에 CUDA 13.2와 Python 3.12, DGX Spark는 CUDA 13.0과 Python 3.12를 쓴다. 플랫폼별 설치 스크립트와 Dockerfile은 scripts/deployment/ 아래에 있다.

설치 절차

의존성 관리는 uv를 쓴다. 순서는 다음과 같다.

• git-lfs를 먼저 설치한다. demo_data/의 parquet 파일을 받는 데 필요하다.
• submodule을 포함해 clone한다: git clone --recurse-submodules. 이미 clone했다면 git submodule update --init --recursive로 따로 초기화한다.
• FFmpeg를 설치한다. 유일하게 지원되는 영상 backend인 torchcodec이 요구한다.
• uv sync --python 3.12로 환경을 만든다. flash-attn과 TensorRT 같은 GPU 의존성이 기본 설치에 포함된다.
• import gr00t가 되는지 확인한다.
• HuggingFace에 로그인한다. huggingface-cli login 또는 HF_TOKEN 환경변수를 쓴다.

uv 대신 pip을 쓰려면 Python 3.12 가상환경을 만들고 pip install -e .를 실행한다. 다만 GPU 의존성은 직접 설치해야 할 수 있다. 시스템 의존성 충돌을 피하려면 Docker 이미지를 먼저 띄우고 그 안에서 저장소를 clone하는 순서를 권장한다.

uv run을 실행할 때마다 Installing flash-attn... 메시지가 나오는 것은 알려진 동작이다. URL로 고정한 wheel을 uv가 매번 재검증하는 것이며 소스 빌드가 아니라 2~3초짜리 캐시 확인이다. fine-tuning이 CUDA_HOME is unset으로 실패하면 scripts/deployment/dgpu/install_deps.sh를 한 번 실행하거나 CUDA_HOME을 직접 지정한다.

추론과 배포

zero-shot 추론

포함된 demo_data/droid_sample은 베이스 모델과 바로 맞물린다. scripts/deployment/standalone_inference_script.py에 --model-path nvidia/GR00T-N1.7-3B, 데이터셋 경로, embodiment tag, --traj-ids, --inference-mode pytorch, --execution-horizon 8을 주면 DROID episode 2개에 대해 open-loop 추론이 실행된다. open-loop 실행은 한 번 계산한 action 묶음을 중간 피드백 없이 끝까지 내보내는 방식이다. 베이스 모델은 첫 실행 시 약 6GB를 HuggingFace에서 자동으로 내려받는다.

fine-tuning 체크포인트로 바꿀 때는 --model-path만 해당 모델 ID로 교체한다. 다만 LIBERO처럼 중첩 폴더 구조를 쓰는 체크포인트는 hf download로 필요한 파일을 먼저 받은 뒤 로컬 경로를 지정한다.

server-client 구조

실제 기기 배포나 시뮬레이션 평가는 server-client 구조로 실행한다. policy는 GPU 서버에서 구동되고 가벼운 client가 ZMQ로 observation을 보내 action을 받는다.

gr00t/eval/run_gr00t_server.py로 서버를 띄우고 기본 포트 5555를 쓴다. client 쪽은 PolicyClient를 만들어 policy.get_action(obs) 한 줄로 gym 스타일 루프에 결합한다. 포트가 점유되어 ZMQError: Address already in use가 나면 --port로 다른 값을 준다.

학습된 모델 없이 환경 설정만 확인하려면 --model-path 대신 --dataset-path를 주어 서버를 띄운다. 기록된 action을 그대로 재생하는 ReplayPolicy로 동작하므로 환경 연결 문제와 모델 문제를 분리해 볼 수 있다.

fine-tuning

fine-tuning은 gr00t/experiment/launch_finetune.py 하나가 단일 GPU와 torchrun 멀티 GPU를 모두 덮는다. 단일 GPU는 CUDA_VISIBLE_DEVICES=0과 --num-gpus 1로, 8장 구성은 torchrun --nproc_per_node=8로 실행한다. 예제 명령이 쓰는 값은 --max-steps 2000, --global-batch-size 32, --dataloader-num-workers 4다.

자기 로봇을 붙일 때 바꾸는 인자는 두 개다. 데이터셋 경로를 자기 데이터로, --modality-config-path를 자기 modality config로 바꾸고 embodiment tag는 NEW_EMBODIMENT를 쓴다. Weights & Biases 로깅은 --use-wandb로 켜고, 더 세밀한 설정이 필요하면 launch_train.py를 쓴다. 멀티 GPU에서는 가상환경이 제대로 잡히도록 맨 torchrun이 아니라 uv run torchrun을 쓰라고 안내한다.

공개 벤치마크 결과를 재현하려면 각 벤치마크의 자체 README를 따른다. 데이터셋 다운로드, fine-tuning, 평가 명령이 벤치마크마다 한 문서에 정리되어 있다.

학습 시 알아 두어야 할 항목이 세 가지 있다. 하드웨어가 감당하는 최대 배치 크기를 쓰고 수천 step을 학습하라는 것이 첫째다. 둘째로 같은 설정으로 다시 학습해도 이미지 augmentation이 결정론적이지 않아 실행 간 5~6%의 편차가 난다. 즉 공개 벤치마크 수치와 자기 결과를 비교할 때 이 폭을 감안해야 한다.

셋째가 --state_dropout_prob인데, 값이 세 군데서 다르게 잡혀 있어 혼동하기 쉽다. 학습 중 state 입력을 무작위로 떨어뜨려 일반화를 돕고 proprioception 의존을 줄이는 장치이며, proprioception은 관절 각도 같은 로봇 자신의 상태 감각 입력을 말한다.

자기 상태 감각에 크게 기대는 과제라면 이 값을 낮추라는 것이 README의 안내다.

평가

평가는 두 가지 방식으로 나뉜다. open-loop 평가는 데이터셋의 정답 action과 예측을 맞대어 MSE와 그래프를 /tmp/open_loop_eval/traj_{traj_id}.jpeg로 남긴다. 저장 위치는 --save-plot-path로 바꿀 수 있다.

closed-loop 평가는 앞서 설명한 server-client 구조로 시뮬레이터나 실제 기기에서 실행한다. closed-loop 제어는 매 timestep 새 observation을 받아 action을 다시 정하는 방식이다.

시뮬레이션 벤치마크는 첫 실행 전에 한 번의 환경 설정이 필요하다. 공용 시스템 라이브러리(libegl1-mesa-dev, libglu1-mesa)를 설치한 뒤 벤치마크별 setup_*.sh를 실행한다. LIBERO, SimplerEnv, robocasa, robocasa-gr1이 여기에 해당하고, DROID와 RoboLab과 SO100처럼 실제 기기나 사용자 정의 embodiment를 쓰는 경로는 설정 스크립트 없이 각자의 README를 따른다. 설정이 제대로 됐는지는 scripts/eval/check_sim_eval_ready.py로 확인한다.

새 시뮬레이션 벤치마크를 추가할 때 주의할 점이 하나 있다. 각 벤치마크는 {prefix}/{task_name} 형식의 gym 환경 이름으로 등록되고, 평가 프레임워크는 gr00t/eval/sim/env_utils.py의 ENV_PREFIX_TO_EMBODIMENT_TAG 매핑으로 prefix에서 embodiment tag를 찾는다. 그런데 prefix와 tag 이름이 일치하지 않는 경우가 많다. 예를 들어 prefix libero_sim은 EmbodimentTag.LIBERO_PANDA로 이어진다. 따라서 prefix가 tag 이름과 같다고 가정하면 안 된다. 여러 prefix를 쓰는 벤치마크라면 관련 prefix 전부를 같은 tag로 매핑해야 한다.

테스트를 실행하려면 uv sync --python 3.12 --extra dev로 개발 의존성을 설치한 뒤 pytest를 실행한다. GPU 표시가 붙은 테스트는 해당 CUDA 하드웨어가 있는 장비에서만 실행한다.

whole-body control 연동

whole-body control은 UNITREE_G1_SONIC tag와 GEAR-SONIC 컨트롤러 경로로 지원된다. 이 경로에서 VLA는 관절 명령을 직접 내지 않고 압축된 latent action 토큰을 출력하며, 학습된 whole-body 컨트롤러가 그것을 다리와 팔과 손을 포함한 전신 관절 명령으로 푼다. latent action은 두 프레임 사이의 시각적 변화를 action 라벨 없이 부호화한 벡터를 말한다. 하나의 policy가 언어 조건을 받아 manipulation과 locomotion을 함께 출력하며, locomotion은 다리로 이동하는 과제 영역이다.

세대 간 지원 범위가 나뉜다는 점을 확인해야 한다. UNITREE_G1 tag는 이전 세대 decoupled WBC 컨트롤러와 호환되지만, 데이터 수집부터 fine-tuning과 배포까지 이어지는 end-to-end 워크플로는 GEAR-SONIC 경로에서만 지원한다. 실제 절차는 이 저장소가 아니라 GR00T-WholeBodyControl (GEAR-SONIC / Decoupled WBC / MotionBricks)의 튜토리얼 문서가 담당하며, VR teleoperation 기반 데이터 수집, fine-tuning과 배포, PolicyServer와 SONIC decoder 조합의 실시간 제어가 각각 문서화되어 있다. teleoperation은 사람이 로봇을 원격으로 움직여 시연을 만드는 방식이다.

LeRobot과의 역할 분담

GR00T N1.7은 HuggingFace LeRobot에서도 groot policy type으로 쓸 수 있다. README는 두 저장소의 역할을 명시적으로 나눈다. LeRobot 원생 학습과 평가와 rollout 흐름은 LeRobot 문서를 따르고, 모델 내부 구현과 배포 도구와 벤치마크별 예제는 이 저장소를 참고하라는 것이다.

실행 시 걸리는 제약

설치 제약이 촘촘해서, 실제로 실행하려면 README에 흩어진 제약 목록을 먼저 확인해야 한다.

마지막 두 항목은 오류 없이 조용히 실패하는 종류라 초기 진입 비용을 실제로 키운다.

라이선스

라이선스 표기가 문서 안에서 한 군데 어긋난다. 소개 절은 N1.7이 Apache 2.0으로 완전히 상용 라이선스 가능하다고 적지만, License 절은 코드만 Apache 2.0이고 모델 가중치는 NVIDIA Open Model License라고 나눈다. 가중치를 사용할 계획이라면 뒤쪽 표기를 기준으로 삼아야 한다.

성능 근거를 이 저장소만으로 판단할 수 없다는 점도 함께 확인해야 한다. 인용으로 걸린 대응 논문은 여전히 2025년 N1 논문이며, N1.5와 N1.6과 N1.7의 변경을 다룬 문헌은 README가 가리키지 않는다.

핵심 용어

관련 페이지

• GR00T N1: An Open Foundation Model for Generalist Humanoid Robots: 이 저장소가 구현하는 계열의 원 논문. 아키텍처 내부와 정량 평가는 원 논문 페이지 참고.
• 03-13. Groot N1 - 모두의 로보틱스 - VLA 입문: GR00T N1의 한국어 해설. 모델 구조를 개념부터 풀어 설명한다.
• 03-14. Groot N1.5 - 모두의 로보틱스 - VLA 입문: N1.5 세대의 한국어 해설. N1에서 N1.7로 이어지는 중간 단계를 다룬다.
• GR00T-WholeBodyControl (GEAR-SONIC / Decoupled WBC / MotionBricks): whole-body control 쪽 저장소. N1.7부터 UNITREE_G1_SONIC tag로 두 계열이 맞물린다.
• Eagle: Frontier Vision-Language Models with Data-Centric Strategies: N1.6까지 쓰던 VLM backbone 공급처. N1.7에서 Cosmos-Reason2-2B로 교체됐다.
• RoboCasa: 공식 구현 저장소 (RoboCasa365 v1.0.1): 지원 벤치마크로 올라 있는 robocasa 계열의 공식 구현. 환경과 데이터 쪽 짝이다.
• LeRobot: State-of-the-art Machine Learning for Real-World Robotics in PyTorch: 데이터 형식의 바탕이자 groot policy type으로 N1.7을 싣는 반대 방향의 연결.
• Awesome-Dual-System-VLA: System 1이 실시간 perception 입력을 직접 받아야 한다는 기준으로 GR00T를 dual-system VLA에서 제외한 목록.
• Physical AI 카테고리 지도와 학습 경로: physical-ai 카테고리 허브. GEAR와 GR00T와 SONIC과 GEAR-SONIC 이름 구분표가 있다.
• GR00T N1.7 3B 체크포인트와 LeRobot 통합: 모델 카드 규격, 플랫폼별 추론 지연, fine-tuning과 rollout 레시피: 이 저장소가 배포하는 베이스 체크포인트의 Hugging Face 모델 카드와 LeRobot 통합 문서. 플랫폼별 추론 지연 시간과 LeRobot 레시피를 다룬다.