Llama Cpp Python: installazione, compilazione con supporto GPU e parametri

llama-cpp-python è il binding Python per llama.cpp. Carica modelli GGUF direttamente nel processo, espone un wrapper ctypes a basso livello oltre a una classe ad alto livello e include un server HTTP compatibile con OpenAI. L'installazione predefinita tramite pip compila una versione funzionante solo su CPU. Per utilizzare la GPU occorre installare una wheel con supporto GPU oppure ricompilare da sorgente con Llama , quindi passare CMAKE_ARGScome parametro. n_gpu_layers.

Perché l'installazione predefinita supporta solo la CPU

Il pacchetto è un sottile binding intorno a una libreria C++ che deve essere compilata con il supporto per il backend integrato già al momento della compilazione. Non esiste alcun flag di runtime che attivi CUDA a posteriori. Quando pip compila l'archivio sorgente (sdist) senza aver specificato CMAKE_ARGS nessun parametro, CMake configura automaticamente il backend generico per CPU, e questo è ciò che si ottiene in modo definitivo, fino a quando non si esegue nuovamente la compilazione. Su macOS arm64 questo problema è meno rilevante perché nelle versioni recenti il backend Metal viene abilitato di default; su Linux e Windows, invece, un'installazione standard verrà eseguita interamente sulla CPU.

Due conseguenze da tenere bene a mente: innanzitutto, n_gpu_layers=-1 in una build priva di supporto GPU non ha alcun effetto utile, portando spesso gli utenti a concludere erroneamente che la propria GPU sia «troppo lenta», mentre in realtà non è mai stata utilizzata. In secondo luogo, pip memorizza nella cache le wheel già compilate. Se si esegue nuovamente l’installazione con parametri diversi, potrebbe venire restituita la wheel per CPU precedentemente memorizzata nella cache; ecco perché ogni comando di ricompilazione riportato di seguito include CMAKE_ARGS --no-cache-dir --force-reinstall Opzione 1: wheel precompilate (nessun compilatore necessario).

Installare llama-cpp-python con supporto GPU

Il progetto pubblica indici di wheel, inclusi un indice per CPU all’indirizzo

https://abetlen.github.io/llama-cpp-python/whl/cpu e varianti CUDA il cui segmento di percorso codifica la versione di CUDA, ad esempio .../whl/cu124 . Per installare, eseguire:pip install llama-cpp-python --extra-index-url https://abetlen.github.io/llama-cpp-python/whl/cu124

Le versioni di CUDA e le versioni di Python supportate variano ad ogni rilascio, e gli indici possono talvolta risultare leggermente in ritardo rispetto alla versione più recente disponibile su PyPI. Consultare il README del progetto per verificare quali tag sono effettivamente disponibili, anziché presupporne l’esistenza: un tag errato restituirà un errore 404 e pip passerà silenziosamente alla compilazione da sorgente.

Opzione 2: compilazione da sorgente (Linux, CUDA)

È necessario disporre di una toolchain C++, di CMake e del toolkit CUDA, con

nvcc disponibile nel PATH. nvcc --version # deve visualizzare una versione, non l'errore "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: le guide molto vecchie usano

-DLLAMA_CUBLAS=on , quelle di metà 2024 usano-DLLAMA_CUDA=on , mentre la versione corrente upstream utilizza il prefissoGGML_ . Se la compilazione fallisce a causa di un'opzione CMake sconosciuta, questa discrepanza è quasi sempre la causa. Anche gli altri backend seguono lo stesso schema: Vulkan usa -DGGML_VULKAN=on , SYCL usa-DGGML_SYCL=on , mentre l’opzione per AMD/ROCm è stata rinominata più volte; pertanto, consultare il README della versione installata piuttosto che copiare un flag da un post su un forum.È possibile ridurre sensibilmente i tempi di compilazione limitando la build alla compute capability specifica della propria GPU, ad esempio

-DCMAKE_CUDA_ARCHITECTURES=89 per una GPU Ada come l’RTX 4090, oppure per una RTX 3090. Verificare la compute capability della propria scheda grafica nell’elenco ufficiale NVIDIA; se si sta ancora valutando l’acquisto dell’hardware, la nostra 86 guida alle migliori GPU per eseguire LLM in locale analizza i compromessi tra VRAM e costo. Opzione 3: macOS con Metal

xcode-select --installCMAKE_ARGS="-DGGML_METAL=on" pip install llama-cpp-python --no-cache-dir --force-reinstall

Su Apple Silicon, verificare di non utilizzare un interprete Python x86 tramite Rosetta:

python -c "import platform; print(platform.machine())" deve restituire arm64 . Un interprete x86_64 produrrà comunque una build priva di supporto Metal, indipendentemente dai valori impostati in CMAKE_ARGS. Poiché su Apple Silicon GPU e CPU condividono la stessa memoria,è quasi sempre l’impostazione corretta in questo caso. n_gpu_layers=-1 Opzione 4: Windows con CUDA

Installare Visual Studio Build Tools 2022 con il carico di lavoro «Sviluppo desktop con C++»

, quindi il toolkit CUDA, affinché quest’ultimo possa integrarsi correttamente con Visual Studio già installato. Successivamente, in PowerShell: primo$env:CMAKE_ARGS = "-DGGML_CUDA=on" pip install llama-cpp-python --no-cache-dir --force-reinstall --upgrade

In cmd.exe

In l’equivalente è set CMAKE_ARGS=-DGGML_CUDA=on su una riga separata. Le compilazioni da sorgente su Windows rappresentano il percorso più soggetto a errori tra le tre piattaforme; se l’obiettivo è semplicemente l’inferenza e non una build personalizzata, le wheel CUDA precompilate o WSL2 costituiscono entrambe scelte meno problematiche. Il controllo più affidabile è l’output dettagliato del caricatore, indipendente dalla versione:

Come verificare quale versione è stata installata

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

In una build CUDA appariranno righe di inizializzazione del backend che menzionano CUDA e il nome del dispositivo, oltre a una riga relativa al caricamento dei tensori che indica quanti strati del modello sono stati scaricati sulla GPU. Con Metal compariranno invece righe relative al dispositivo Metal. Una build per CPU mostrerà né l’una né l’altra, indicando zero strati scaricati sulla GPU. Verificare incrociando con

In una build CUDA vedrai righe di inizializzazione del backend che menzionano CUDA e un nome del dispositivo, oltre a una riga di caricamento dei tensori che indica quante delle layer del modello sono state offloadate sulla GPU. Su Metal vedrai invece righe relative al dispositivo Metal. Una build esclusivamente CPU non stampa nessuna di queste righe e riporta zero layer offloadate. Verifica incrociata con nvidia-smi durante la generazione: se il processo Python non sta occupando la VRAM, nulla viene eseguito sulla GPU.

Le versioni recenti espongono inoltre un controllo diretto delle capacità:

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

Se tale attributo genera un'eccezione AttributeError, la tua build è precedente a questa funzionalità: torna al metodo basato sui log verbosi.

Caricamento di un file GGUF ed esecuzione della prima generazione di testo

Punto model_path a qualsiasi file GGUF. Se preferisci scaricare direttamente da Hugging Face, Llama.from_pretrained(repo_id=..., filename="*Q4_K_M.gguf", ...) esegue automaticamente il download 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": "Spiega cos'è una cache KV in due frasi."}],
    max_tokens=256,
    temperature=0.7,
)
print(out["choices"][0]["message"]["content"])

Per la continuazione diretta di testo non strutturato, chiama l'oggetto direttamente: llm("Q: Cos'è un file GGUF? A:", max_tokens=128, stop=["Q:"]) e leggi out["choices"][0]["text"].

Streaming dei token

Passa stream=True e itera. La struttura della risposta rispecchia il formato di streaming OpenAI, quindi il primo chunk contiene tipicamente solo il ruolo ("role"), mentre i chunk successivi contengono i delta relativi al campo content (contenuto):

stream = llm.create_chat_completion(
    messages=[{"role": "user", "content": "Scrivi un haiku sui file GGUF."}],
    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 modello di chat che llama-cpp-python applica automaticamente. Quando l'output appare corrotto o il modello non termina mai, il modello di chat è il primo sospettato: sovrascrivilo utilizzando l'argomento chat_format Esplora le opzioni quantizzate e le relative dimensioni nella nostra Database di modelli IA.

I parametri che contano

Nota che l'attenzione flash e la quantizzazione della cache KV (type_k / type_vsono state modificate tra le varie versioni — l'opzione flash-attention è stata un semplice valore booleano in alcune versioni e un'impostazione a tre opzioni (auto/on/off) in altre. Eseguire help(Llama) sulla versione installata piuttosto che fidarsi di un nome di flag preso da un articolo sul web.

Ottimizzazione nella pratica

Le due impostazioni che interagiscono sono n_gpu_layers e n_ctx. Pesi e cache KV competono per la stessa VRAM, e la cache KV cresce approssimativamente in modo lineare con la lunghezza del contesto. Ridurre n_ctx da 8192 a 4096 libera spesso memoria sufficiente per scaricare su GPU diversi strati aggiuntivi, il che rappresenta generalmente un compromesso migliore. Calcolare preventivamente il budget disponibile prima di procedere a tentativi casuali, utilizzando il nostro Calcolatore VRAM, oppure verificare i dati specifici per ciascun modello nella tabella di riferimento dei requisiti di VRAM.

Lo scaricamento parziale funziona — è infatti la caratteristica distintiva di llama.cpp — ma ci si deve aspettare un calo significativo delle prestazioni non appena anche un solo strato rimane sulla CPU, poiché ogni token deve attraversare il bus PCIe. Se è possibile caricare tutti gli strati sulla GPU, farlo.

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 esattamente gli argomenti del costruttore, compresi i trattini bassi. Si ottiene /v1/chat/completions, /v1/completions, /v1/models, e documentazione interattiva all'indirizzo /docs. Qualsiasi client OpenAI è compatibile e lo streaming è supportato tramite 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 non si configurino alias di modello
    messages=[{"role": "user", "content": "Ciao"}],
    stream=True,
):
    print(event.choices[0].delta.content or "", end="", flush=True)

Per gestire più di un modello, passare --config_file config.json con un modelli array, in cui ogni voce specifichi un modello path, un model_alias che i client possono richiedere per nome, e i propri parametri n_gpu_layers / n_ctx. Aggiungere --api_key se la porta è accessibile anche da indirizzi esterni a localhost. Valutare questa soluzione rispetto a un endpoint ospitato? Il Calcolatore del punto di pareggio tra auto-hosting e utilizzo di API fornisce dati quantitativi al riguardo.

Errori comuni durante la compilazione e relative soluzioni

Domande frequenti

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

No. llama.cpp è il motore di inferenza in C/C++; llama-cpp-python include una specifica commit di tale progetto e ne fornisce un’interfaccia per Python. Poiché la versione inclusa è bloccata per ogni rilascio, i binding possono rimanere indietro rispetto al codice principale di llama.cpp di alcuni giorni o settimane — aspetto rilevante quando una nuova architettura di modello è stata appena integrata in llama.cpp, ma non è ancora disponibile in una versione pubblicata dei binding.

Come faccio a verificare che la GPU venga effettivamente utilizzata?

Carica con verbose=True e cerca le righe di inizializzazione del backend e il rapporto sul numero di livelli scaricati sulla GPU. Quindi osserva nvidia-smi (o la cronologia dell’utilizzo della GPU nel Monitor attività su macOS) durante la generazione. Se l’utilizzo della VRAM non aumenta e i token al secondo sono simili a quelli ottenibili su CPU, stai utilizzando una build esclusivamente per CPU.

Posso evitare completamente la compilazione?

Spesso sì: usa gli indici di wheel precompilati del progetto con l’opzione --extra-index-url, assicurandoti che il tag CUDA corrisponda alla tua versione del toolkit. Quando non esiste un wheel compatibile per la tua versione di Python e piattaforma, pip ricade automaticamente su una compilazione da sorgente, che richiede tipicamente diversi minuti con CUDA abilitato.

Devo usare llama-cpp-python, Ollama o LM Studio?

Usa llama-cpp-python quando desideri caricare il modello direttamente nel tuo processo Python, con controllo diretto sui parametri di campionamento, sui logit e sulle grammatiche. Preferisci Ollama per un demone gestito con supporto al download dei modelli e gestione automatica della memoria, oppure LM Studio per un’interfaccia grafica. Tutti e tre si basano su llama.cpp, quindi la qualità è paragonabile; la differenza sta nell’usabilità.

Posso eseguire un modello più grande della mia VRAM?

Sì. Imposta n_gpu_layers a un valore inferiore al numero totale di livelli del modello: i livelli rimanenti verranno eseguiti sulla CPU utilizzando la RAM di sistema. Questo approccio funziona in modo affidabile, ma la penalità in termini di velocità diventa severa non appena una percentuale significativa di livelli rimane sulla CPU; pertanto, un modello più piccolo con una quantizzazione più elevata offre generalmente prestazioni migliori rispetto a un modello più grande parzialmente scaricato sulla CPU.

Il supporto GPU funziona su Windows senza WSL?

Sì. Puoi installare un wheel CUDA precompilato oppure compilare da sorgente utilizzando Visual Studio Build Tools 2022 (con il carico di lavoro «Sviluppo desktop con C++») installato prima del CUDA Toolkit, impostando la variabile di ambiente $env:CMAKE_ARGS in PowerShell. Tuttavia, WSL2 rimane il percorso più agevole se ti trovi a tuo agio con esso, poiché le istruzioni per la compilazione su Linux sono più consolidate.