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 推理，在无需任何模型训练的情况下，在广泛的基准上达到最先进水平。