Instructions to use unsloth/gemma-3-12b-it-unsloth-bnb-4bit with libraries, inference providers, notebooks, and local apps. Follow these links to get started.

Libraries

How to use unsloth/gemma-3-12b-it-unsloth-bnb-4bit with Transformers:

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

pipe = pipeline("image-text-to-text", model="unsloth/gemma-3-12b-it-unsloth-bnb-4bit")
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("unsloth/gemma-3-12b-it-unsloth-bnb-4bit")
model = AutoModelForMultimodalLM.from_pretrained("unsloth/gemma-3-12b-it-unsloth-bnb-4bit", 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 unsloth/gemma-3-12b-it-unsloth-bnb-4bit with vLLM:

Install from pip and serve model

# Install vLLM from pip:
pip install vllm
# Start the vLLM server:
vllm serve "unsloth/gemma-3-12b-it-unsloth-bnb-4bit"
# Call the server using curl (OpenAI-compatible API):
curl -X POST "http://localhost:8000/v1/chat/completions" \
	-H "Content-Type: application/json" \
	--data '{
		"model": "unsloth/gemma-3-12b-it-unsloth-bnb-4bit",
		"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/unsloth/gemma-3-12b-it-unsloth-bnb-4bit

SGLang

How to use unsloth/gemma-3-12b-it-unsloth-bnb-4bit 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 "unsloth/gemma-3-12b-it-unsloth-bnb-4bit" \
    --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": "unsloth/gemma-3-12b-it-unsloth-bnb-4bit",
		"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 "unsloth/gemma-3-12b-it-unsloth-bnb-4bit" \
        --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": "unsloth/gemma-3-12b-it-unsloth-bnb-4bit",
		"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"
						}
					}
				]
			}
		]
	}'

Unsloth Studio

How to use unsloth/gemma-3-12b-it-unsloth-bnb-4bit with Unsloth Studio:

Install Unsloth Studio (macOS, Linux, WSL)

curl -fsSL https://unsloth.ai/install.sh | sh
# Run unsloth studio
unsloth studio -H 0.0.0.0 -p 8888
# Then open http://localhost:8888 in your browser
# Search for unsloth/gemma-3-12b-it-unsloth-bnb-4bit to start chatting

Install Unsloth Studio (Windows)

irm https://unsloth.ai/install.ps1 | iex
# Run unsloth studio
unsloth studio -H 0.0.0.0 -p 8888
# Then open http://localhost:8888 in your browser
# Search for unsloth/gemma-3-12b-it-unsloth-bnb-4bit to start chatting

Using HuggingFace Spaces for Unsloth

# No setup required
# Open https://huggingface.co/spaces/unsloth/studio in your browser
# Search for unsloth/gemma-3-12b-it-unsloth-bnb-4bit to start chatting

Load model with FastModel

pip install unsloth
from unsloth import FastModel
model, tokenizer = FastModel.from_pretrained(
    model_name="unsloth/gemma-3-12b-it-unsloth-bnb-4bit",
    max_seq_length=2048,
)

Docker Model Runner
How to use unsloth/gemma-3-12b-it-unsloth-bnb-4bit with Docker Model Runner:
```
docker model run hf.co/unsloth/gemma-3-12b-it-unsloth-bnb-4bit
```

Error loading model with vllm

by ggeo - opened Mar 20, 2025

Discussion

ggeo

Mar 20, 2025

I have downloaded the model and when i try to start with vllm:

        --max-model-len 1024 \
        --max-num-seqs 10 \
        --dtype bfloat16 \
        --device=cuda \
        --trust-remote-code \
        --max-num-batched-tokens 24576 \
        --gpu-memory-utilization 0.8 \
        --host 0.0.0.0 \
        --port 8080```

it gives me:


        ERROR 03-20 12:24:30 [engine.py:443] 
Traceback (most recent call last):
  File "/home/ggous/vllm/lib/python3.11/site-packages/vllm/engine/multiprocessing/engine.py", line 431, in run_mp_engine
    engine = MQLLMEngine.from_vllm_config(
             ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
  File "/home/ggous/vllm/lib/python3.11/site-packages/vllm/engine/multiprocessing/engine.py", line 126, in from_vllm_config
    return cls(
           ^^^^
  File "/home/ggous/vllm/lib/python3.11/site-packages/vllm/engine/multiprocessing/engine.py", line 80, in __init__
    self.engine = LLMEngine(*args, **kwargs)
                  ^^^^^^^^^^^^^^^^^^^^^^^^^^
  File "/home/ggous/vllm/lib/python3.11/site-packages/vllm/engine/llm_engine.py", line 280, in __init__
    self.model_executor = executor_class(vllm_config=vllm_config, )
                          ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
  File "/home/ggous/vllm/lib/python3.11/site-packages/vllm/executor/executor_base.py", line 52, in __init__
    self._init_executor()
  File "/home/ggous/vllm/lib/python3.11/site-packages/vllm/executor/uniproc_executor.py", line 47, in _init_executor
    self.collective_rpc("load_model")
  File "/home/ggous/vllm/lib/python3.11/site-packages/vllm/executor/uniproc_executor.py", line 56, in collective_rpc
    answer = run_method(self.driver_worker, method, args, kwargs)
             ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
  File "/home/ggous/vllm/lib/python3.11/site-packages/vllm/utils.py", line 2216, in run_method
    return func(*args, **kwargs)
           ^^^^^^^^^^^^^^^^^^^^^
  File "/home/ggous/vllm/lib/python3.11/site-packages/vllm/worker/worker.py", line 183, in load_model
    self.model_runner.load_model()
  File "/home/ggous/vllm/lib/python3.11/site-packages/vllm/worker/model_runner.py", line 1113, in load_model
    self.model = get_model(vllm_config=self.vllm_config)
                 ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
  File "/home/ggous/vllm/lib/python3.11/site-packages/vllm/model_executor/model_loader/__init__.py", line 14, in get_model
    return loader.load_model(vllm_config=vllm_config)
           ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
  File "/home/ggous/vllm/lib/python3.11/site-packages/vllm/model_executor/model_loader/loader.py", line 426, in load_model
    loaded_weights = model.load_weights(
                     ^^^^^^^^^^^^^^^^^^^
  File "/home/ggous/vllm/lib/python3.11/site-packages/vllm/model_executor/models/gemma3_mm.py", line 618, in load_weights
    return loader.load_weights(weights)
           ^^^^^^^^^^^^^^^^^^^^^^^^^^^^
  File "/home/ggous/vllm/lib/python3.11/site-packages/vllm/model_executor/models/utils.py", line 235, in load_weights
    autoloaded_weights = set(self._load_module("", self.module, weights))
                         ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
  File "/home/ggous/vllm/lib/python3.11/site-packages/vllm/model_executor/models/utils.py", line 196, in _load_module
    yield from self._load_module(prefix,
  File "/home/ggous/vllm/lib/python3.11/site-packages/vllm/model_executor/models/utils.py", line 173, in _load_module
    loaded_params = module_load_weights(weights)
                    ^^^^^^^^^^^^^^^^^^^^^^^^^^^^
  File "/home/ggous/vllm/lib/python3.11/site-packages/vllm/model_executor/models/gemma3.py", line 528, in load_weights
    return loader.load_weights(weights)
           ^^^^^^^^^^^^^^^^^^^^^^^^^^^^
  File "/home/ggous/vllm/lib/python3.11/site-packages/vllm/model_executor/models/utils.py", line 235, in load_weights
    autoloaded_weights = set(self._load_module("", self.module, weights))
                         ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
  File "/home/ggous/vllm/lib/python3.11/site-packages/vllm/model_executor/models/utils.py", line 196, in _load_module
    yield from self._load_module(prefix,
  File "/home/ggous/vllm/lib/python3.11/site-packages/vllm/model_executor/models/utils.py", line 173, in _load_module
    loaded_params = module_load_weights(weights)
                    ^^^^^^^^^^^^^^^^^^^^^^^^^^^^
  File "/home/ggous/vllm/lib/python3.11/site-packages/vllm/model_executor/models/gemma3.py", line 452, in load_weights
    weight_loader(param, loaded_weight)
  File "/home/ggous/vllm/lib/python3.11/site-packages/vllm/model_executor/layers/linear.py", line 1228, in weight_loader
    assert param_data.shape == loaded_weight.shape
           ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
AssertionError
Process SpawnProcess-1:
Traceback (most recent call last):

........
        ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
AssertionError
Loading safetensors checkpoint shards:   0% Completed | 0/3 [00:00<?, ?it/s]

[rank0]:[W320 12:24:31.921018915 ProcessGroupNCCL.cpp:1496] Warning: WARNING: destroy_process_group() was not called before program exit, which can leak resources. For more info, please see https://pytorch.org/docs/stable/distributed.html#shutdown (function operator())
Traceback (most recent call last):
....
 File "/home/ggous/vllm/lib/python3.11/site-packages/vllm/entrypoints/openai/api_server.py", line 259, in build_async_engine_client_from_engine_args
    raise RuntimeError(
RuntimeError: Engine process failed to start. See stack trace for the root cause.

shimmyshimmer

Unsloth AI org Mar 22, 2025

I have downloaded the model and when i try to start with vllm:

        --max-model-len 1024 \
        --max-num-seqs 10 \
        --dtype bfloat16 \
        --device=cuda \
        --trust-remote-code \
        --max-num-batched-tokens 24576 \
        --gpu-memory-utilization 0.8 \
        --host 0.0.0.0 \
        --port 8080```

it gives me:


        ERROR 03-20 12:24:30 [engine.py:443] 
Traceback (most recent call last):
  File "/home/ggous/vllm/lib/python3.11/site-packages/vllm/engine/multiprocessing/engine.py", line 431, in run_mp_engine
    engine = MQLLMEngine.from_vllm_config(
             ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
  File "/home/ggous/vllm/lib/python3.11/site-packages/vllm/engine/multiprocessing/engine.py", line 126, in from_vllm_config
    return cls(
           ^^^^
  File "/home/ggous/vllm/lib/python3.11/site-packages/vllm/engine/multiprocessing/engine.py", line 80, in __init__
    self.engine = LLMEngine(*args, **kwargs)
                  ^^^^^^^^^^^^^^^^^^^^^^^^^^
  File "/home/ggous/vllm/lib/python3.11/site-packages/vllm/engine/llm_engine.py", line 280, in __init__
    self.model_executor = executor_class(vllm_config=vllm_config, )
                          ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
  File "/home/ggous/vllm/lib/python3.11/site-packages/vllm/executor/executor_base.py", line 52, in __init__
    self._init_executor()
  File "/home/ggous/vllm/lib/python3.11/site-packages/vllm/executor/uniproc_executor.py", line 47, in _init_executor
    self.collective_rpc("load_model")
  File "/home/ggous/vllm/lib/python3.11/site-packages/vllm/executor/uniproc_executor.py", line 56, in collective_rpc
    answer = run_method(self.driver_worker, method, args, kwargs)
             ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
  File "/home/ggous/vllm/lib/python3.11/site-packages/vllm/utils.py", line 2216, in run_method
    return func(*args, **kwargs)
           ^^^^^^^^^^^^^^^^^^^^^
  File "/home/ggous/vllm/lib/python3.11/site-packages/vllm/worker/worker.py", line 183, in load_model
    self.model_runner.load_model()
  File "/home/ggous/vllm/lib/python3.11/site-packages/vllm/worker/model_runner.py", line 1113, in load_model
    self.model = get_model(vllm_config=self.vllm_config)
                 ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
  File "/home/ggous/vllm/lib/python3.11/site-packages/vllm/model_executor/model_loader/__init__.py", line 14, in get_model
    return loader.load_model(vllm_config=vllm_config)
           ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
  File "/home/ggous/vllm/lib/python3.11/site-packages/vllm/model_executor/model_loader/loader.py", line 426, in load_model
    loaded_weights = model.load_weights(
                     ^^^^^^^^^^^^^^^^^^^
  File "/home/ggous/vllm/lib/python3.11/site-packages/vllm/model_executor/models/gemma3_mm.py", line 618, in load_weights
    return loader.load_weights(weights)
           ^^^^^^^^^^^^^^^^^^^^^^^^^^^^
  File "/home/ggous/vllm/lib/python3.11/site-packages/vllm/model_executor/models/utils.py", line 235, in load_weights
    autoloaded_weights = set(self._load_module("", self.module, weights))
                         ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
  File "/home/ggous/vllm/lib/python3.11/site-packages/vllm/model_executor/models/utils.py", line 196, in _load_module
    yield from self._load_module(prefix,
  File "/home/ggous/vllm/lib/python3.11/site-packages/vllm/model_executor/models/utils.py", line 173, in _load_module
    loaded_params = module_load_weights(weights)
                    ^^^^^^^^^^^^^^^^^^^^^^^^^^^^
  File "/home/ggous/vllm/lib/python3.11/site-packages/vllm/model_executor/models/gemma3.py", line 528, in load_weights
    return loader.load_weights(weights)
           ^^^^^^^^^^^^^^^^^^^^^^^^^^^^
  File "/home/ggous/vllm/lib/python3.11/site-packages/vllm/model_executor/models/utils.py", line 235, in load_weights
    autoloaded_weights = set(self._load_module("", self.module, weights))
                         ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
  File "/home/ggous/vllm/lib/python3.11/site-packages/vllm/model_executor/models/utils.py", line 196, in _load_module
    yield from self._load_module(prefix,
  File "/home/ggous/vllm/lib/python3.11/site-packages/vllm/model_executor/models/utils.py", line 173, in _load_module
    loaded_params = module_load_weights(weights)
                    ^^^^^^^^^^^^^^^^^^^^^^^^^^^^
  File "/home/ggous/vllm/lib/python3.11/site-packages/vllm/model_executor/models/gemma3.py", line 452, in load_weights
    weight_loader(param, loaded_weight)
  File "/home/ggous/vllm/lib/python3.11/site-packages/vllm/model_executor/layers/linear.py", line 1228, in weight_loader
    assert param_data.shape == loaded_weight.shape
           ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
AssertionError
Process SpawnProcess-1:
Traceback (most recent call last):

........
        ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
AssertionError
Loading safetensors checkpoint shards:   0% Completed | 0/3 [00:00<?, ?it/s]

[rank0]:[W320 12:24:31.921018915 ProcessGroupNCCL.cpp:1496] Warning: WARNING: destroy_process_group() was not called before program exit, which can leak resources. For more info, please see https://pytorch.org/docs/stable/distributed.html#shutdown (function operator())
Traceback (most recent call last):
....
 File "/home/ggous/vllm/lib/python3.11/site-packages/vllm/entrypoints/openai/api_server.py", line 259, in build_async_engine_client_from_engine_args
    raise RuntimeError(
RuntimeError: Engine process failed to start. See stack trace for the root cause.

Use the latest version of vllm and try. Try the standard model and then our one. If the standard one doesn't work then it might not be suppoted yet

Upload images, audio, and videos by dragging in the text input, pasting, or clicking here.

Tap or paste here to upload images

· Sign up or log in to comment