NVlabs/SpatialClaw

📚 什麼是 SpatialClaw？

SpatialClaw 是一個免訓練的空間推理代理框架。它讓視覺-語言模型（VLM）能在已載入感知工具（例如 SAM-3 分割、Depth-Anything-3 3D 重構）與科學計算庫（NumPy、SciPy、Matplotlib）的持續性 Jupyter 內核中，逐步撰寫並執行 Python 程式碼。代理可檢視中間結果、組合工具輸出，並在最終以 ReturnAnswer(...) 回傳答案前，不斷調整計畫。

作者在 20 個不同的空間推理基準（靜態影像、多視角場景、影片/4D 任務）上評估此系統，報告的平均準確率為 59.9%，比先前最佳空間代理高出 11.2 點，且在所有基準與六個 VLM 後端（參數量從 26B 到 397B）中皆使用相同的提示、工具集與超參數。

🔧 如何運作

三服務執行環境 – vLLM 伺服器（VLM）、GPU 加速的感知工具伺服器（分割、深度、幾何）、代理本身（Jupyter 內核）。它們透過 JSON 註冊表通訊，可於單一 GPU 機器或 SLURM 集群上執行。
每個樣本的五階段循環
- 規劃器提出高階策略。
- VLM 撰寫一個 Python 細胞，可呼叫感知工具、建立變數、繪圖等。
- 細胞經由 AST 安全檢查後，在持續內核中執行。
- 內核的 stdout、新變數以及任何 show() 圖像作為下一次觀察回傳。
- 循環重複，直到 VLM 發出 ReturnAnswer(...)。
有狀態內核 – 所有變數與載入的影像在步驟間保持存活，因此後續細胞可直接重用先前結果，無需重新計算。
工具包裝器 – 輕量級 Python 包裝器將 SAM-3、Depth-Anything-3 與幾何工具暴露為簡單的函數呼叫。
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（非商業用途）。第三方工具各有其授權。

📖 引用

若在研究中使用 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 推理，在無需任何模型訓練的情況下，於廣泛的空間基準上達成最尖端成果。