Spacethinker Qwen2.5VL 3B

🚀 SpaceThinker-Qwen2.5VL-3B

SpaceThinker-Qwen2.5VL-3B 是一款多模態/視覺語言模型（VLM），專注于思考和推理能力。它通過在合成推理軌跡上微調基礎模型，增強了空間推理能力，可廣泛應用於需要空間規劃和導航的具身AI領域。

🚀 快速開始

• 在線體驗：點擊 在線試用 SpaceThinker。
• 本地運行：
  • 使用 llama.cpp：安裝並構建 此分支，並從 這裡 下載 .gguf 權重。

./llama-qwen2vl-cli -m spacethinker-qwen2.5VL-3B-F16.gguf
--mmproj spacethinker-qwen2.5vl-3b-vision.gguf
--image images/example_1.jpg --threads 24 -ngl 9
-p "Does the man in blue shirt working have a greater \\
height compared to the wooden pallet with boxes on floor?" 

- **使用 Colab 中的 llama.cpp**：點擊 [![Open In Colab](https://colab.research.google.com/assets/colab-badge.svg)](https://colab.research.google.com/drive/1_ShhJAqnac8L4N9o1YNdsxCksSLJCrU7?usp=sharing) 在 Colab 中運行。
- **使用 Transformers**：

import torch
from PIL import Image
from transformers import Qwen2_5_VLForConditionalGeneration, AutoProcessor
import requests
from io import BytesIO

# Configuration
model_id = "remyxai/SpaceThinker-Qwen2.5VL-3B"
image_path = "images/example_1.jpg"  # or local path
prompt = "What can you infer from this image about the environment?"
system_message = (
  "You are VL-Thinking 🤔, a helpful assistant with excellent reasoning ability. "
  "You should first think about the reasoning process and then provide the answer. "
  "Use <think>...</think> and <answer>...</answer> tags."
)

# Load model and processor
model = Qwen2_5_VLForConditionalGeneration.from_pretrained(
    model_id, device_map="auto", torch_dtype=torch.bfloat16
)
processor = AutoProcessor.from_pretrained(model_id)

# Load and preprocess image
if image_path.startswith("http"):
    image = Image.open(BytesIO(requests.get(image_path).content)).convert("RGB")
else:
    image = Image.open(image_path).convert("RGB")
if image.width > 512:
    ratio = image.height / image.width
    image = image.resize((512, int(512 * ratio)), Image.Resampling.LANCZOS)

# Format input
chat = [
    {"role": "system", "content": [{"type": "text", "text": system_message}]},
    {"role": "user", "content": [{"type": "image", "image": image},
                                {"type": "text", "text": prompt}]}
]
text_input = processor.apply_chat_template(chat, tokenize=False,
                                                  add_generation_prompt=True)

# Tokenize
inputs = processor(text=[text_input], images=[image],
                                      return_tensors="pt").to("cuda")

# Generate response
generated_ids = model.generate(**inputs, max_new_tokens=1024)
output = processor.batch_decode(generated_ids, skip_special_tokens=True)[0]

print("Response:\n", output)

✨ 主要特性

• 多模態與視覺語言融合：作為多模態、視覺語言模型，能夠處理圖像和文本信息。
• 強大的空間推理能力：經過訓練，增強了定量空間推理能力，如距離估計、物體空間關係判斷等。
• 基於測試時計算的優化：通過測試時計算，提升模型在空間推理任務中的表現。

📦 安裝指南

使用 llama.cpp

安裝並構建 此分支，並從 這裡 下載 .gguf 權重。

使用 Transformers

確保安裝了 torch、transformers、Pillow、requests 等必要庫。

💻 使用示例

基礎用法

import torch
from PIL import Image
from transformers import Qwen2_5_VLForConditionalGeneration, AutoProcessor
import requests
from io import BytesIO

# Configuration
model_id = "remyxai/SpaceThinker-Qwen2.5VL-3B"
image_path = "images/example_1.jpg"  # or local path
prompt = "What can you infer from this image about the environment?"
system_message = (
  "You are VL-Thinking 🤔, a helpful assistant with excellent reasoning ability. "
  "You should first think about the reasoning process and then provide the answer. "
  "Use <think>...</think> and <answer>...</answer> tags."
)

# Load model and processor
model = Qwen2_5_VLForConditionalGeneration.from_pretrained(
    model_id, device_map="auto", torch_dtype=torch.bfloat16
)
processor = AutoProcessor.from_pretrained(model_id)

# Load and preprocess image
if image_path.startswith("http"):
    image = Image.open(BytesIO(requests.get(image_path).content)).convert("RGB")
else:
    image = Image.open(image_path).convert("RGB")
if image.width > 512:
    ratio = image.height / image.width
    image = image.resize((512, int(512 * ratio)), Image.Resampling.LANCZOS)

# Format input
chat = [
    {"role": "system", "content": [{"type": "text", "text": system_message}]},
    {"role": "user", "content": [{"type": "image", "image": image},
                                {"type": "text", "text": prompt}]}
]
text_input = processor.apply_chat_template(chat, tokenize=False,
                                                  add_generation_prompt=True)

# Tokenize
inputs = processor(text=[text_input], images=[image],
                                      return_tensors="pt").to("cuda")

# Generate response
generated_ids = model.generate(**inputs, max_new_tokens=1024)
output = processor.batch_decode(generated_ids, skip_special_tokens=True)[0]

print("Response:\n", output)

高級用法

在實際應用中，可以根據具體需求調整輸入的圖像、提示信息和系統消息，以滿足不同的空間推理任務。

📚 詳細文檔

模型概述

SpaceThinker-Qwen2.5VL-3B 是通過在 VQASynth 管道生成的合成推理軌跡上微調 UCSC-VLAA/VLAA-Thinker-Qwen2.5VL-3B 而得到的多模態/視覺語言模型。

空間推理能力

強大的定量空間推理能力對於需要在3D空間中進行規劃和導航的具身AI應用（如機器人和無人機）至關重要。SpaceThinker 通過測試時計算提升了能力，其訓練樣本基於對場景觀察的一致解釋來確定最終響應。

• 增強的定量空間推理：能夠準確估計距離、大小等空間信息。
• 基於實際的物體關係判斷：如判斷物體的上下、左右、包含等關係。

示例展示

提示：戴紅帽子的男人離裝著箱子的托盤有多遠（英尺）？	提示：在這張圖片中，球門離罰球者有多遠？	提示：椅子和書架大約相隔多少米？
推理過程：要確定戴紅帽子的男人離裝著箱子的托盤有多遠，我需要考慮倉庫中的空間佈局。男人在地板上行走，他和托盤之間有明顯的間隙。首先，我會估計托盤的大小。一個標準托盤通常約4英尺寬、8英尺長。鑑於男人站在托盤邊緣附近，他可能離托盤前緣約2 - 3英尺。接下來，我會考慮從托盤到男人的距離。男人似乎沿著過道行走，過道看起來約6 - 7英尺寬。如果他站在托盤邊緣，他可能離托盤前緣約2 - 3英尺。綜合這些觀察，戴紅帽子的男人離裝著箱子的托盤大約2 - 3英尺。	推理過程：首先，我觀察到一名穿紅色制服的球員站在球門附近的場景。球門本身是一個標準的足球門柱，通常超出球門線2.5米。球員似乎站在靠近球門的位置，但不是直接在球門線上。為了估計距離，我考慮到球員相對於球門的位置表明他可能站在距離球門不到2.5米的地方。鑑於點球場景的典型設置，球員會比球門本身更靠後。通過視覺估計，球員似乎站在距離球門約10 - 15米的地方。這個範圍與點球的常見距離相符，考慮到球員的站位和球門的結構。因此，球門到罰球者的距離可能約為10 - 15米。	推理過程：為了確定椅子和書架之間的距離，我會考慮這些物體的典型尺寸。一把標準辦公椅約60 - 70釐米高，書架的高度可以在1.2到1.8米之間。鑑於椅子可能放在桌子或地板上，椅子和書架頂部之間的高度差約為1米。假設書架至少1米高，椅子在地面上，它們之間的垂直距離確實是1米。水平距離可能會根據佈局而有所不同，但考慮到房間的尺寸和椅子相對於書架的位置，椅子和書架頂部之間的總距離可能約為1米。因此，椅子和書架大約相隔1米。
答案：2 - 3英尺	答案：10 - 15米	答案：1米

數據集信息

SpaceThinker 數據集包含約12K個合成的空間推理軌跡，由 VQASynth 在 the cauldron 的局部敘事分割圖像子集上合成。

訓練配置

PEFT 配置

可以使用以下腳本重現 LoRA SFT 訓練：

python train.py

Wandb 日誌可在 這裡 查看。

模型評估

使用 Q-Spatial-Bench 數據集 對 SpaceThinker 進行評估，該數據集包含數百個高精度的視覺問答樣本，用於評估視覺語言模型的定量空間推理能力。

• 默認系統提示：完成提示 93 / 101，正確答案 30 個，準確率 32.26%。
• 使用逐步推理提示：使用 Q-Spatial-Bench 中的空間提示，正確答案 53 個，準確率 52.48%。

使用空間提示可以提高正確答案的數量和整體準確率，同時提高任務完成率。

QSpatial++ 比較表（4/25/25）

模型	SpaceThinker-Qwen2.5VL-3B	gpt-4o	gemini-2.5-pro-preview-03-25
QSpatial++ 預測示例
Colab 筆記本鏈接
成功率（%）↑	55	43	52
完成樣本數 ↑	99 / 100	95 / 100	99 / 100
對稱平均絕對百分比誤差（%）↓	66	71	62

指標說明

• 成功率（%）：越高越好。
• 完成樣本數：越高越好。
• 對稱平均絕對百分比誤差（%）：越低越好。

🔧 技術細節

模型架構

基於 Qwen2.5-VL-3B 架構，通過 LoRA 微調對基礎模型 UCSC-VLAA/VLAA-Thinker-Qwen2.5VL-3B 進行優化。

訓練過程

使用合成的空間推理軌跡數據進行訓練，採用 LoRA 微調方法，設置了特定的 LoRA 參數（Alpha = 256，Rank = 128）和目標模塊（q_proj, v_proj）。優化器使用 AdamW，學習率為 2e-5，批量大小為 1，訓練輪數為 3。

推理機制

在推理過程中，模型結合圖像和文本輸入，通過測試時計算進行空間推理，使用 <think>...</think> 和 <answer>...</answer> 標籤來組織推理過程和輸出答案。

📄 許可證

本項目採用 Apache-2.0 許可證。

⚠️ 侷限性

• 環境適應性：在雜亂環境或特定相機視角下，模型性能可能會下降。
• 數據侷限性：模型是在互聯網圖像數據集上使用合成推理進行微調的，可能存在一定的偏差。
• 基礎模型偏差：基礎模型（Qwen2.5-VL）固有的多模態偏差可能仍然存在。
• 適用範圍：不適合用於安全關鍵或法律決策場景。

建議用戶批判性地評估模型輸出，並考慮針對特定領域進行微調，以提高安全性和性能。使用自迴歸變壓器估計的距離可用於規劃和行為的高階推理，但不能替代高精度傳感器、校準立體視覺系統或能夠進行更準確像素級預測和即時性能的專業單目深度估計模型的測量結果。

📜 引用

@article{chen2024spatialvlm,
  title = {SpatialVLM: Endowing Vision-Language Models with Spatial Reasoning Capabilities},
  author = {Chen, Boyuan and Xu, Zhuo and Kirmani, Sean and Ichter, Brian and Driess, Danny and Florence, Pete and Sadigh, Dorsa and Guibas, Leonidas and Xia, Fei},
  journal = {arXiv preprint arXiv:2401.12168},
  year = {2024},
  url = {https://arxiv.org/abs/2401.12168},
}

@misc{qwen2.5-VL,
  title = {Qwen2.5-VL},
  url = {https://qwenlm.github.io/blog/qwen2.5-vl/},
  author = {Qwen Team},
  month = {January},
  year = {2025}
}

@misc{vl-thinking2025,
  title={SFT or RL? An Early Investigation into Training R1-Like Reasoning Large Vision-Language Models },
  author={Hardy Chen and Haoqin Tu and Fali Wang and Hui Liu and Xianfeng Tang and Xinya Du and Yuyin Zhou and Cihang Xie},
  year = {2025},
  publisher = {GitHub},
  journal = {GitHub repository},
  howpublished = {\url{https://github.com/UCSC-VLAA/VLAA-Thinking}},
}

@inproceedings{
  liaos2024reasoning,
  title={Reasoning Paths with Reference Objects Elicit Quantitative Spatial Reasoning in Large Vision-Language Models},
  author={Yuan-Hong Liao and Rafid Mahmood and Sanja Fidler and David Acuna},
  booktitle={The 2024 Conference on Empirical Methods in Natural Language Processing},
  year={2024},
  url={https://arxiv.org/abs/2409.09788},
}