Instructions to use unsloth/Laguna-S-2.1-GGUF with libraries, inference providers, notebooks, and local apps. Follow these links to get started.
- Libraries
- Transformers
How to use unsloth/Laguna-S-2.1-GGUF with Transformers:
# Use a pipeline as a high-level helper from transformers import pipeline pipe = pipeline("text-generation", model="unsloth/Laguna-S-2.1-GGUF") messages = [ {"role": "user", "content": "Who are you?"}, ] pipe(messages)# Load model directly from transformers import AutoModel model = AutoModel.from_pretrained("unsloth/Laguna-S-2.1-GGUF", device_map="auto") - Notebooks
- Google Colab
- Kaggle
- Local Apps Settings
- llama.cpp
How to use unsloth/Laguna-S-2.1-GGUF with llama.cpp:
Install (macOS, Linux)
curl -LsSf https://llama.app/install.sh | sh # Start a local OpenAI-compatible server with a web UI: llama serve -hf unsloth/Laguna-S-2.1-GGUF:UD-Q4_K_M # Run inference directly in the terminal: llama cli -hf unsloth/Laguna-S-2.1-GGUF:UD-Q4_K_M
Install from WinGet (Windows)
winget install llama.cpp # Start a local OpenAI-compatible server with a web UI: llama serve -hf unsloth/Laguna-S-2.1-GGUF:UD-Q4_K_M # Run inference directly in the terminal: llama cli -hf unsloth/Laguna-S-2.1-GGUF:UD-Q4_K_M
Use pre-built binary
# Download pre-built binary from: # https://github.com/ggerganov/llama.cpp/releases # Start a local OpenAI-compatible server with a web UI: ./llama-server -hf unsloth/Laguna-S-2.1-GGUF:UD-Q4_K_M # Run inference directly in the terminal: ./llama-cli -hf unsloth/Laguna-S-2.1-GGUF:UD-Q4_K_M
Build from source code
git clone https://github.com/ggerganov/llama.cpp.git cd llama.cpp cmake -B build cmake --build build -j --target llama-server llama-cli # Start a local OpenAI-compatible server with a web UI: ./build/bin/llama-server -hf unsloth/Laguna-S-2.1-GGUF:UD-Q4_K_M # Run inference directly in the terminal: ./build/bin/llama-cli -hf unsloth/Laguna-S-2.1-GGUF:UD-Q4_K_M
Use Docker
docker model run hf.co/unsloth/Laguna-S-2.1-GGUF:UD-Q4_K_M
- LM Studio
- Jan
- vLLM
How to use unsloth/Laguna-S-2.1-GGUF with vLLM:
Install from pip and serve model
# Install vLLM from pip: pip install vllm # Start the vLLM server: vllm serve "unsloth/Laguna-S-2.1-GGUF" # 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/Laguna-S-2.1-GGUF", "messages": [ { "role": "user", "content": "What is the capital of France?" } ] }'Use Docker
docker model run hf.co/unsloth/Laguna-S-2.1-GGUF:UD-Q4_K_M
- SGLang
How to use unsloth/Laguna-S-2.1-GGUF 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/Laguna-S-2.1-GGUF" \ --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/Laguna-S-2.1-GGUF", "messages": [ { "role": "user", "content": "What is the capital of France?" } ] }'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/Laguna-S-2.1-GGUF" \ --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/Laguna-S-2.1-GGUF", "messages": [ { "role": "user", "content": "What is the capital of France?" } ] }' - Ollama
How to use unsloth/Laguna-S-2.1-GGUF with Ollama:
ollama run hf.co/unsloth/Laguna-S-2.1-GGUF:UD-Q4_K_M
- Unsloth Studio
How to use unsloth/Laguna-S-2.1-GGUF 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/Laguna-S-2.1-GGUF 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/Laguna-S-2.1-GGUF to start chatting
Using HuggingFace Spaces for Unsloth
# No setup required # Open https://huggingface.co/spaces/unsloth/studio in your browser # Search for unsloth/Laguna-S-2.1-GGUF to start chatting
- Pi
How to use unsloth/Laguna-S-2.1-GGUF with Pi:
Start the llama.cpp server
# Install llama.cpp: brew install llama.cpp # Start a local OpenAI-compatible server: llama serve -hf unsloth/Laguna-S-2.1-GGUF:UD-Q4_K_M
Configure the model in Pi
# Install Pi: npm install -g @mariozechner/pi-coding-agent # Add to ~/.pi/agent/models.json: { "providers": { "llama-cpp": { "baseUrl": "http://localhost:8080/v1", "api": "openai-completions", "apiKey": "none", "models": [ { "id": "unsloth/Laguna-S-2.1-GGUF:UD-Q4_K_M" } ] } } }Run Pi
# Start Pi in your project directory: pi
- Docker Model Runner
How to use unsloth/Laguna-S-2.1-GGUF with Docker Model Runner:
docker model run hf.co/unsloth/Laguna-S-2.1-GGUF:UD-Q4_K_M
- Lemonade
How to use unsloth/Laguna-S-2.1-GGUF with Lemonade:
Pull the model
# Download Lemonade from https://lemonade-server.ai/ lemonade pull unsloth/Laguna-S-2.1-GGUF:UD-Q4_K_M
Run and chat with the model
lemonade run user.Laguna-S-2.1-GGUF-UD-Q4_K_M
List all available models
lemonade list
- Hermes Agent
How to use unsloth/Laguna-S-2.1-GGUF with Hermes Agent:
Start the llama.cpp server
# Install llama.cpp: brew install llama.cpp # Start a local OpenAI-compatible server: llama serve -hf unsloth/Laguna-S-2.1-GGUF:UD-Q4_K_M
Configure Hermes
# Install Hermes: curl -fsSL https://hermes-agent.nousresearch.com/install.sh | bash hermes setup # Point Hermes at the local server: hermes config set model.provider custom hermes config set model.base_url http://127.0.0.1:8080/v1 hermes config set model.default unsloth/Laguna-S-2.1-GGUF:UD-Q4_K_M
Run Hermes
hermes
- Atomic Chat
- OpenClaw
How to use unsloth/Laguna-S-2.1-GGUF with OpenClaw:
Start the llama.cpp server
# Install llama.cpp: brew install llama.cpp # Start a local OpenAI-compatible server: llama serve -hf unsloth/Laguna-S-2.1-GGUF:UD-Q4_K_M
Configure OpenClaw
# Install OpenClaw: npm install -g openclaw@latest # Register the local server and set it as the default model: openclaw onboard --non-interactive --mode local \ --auth-choice custom-api-key \ --custom-base-url http://127.0.0.1:8080/v1 \ --custom-model-id "unsloth/Laguna-S-2.1-GGUF:UD-Q4_K_M" \ --custom-provider-id llama-cpp \ --custom-compatibility openai \ --custom-text-input \ --accept-risk \ --skip-health
Run OpenClaw
openclaw agent --local --agent main --message "Hello from Hugging Face"
Laguna updates July 26th 2026
We updated all GGUFs with the official upstream changes, which should fix looping and other issues hopefully.
- Default context length reduced from 1M to 262144. Using 1M will need
--ctx-size 1048576 --rope-scaling yarn --rope-scale 128 --yarn-orig-ctx 8192 laguna.rope.scaling.yarn_attn_factoris now 1.0 from before.
You are just the best! π€
With UD-Q4_K_XL, I'm getting ~30 t/s.
Tools are working as expected.
No loop from limited testing.
System:
- Nvidia RTX 5090 with 32GB VRAM
- Intel Xeon W5-3425
- 256GB of DDR5-4800 RAM (8 channels)
- Ubuntu 24
logs:
prompt eval time = 11s / 1571 tokens ( 7.48 ms per token, 133.69 tokens per second)
eval time = 48s / 1476 tokens ( 32.85 ms per token, 30.44 tokens per second)
total time = 60s / 3047 tokens
my docker-compose.yaml:
services:
llama-router:
image: ghcr.io/ggml-org/llama.cpp:server-cuda13-b10143
container_name: router
devices:
- "nvidia.com/gpu=all"
ports:
- "8080:8080"
environment:
- NVIDIA_VISIBLE_DEVICES=all
- NVIDIA_DRIVER_CAPABILITIES=compute,utility
volumes:
- /var/lib/docker/.cache:/root/.cache
- ./models.ini:/app/models.ini:ro
entrypoint: ["./llama-server"]
command: >
--models-max 1
--models-preset ./models.ini
--host 0.0.0.0 --port 8080
--tools all
my models.ini:
version = 1
[unsloth/Laguna-S-2.1-GGUF:Q4_K_XL]
ctx-size=32768
I see that poolside/Laguna-S-2.1-GGUF:Q4_K_M has DFlash included, but unsloth doesn't. Are you planning to included it in the feature?
@SlavikF you can use the upstream DFlash model right now https://huggingface.co/poolside/Laguna-S-2.1-GGUF/blob/main/laguna-s-2.1-DFlash-BF16.gguf. In my limited testing, it can give me an additional 30tps of decode in the select tasks. without it I get ~35tps on 4x AMD r9700 AI Pro in layer split mode with the rocm backend (Q4_k_XL).
A lower bit version of DFlash would be cool if it speeds things up even more.
@Schimazing ,Can you please share the command or compose file you're using to start it with DFlash? which version or branch are you using?
When I try, I'm getting this:> failed to load draft model, '/root/.cache/huggingface/laguna-s-2.1-DFlash-BF16.gguf'
ok, found that because fit doesn't account for DFlash VRAM usage.
It works with fit-target:
services:
laguna21:
image: ghcr.io/ggml-org/llama.cpp:server-cuda13-b10143
container_name: laguna21
devices:
- "nvidia.com/gpu=all"
ports:
- "8080:8080"
environment:
- NVIDIA_VISIBLE_DEVICES=all
- NVIDIA_DRIVER_CAPABILITIES=compute,utility
volumes:
- /var/lib/docker/.cache:/root/.cache:ro
entrypoint: ["./llama-server"]
command: >
--host 0.0.0.0 --port 8080
--tools all
--ctx-size 65536
--model /root/.cache/huggingface/hub/models--unsloth--Laguna-S-2.1-GGUF/snapshots/750f92f90cf54159c4d7a610cb7b3e74498e75c6/UD-Q4_K_XL/Laguna-S-2.1-UD-Q4_K_XL-00001-of-00003.gguf
--spec-type draft-dflash
--spec-draft-n-max 15
--spec-draft-model /root/.cache/huggingface/laguna-s-2.1-DFlash-BF16.gguf
--fit-target 8192
But it slower with DFlash:
prompt eval time = 12s / 1571 tokens ( 7.87 ms per token, 127.01 tokens per second)
eval time = 67s / 1997 tokens ( 33.61 ms per token, 29.75 tokens per second)
total time = 79s / 3568 tokens
I guess it's slower with DFlash in my case because it uses RAM. Probably will faster with DFlash in case I would have enough VRAM
@SlavikF My issue was building poolsideai's llama.cpp fork on the main branch. You must checkout the branch laguna for DFlash to work.
Here is my command:
./build/bin/llama-cli \
-hf unsloth/Laguna-S-2.1-GGUF \
-hff UD-Q4_K_XL/Laguna-S-2.1-UD-Q4_K_XL-00001-of-00003.gguf \
--split-mode layer \
--tensor-split 1,1,1,1 \
-ngl -1 \
-c 262144 \
--cache-type-k q8_0 \
--cache-type-v q8_0 \
-cnv \
--jinja \
--flash-attn on \
--no-mmap \
--fit off \
--direct-io \
--chat-template-kwargs '{"enable_thinking":true, "preserve_thinking":true}' \
--perf \
-md ~/.cache/huggingface/hub/models--poolside--Laguna-S-2.1-GGUF/snapshots/edd093522473dc7313b0738d8b4116b7f8b9745f/laguna-s-2.1-DFlash-BF16.gguf \
--spec-type draft-dflash \
--spec-draft-n-max 6
does the lastest release of llama.cpp (b10176) support dflash now? I still get errors when trying to load it with dflash
With
UD-Q4_K_XL, I'm getting ~30 t/s.
Tools are working as expected.
No loop from limited testing.System:
- Nvidia RTX 5090 with 32GB VRAM
- Intel Xeon W5-3425
- 256GB of DDR5-4800 RAM (8 channels)
- Ubuntu 24
logs:
prompt eval time = 11s / 1571 tokens ( 7.48 ms per token, 133.69 tokens per second) eval time = 48s / 1476 tokens ( 32.85 ms per token, 30.44 tokens per second) total time = 60s / 3047 tokensmy docker-compose.yaml:
services: llama-router: image: ghcr.io/ggml-org/llama.cpp:server-cuda13-b10143 container_name: router devices: - "nvidia.com/gpu=all" ports: - "8080:8080" environment: - NVIDIA_VISIBLE_DEVICES=all - NVIDIA_DRIVER_CAPABILITIES=compute,utility volumes: - /var/lib/docker/.cache:/root/.cache - ./models.ini:/app/models.ini:ro entrypoint: ["./llama-server"] command: > --models-max 1 --models-preset ./models.ini --host 0.0.0.0 --port 8080 --tools allmy models.ini:
version = 1 [unsloth/Laguna-S-2.1-GGUF:Q4_K_XL] ctx-size=32768I see that
poolside/Laguna-S-2.1-GGUF:Q4_K_Mhas DFlash included, butunslothdoesn't. Are you planning to included it in the feature?
with that caed, you can probably get 1000+ tokens/sec prefill if you use a batch and ubatch size of 2048 or 4096. The model doesn't fit in VRAM, so llama.cpp defaults to much smaller sizes. my 2x 5060ti get me 380 Tok/sec pp and 11 gen speed. (DDR4)
if this tip improves your speed, maybe you should buy me DDR5 RAM. lol
So, I'm getting
llama_context: n_ctx_seq (1048576) > n_ctx_train (262144) -- possible training context overflow
srv load_model: the slot context (1048576) exceeds the training context of the model (262144) - capping
with both llama.cpp b10181 and the laguna fork, regardless of yarn and rope settings. Any ideas?
Arguments (laguna fork): --ctx-size 1048576 --rope-scaling yarn --rope-scale 128 --yarn-orig-ctx 8192 --yarn-attn-factor 1.0 --no-mmap -ndio -ctk q8_0 -ctv q8_0 --jinja --fit off
Never mind, seems that it's just this outstanding bug: https://github.com/ggml-org/llama.cpp/issues/17459
