KoboldCpp: installare, configurare (GGUF, ROCm, API) — e confronto con Ollama

#Perché KoboldCpp

KoboldCpp è un fork di llama.cpp distribuito come un unico eseguibile autonomo. Scarichi un file, lo avvii e hai subito un'interfaccia web di chat nel tuo browser, oltre a un'API HTTP. Nessun demone da installare, nessuna dipendenza Python da gestire, nessun gestore di modelli proprietario: indichi all'eseguibile un file GGUF scaricato da Hugging Face e basta.

Rispetto a Ollama, la differenza di filosofia è netta. Ollama gestisce un catalogo di modelli, un daemon in background (su http://localhost:11434) e un proprio formato di pacchettizzazione. KoboldCpp, invece, non gestisce nulla: esegue direttamente il GGUF che gli fornisci. Questo lo rende ideale quando vuoi testare una quantizzazione specifica scaricata manualmente, quando sei su una macchina su cui non puoi installare nulla o quando la tua GPU è una AMD poco supportata altrove.

Binario unico

Un solo file eseguibile, portatile, senza installazione né diritti amministrativi.

GGUF diretto

Carica qualsiasi .gguf scaricato da Hugging Face, senza conversione.

Supporto di prima classe per AMD

Build ROCm dedicate e backend Vulkan che sfruttano davvero le Radeon.

Tutto incluso

Interfaccia web KoboldAI Lite + API (nativa e compatibile con OpenAI) nello stesso binario.

#Prerequisiti

KoboldCpp funziona su Windows, Linux e macOS. Può funzionare usando solo la CPU, ma una GPU accelera notevolmente l'inferenza. Il punto chiave, come per ogni runner GGUF, è la VRAM disponibile: determina la dimensione del modello e la quantizzazione che potrai caricare interamente sulla scheda.

RAM di sistema

Almeno 8 GB per un piccolo modello su CPU, 16 GB per lavorare comodamente, 32 GB per l'offload di modelli di grandi dimensioni nella RAM di sistema.

VRAM (riferimenti Q4_K_M)

3B ≈ 2 GB · 7B ≈ 5 GB · 14B ≈ 9 GB · 32B ≈ 19 GB · 70B ≈ 40 GB.

GPU NVIDIA

Build CUDA. RTX 3060 12GB (fascia d'ingresso), 4070 12GB, 4080 16GB, 4090 24GB.

GPU AMD

Build ROCm (Radeon RX 6000/7000) o backend Vulkan universale.

Un file GGUF

Da scaricare da Hugging Face (es. bartowski, uno dei principali fornitori di modelli quantizzati in formato GGUF).

#Scaricare il binario

Tutto avviene a partire dalle release GitHub del progetto (LostRuins/koboldcpp). Scegli il binario adatto al tuo sistema operativo e alla tua GPU — non c'è un installer, solo un file da rendere eseguibile.

1. 01
   Aprire le release

   Vai su github.com/LostRuins/koboldcpp/releases e individua la versione stabile più recente.
2. 02
   Scegliere il file giusto

   Windows NVIDIA: koboldcpp.exe (build CUDA). Windows senza NVIDIA: koboldcpp_nocuda.exe (utilizza Vulkan/CLBlast). Linux: koboldcpp-linux-x64. AMD su Linux: la build ROCm koboldcpp-linux-x64-rocm (vedi la sezione AMD).
3. 03
   Rendere eseguibile (Linux/macOS)

   Scarica e assegna il permesso di esecuzione al file prima di avviarlo.

# Récupérer le binaire (adaptez l'URL à la dernière release)
wget https://github.com/LostRuins/koboldcpp/releases/latest/download/koboldcpp-linux-x64

# Le rendre exécutable
chmod +x koboldcpp-linux-x64

# Vérifier qu'il se lance
./koboldcpp-linux-x64 --help

#Caricare un GGUF e chattare

Il cuore del funzionamento si riduce a un comando: passi il percorso del file GGUF con --model. KoboldCpp avvia un server locale e apre (o ti indica) l'URL dell'interfaccia web, per default http://localhost:5001.

# Lancer avec un modèle, en offloadant toutes les couches sur le GPU
./koboldcpp-linux-x64 \
  --model ./qwen3.5-9b-instruct-Q4_K_M.gguf \
  --gpulayers 999 \
  --contextsize 8192

--model

Percorso del file .gguf da caricare.

--gpulayers

Numero di layer trasferiti sulla GPU. 999 = tutto ciò che entra in VRAM.

--contextsize

Dimensione della finestra di contesto in token (es. 4096, 8192, 16384).

--port

Porta di ascolto (5001 per default).

--host

Indirizzo di ascolto. 0.0.0.0 per esporre sulla rete locale.

Una volta avviato, apri http://localhost:5001 nel tuo browser: ti trovi su KoboldAI Lite, un'interfaccia di chat completa con cronologia, impostazioni di sampling e modalità (chat, instruct, scrittura). Non è necessaria alcun'altra installazione.

#GPU AMD: ROCm e Vulkan

È qui che KoboldCpp si distingue di più da Ollama. Esistono due opzioni per accelerare su una Radeon, a seconda del tuo sistema e della tua scheda.

#La strada ROCm (Linux, prestazioni massime)

ROCm è lo stack di calcolo GPU di AMD, l'equivalente di CUDA. Il progetto fornisce build ROCm dedicate che offrono le migliori prestazioni su Radeon RX 6000/7000. ROCm deve essere installato sul sistema, poi si avvia il binario ROCm esattamente come gli altri.

# Build ROCm dédié
chmod +x koboldcpp-linux-x64-rocm

# Certaines cartes non officiellement supportées nécessitent de forcer
# la version d'architecture GPU (ex. RX 6700 XT -> gfx1030)
export HSA_OVERRIDE_GFX_VERSION=10.3.0

./koboldcpp-linux-x64-rocm \
  --model ./gemma-4-12b-it-Q4_K_M.gguf \
  --usecublas \
  --gpulayers 999 \
  --contextsize 8192

#La via Vulkan (universale, semplice)

Se ROCm ti scoraggia o non è disponibile (Windows, scheda troppo vecchia, iGPU), il backend Vulkan è un'ottima alternativa. È indipendente dal produttore: funziona su AMD, Intel e NVIDIA senza uno stack di calcolo specifico, al prezzo di una lieve penalizzazione delle prestazioni rispetto a ROCm o CUDA.

./koboldcpp-linux-x64 \
  --model ./granite-4.2-8b-instruct-Q4_K_M.gguf \
  --usevulkan \
  --gpulayers 999 \
  --contextsize 8192

#Contesto e offloading

Due impostazioni determinano se il tuo modello entra nella memoria della GPU e a quale velocità risponde: il numero di layer trasferiti alla GPU e la dimensione del contesto. Calibrarle bene evita che parte del modello finisca nella RAM di sistema, facendo crollare la velocità.

#Offloading dei layer (--gpulayers)

Un modello è composto da strati (layers). Ogni strato caricato nella VRAM viene elaborato dalla GPU; quelli che restano vengono eseguiti sulla CPU. --gpulayers 999 tenta di caricare tutto sulla GPU. Se la scheda non ha abbastanza VRAM, riduci questo numero: il modello viene così ripartito tra GPU e CPU (offloading parziale), con un'esecuzione più lenta ma funzionante.

Tutto entra in VRAM

--gpulayers 999, velocità massima, tutto il modello sulla GPU.

VRAM insufficiente

Diminuisci il valore (es. 20, 30) fino a quando il caricamento avviene senza saturare la scheda.

Nessuna GPU

--gpulayers 0, tutto sulla CPU: lento ma funziona ovunque.

#Finestra di contesto (--contextsize)

Il contesto è la quantità di testo (in token) che il modello mantiene in memoria: prompt di sistema, cronologia e domanda. Più è ampio, più la cache KV occupa VRAM. Non aumentare il contesto oltre ciò che ti serve: da 4096 a 8192 token bastano per una normale chat, 16384+ per analizzare documenti lunghi.

#API e interfaccia web integrate

KoboldCpp espone due API sulla stessa porta (5001 per impostazione predefinita): la propria API nativa KoboldAI e un'API compatibile con OpenAI sotto /v1. Quest'ultima ti permette di collegare KoboldCpp come backend a qualsiasi strumento che utilizzi il protocollo OpenAI — esattamente come un endpoint Ollama o llama-server.

curl http://localhost:5001/v1/chat/completions \
  -H "Content-Type: application/json" \
  -d '{
    "model": "koboldcpp",
    "messages": [
      {"role": "user", "content": "Explique le offloading GPU en une phrase."}
    ]
  }'

In Python, la compatibilità con OpenAI permette di riutilizzare l'SDK ufficiale semplicemente cambiando l'URL di base e inserendo una chiave fittizia.

from openai import OpenAI

client = OpenAI(
    base_url="http://localhost:5001/v1",
    api_key="koboldcpp",  # non vérifiée en local
)

resp = client.chat.completions.create(
    model="koboldcpp",
    messages=[{"role": "user", "content": "Bonjour en une phrase."}],
)
print(resp.choices[0].message.content)

Interfaccia web

KoboldAI Lite su http://localhost:5001 : chat, sampling avanzato, personaggi, memoria.

API OpenAI

Endpoint /v1/chat/completions per collegare Open WebUI, script o agenti.

API nativa

Endpoint KoboldAI per un controllo molto fine del sampling e della generazione.

#Risoluzione dei problemi

Caricamento che fallisce su AMD

Scheda non riconosciuta da ROCm: imposta HSA_OVERRIDE_GFX_VERSION con un'architettura simile (es. 10.3.0), oppure passa a --usevulkan.

Generazione molto lenta

Il modello viene eseguito in parte sulla CPU. Riduci --contextsize, diminuisci --gpulayers per evitare la saturazione oppure passa a una quantizzazione più spinta (Q5 → Q4_K_M).

« out of memory » all'avvio

VRAM saturata dal modello + dalla cache KV. Riduci il contesto o l'offloading, oppure scegli una quantizzazione più leggera.

Porta già in uso

Cambia la porta con --port (es. --port 5002) se la 5001 è occupata.

Accesso da un'altra macchina

Aggiungi --host 0.0.0.0 per metterti in ascolto sulla rete locale e apri la porta nel firewall.

In sintesi, KoboldCpp è la scelta pragmatica quando vuoi evitare qualsiasi installazione, avere un controllo diretto sul file GGUF e sull'offloading, o semplicemente far finalmente lavorare seriamente una scheda AMD. Per un catalogo di modelli e un'integrazione con il sistema pronta all'uso, Ollama rimane più comodo; per la portabilità e la regolazione fine, KoboldCpp vince.

#Per approfondire

Queste guide approfondiscono questa e trattano i componenti correlati:

Ollama con GPU AMD (ROCm)

L'altro approccio AMD, sul versante Ollama, per confrontare ROCm nei due ecosistemi.

Scegliere la quantizzazione (Q4, Q5, Q8, FP16)

Per bilanciare dimensione del modello, VRAM e qualità prima di scaricare un GGUF.

llama-server : un'API OpenAI locale con llama.cpp

L'alternativa più vicina, basata sullo stesso fondamento tecnologico, llama.cpp, se dai la priorità all'API.