Llama Cpp Python: installazione, build GPU e parametri

llama-cpp-python è il binding Python per llama.cpp. Carica Modelli GGUF in-process, espone un wrapper ctypes di basso livello più uno di alto livello Llama class, e include un server HTTP compatibile con OpenAI. L'installazione pip predefinita compila una build solo CPU. Per usare una GPU installi una GPU wheel o ricompila da sorgente con CMAKE_ARGS, quindi passi n_gpu_layers.

Perché l'installazione predefinita è solo CPU

Il pacchetto è un binding sottile attorno a una libreria C++ che deve essere compilata con il supporto backend integrato al momento della compilazione. Non esiste un flag runtime che attiva CUDA dopo il fatto. Quando pip compila l'sdist senza CMAKE_ARGS impostato, CMake configura il backend CPU generico e questo è quello che ottieni, permanentemente, finché non ricompili. Su macOS arm64 questo è meno problematico perché i rilasci recenti abilitano il backend Metal per impostazione predefinita, ma su Linux e Windows un'installazione base girerà interamente sulla tua CPU.

Due conseguenze da interiorizzare: primo, n_gpu_layers=-1 su una build solo CPU silenziosamente non fa nulla di utile, quindi spesso le persone concludono che la loro GPU è «troppo lenta» quando non è mai stata toccata. Secondo, pip memorizza nella cache le wheel compilate. Rieseguire l'installazione con CMAKE_ARGS diverso può darti di nuovo la wheel CPU memorizzata nella cache, ecco perché ogni comando di ricompilazione qui sotto include --no-cache-dir --force-reinstall.

Installare llama-cpp-python con supporto GPU

Opzione 1: wheel precompilate (nessun compilatore necessario)

Il progetto pubblica indici di wheel, incluso un indice CPU su https://abetlen.github.io/llama-cpp-python/whl/cpu e varianti CUDA il cui segmento di percorso codifica la versione CUDA, ad esempio .../whl/cu124. Installa con:

pip install llama-cpp-python --extra-index-url https://abetlen.github.io/llama-cpp-python/whl/cu124

Quali tag CUDA e versioni Python vengono pubblicati cambiano da rilascio a rilascio, e gli indici talvolta rimangono indietro rispetto alla versione più recente di PyPI. Controlla il README del progetto per i tag attualmente disponibili piuttosto che assumerne uno — un tag sbagliato restituisce un 404 e pip silenziosamente ritorna a compilare da sorgente.

Opzione 2: compilare da sorgente (Linux, CUDA)

Hai bisogno di una toolchain C++, CMake e il toolkit CUDA con nvcc nel tuo PATH.

nvcc --version   # deve stampare una versione, non "command not found"

CMAKE_ARGS="-DGGML_CUDA=on" 
  pip install llama-cpp-python --no-cache-dir --force-reinstall --upgrade

Il nome del flag è cambiato nel corso della vita del progetto: guide molto vecchie usano -DLLAMA_CUBLAS=on, guide di metà 2024 usano -DLLAMA_CUDA=on, e l'upstream attuale usa il GGML_ prefisso. Se una compilazione errori su un'opzione CMake sconosciuta, quella mancata corrispondenza è solitamente il motivo. Gli altri backend seguono lo stesso modello — Vulkan è -DGGML_VULKAN=on, SYCL è -DGGML_SYCL=on, e l'opzione AMD/ROCm è stata rinominata più di una volta, quindi leggi il README per la tua versione installata invece di copiare un flag da un post su un forum.

Puoi ridurre notevolmente il tempo di compilazione compilando solo per la compute capability della tua GPU, ad esempio -DCMAKE_CUDA_ARCHITECTURES=89 per una scheda Ada come la RTX 4090, o 86 per una 3090. Cerca la compute capability della tua scheda nella lista ufficiale NVIDIA; se stai ancora scegliendo hardware, la nostra guida alle migliori GPU per eseguire LLM localmente copre i tradeoff VRAM per dollaro.

Opzione 3: macOS con Metal

xcode-select --install

CMAKE_ARGS="-DGGML_METAL=on" 
  pip install llama-cpp-python --no-cache-dir --force-reinstall

Su Apple Silicon, verifica di non eseguire un Python x86 Rosetta: python -c "import platform; print(platform.machine())" deve stampare arm64. Un interprete x86_64 produce una build senza backend Metal indipendentemente da quale CMAKE_ARGS passi. Poiché la GPU e la CPU condividono memoria su Apple Silicon, n_gpu_layers=-1 è quasi sempre l'impostazione giusta lì.

Opzione 4: Windows con CUDA

Installa Visual Studio Build Tools 2022 con il carico di lavoro «Desktop development with C++» primo, quindi il CUDA Toolkit, così CUDA installa la sua integrazione MSBuild in un Visual Studio esistente. Quindi, in PowerShell:

$env:CMAKE_ARGS = "-DGGML_CUDA=on"
pip install llama-cpp-python --no-cache-dir --force-reinstall --upgrade

In cmd.exe l'equivalente è set CMAKE_ARGS=-DGGML_CUDA=on sulla propria riga. I build da sorgenti su Windows sono il percorso più soggetto a fallimenti tra le tre piattaforme; se desideri solo l'inferenza e non un build personalizzato, le wheel CUDA precompilate o WSL2 sono entrambe meno problematiche.

Come verificare quale build hai

Il controllo più affidabile è l'output dettagliato del loader, che è indipendente dalla versione:

from llama_cpp import Llama
llm = Llama(model_path="./models/model.gguf", n_gpu_layers=-1, verbose=True)

Su un build CUDA vedrai righe di inizializzazione del backend che menzionano CUDA e un nome di dispositivo, più una riga di caricamento dei tensor che riporta quanti strati del modello sono stati trasferiti su GPU. Su Metal vedrai righe di dispositivo Metal invece. Un build solo CPU non stampa nulla e riporta zero strati trasferiti. Verifica incrociata con nvidia-smi durante la generazione: se il tuo processo Python non sta occupando VRAM, nulla è in esecuzione sulla GPU.

Le versioni recenti espongono anche un controllo di compatibilità diretto:

from llama_cpp import llama_cpp, __version__
print(__version__)
print(llama_cpp.llama_supports_gpu_offload())

Se quell'attributo genera AttributeError, il tuo build è precedente — ricorri al metodo del log verboso.

Caricare un GGUF ed eseguire il primo completamento

Punto model_path su qualsiasi file GGUF. Se preferisci scaricarlo da Hugging Face, Llama.from_pretrained(repo_id=..., filename="*Q4_K_M.gguf", ...) esegue il download per te quando huggingface-hub è installato.

from llama_cpp import Llama

llm = Llama(
    model_path="./models/qwen2.5-7b-instruct-q4_k_m.gguf",
    n_gpu_layers=-1,
    n_ctx=4096,
    n_batch=512,
    verbose=False,
)

out = llm.create_chat_completion(
    messages=[{"role": "user", "content": "Explain a KV cache in two sentences."}],
    max_tokens=256,
    temperature=0.7,
)
print(out["choices"][0]["message"]["content"])

Per la continuazione di testo grezzo, chiama l'oggetto direttamente: llm("Q: What is a GGUF file? A:", max_tokens=128, stop=["Q:"]) e leggi out["choices"][0]["text"].

Streaming di token

Passa stream=True e itera. La forma della risposta rispecchia il formato di streaming di OpenAI, quindi il primo chunk in genere contiene solo il ruolo e i chunk successivi contengono content delta:

stream = llm.create_chat_completion(
    messages=[{"role": "user", "content": "Write a haiku about GGUF files."}],
    stream=True,
)
for chunk in stream:
    delta = chunk["choices"][0]["delta"]
    if "content" in delta:
        print(delta["content"], end="", flush=True)

La maggior parte dei file GGUF incorpora un template di chat che llama-cpp-python applica automaticamente. Quando l'output appare corrotto o il modello non si ferma mai, il template è il primo sospettato — sostituiscilo con l'argomento chat_format Sfoglia le opzioni quantizzate e i loro tagli nella nostra database dei modelli AI.

I parametri che contano

Parametro	Funzionalità	Guida pratica
n_gpu_layers	Quanti strati transformer trasferire su GPU. Predefinito 0, cioè solo CPU. -1 significa tutti.	Inizia con -1. Se ricevi un errore di memoria esaurita al caricamento, riduci fino a quando non si adatta.
n_ctx	Finestra di contesto in token. Predefinito a un valore volutamente piccolo (512 nelle versioni attuali). Passare 0 dice a llama.cpp di prendere il valore dai metadati del modello stesso.	Impostalo esplicitamente. 0 è legale ma un modello addestrato per 128K di contesto tenterà di allocare una cache KV per 128K token, il che di solito è ciò che esaurisce la tua VRAM.
n_batch	Dimensione logica del batch per l'elaborazione del prompt (prefill), non per la generazione.	512 è il valore predefinito comune. Aumentarlo a 1024–2048 accelera i prompt lunghi su GPU al costo di più memoria; abbassalo se vedi errori di allocazione del buffer.
n_ubatch	Micro-batch fisico effettivamente inviato al backend.	Lascialo stare a meno che tu non sia vincolato dalla memoria, nel qual caso un valore più piccolo riduce le dimensioni di picco del buffer di calcolo.
n_threads	Thread per la generazione. n_threads_batch copre l'elaborazione del prompt.	Importa solo per il lavoro ancora su CPU. Impostalo ai core fisici, non a quelli logici (hyperthreaded).
offload_kqv	Se la cache KV risiede su GPU.	Attivo per predefinito ed è normalmente quello che desideri; disabilitarlo libera VRAM ma costa molto in termini di velocità.
use_mmap / usa_mlock	Memory-map il file; bloccalo in RAM.	Mantieni mmap attivo. Usa mlock solo se il sistema operativo sta facendo paging dei pesi del modello.
chat_format	Sostituisce il template di chat incorporato.	Impostalo quando il template integrato del modello manca o è errato.

Nota che flash attention e quantizzazione KV-cache (type_k / type_v) si sono spostati tra le versioni — lo switch di flash-attention è stato un booleano in alcune versioni e un'impostazione a tre vie auto/on/off in altre. Esegui help(Llama) sulla tua versione installata invece di fidarti del nome di un flag da un blog post.

Tuning in pratica

Le due impostazioni che interagiscono sono n_gpu_layers e n_ctx. I pesi e la cache KV competono per la stessa VRAM, e la cache KV scala all'incirca linearmente con la lunghezza del contesto. Dimezzare n_ctx da 8192 a 4096 spesso libera memoria sufficiente per offloadare diversi strati in più, il che di solito è il trade-off migliore. Calcola il budget prima di iniziare a indovinare con il nostro Calcolatore VRAM, oppure controlla le cifre per modello nella guida dei requisiti di VRAM.

L'offload parziale funziona — è la caratteristica distintiva di llama.cpp — ma aspettati un calo netto una volta che uno strato rimane su CPU, perché ogni token deve attraversare il bus PCIe. Se riesci a contenere tutti gli strati, fallo.

Modalità server compatibile con OpenAI

pip install "llama-cpp-python[server]"

python -m llama_cpp.server 
  --model ./models/qwen2.5-7b-instruct-q4_k_m.gguf 
  --n_gpu_layers -1 
  --n_ctx 4096 
  --host 0.0.0.0 --port 8000

I flag del server rispecchiano gli argomenti del costruttore, caratteri di sottolineatura inclusi. Ottieni /v1/chat/completions, /v1/completions, /v1/models, e documentazione interattiva su /docs. Qualsiasi client OpenAI funziona, e lo streaming è supportato su SSE:

from openai import OpenAI

client = OpenAI(base_url="http://localhost:8000/v1", api_key="not-needed")
for event in client.chat.completions.create(
    model="gpt-3.5-turbo",  # ignorato a meno che tu non imposti alias di modello
    messages=[{"role": "user", "content": "Hello"}],
    stream=True,
):
    print(event.choices[0].delta.content or "", end="", flush=True)

Per più di un modello, passa --config_file config.json con un modelli array, assegnando a ogni voce un modello path, un model_alias che i client possono richiedere per nome, e il suo personale n_gpu_layers / n_ctx. Aggiungi --api_key se la porta è raggiungibile al di là di localhost. Pesando questo rispetto a un endpoint ospitato? Il Calcolatore del break-even self-hosting vs API fornisce i numeri.

Errori di compilazione comuni e correzioni

Sintomo	Causa	Soluzione
L'installazione ha successo ma nessuna riga GPU nell'output verbose	pip ha riutilizzato una wheel CPU nella cache	Reinstalla con --no-cache-dir --force-reinstall
Creazione della wheel fallita, CMake non trovato	Nessuna toolchain di build	Linux: build-essential più CMake. macOS: xcode-select --install. Windows: VS Build Tools workload C++
nvcc non trovato durante configure	Driver presente, toolkit mancante	Installa il CUDA Toolkit. La versione CUDA in nvidia-smi è il massimo del driver, non un toolkit installato
«unsupported GNU version» da nvcc	gcc di sistema più recente di quello supportato da CUDA	Punta CUDA a un compilatore più vecchio con -DCMAKE_CUDA_HOST_COMPILER=/usr/bin/gcc-12
Il computer si blocca o esaurisce la memoria durante la compilazione	Troppi job di compilazione paralleli	Imposta CMAKE_BUILD_PARALLEL_LEVEL=4 prima di pip install
«architettura modello sconosciuta» al caricamento	GGUF più recente della tua versione di llama.cpp	Aggiorna llama-cpp-python; è necessario un rebuild, non solo una modifica della configurazione
CUDA memoria esaurita al momento del caricamento	I pesi più la cache KV superano la VRAM	Più basso n_ctx innanzitutto, poi n_gpu_layers
Errore nell'allocazione dei buffer di calcolo	n_batch troppo grande per la memoria disponibile	Riduci n_batch (e n_ubatch)

Domande frequenti

llama-cpp-python è la stessa cosa di llama.cpp?

No. llama.cpp è il motore di inferenza C/C++; llama-cpp-python include un commit specifico e lo wrappa per Python. Poiché la versione inclusa è fissata per release, i binding possono rimanere indietro rispetto a upstream di giorni o settimane — il che conta quando un'architettura modello completamente nuova è appena arrivata in llama.cpp ma non ancora in una release binding pubblicata.

Come confermo che la GPU è davvero in uso?

Carica con verbose=True e cerca le righe di inizializzazione del backend e un rapporto dei layer scaricati sulla GPU. Quindi osserva nvidia-smi (o la cronologia GPU di Activity Monitor su macOS) durante una generazione. Se l'utilizzo della VRAM non aumenta e i token al secondo assomigliano a numeri da CPU, sei su una build solo CPU.

Posso evitare completamente la compilazione?

Spesso sì — usa gli indici wheel precompilati del progetto con --extra-index-url: abbinando il tag CUDA al tuo toolkit. Quando non esiste alcuna wheel corrispondente per la tua versione di Python e piattaforma, pip ricorre a un build da source, che tipicamente richiede diversi minuti con CUDA abilitato.

Should I use llama-cpp-python, Ollama, or LM Studio?

Usa llama-cpp-python quando vuoi il modello dentro il tuo stesso processo Python, con controllo diretto su campionamento, logit e grammatiche. Preferisci Ollama per un daemon gestito con pull di modelli e gestione automatica della memoria, o LM Studio per un'interfaccia grafica. Tutti e tre si basano su llama.cpp, quindi la qualità è comparabile; la differenza è nell'ergonomia.

Posso eseguire un modello più grande della mia VRAM?

Sì. Imposta n_gpu_layers a un valore inferiore al conteggio dei layer del modello e il resto gira su CPU con RAM di sistema. Funziona in modo affidabile ma la penalità di velocità è severa una volta che una quota significativa di layer rimane su CPU, quindi un modello più piccolo con quantizzazione più alta generalmente batte un modello grande mezzo-offloadato.

Il supporto GPU funziona su Windows senza WSL?

Funziona. Installa una wheel CUDA precompilata, oppure compila da source con Visual Studio Build Tools 2022 (Sviluppo Desktop con C++) installato prima del CUDA Toolkit, impostando $env:CMAKE_ARGS in PowerShell. WSL2 rimane il percorso più fluido se sei a tuo agio con esso, poiché le istruzioni di build per Linux sono più battute.