workspace

该工作空间的核心是VSI-Bench数据集，这是一个用于评估模型在真实3D室内场景中进行视觉空间推理能力的基准测试。数据集包含来自ScanNet、ARKitScenes和ScanNet++等多个真实世界扫描数据集的场景视频。每个场景都附带一系列需要空间理解和推理的问题，例如物体计数、空间关系、距离比较、物体出现顺序和路径规划等。数据集中提供了每个问题的标准格式（`test.jsonl`），包括问题文本、多项选择选项（如适用）以及真实答案。此外，数据集还包含了官方的3D标注信息（物体边界框、房间尺寸等），存储在`data/meta_info/*.json`中，这些标注被用作构建完美感知空间代码的地面实况来源。该数据集旨在推动视觉语言模型和几何推理系统在复杂、接地气的空间推理任务上的发展。At the core of this workspace is the VSI-Bench dataset, a benchmark for evaluating models visual-spatial reasoning capabilities in real-world 3D indoor scenes. The dataset includes scene videos sourced from multiple real-world scanning datasets such as ScanNet, ARKitScenes, and ScanNet++. Each scene is accompanied by a series of questions that require spatial understanding and reasoning, such as object counting, spatial relationships, distance comparisons, object occurrence order, and path planning. The dataset provides a standard format (`test.jsonl`) for each question, including the question text, multiple-choice options (where applicable), and ground-truth answers. Additionally, it includes official 3D annotation information (e.g., object bounding boxes, room dimensions) stored in `data/meta_info/*.json`, which serves as the ground truth source for building perfect perception spatial code. The dataset aims to advance the development of visual-language models and geometric reasoning systems in complex, grounded spatial reasoning tasks.

原始信息汇总

数据集详情概述：Spatial Code VSI-Bench Workspace

数据集基本信息

• 数据集名称：Spatial Code VSI-Bench Workspace
• 数据集链接：https://huggingface.co/datasets/AntonioJun/workspace
• 用途：用于评估 VSI-Bench 问答任务，支持多种输入模式（原始视频帧、感知空间码、真实空间码、确定性符号求解器）

核心功能与工作流

三大工件分类

1. 源代码与测试：位于 /workspace
2. 数据、缓存与模型检查点：位于 /root/data 和 /root/models
3. 生成结果与报告：位于 /root/results 和 /workspace/reports

标准工作流

1. 运行感知缓存（inference.run 或 inference.launch）
2. 构建感知空间码（encoder.run 或 encoder.launch）
3. 运行 VLM 测试集 A-C 或符号测试集 F
4. 生成报告（analysis.letters_reports）
5. 备份选定输出（backup.py）

主要组件与命令参考

设置与备份

• ./setup.sh：安装包、克隆仓库、下载数据/模型
• ./setup.sh 支持跳过模型、数据、工作空间等选项
• backup.py：备份代码、报告、空间码或特定测试集结果到 Hugging Face 数据集

推理：原始模型缓存

• 支持 SAM3 和 Depth Anything 3 模型后端
• 支持单场景和批量运行
• 重要文件：inference/__init__.py、inference/adapters.py、inference/prompts.py、inference/run.py、inference/launch.py

编码器：空间码生成

• 从现有 SAM3/DA3 缓存构建空间码
• 支持显式 JSON 格式输出
• 重要文件：encoder/config.py、encoder/adapters.py、encoder/geometric.py、encoder/render.py、encoder/run.py、encoder/launch.py

符号求解器

• 确定性 VSI-Bench 回答逻辑
• 支持显式/紧凑格式的空间码输入
• 重要文件：symbolic/adapters.py、symbolic/solver.py、symbolic/run.py、symbolic/launch.py

测试集 A-C 及符号测试集 F

测试集	输入类型	说明
测试集 A	原始视频帧	支持帧选择或完整视频，多种 VLM 模型
测试集 B	空间码文本	仅使用空间码文本，支持多种深度/跟踪配置
测试集 C	帧 + 空间码	结合视觉输入和空间码的双输入模式
测试集 F	符号求解器	将符号求解器封装为测试集格式

实验：几何假设

• 支持多种几何假设分支（如 "Compute Gravity Before Building Object Instances"）
• 可从已有缓存构建假设空间码并进行符号评估

默认输出布局

生产者	默认输出路径
SAM3 推理	/root/data/caches/sam3/<tracking>/frames/<input>/<frames>/<scene>.pt
DA3 推理	/root/data/caches/depth-anything-3/<depth>/frames/<input>/<frames>/<scene>.pkl
编码器组合缓存	/root/data/caches/sam3+depth-anything-3/<tracking>/frames/<input>/<frames>/<scene>.pkl.gz
感知空间码	$VSI_CODES/sam3+depth-anything-3/<tracking>/frames/<input>/<frames>/explicit/<scene>.json
A 结果	`/root/results/A/<model>/{<selection>/<frames>
B/C/F 结果	类似路径结构，包含深度/跟踪/输入选择等维度
报告	/workspace/reports/*_report.json

可再现性保证

• 固定输入、包、检查点、命令/配置及冻结的 SAM3/DA3 缓存下，空间码生成可代码级别再现
• VLM 调用使用固定提示和确定性解码配置
• 测试集输出按所有有意义的配置轴组织以避免碰撞
• 测试使用合成夹具，无需真实数据、结果、缓存或检查点

搜集汇总

数据集介绍

构建方式

该数据集基于VSI-Bench基准构建，旨在探究显式空间编码（即房间三维几何结构的符号化描述）对视觉语言模型性能的影响。数据集的构建涉及多阶段流程：首先通过SAM3分割模型与Depth Anything 3深度估计模型对视频帧进行感知处理，生成原始三维点云及跨帧跟踪结果；随后由编码器模块对点云进行几何分析，拟合有向包围盒、重建地板区域并计算表面间距离，从而生成紧凑型与显式型两种空间编码格式。为隔离感知误差，研究者还利用VSI-Bench数据集真实标注的三维边界框和房间尺寸，构建了完美感知对照版本的空间编码，作为理想上限。

特点

数据集的核心特色在于其系统性的控制实验设计，包含五个精心编排的测试框架：框架A仅使用原始视频帧，框架B仅输入感知空间编码文本，框架C同时提供视频帧与空间编码，框架D采用理想真实空间编码，框架E则完全盲测以评估先验知识影响。这种分层设计使得研究能够精确分离感知误差与推理能力的贡献。此外，数据集同时支持衡量协议（基础协议与扩展协议）和两种空间编码格式（紧凑型与显式型），为23个预设假说的验证提供了完备的实验基础设施。

使用方法

使用者可通过模块化命令行接口灵活调用各组件：推理模块支持指定模型类型、帧选择策略及帧数量，编码器模块可配置深度类型、跟踪策略与输出格式，符号求解器支持直接基于空间编码进行确定性几何推理。分析工具提供聚合评分、跨框架对比及场景聚类Bootstrap统计检验功能，所有结果以标准化JSON格式输出，确保各框架间的直接可比较性。环境安装脚本支持一键部署，自动处理模型权重下载及依赖配置，适配从单GPU到多GPU的多种硬件环境。

背景与挑战

背景概述

VSI-Bench（Visual Spatial Intelligence Benchmark）由纽约大学（NYU）研究团队于2024年末提出，旨在系统评估视觉语言模型在三维空间理解任务上的能力。该数据集基于真实场景的3D扫描数据，涵盖室内空间中的物体定位、空间关系推理、路径规划等核心问题，为空间智能研究提供了标准化的评测平台。数据集整合了ScanNet、ARKitScenes等多源室内场景数据，每个样本包含多视角视频帧、精确3D标注以及多样化的问答对，促使研究者从传统的二维图像理解迈向三维空间推理。VSI-Bench的发布填补了空间智能领域缺乏基准测试的空白，对推动具身智能机器人和自主导航系统的研究具有深远影响。

当前挑战

VSI-Bench面临的核心挑战在于：1）视觉语言模型在三维空间推理中需克服从二维视频帧中准确感知深度、物体尺寸和空间布局的固有歧义，现有模型在遮挡场景下表现显著下降；2）构造过程中，如何从原始3D扫描中自动生成高质量、可扩展的标注是一项技术难题，包括物体轮廓的精准分割、跨帧跟踪的一致性维护以及复杂空间关系的符号化表达。此外，构建流程中感知模块（如SAM3分割和Depth Anything 3深度估计）的误差会层层传递至最终的空间编码，需要通过与真值标注的对比实验来分离感知误差与推理误差，这对实验设计提出了严格要求。

常用场景

经典使用场景

workspace数据集的核心价值在于为视觉语言模型在三维空间理解任务上的表现提供可复现、可分解的评测框架。该数据集依托VSI-Bench基准，精心设计了一套对照实验体系，允许研究者系统地分离和衡量不同因素对模型空间推理能力的影响。最经典的使用场景是将原始视频帧输入与显式的空间编码输入进行对比，通过控制是否向模型提供结构化的三维几何描述（如物体的朝向包围盒、房间地面边界多边形等），量化几何先验信息对模型回答空间问题的增益。研究者可以灵活选择五种不同的输入配置——纯视频帧、纯空间编码文本、两者结合、基于地面真值标注的理想化编码、以及仅问题文本的盲基线——从而在统一的评测协议下揭示模型究竟是依赖视觉特征中的隐式几何线索，还是真正利用显式空间结构进行推理。

解决学术问题

该数据集精准地回应当前视觉语言模型研究中一个未被充分解答的核心问题：模型在空间问答任务上的能力究竟来源于对场景几何的真实理解，抑或只是利用了视觉数据中的统计关联和语言先验。通过构造'纯几何代码'输入通道，workspace首次实现了对空间感知与语言推理两个认知模块的严格解耦。实验设计中的关键学术创新在于引入了基于公式的确定性求解器作为理论天花板，并与基于地面真值标注的完美感知条件相对照，从而能够定量地刻画感知误差（来源于分割与深度估计的不完美）与推理不足各自在性能下降中扮演的角色。这一框架使得研究者得以验证一个深层的理论命题：当场景的几何信息被以无歧义的符号形式呈现时，一个纯粹的计算公式是否能够替代大语言模型的'理解'来完成空间推理，这为评估当前多模态模型的空间智能边界提供了严谨的方法论基础。

衍生相关工作

基于workspace数据集的实验框架，学术界可以衍生出一系列具有开创性的相关工作。首先，该数据集所提出的20个形式化假设可以成为后续研究的标准检验清单，任何关于视觉语言模型空间能力的新理论或新架构都可以通过这一假设体系进行系统性验证。其次，'空间编码'这一中间表示形式本身可以被抽象为一种新的模态理解任务，即训练模型从视频帧中学习生成与workspace格式兼容的结构化几何描述，从而将空间感知问题转化为序列生成与几何约束满足的联合优化问题。此外，实验中发现的感知误差与推理误差的分离方法为开发可解释的视觉语言模型提供了直接的技术路径——研究者可以借鉴其中基于地面真值与感知输入的对照设计，分别评估和改进视觉前端（分割与深度估计）和后端（语言推理模块）的性能。最后一个值得关注的方向是将workspace中的确定性求解器与神经方法进行混合集成，例如在模型无法通过语言形式给出可靠答案时回退到公式计算，这种'神经-符号'协作模式正是该数据集实验设计所直接孕育的研究方向。