Instructions to use ByteDance/Sa2VA-Qwen3-VL-4B-SAM3 with libraries, inference providers, notebooks, and local apps. Follow these links to get started.

Libraries

How to use ByteDance/Sa2VA-Qwen3-VL-4B-SAM3 with Transformers:

# Use a pipeline as a high-level helper
from transformers import pipeline

pipe = pipeline("image-text-to-text", model="ByteDance/Sa2VA-Qwen3-VL-4B-SAM3", trust_remote_code=True)
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 AutoModel
model = AutoModel.from_pretrained("ByteDance/Sa2VA-Qwen3-VL-4B-SAM3", trust_remote_code=True, device_map="auto")

Notebooks
Google Colab
Kaggle
Local Apps Settings

vLLM

How to use ByteDance/Sa2VA-Qwen3-VL-4B-SAM3 with vLLM:

Install from pip and serve model

# Install vLLM from pip:
pip install vllm
# Start the vLLM server:
vllm serve "ByteDance/Sa2VA-Qwen3-VL-4B-SAM3"
# Call the server using curl (OpenAI-compatible API):
curl -X POST "http://localhost:8000/v1/chat/completions" \
	-H "Content-Type: application/json" \
	--data '{
		"model": "ByteDance/Sa2VA-Qwen3-VL-4B-SAM3",
		"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/ByteDance/Sa2VA-Qwen3-VL-4B-SAM3

SGLang

How to use ByteDance/Sa2VA-Qwen3-VL-4B-SAM3 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 "ByteDance/Sa2VA-Qwen3-VL-4B-SAM3" \
    --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": "ByteDance/Sa2VA-Qwen3-VL-4B-SAM3",
		"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 "ByteDance/Sa2VA-Qwen3-VL-4B-SAM3" \
        --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": "ByteDance/Sa2VA-Qwen3-VL-4B-SAM3",
		"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 ByteDance/Sa2VA-Qwen3-VL-4B-SAM3 with Docker Model Runner:
```
docker model run hf.co/ByteDance/Sa2VA-Qwen3-VL-4B-SAM3
```

Sa2VA-Qwen3-VL-4B-SAM3

Sa2VA-Qwen3-VL-4B-SAM3 is a Sa2VA model built on Qwen3-VL-4B-Instruct with a SAM3 PVS-tracker grounding encoder. The MLLM predicts a [SEG] token whose hidden state conditions the SAM3 mask decoder, producing dense image and video referring segmentation alongside open-ended chat.

This checkpoint is self-contained: the SAM3 grounding code is vendored into the repository, so it loads with trust_remote_code=True without any extra packages.

Results

Image referring segmentation (cIoU):

RefCOCO val / testA / testB	RefCOCO+ val / testA / testB	RefCOCOg val / test
83.7 / 84.7 / 81.9	79.4 / 83.2 / 76.0	83.0 / 83.0

Video referring segmentation (J&F):

MeViS (val_u)	ReVOS	Ref-DAVIS17
65.3	66.3	77.1

Grounded conversation generation (GCG, val):

AP50	mIoU	Recall
37.1	70.1	49.4

Usage

import torch
from transformers import AutoModel, AutoProcessor
from PIL import Image

path = "HarborYuan/Sa2VA-Qwen3-VL-4B-SAM3"
model = AutoModel.from_pretrained(
    path, torch_dtype=torch.bfloat16, trust_remote_code=True, low_cpu_mem_usage=True,
).eval().cuda()
processor = AutoProcessor.from_pretrained(path, trust_remote_code=True)

image = Image.open("your_image.jpg").convert("RGB")
out = model.predict_forward(
    image=image,
    text="Please segment the dog in the image.",
    processor=processor,
)
print(out["prediction"])          # text response containing [SEG]
masks = out["prediction_masks"]   # list of boolean masks at the original image size

Load in bfloat16 (the lm_head is kept in higher precision; torch_dtype="auto" mixes dtypes and fails).

For video, pass video=[frame0, frame1, ...] (a list of PIL images) instead of image.

Notes

SAM3 grounding input resolution is 1008.
Built on Sa2VA.

Citation

If you find this project useful in your research, please consider citing:

@article{sa2va,
  title={Sa2VA: Marrying SAM2 with LLaVA for Dense Grounded Understanding of Images and Videos},
  author={Yuan, Haobo and Li, Xiangtai and Zhang, Tao and Sun, Yueyi and Huang, Zilong and Xu, Shilin and Ji, Shunping and Tong, Yunhai and Qi, Lu and Feng, Jiashi and Yang, Ming-Hsuan},
  journal={IEEE TPAMI},
  year={2026}
}

Downloads last month: 42

Safetensors

Model size

5B params

Tensor type

F32