SpatialClaw – 空间推理的代码优先代理

它是什么 – SpatialClaw 是一个研究级、无需训练的框架，允许视觉语言模型（VLM）通过在持久化的 Jupyter 内核中逐步编写和执行 Python 代码来解决 3D/4D 推理问题。内核预加载了感知工具（例如 Segment-Anything-3、Depth-Anything-3）和科学库（NumPy、SciPy、Matplotlib）。VLM 制定计划，然后为每个推理步骤生成一个 Python 单元；每个单元经过安全检查、运行，其输出（变量、图像、控制台文本）被反馈给模型。循环持续进行，直到模型调用 ReturnAnswer(...)。

---

关键思想

• 代码作为动作接口 – 代理不是使用固定的工具调用 API，而是编写任意 Python 代码，从而完全灵活地链接工具、检查中间结果并修改其分析。
• 无需训练 – 相同的提示、工具集和超参数适用于 20 个空间基准和六个不同的 VLM 后端（参数从 26B 到 397B）。
• 三服务运行时 – vLLM 服务器提供 VLM，GPU 加速的感知工具服务器托管 SAM-3、Depth-Anything-3 等，代理在状态化的 Jupyter 内核中运行。它们通过 JSON 注册表通信，可以在单 GPU 机器或 SLURM 集群上启动。
• 安全性 – 每个生成的单元在执行前被解析为抽象语法树（AST）并检查，以防止恶意代码。
• 基准覆盖 – 为 20 个数据集提供开箱即用的加载器，涵盖单图像、多视图和基于视频的空间任务（例如 ERQA、Omni3D、MindCube、MMSI-Video、Video-M​​ME）。

---

快速开始（单机，无 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

脚本下载模型权重，启动 vLLM 服务器、感知工具服务器和 Jupyter 内核，然后评估所选基准。

---

文档亮点

指南	你将找到的内容
安装	详细的 conda/vLLM 环境设置、第三方子模块处理以及 .env 配置。
运行实验	如何启动三个服务、使用 SLURM 启动管理器或在本地运行所有内容。
监控与日志	仪表板提示、每个样本的输出检查以及 SLURM 日志处理。
配置	模型和数据集的 JSON 模式、支持的基准列表以及如何添加新基准。
架构	五阶段循环的图表（规划器 → VLM 编写单元 → AST 检查 → 执行 → 观察）。
故障排除	常见设置错误及修复方法。

---

何时使用 SpatialClaw

• 研究 灵活的基于代码的接口如何影响 VLM 空间推理。
• 基准测试 在广泛的 3D/4D 任务上测试新的 VLM 或感知工具，无需重新训练。
• 原型设计 自定义空间代理，需要组合任意 Python 库。
• 教育演示 展示逐步推理和可视化中间输出。

---

许可证

• 核心仓库根据 NVIDIA 源代码许可-非商业（非商业）发布。详情请参阅 LICENSE。
• 其他第三方工具根据其各自的许可证捆绑（请参阅 tools/third_party/<repo>/LICENSE）。

---

引用

如果您在出版物中使用 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 允许 VLM 通过在实时 Jupyter 内核中编写真实 Python 代码来解决复杂的空间任务，在 20 个基准上实现最先进的结果，无需任何特定模型的训练。