NVlabs/SpatialClaw

📚 SpatialClaw란 무엇인가요?

SpatialClaw는 공간 추론 에이전트를 위한 학습 없이 사용 가능한 프레임워크입니다. 비전-언어 모델(VLM)이 이미 세그멘테이션(SAM-3), 3D 재구성(Deep-Anything-3), 과학 계산 라이브러리(Numpy, SciPy, Matplotlib)가 로드된 지속적인 Jupyter 커널 내부에서 단계별로 Python 코드를 작성하고 실행할 수 있게 해줍니다. 에이전트는 중간 결과를 검토하고, 도구 출력을 조합하며, 마지막으로 ReturnAnswer(...)를 통해 답을 반환할 때까지 계획, 코드 생성, 안전성 검사 실행, 관측의 루프를 반복합니다.

저자들은 20개의 다양한 공간 추론 벤치마크(정적 이미지, 다중 뷰 장면, 비디오/4D 작업)에서 시스템을 평가하고, 평균 정확도 59.9% 를 기록했습니다. 이는 동일한 프롬프트, 도구 세트, 하이퍼파라미터를 사용해 6개의 VLM 백엔드(26B~397B 파라미터)에서 평가된 이전 최고 성능 에이전트보다 +11.2점 높은 결과입니다.

🔧 작동 방식

3서비스 런타임 – vLLM 서버(VLM), GPU 가속 인식 도구 서버(세그멘테이션, 깊이, 기하학), 에이전트 자체(Jupyter 커널). JSON 레지스트리를 통해 통신 가능하며, 단일 GPU 머신 또는 SLURM 클러스터에서 실행 가능합니다.
샘플당 5단계 루프
- 플래너가 고수준 전략을 제안합니다.
- VLM이 1개의 Python 셀을 작성합니다. 인식 도구 호출, 변수 생성, 플롯 등이 가능합니다.
- 셀은 AST 검사를 통해 안전성 확인되고 지속적인 커널에서 실행됩니다.
- 커널의 stdout, 새로운 변수, show()로 생성된 이미지가 다음 관측으로 반환됩니다.
- VLM이 ReturnAnswer(...)를 출력할 때까지 루프를 반복합니다.
상태 유지 커널 – 모든 변수와 로드된 이미지가 단계 간에 유지되므로, 후속 셀에서 이전 결과를 재계산 없이 재사용할 수 있습니다.
도구 래퍼 – SAM-3, Depth-Anything-3, 기하학 유틸리티를 간단한 함수 호출로 노출하는 얇은 Python 래퍼입니다.
LangGraph 워크플로우 – 전체 오케스트레이션은 LangGraph 기반으로 구현되어 있어 루프를 쉽게 확장할 수 있습니다.

🚀 빠른 시작 (단일 머신, SLURM 없음)

# 1. 하위 모듈 포함 복제 및 환경 설치 (약 15~30분)
git clone --recursive https://github.com/NVlabs/SpatialClaw.git
cd SpatialClaw
bash spatial_agent/scripts/setup.sh

# 2. API 키 제공 (또는 자체 호스팅 vLLM 사용 시 키 필요 없음)
cp .env.example .env   # 키로 파일 편집

# 3. 단일 벤치마크 예제 실행
python -m spatial_agent.entrypoints.run \
    --dataset spatial_agent/config/dataset/erqa.json \
    --model   spatial_agent/config/model/gemini-3-pro.json \
    --concurrency 4

클러스터 실행의 경우, docs/installation.md 및 docs/running.md를 참조하여 SLURM 시작 매니저 및 가중치 사전 다운로드 단계를 확인하세요.

📂 리포지토리 구조 (개요)

spatial_agent/ – 핵심 에이전트 코드, LangGraph 워크플로우, Jupyter 커널 매니저, AST 안전성 검사기.
tools/ – 인식 모듈(SAM-3, Depth-Anything-3) 및 기하학 유틸리티 래퍼.
docs/ – 설치, 실험 실행, 모니터링, 구성, 아키텍처에 대한 상세 가이드.
spatial_agent/config/ – 20개 벤치마크 및 모델 백엔드용 JSON 설정 파일.
scripts/ – 환경 설정 및 SLURM 작업 제출용 헬퍼 스크립트.

🎯 SpatialClaw를 사용할 때

공간 추론 연구 – 모델의 파인튜닝 없이 시각 도구를 유연하게 조합하고 싶을 때.
도구 증강 에이전트 – 고정된 도구 호출 API보다 더 표현력이 풍부한 "코드로서의 행동" 인터페이스 제공.
벤치마크 비교 – 20개의 표준 공간 벤치마크용 로더가 포함되어 있어 재현이 쉬움.
빠른 프로토타이핑 – 새로운 Python 래퍼를 작성하여 인식 도구를 교체하거나 추가 가능. 에이전트는 자동으로 호출 가능.

⚠️ 제한 사항 및 고려 사항

학습 없음만 가능 – 성능은 기반 VLM에 완전히 의존하며, 파인튜닝은 수행되지 않음.
GPU 집약적 – 인식 도구 서버와 VLM 모두 GPU 메모리 필요. 많은 동시 샘플 실행 시 멀티 GPU 환경 또는 SLURM 필요.
안전성 검사는 정적 – AST 검증기는 명백한 위험 코드를 감지하지만, 커널은 임의의 Python을 실행하므로 신뢰할 수 있는 환경에서 실행해야 함.
라이선스 – NVIDIA Source Code License-NC(비상업용). 제3자 도구는 각각 별도 라이선스 보유.

📖 인용

SpatialClaw를 연구에 사용할 경우, 다음을 인용해 주세요:

@article{cho2026spatialclaw,
  title   = {SpatialClaw: Rethinking Action Interface for Agentic Spatial Reasoning},
  author  = {Cho, Seokju and Hachiuma, Ryo and Badki, Abhishek and
             Su, Hang and Lee, Byung-Kwan and Song, Chan Hee and
             Liu, Sifei and Radhakrishnan, Subhashree and Kim, Seungryong and
             Wang, Yu-Chiang Frank and Chen, Min-Hung},
  journal = {arXiv preprint},
  year    = {2026}
}

TL;DR – SpatialClaw는 대규모 비전-언어 모델이 강력한 인식 도구를 호출하는 Python 셀을 작성함으로써 2D/3D/4D의 고도화된 추론을 수행할 수 있는 연구용 코드 기반 에이전트 프레임워크이며, 모델 학습 없이도 다양한 공간 벤치마크에서 최고 성능을 달성합니다.