Instructions to use SpatialAxiom/SpatialAxiom-35B-A3B with libraries, inference providers, notebooks, and local apps. Follow these links to get started.
- Libraries
- Transformers
How to use SpatialAxiom/SpatialAxiom-35B-A3B with Transformers:
# Use a pipeline as a high-level helper from transformers import pipeline pipe = pipeline("image-text-to-text", model="SpatialAxiom/SpatialAxiom-35B-A3B") messages = [ { "role": "user", "content": [ {"type": "image", "url": "https://huggingface.co/datasets/huggingface/documentation-images/resolve/main/p-blog/candy.JPG"}, {"type": "text", "text": "What animal is on the candy?"} ] }, ] pipe(text=messages)# Load model directly from transformers import AutoProcessor, AutoModelForMultimodalLM processor = AutoProcessor.from_pretrained("SpatialAxiom/SpatialAxiom-35B-A3B") model = AutoModelForMultimodalLM.from_pretrained("SpatialAxiom/SpatialAxiom-35B-A3B", device_map="auto") messages = [ { "role": "user", "content": [ {"type": "image", "url": "https://huggingface.co/datasets/huggingface/documentation-images/resolve/main/p-blog/candy.JPG"}, {"type": "text", "text": "What animal is on the candy?"} ] }, ] inputs = processor.apply_chat_template( messages, add_generation_prompt=True, tokenize=True, return_dict=True, return_tensors="pt", ).to(model.device) outputs = model.generate(**inputs, max_new_tokens=40) print(processor.decode(outputs[0][inputs["input_ids"].shape[-1]:])) - Notebooks
- Google Colab
- Kaggle
- Local Apps Settings
- vLLM
How to use SpatialAxiom/SpatialAxiom-35B-A3B with vLLM:
Install from pip and serve model
# Install vLLM from pip: pip install vllm # Start the vLLM server: vllm serve "SpatialAxiom/SpatialAxiom-35B-A3B" # Call the server using curl (OpenAI-compatible API): curl -X POST "http://localhost:8000/v1/chat/completions" \ -H "Content-Type: application/json" \ --data '{ "model": "SpatialAxiom/SpatialAxiom-35B-A3B", "messages": [ { "role": "user", "content": [ { "type": "text", "text": "Describe this image in one sentence." }, { "type": "image_url", "image_url": { "url": "https://cdn.britannica.com/61/93061-050-99147DCE/Statue-of-Liberty-Island-New-York-Bay.jpg" } } ] } ] }'Use Docker
docker model run hf.co/SpatialAxiom/SpatialAxiom-35B-A3B
- SGLang
How to use SpatialAxiom/SpatialAxiom-35B-A3B with SGLang:
Install from pip and serve model
# Install SGLang from pip: pip install sglang # Start the SGLang server: python3 -m sglang.launch_server \ --model-path "SpatialAxiom/SpatialAxiom-35B-A3B" \ --host 0.0.0.0 \ --port 30000 # Call the server using curl (OpenAI-compatible API): curl -X POST "http://localhost:30000/v1/chat/completions" \ -H "Content-Type: application/json" \ --data '{ "model": "SpatialAxiom/SpatialAxiom-35B-A3B", "messages": [ { "role": "user", "content": [ { "type": "text", "text": "Describe this image in one sentence." }, { "type": "image_url", "image_url": { "url": "https://cdn.britannica.com/61/93061-050-99147DCE/Statue-of-Liberty-Island-New-York-Bay.jpg" } } ] } ] }'Use Docker images
docker run --gpus all \ --shm-size 32g \ -p 30000:30000 \ -v ~/.cache/huggingface:/root/.cache/huggingface \ --env "HF_TOKEN=<secret>" \ --ipc=host \ lmsysorg/sglang:latest \ python3 -m sglang.launch_server \ --model-path "SpatialAxiom/SpatialAxiom-35B-A3B" \ --host 0.0.0.0 \ --port 30000 # Call the server using curl (OpenAI-compatible API): curl -X POST "http://localhost:30000/v1/chat/completions" \ -H "Content-Type: application/json" \ --data '{ "model": "SpatialAxiom/SpatialAxiom-35B-A3B", "messages": [ { "role": "user", "content": [ { "type": "text", "text": "Describe this image in one sentence." }, { "type": "image_url", "image_url": { "url": "https://cdn.britannica.com/61/93061-050-99147DCE/Statue-of-Liberty-Island-New-York-Bay.jpg" } } ] } ] }' - Docker Model Runner
How to use SpatialAxiom/SpatialAxiom-35B-A3B with Docker Model Runner:
docker model run hf.co/SpatialAxiom/SpatialAxiom-35B-A3B
SpatialAxiom-35B-A3B
Introduction
We are thrilled to release SpatialAxiom, an open spatial intelligence model for general spatial reasoning that achieves significant advances in 3D relational inference, perspective taking, multi-view correspondence, and embodied video understanding. Built on the Qwen3.5 VLM family without altering the base architecture, SpatialAxiom derives its strength from a spatial data-centric training recipe: a systematic taxonomy of spatial tasks, balanced task distribution, and data synthesis to raise data quality, applied to large-scale spatial supervision spanning indoor scenes, egocentric views, and multi-camera settings. Trained purely with full-parameter SFT, SpatialAxiom serves as a clean starting point for further post-training. We release two open-weight models: SpatialAxiom-9B, a compact dense model, and SpatialAxiom-35B-A3B, a mixture-of-experts model with 3B active parameters.
Highlights
Leading spatial reasoning: On average, our models surpass proprietary models and larger open-source alternatives, with leading results on VSI-Bench, MMSI-Bench, MindCube, ViewSpatial, and EmbSpatial.
Spatial data-centric training recipe: A systematic taxonomy of spatial tasks, balanced task distribution, and data synthesis to raise data quality. SpatialAxiom is trained purely with full-parameter SFT and serves as a clean starting point for downstream fine-tuning or RL.
Qwen3.5 VLM backbone: Inherits the Qwen3.5 vision-language model architecture, preserving a general-purpose multimodal design without task-specific architectural modifications.
Open-weight release: SpatialAxiom-9B and SpatialAxiom-35B-A3B are publicly released on Hugging Face, compatible with
transformersandvLLMout of the box.
Model Overview
- Type: Causal Language Model with Vision Encoder
- Training Stage: Pre-training & Post-training
- Language Model
- Number of Parameters: 35B in total and 3B activated
- Hidden Dimension: 2048
- Token Embedding: 248320 (Padded)
- Number of Layers: 40
- Hidden Layout: 10 × (3 × (Gated DeltaNet → MoE) → 1 × (Gated Attention → MoE))
- Gated DeltaNet:
- Number of Linear Attention Heads: 32 for V and 16 for QK
- Head Dimension: 128
- Gated Attention:
- Number of Attention Heads: 16 for Q and 2 for KV
- Head Dimension: 256
- Rotary Position Embedding Dimension: 64
- Mixture Of Experts
- Number of Experts: 256
- Number of Activated Experts: 8 Routed + 1 Shared
- Expert Intermediate Dimension: 512
- LM Output: 248320 (Padded)
- MTP: trained with multi-steps
- Context Length: 262,144 natively and extensible up to 1,010,000 tokens.
Spatial Benchmark Results
| Rank | Model | Avg | VSI-Bench | MMSI-Bench | MindCube | ViewSpatial | SITE | BLINK | 3DSR | EmbSpatial |
|---|---|---|---|---|---|---|---|---|---|---|
| 1 | SpatialAxiom-35B-A3B | 70.8 | 72.8 | 50.0 | 91.7 | 66.8 | 56.4 | 75.8 | 66.3 | 86.6 |
| 2 | SpatialAxiom-9B | 70.6 | 70.2 | 51.8 | 92.5 | 70.6 | 53.3 | 76.9 | 64.2 | 85.1 |
| 3 | Gemini-3.5-Flash | 69.2 | 63.1 | 50.7 | 77.6 | 56.0 | 70.6 | 80.0 | 72.5 | 83.1 |
| 4 | Qwen3.7-Plus | 66.6 | 63.3 | 45.0 | 68.6 | 54.9 | 71.3 | 76.0 | 69.7 | 83.8 |
| 5 | Gemini-3.1-Pro | 66.5 | 57.5 | 49.5 | 76.4 | 53.1 | 67.0 | 77.3 | 67.3 | 84.0 |
| 6 | SenseNova-SI-1.5-InternVL3-8B | 64.4 | 67.3 | 38.3 | 92.1 | 59.0 | 47.5 | 69.5 | 61.1 | 80.4 |
| 7 | Qwen3.6-27B | 61.6 | 59.8 | 41.1 | 59.9 | 51.5 | 66.0 | 70.6 | 60.7 | 83.4 |
| 8 | Kimi-K2.6 | 61.3 | 54.9 | 37.9 | 67.4 | 46.7 | 63.6 | 75.2 | 64.1 | 80.8 |
| 9 | Qwen3.5-35B-A3B | 61.2 | 58.1 | 41.9 | 63.5 | 50.8 | 61.4 | 70.5 | 59.8 | 83.6 |
| 10 | GPT-5.5 | 60.7 | 60.4 | 42.2 | 65.5 | 46.5 | 58.3 | 73.3 | 59.0 | 80.3 |
| 11 | Qwen3.6-35B-A3B | 60.5 | 56.0 | 40.2 | 60.4 | 50.7 | 63.4 | 69.3 | 60.0 | 83.8 |
| 12 | Gemma-4-31B | 57.2 | 48.1 | 37.0 | 63.3 | 45.3 | 58.0 | 70.3 | 54.4 | 81.0 |
| 13 | Qwen3.5-9B | 55.9 | 54.3 | 38.7 | 57.6 | 48.2 | 42.3 | 67.6 | 56.8 | 81.5 |
| 14 | Seed1.6 | 54.2 | 49.9 | 38.3 | 48.8 | 43.9 | 54.6 | 65.9 | 56.9 | 75.4 |
| 15 | InternVL3.5-8B | 49.0 | 56.1 | 29.0 | 40.2 | 40.0 | 43.8 | 58.2 | 49.2 | 75.7 |
| 16 | Gemma-4-26B-A4B | 47.8 | 32.9 | 29.2 | 48.8 | 41.7 | 39.7 | 63.8 | 53.6 | 72.3 |
| 17 | BAGEL-7B-MoT | 45.3 | 31.4 | 31.0 | 34.7 | 41.3 | 37.0 | 63.6 | 50.2 | 73.1 |
| 18 | Cambrian-S-7B | 45.1 | 62.9 | 27.1 | 37.9 | 41.3 | 36.1 | 37.9 | 45.0 | 72.8 |
Quickstart
SpatialAxiom-35B-A3B is fine-tuned from Qwen3.5-35B-A3B for direct (non-thinking) responses only. It does not produce thinking blocks (no chain-of-thought wrapped in special tags). Do not enable thinking mode at inference time (
enable_thinkingmust remainfalse). The model does not support/thinkor/nothinksoft switches.
Transformers (image)
The latest transformers with Qwen3.5 VLM support is required. Make sure torchvision and pillow are installed.
from transformers import AutoModelForMultimodalLM, AutoProcessor
model_id = "<HF_REPO_ID>"
model = AutoModelForMultimodalLM.from_pretrained(
model_id, dtype="bfloat16", device_map="auto"
)
processor = AutoProcessor.from_pretrained(model_id)
messages = [
{
"role": "user",
"content": [
{"type": "image", "url": "room.jpg"},
{
"type": "text",
"text": "If I stand at the door facing the bed, is the chair to my left or right?",
},
],
}
]
inputs = processor.apply_chat_template(
messages,
add_generation_prompt=True,
tokenize=True,
return_dict=True,
return_tensors="pt",
enable_thinking=False,
).to(model.device)
out = model.generate(**inputs, max_new_tokens=32768)
print(
processor.batch_decode(
out[:, inputs["input_ids"].shape[1]:], skip_special_tokens=True
)[0]
)
Transformers (video)
messages = [
{
"role": "user",
"content": [
{"type": "video", "url": "https://example.com/walkthrough.mp4"},
{
"type": "text",
"text": "Estimate the size of the room in square meters and describe the route taken.",
},
],
}
]
# Same apply_chat_template / generate flow as above.
Serving with vLLM
vLLM is recommended for production serving. A recent vLLM build with Qwen3.5 support is required, which can be installed in a fresh environment with:
uv pip install vllm --torch-backend=auto --extra-index-url https://wheels.vllm.ai/nightly
vllm serve <HF_REPO_ID> \
--port 8000 \
--tensor-parallel-size 4 \
--max-model-len 65536 \
--default-chat-template-kwargs '{"enable_thinking": false}' \
--served-model-name spatialaxiom-35b-a3b
OpenAI-compatible API
Install the OpenAI SDK and point it at your vLLM server:
pip install -U openai
export OPENAI_BASE_URL="http://localhost:8000/v1"
export OPENAI_API_KEY="EMPTY"
Image input
from openai import OpenAI
client = OpenAI()
messages = [
{
"role": "user",
"content": [
{"type": "image_url", "image_url": {"url": "https://example.com/room.jpg"}},
{
"type": "text",
"text": "If I stand at the door facing the bed, is the chair to my left or right?",
},
],
}
]
chat_response = client.chat.completions.create(
model="spatialaxiom-35b-a3b",
messages=messages,
max_tokens=32768,
temperature=0,
top_p=0.95,
)
print(chat_response.choices[0].message.content)
Video input
from openai import OpenAI
client = OpenAI()
messages = [
{
"role": "user",
"content": [
{
"type": "video_url",
"video_url": {"url": "https://example.com/walkthrough.mp4"},
},
{
"type": "text",
"text": "Describe the spatial layout and the route taken through the room.",
},
],
}
]
# Video frame sampling (vLLM): default fps=2, do_sample_frames=True.
# Customizing fps via extra_body requires launching vLLM with
# --media-io-kwargs '{"video": {"num_frames": -1}}'.
chat_response = client.chat.completions.create(
model="spatialaxiom-35b-a3b",
messages=messages,
max_tokens=32768,
temperature=0,
top_p=0.95,
extra_body={
"mm_processor_kwargs": {"fps": 2, "do_sample_frames": True},
},
)
print(chat_response.choices[0].message.content)
If the vLLM server was not launched with --default-chat-template-kwargs '{"enable_thinking": false}', add it per request:
extra_body={
"chat_template_kwargs": {"enable_thinking": False},
}
Citation
If you find our work helpful, feel free to give us a cite.
@misc{spatialaxiom,
title = {SpatialAxiom: An Open Spatial Intelligence Model for General Spatial Reasoning},
author = {Lou, Yujing and Chen, Pingyi and Cao, Shen and Gu, Jiaqi and Guo, Jinhui and Tong, Jintao and Hao, Yunzhuo and Liu, Yao and Fan, Lubin and Wu, Yue and Ye, Jieping},
month = {July},
year = {2026},
url = {https://d2i-ai.github.io/SpatialAxiom}
}
- Downloads last month
- -


docker model run hf.co/SpatialAxiom/SpatialAxiom-35B-A3B