KoboldCpp: guida completa al runtime locale per LLM in un singolo binario

KoboldCpp è un'applicazione monofile LLM locale basata su llama.cpp. Scarica un unico file eseguibile, puntalo a un modello GGUF e ottieni immediatamente un'interfaccia chat basata sul browser e un'API REST compatibile con OpenAI — niente gestore di pacchetti, niente demone da configurare, nessun passaggio di installazione richiesto. Funziona su Windows, macOS e Linux, con accelerazione GPU opzionale tramite CUDA, Metal, Vulkan o OpenCL.

Download di KoboldCpp

Le versioni vengono pubblicate sulla pagina delle release di KoboldCpp su GitHub. Ogni versione include binari specifici per piattaforma; scegli quello adatto al tuo hardware.

Windows

Scarica koboldcpp.exe per il supporto GPU NVIDIA (le librerie CUDA sono incluse nel pacchetto — non è necessaria alcuna installazione separata del toolkit CUDA, ma solo il driver grafico NVIDIA standard). Se non disponi di una GPU NVIDIA, scarica invece koboldcpp_nocuda.exe . Un doppio clic sul file .exe apre un lanciatore grafico che ti consente di cercare il file del modello e configurare le impostazioni prima di avviare il server. Per saltare il lanciatore e avviare direttamente dalla riga di comando, utilizza l'opzione --skiplauncher .

macOS

Scarica il binario macOS dalla pagina delle release (solitamente denominato koboldcpp_mac o distribuito come file .dmg). L'accelerazione GPU Metal è inclusa automaticamente — non è necessario alcun flag aggiuntivo; KoboldCpp rileva automaticamente i chip Apple Silicon e utilizza Metal di default. Al primo avvio, macOS potrebbe avvisarti che il binario proviene da uno sviluppatore non identificato; fai clic destro → Apri per aggirare Gatekeeper.

Linux

Scarica il binario Linux e rendilo eseguibile:

chmod +x koboldcpp
./koboldcpp --model /path/to/model.gguf

I binari Linux precompilati includono il supporto per CPU e Vulkan. Per CUDA sulle schede NVIDIA, cerca un asset della release con suffisso cu nel nome del file oppure compila da sorgente con make LLAMA_CUDA=1. Se il tuo driver è troppo vecchio per la versione CUDA inclusa, la build Vulkan rappresenta un'alternativa affidabile.

Ottenere un modello GGUF

KoboldCpp carica direttamente i file GGUF — lo stesso formato utilizzato da llama.cpp e Ollama. La fonte principale è Hugging Face; cerca il nome di un modello seguito da "GGUF". Prima di scaricare, usa il Calcolatore VRAM per verificare che il modello possa essere caricato sulla tua GPU alla dimensione di contesto scelta. Livelli di quantizzazione da conoscere:

Avvio di KoboldCpp

Il comando minimo su qualsiasi piattaforma:

./koboldcpp --model /path/to/model.gguf

Questo avvia il server all'indirizzo http://localhost:5001. Apri tale URL nel tuo browser per accedere all'interfaccia web.

Windows — Lanciatore grafico

Fai doppio clic su koboldcpp.exe. La finestra del lanciatore ti permette di selezionare il file del modello, impostare il numero di layer GPU, la dimensione del contesto e il backend senza usare la riga di comando. Clicca su Avvia al termine; si aprirà una finestra del terminale che mostrerà i log del server e l'interfaccia web verrà lanciata automaticamente.

Riga di comando (tutte le piattaforme)

Un comando tipico di avvio con offload GPU, contesto personalizzato e porta esplicita:

./koboldcpp 
  --model ./models/llama3-8b-q4_k_m.gguf 
  --gpulayers 32 
  --contextsize 8192 
  --port 5001

Riferimento alle opzioni principali:

Interfaccia web e API compatibile con OpenAI

Una volta avviato, KoboldCpp espone due interfacce sulla stessa porta:

• Interfaccia web — http://localhost:5001Un'interfaccia completa per la generazione testuale, con modalità storia, chat e istruzioni. Supporta modelli di prompt, memoria, note dell'autore e campi di informazioni sul mondo ereditati dal progetto KoboldAI.
• API KoboldAI — http://localhost:5001/api/v1Utilizzata da frontend come SillyTavern e Agnaistic.
• API compatibile con OpenAI — http://localhost:5001/v1Implementa /v1/chat/completions e /v1/completions. Qualsiasi client che accetti un URL base personalizzato funziona, inclusi LangChain, l'SDK Python di OpenAI e la maggior parte delle applicazioni open-source per chat.

Per configurare l'SDK Python di OpenAI in modo che punti a KoboldCpp:

from openai import OpenAI

client = OpenAI(
    base_url="http://localhost:5001/v1",
    api_key="unused"  # KoboldCpp non richiede una chiave API per impostazione predefinita
)
response = client.chat.completions.create(
    model="koboldcpp",
    messages=[{"role": "user", "content": "Ciao"}]
)

Offload GPU: scelta del valore corretto per l'opzione --gpulayers

Ogni livello transformer trasferito sulla GPU sposta l'elaborazione dalla CPU e aumenta drasticamente i token al secondo. Il compromesso è l'uso di VRAM. Il numero totale di livelli di un modello è fissato dall'architettura — valori comuni sono 32 per modelli da 7B/8B, 40 per modelli da 13B e 80 per modelli da 70B. Ogni livello consuma una quota approssimativamente uguale della memoria GPU totale richiesta dal modello.

Approccio pratico:

1. Usa la Calcolatore VRAM per stimare quanti livelli possono essere caricati con la dimensione di contesto desiderata.
2. Inizia con --gpulayers 999 per tentare il trasferimento completo sulla GPU. KoboldCpp limita automaticamente questo valore al numero effettivo di livelli del modello.
3. Se ricevi un errore di memoria insufficiente all'avvio, riduci il valore e riprova. Il log del server mostra l'allocazione per ogni livello, aiutandoti a calibrare correttamente.

Il trasferimento parziale è supportato ed efficace: anche trasferire metà dei livelli di un modello grande offre un miglioramento significativo della velocità rispetto all'inferenza puramente su CPU. Se non sei sicuro di quale GPU abbinare a un determinato modello, consulta la migliore GPU per LLM locali guida e il suddivisione dei requisiti di VRAM per modello.

Dimensione del contesto e impostazioni delle prestazioni

Dimensione del contesto (--contextsize) è il fattore più importante che influenza il consumo di VRAM oltre ai pesi del modello. Un modello da 7B in formato Q4_K_M richiede circa 4 GB per i pesi; estendere il contesto da 4096 a 32768 token può aggiungere diversi gigabyte ulteriori alla cache KV. Abilita --flashattention per ridurre l'occupazione di memoria della cache KV — questa opzione è particolarmente efficace con contesti molto lunghi e non comporta alcun degrado nella qualità dell'output.

Altre impostazioni che influenzano la velocità:

• --threads: per l'inferenza esclusivamente su CPU, imposta questo valore vicino al numero di core fisici, non al numero di thread logici (hyperthreading).
• --batchsize: valori più elevati (ad esempio 512) migliorano la velocità di elaborazione del prompt, ma aumentano il picco di utilizzo di VRAM durante la fase di prefill.
• --smartcontext: quando il contesto si riempie, KoboldCpp sposta fuori i token più vecchi anziché interrompere la generazione — utile per sessioni interattive prolungate.

KoboldCpp vs Ollama vs llama.cpp

Tutti e tre sono basati sullo stesso motore llama.cpp e supportano modelli GGUF. Le differenze riguardano il flusso di lavoro e l'interfaccia.

Scegli KoboldCpp se desideri una configurazione pronta all’uso senza installazione, un’interfaccia integrata per storie/chat oppure la compatibilità con frontend KoboldAI come SillyTavern.
Scegli Ollama se desideri una libreria di modelli gestita, un systemd servizio oppure un’integrazione più stretta con la CLI — consulta la Guida completa a Ollama per una guida completa.
Scegli direttamente llama.cpp se stai sviluppando un’integrazione personalizzata o hai bisogno delle funzionalità più recenti disponibili upstream, ancor prima che vengano integrate nei wrapper di livello inferiore.

Se stai ancora decidendo se eseguire autonomamente il modello (self-hosting) oppure chiamare un’API ospitata esternamente, la calcolatore di pareggio tra auto-hosting e API può aiutarti a calcolare il punto di pareggio dei costi.

Domande frequenti

KoboldCpp richiede l’installazione separata dei driver CUDA?

Su Windows, koboldcpp.exe include le librerie di runtime CUDA, quindi è sufficiente installare il normale driver grafico NVIDIA — non è necessaria alcuna installazione separata del toolkit CUDA. Su Linux, le build CUDA dipendono in genere dal runtime CUDA installato localmente, pertanto la compatibilità della versione del driver è fondamentale; se il driver è troppo vecchio, la build Vulkan rappresenta la soluzione di fallback più semplice.

Cosa significa l’opzione --gpulayers 0?

Zero layer sulla GPU significa che tutti i calcoli vengono eseguiti sulla CPU. Questa è la configurazione predefinita quando nessun flag GPU viene specificato. L’inferenza su CPU è molto più lenta — tipicamente 2–10 token/secondo su una CPU moderna, contro 40–100+ token/secondo su una GPU di fascia media — ma funziona su qualsiasi macchina, indipendentemente dalla presenza di una GPU.

Posso utilizzare KoboldCpp come sostituto 'plug-and-play' dell’API OpenAI nella mia applicazione?

Sì. Imposta l’URL dell’endpoint API del tuo client OpenAI su base_url a http://localhost:5001/v1 e imposta una stringa non vuota come valore del parametro api_key (di default non viene effettuata alcuna validazione). Il campo modello è accettato ma ignorato — verrà sempre utilizzato il file GGUF caricato. Sono supportati sia i completamenti chat che i completamenti testuali; non sono invece supportati gli endpoint per gli embedding e le immagini.

Come faccio a eseguire contemporaneamente due modelli diversi?

Ogni processo KoboldCpp gestisce un singolo modello. Avvia una seconda istanza con un valore diverso per il parametro --port (ad esempio, 5002) che punti a un file GGUF differente. Non è previsto alcun bilanciatore di carico integrato; la distribuzione del traffico tra le istanze deve avvenire a livello applicativo.

Perché la generazione risulta più lenta del previsto anche con una GPU?

La causa più comune è un’offload parziale sulla CPU: se il numero specificato con l’opzione --gpulayers è inferiore al numero totale di layer del modello, i layer rimanenti verranno eseguiti sulla CPU, creando un collo di bottiglia. Controlla il log di avvio — KoboldCpp indica esattamente quanti layer sono stati assegnati alla GPU e quanti alla CPU. Verifica inoltre che nel messaggio di avvio compaia il backend corretto (CUDA/Metal/Vulkan) e non un fallback automatico sulla CPU.

È sicuro esporre KoboldCpp su una rete?

Per impostazione predefinita KoboldCpp si collega a 127.0.0.1 (solo localhost). Per esporlo su una rete locale (LAN), aggiungi l’opzione --host 0.0.0.0. Poiché non è prevista alcuna autenticazione integrata, non è consigliabile esporlo su reti non attendibili o su Internet pubblico, a meno che non venga protetto da un reverse proxy dotato di autenticazione.