license: apache-2.0
tags:
- multimodal
- vision-language
- video understanding
- spatial reasoning
- visuospatial cognition
- llava
- qwen
- llava-video
datasets:
- nkkbr/ViCA-322K
- nkkbr/ViCA-thinking-2.68k
language:
- en
library_name: transformers
pipeline_tag: video-text-to-text
model_name: ViCA-7B
base_model: lmms-lab/LLaVA-Video-7B-Qwen2
model-index:
- name: ViCA-7B
results:
- task:
type: visual-question-answering
dataset:
name: VSI-Bench
type: vsi-bench
metrics:
- type: score
value: 60.56
name: Average
verified: false
- type: MRA
value: 68.81
name: Object Count
- type: MRA
value: 57.01
name: Absolute Distance
- type: MRA
value: 79.17
name: Object Size
- type: MRA
value: 75.14
name: Room Size
- type: accuracy
value: 58.45
name: Relative Distance
- type: accuracy
value: 42.56
name: Relative Direction
- type: accuracy
value: 34.54
name: Route Plan
- type: accuracy
value: 68.77
name: Appearance Order
ViCA-7B: Visuospatial Cognitive Assistant
You may also be interested in our other project, ViCA2. Please refer to the following links:
Overview
ViCA-7B is a vision-language model specifically fine-tuned for visuospatial reasoning in indoor video environments. Built upon the LLaVA-Video-7B-Qwen2 architecture, it is trained using our newly proposed ViCA-322K dataset, which emphasizes both structured spatial annotations and complex instruction-based reasoning tasks.
ViCA-7B achieves state-of-the-art performance on VSI-Bench, outperforming both proprietary models like GPT-4o and Gemini-1.5 Pro, as well as larger open-source baselines.
ViCA-7B sets a new standard for open-source multimodal spatial reasoning on indoor videos, making it a strong candidate for embodied AI and robotics use cases.
Figure 1: Performance comparison of ViCA-7B and other models on VSI-Bench.
Model Architecture and Training Strategy
ViCA-7B is built upon the LLaVA-NeXT framework, using Qwen2-7B as the language backbone and SigLIP as the visual encoder.
Key Training Features
Fixed-Length Visual Tokenization
Each video is uniformly sampled into 64 frames, and each frame is encoded into 210 visual tokens, resulting in a total of 13,440 visual tokens per example. This fixed-length design ensures consistent memory usage and stable optimization across batches.Multimodal Alignment via Lightweight Projector
A simple MLP-based projector maps visual embeddings into the language embedding space, enabling effective fusion between video content and textual prompts during both training and inference.Efficient Distributed Training with DeepSpeed
Training is conducted using DeepSpeed ZeRO-3 Offload on 8× NVIDIA H100 80GB GPUs, with full parameter and optimizer state partitioning across devices. This setup supports large batch sizes and minimizes GPU memory overhead.Mixed-Precision Computation (fp16)
We adopt mixed-precision training (fp16) to accelerate computation and reduce memory usage, without compromising accuracy. This is combined with ZeRO-3 partitioning to further enhance training scalability.
The training was conducted over 55 hours, covering both base and complex spatial reasoning subsets.
Training Dynamics
Figure 2: Training loss, learning rate schedule, and gradient norm curves during ViCA-7B fine-tuning. These curves illustrate a stable optimization process and smooth convergence under the DeepSpeed ZeRO-3 setup.
Dataset
ViCA-7B is fine-tuned on two complementary datasets:
ViCA-322K:
A large-scale dataset covering both base spatial reasoning tasks (e.g., object distance, size, count, appearance order) and complex spatial reasoning tasks involving natural language questions and scene understanding. This dataset forms the core of the model's spatial reasoning capabilities.ViCA-thinking-2.68k:
A focused dataset used for instruction tuning to enhance the model's ability to generate step-by-step reasoning traces before outputting final answers. This supports more interpretable and cognitively-aligned response generation.
For details, please refer to the individual dataset pages linked above.
Evaluation: VSI-BENCH Benchmark
Figure 3: Quantitative comparison of ViCA-7B and baseline models on VSI-Bench. ViCA-7B achieves the best overall performance across both numerical and multiple-choice tasks.
Effect of CSR Data
| Configuration | Avg Score |
|---|---|
| Base-only (281K) | 55.35 |
| Full with CSR (322K) | 60.56 |
CSR(Complex Spatial Reasoning) boosts generalization and accelerates learning, with notable performance jumps at intermediate checkpoints (e.g., +2.02 at 50–55%).
Data Scale vs. Performance
Performance improves significantly between 5% → 60% of data usage. After 80%, improvements plateau, indicating dataset is well-matched to model capacity.
Figure 4: Performance of ViCA-7B under varying training data sizes (from 5% to 100%). The full dataset (including Complex Spatial Reasoning, CSR) consistently outperforms the base-only configuration. Notably, the CSR-enhanced model shows a +2.02 score jump between 50% and 55%, and a final performance gain of +4.75 at full scale. Performance plateaus beyond 80%, indicating the dataset is well-aligned with the model capacity.
Intermediate Checkpoints and Evaluation Outputs
To support detailed analysis and reproducibility, we provide two sets of intermediate checkpoints saved at every 5% increment of the training data. These models are trained for a single epoch and are useful for understanding how performance evolves as training progresses.
We also release the corresponding raw evaluation outputs (e.g., .json prediction files) for each checkpoint.
The evaluation script used to produce these outputs is available in our GitHub repository.
Full Dataset (ViCA-322K: Base + CSR)
This series corresponds to the full training set, including both base spatial reasoning and complex spatial reasoning (CSR):
| Data Usage | Checkpoint | Data Usage | Checkpoint |
|---|---|---|---|
| 5% | nkkbr/ViCA-5p |
55% | nkkbr/ViCA-55p |
| 10% | nkkbr/ViCA-10p |
60% | nkkbr/ViCA-60p |
| 15% | nkkbr/ViCA-15p |
65% | nkkbr/ViCA-65p |
| 20% | nkkbr/ViCA-20p |
70% | nkkbr/ViCA-70p |
| 25% | nkkbr/ViCA-25p |
75% | nkkbr/ViCA-75p |
| 30% | nkkbr/ViCA-30p |
80% | nkkbr/ViCA-80p |
| 35% | nkkbr/ViCA-35p |
85% | nkkbr/ViCA-85p |
| 40% | nkkbr/ViCA-40p |
90% | nkkbr/ViCA-90p |
| 45% | nkkbr/ViCA-45p |
95% | nkkbr/ViCA-95p |
| 50% | nkkbr/ViCA-50p |
100% (This repo) | nkkbr/ViCA |
Raw evaluation outputs are available here.
Base-only Subset (ViCA-322K: Base)
This series is trained only on the base spatial reasoning subset of ViCA-322K, without any CSR examples:
| Data Usage | Checkpoint | Data Usage | Checkpoint |
|---|---|---|---|
| 5% | nkkbr/ViCA-base-5p |
55% | nkkbr/ViCA-base-55p |
| 10% | nkkbr/ViCA-base-10p |
60% | nkkbr/ViCA-base-60p |
| 15% | nkkbr/ViCA-base-15p |
65% | nkkbr/ViCA-base-65p |
| 20% | nkkbr/ViCA-base-20p |
70% | nkkbr/ViCA-base-70p |
| 25% | nkkbr/ViCA-base-25p |
75% | nkkbr/ViCA-base-75p |
| 30% | nkkbr/ViCA-base-30p |
80% | nkkbr/ViCA-base-80p |
| 35% | nkkbr/ViCA-base-35p |
85% | nkkbr/ViCA-base-85p |
| 40% | nkkbr/ViCA-base-40p |
90% | nkkbr/ViCA-base-90p |
| 45% | nkkbr/ViCA-base-45p |
95% | nkkbr/ViCA-base-95p |
| 50% | nkkbr/ViCA-base-50p |
100% | nkkbr/ViCA-base |
Raw evaluation outputs are available here.
Source-wise Checkpoints
While the full ViCA-322K dataset was curated by us, the underlying videos and associated metadata are sourced from three distinct indoor video datasets:
To better understand how each source contributes to model performance, we fine-tuned ViCA-7B on subsets of ViCA-322K that exclusively use data from each source. For each subset, we provide checkpoints trained with 10% increments of the available data, from 10% to 100%.
Corresponding raw evaluation outputs (e.g., .json predictions) are also provided for all checkpoints.
ARKitScenes-Only Checkpoints
| Data Usage | Checkpoint | Data Usage | Checkpoint |
|---|---|---|---|
| 10% | nkkbr/ViCA-ARKitScenes-10p |
60% | nkkbr/ViCA-ARKitScenes-60p |
| 20% | nkkbr/ViCA-ARKitScenes-20p |
70% | nkkbr/ViCA-ARKitScenes-70p |
| 30% | nkkbr/ViCA-ARKitScenes-30p |
80% | nkkbr/ViCA-ARKitScenes-80p |
| 40% | nkkbr/ViCA-ARKitScenes-40p |
90% | nkkbr/ViCA-ARKitScenes-90p |
| 50% | nkkbr/ViCA-ARKitScenes-50p |
100% | nkkbr/ViCA-ARKitScenes |
🔗 Raw evaluation outputs: ARKitScenes results
ScanNet++-Only Checkpoints
| Data Usage | Checkpoint | Data Usage | Checkpoint |
|---|---|---|---|
| 10% | nkkbr/ViCA-ScanNetPP-10p |
60% | nkkbr/ViCA-ScanNetPP-60p |
| 20% | nkkbr/ViCA-ScanNetPP-20p |
70% | nkkbr/ViCA-ScanNetPP-70p |
| 30% | nkkbr/ViCA-ScanNetPP-30p |
80% | nkkbr/ViCA-ScanNetPP-80p |
| 40% | nkkbr/ViCA-ScanNetPP-40p |
90% | nkkbr/ViCA-ScanNetPP-90p |
| 50% | nkkbr/ViCA-ScanNetPP-50p |
100% | nkkbr/ViCA-ScanNetPP |
🔗 Raw evaluation outputs: ScanNet++ results
ScanNet-Only Checkpoints
| Data Usage | Checkpoint | Data Usage | Checkpoint |
|---|---|---|---|
| 10% | nkkbr/ViCA-ScanNet-10p |
60% | nkkbr/ViCA-ScanNet-60p |
| 20% | nkkbr/ViCA-ScanNet-20p |
70% | nkkbr/ViCA-ScanNet-70p |
| 30% | nkkbr/ViCA-ScanNet-30p |
80% | nkkbr/ViCA-ScanNet-80p |
| 40% | nkkbr/ViCA-ScanNet-40p |
90% | nkkbr/ViCA-ScanNet-90p |
| 50% | nkkbr/ViCA-ScanNet-50p |
100% | nkkbr/ViCA-ScanNet |
🔗 Raw evaluation outputs: ScanNet results
Additional Probing
Time Instructions
Including 64 frame timestamps in the prompt slightly hurts performance, suggesting that models fail to leverage temporal alignment and are negatively impacted by instruction verbosity.
Figure 5: Adding explicit frame timestamps (64 values) degrades model performance on VSI-Bench, indicating an inability to exploit temporal alignment and sensitivity to prompt length.
More Frames
Increasing input from 64 to 128 frames doubles the number of visual tokens (13,440 → 26,880) but yields no performance gain, highlighting overfitting to fixed token length and architectural inflexibility.
Figure 6: Comparison between 64-frame and 128-frame inputs. Despite doubling the visual token count, performance remains unchanged, indicating overfitting to fixed-length input and limited adaptability to variable-length sequences.
Potential Applications
ViCA-7B supports a broad range of spatially grounded multimodal applications:
- Indoor navigation assistants
- Robotics planning and spatial querying
- Smart room arrangement and AR layout analysis
- Scene understanding for embodied AI agents
Known Limitations
- Limited temporal reasoning: Time instructions not effectively utilized
- Frame scaling issues: Models expect fixed input lengths
- No depth/point cloud: Only RGB video input supported
- Zero-shot generalization is good, but not task-agnostic
Download
You can download the model weights to your local environment (optional).
from huggingface_hub import snapshot_download
save_dir = "./ViCA"
repo_id = "nkkbr/ViCA"
cache_dir = save_dir + "/cache"
snapshot_download(cache_dir=cache_dir,
local_dir=save_dir,
repo_id=repo_id,
local_dir_use_symlinks=False,
resume_download=True,
)
Inference
Here is a runnable example using ViCA-7B on a VSI-Bench question.
# This inference script is adapted from:
# https://huggingface.co/lmms-lab/LLaVA-Video-7B-Qwen2
# pip install git+https://github.com/LLaVA-VL/LLaVA-NeXT.git
from llava.model.builder import load_pretrained_model
from llava.mm_utils import get_model_name_from_path, process_images, tokenizer_image_token
from llava.constants import IMAGE_TOKEN_INDEX, DEFAULT_IMAGE_TOKEN, DEFAULT_IM_START_TOKEN, DEFAULT_IM_END_TOKEN, IGNORE_INDEX
from llava.conversation import conv_templates, SeparatorStyle
from PIL import Image
import requests
import copy
import torch
import sys
import warnings
from decord import VideoReader, cpu
import numpy as np
import json
from tqdm import tqdm
import os
warnings.filterwarnings("ignore")
def load_video(video_path, max_frames_num,fps=1,force_sample=False):
if max_frames_num == 0:
return np.zeros((1, 336, 336, 3))
vr = VideoReader(video_path, ctx=cpu(0),num_threads=1)
total_frame_num = len(vr)
video_time = total_frame_num / vr.get_avg_fps()
fps = round(vr.get_avg_fps()/fps)
frame_idx = [i for i in range(0, len(vr), fps)]
frame_time = [i/fps for i in frame_idx]
if len(frame_idx) > max_frames_num or force_sample:
sample_fps = max_frames_num
uniform_sampled_frames = np.linspace(0, total_frame_num - 1, sample_fps, dtype=int)
frame_idx = uniform_sampled_frames.tolist()
frame_time = [i/vr.get_avg_fps() for i in frame_idx]
frame_time = ",".join([f"{i:.2f}s" for i in frame_time])
spare_frames = vr.get_batch(frame_idx).asnumpy()
# import pdb;pdb.set_trace()
return spare_frames,frame_time,video_time
pretrained = 'nkkbr/ViCA'
model_name = "llava_qwen"
device = "cuda"
device_map = "auto"
tokenizer, model, image_processor, max_length = load_pretrained_model(pretrained, None, model_name, torch_dtype="bfloat16", device_map=device_map) # Add any other thing you want to pass in llava_model_args
model.eval()
from datasets import load_dataset
vsi_bench = load_dataset("nyu-visionx/VSI-Bench")
vsi_bench = vsi_bench['test']
data_curr = vsi_bench[1000]
video_path = f"[VIDEO PATH]"
max_frames_num = 64
video,frame_time,video_time = load_video(video_path, max_frames_num, 1, force_sample=True)
video = image_processor.preprocess(video, return_tensors="pt")["pixel_values"].cuda().to(torch.bfloat16)
video = [video]
conv_template = "qwen_1_5"
# time_instruciton = f"The video lasts for {video_time:.2f} seconds, and {len(video[0])} frames are uniformly sampled from it. These frames are located at {frame_time}.Please answer the following questions related to this video."
time_instruciton = ""
question = DEFAULT_IMAGE_TOKEN + f"\n{time_instruciton}\n\n"
question += f"These are frames of a video.\n\n"
question += f"Question: {data_curr['question']}\n"
if data_curr['options'] is not None:
question += '\n'.join(data_curr['options']) + "\n"
question += f"Answer with the option’s letter from the given choices directly.\n"
else:
question += f"Please answer the question using a single word or phrase.\n"
print(f"Prompt:\n{question}")
conv = copy.deepcopy(conv_templates[conv_template])
conv.append_message(conv.roles[0], question)
conv.append_message(conv.roles[1], None)
prompt_question = conv.get_prompt()
input_ids = tokenizer_image_token(prompt_question, tokenizer, IMAGE_TOKEN_INDEX, return_tensors="pt").unsqueeze(0).to(device)
cont = model.generate(
input_ids,
images=video,
modalities= ["video"],
do_sample=False,
temperature=0,
max_new_tokens=1024,
)
text_outputs = tokenizer.batch_decode(cont, skip_special_tokens=True)[0].strip()
print(repr(text_outputs))