AirLLM: Guida all’Installazione Passo Passo per Eseguire Modelli LLM Localmente
Eseguire un modello da 2,8 trilioni di parametri su una GPU da 4 GB non è più teoria. AirLLM lo rende possibile caricando un layer alla volta in memoria, così la dimensione complessiva dei pesi smette di dettare l’hardware necessario. Questa guida copre l’installazione completa su Linux, macOS e Windows, la prima esecuzione, la compressione e gli errori più comuni, tutto ciò che serve per passare dal terminale vuoto a un modello funzionante.
Obiettivo finale: ottenere un ambiente Python funzionante con AirLLM v3.1.0, verificare che il pacchetto comunichi con l’acceleratore hardware e generare il primo output di testo.
Prerequisiti: Python 3.9 o superiore, pip aggiornato, spazio su disco sufficiente e una connessione a internet per scaricare i modelli da Hugging Face.
Fasi previste: preparazione dell’ambiente, installazione specifica per sistema operativo, verifica, prima esecuzione, compressione opzionale.
Promuovendo l’Umanesimo Tecnologico, sottolineo spesso un principio applicabile anche a questa guida: capire prima di automatizzare. Installare uno strumento è il primo passo; comprendere come funziona è ciò che lo rende utile.
Come funziona AirLLM e perché cambia i requisiti hardware
AirLLM è una libreria open source con licenza Apache 2.0 che scompone un modello linguistico in shard per singolo layer scritti su disco. Durante la generazione, carica un layer alla volta nella GPU, esegue il calcolo e lo scarica prima di passare al successivo. La memoria necessaria non scala con il numero totale di parametri, ma con la dimensione del singolo layer più grande.
Per i modelli mixture-of-experts (MoE), lo streaming avviene esperto per esperto. È per questo che modelli enormi come Kimi K3 da 2,8T parametri richiedono appena 3,72 GB di VRAM, mentre un Llama 3.x 70B denso ne richiede circa 4 GB e un Llama 3.1 405B circa 8 GB.
La fase di splitting è lenta e pesante per il disco, ma avviene una sola volta per modello. Le esecuzioni successive riutilizzano gli shard già creati. Il repository ufficiale è disponibile su GitHub e il pacchetto su PyPI.
Prerequisiti: cosa serve prima di installare AirLLM
L’installazione in sé è un solo comando. Ciò che determina davvero se AirLLM funzionerà è lo spazio su disco.
Creare un ambiente virtuale
Fortemente consigliato. Tenere AirLLM isolato evita di rompere altri progetti Python.
Linux / macOS:
python3 -m venv airllm-env
source airllm-env/bin/activate
Windows PowerShell:
python -m venv airllm-env
.\airllm-env\Scripts\Activate.ps1
Il prompt dovrebbe ora mostrare il prefisso (airllm-env). Se non lo vedi, l’attivazione non è andata a buon fine.
Errore comune: dimenticare di attivare l’ambiente virtuale prima di installare i pacchetti. Ogni comando pip install successivo deve avvenire dentro l’ambiente attivato.
AirLLM setup tutorial: installazione su Linux con NVIDIA
Questo è il percorso principale e meglio supportato, con accelerazione CUDA completa e tutti gli extra opzionali disponibili.
Passo 1 — Verifica il driver NVIDIA
nvidia-smi
Dovresti vedere la tua GPU e una versione di CUDA. Se il comando non viene trovato, installa il driver NVIDIA per la tua distribuzione prima di proseguire.
Passo 2 — Installa PyTorch con CUDA
pip install torch --index-url https://download.pytorch.org/whl/cu124
Per i modelli recenti è consigliata CUDA 12.x. Se il tuo driver è più vecchio, scegli il wheel corrispondente dalla guida ufficiale PyTorch.
Errore comune: installare PyTorch senza specificare l’index URL CUDA. Il risultato è una build solo CPU, e torch.cuda.is_available() restituirà False.
Passo 3 — Installa AirLLM
pip install airllm
Il pacchetto porta con sé transformers, accelerate, safetensors e le altre dipendenze in automatico.
Passo 4 (opzionale) — bitsandbytes per la compressione
pip install -U bitsandbytes
Serve solo per la quantizzazione a 4-bit o 8-bit.
Passo 5 (opzionale) — Extra per modelli recenti
pip install compressed-tensors flash-attn
Installali solo se il caricamento di un modello li richiede espressamente. flash-attn viene compilato dai sorgenti e può richiedere molto tempo.
Come installare AirLLM su macOS Apple Silicon
L’installazione su macOS funziona solo su Apple Silicon — M1, M2, M3, M4. I Mac Intel non sono supportati. AirLLM usa MLX, il framework di array di Apple, per l’inferenza accelerata.
Passo 1 — Verifica di usare un Python ARM nativo
python3 -c "import platform; print(platform.machine())"
L’output deve essere arm64. Se leggi x86_64, stai usando un Python emulato con Rosetta e MLX non funzionerà. Installa un Python nativo, ad esempio con brew install python@3.11 tramite Homebrew in /opt/homebrew.
Passo 2 — Installa MLX e PyTorch
pip install mlx torch
Passo 3 — Installa AirLLM
pip install airllm
Passo 4 — Adatta il codice
L’API è identica a quella Linux, con una differenza critica: non chiamare .cuda() sui tensori di input. Passa input_tokens['input_ids'] direttamente a model.generate().
Il supporto macOS è presente dalla v2.8.2. La pressione sulla memoria unificata conta molto — chiudi le applicazioni pesanti prima di eseguire un modello grande.
AirLLM configurazione passo passo su Windows
Il pacchetto è indipendente dal sistema operativo, ma parti dell’ecosistema sono meno affidabili su Windows nativo. Esistono due percorsi.
Opzione A — WSL2 (consigliata)
- Apri PowerShell come amministratore ed esegui
wsl --install - Riavvia, poi imposta nome utente e password di Ubuntu
- Installa un driver NVIDIA recente su Windows, non dentro WSL — espone la GPU automaticamente
- Nel terminale Ubuntu, conferma la GPU con
nvidia-smi - Segui la sezione Linux esattamente come scritta
Errore comune: tenere la cache di Hugging Face sul filesystem Windows (/mnt/c/). L’I/O tra filesystem in WSL è drasticamente più lento. Usa ~/.cache/huggingface nel filesystem Linux.
Opzione B — Windows nativo
python -m venv airllm-env
.\airllm-env\Scripts\Activate.ps1
pip install -U pip
pip install torch --index-url https://download.pytorch.org/whl/cu124
pip install airllm
Note importanti per Windows nativo:
- Percorsi lunghi — i percorsi degli shard possono diventare molto profondi. Abilita il supporto ai percorsi lunghi (Impostazioni → Sistema → Per gli sviluppatori)
- bitsandbytes — i wheel per Windows esistono ma sono meno stabili. Se fallisce, rinuncia alla compressione o passa a WSL2
- flash-attn — in genere non compila su Windows nativo. Usa WSL2 se un modello lo richiede
Il progetto non pubblica istruzioni ufficiali per Windows. Questa sezione riflette la prassi consolidata dell’ecosistema circostante.
Verificare l’installazione di AirLLM
Due controlli bastano: il pacchetto si importa e PyTorch vede l’acceleratore.
Controllo 1 — Versione del pacchetto:
python -c "import airllm; print(airllm.__version__)"
Controllo 2 — Acceleratore NVIDIA (Linux / WSL / Windows):
python -c "import torch; print(torch.cuda.is_available(), torch.cuda.get_device_name(0))"
Controllo 2 — Acceleratore Apple Silicon:
python -c "import torch, mlx.core as mx; print(torch.backends.mps.is_available(), mx.default_device())"
Se l’import va a buon fine e l’acceleratore viene rilevato, sei pronto per la prima esecuzione.
La prima esecuzione: installare modelli LLM localmente
Parti da qualcosa di contenuto per verificare l’intera pipeline prima di scaricare un modello da 70B.
from airllm import AutoModel
MAX_LENGTH = 128
model = AutoModel.from_pretrained("Qwen/Qwen3-32B")
input_text = ['What is the capital of United States?']
input_tokens = model.tokenizer(
input_text,
return_tensors="pt",
return_attention_mask=False,
truncation=True,
max_length=MAX_LENGTH,
padding=False,
)
generation_output = model.generate(
input_tokens['input_ids'].cuda(), # togli .cuda() su macOS / solo CPU
max_new_tokens=20,
use_cache=True,
return_dict_in_generate=True,
)
print(model.tokenizer.decode(generation_output.sequences[0]))
Cosa aspettarsi la prima volta: un download lungo, poi una fase di splitting dei layer che scrive un’enorme quantità di dati su disco. Porta pazienza e tieni d’occhio lo spazio libero. Le esecuzioni successive saltano entrambi i passaggi.
AirLLM funziona senza configurazioni aggiuntive con la maggior parte dei modelli aperti diffusi — Llama 2, 3, 3.1, 3.3 e 4, Qwen, DeepSeek, Mistral, Phi, Gemma, ChatGLM, Baichuan, InternLM, Yi e altri. Usa sempre AutoModel — seleziona da sé l’architettura corretta.
Nell’approccio di Ace Spagni alla formazione sulla metacognizione, la comprensione del funzionamento interno degli strumenti è il primo livello di competenza. Sapere che AirLLM scorre i layer uno alla volta non è un dettaglio tecnico irrilevante: è ciò che ti permette di ottimizzare disco e memoria in modo consapevole.
Compressione 4-bit e 8-bit: velocità triplicata
La quantizzazione a blocchi riduce i dati spostati dal disco alla GPU a ogni layer — il collo di bottiglia principale. Aspettati all’incirca un triplo di velocità.
pip install -U bitsandbytes
pip install -U airllm # richiede airllm >= 2.0.0
model = AutoModel.from_pretrained(
"garage-bAInd/Platypus2-70B-instruct",
compression='4bit', # oppure '8bit'
)
Vengono quantizzati solo i pesi; le attivazioni restano a precisione piena, il che mantiene contenuta la perdita di accuratezza.
Opzioni di configurazione avanzate
Tutti i parametri si passano a AutoModel.from_pretrained().
Esempio con configurazione completa:
model = AutoModel.from_pretrained(
"meta-llama/Llama-2-70b-hf",
compression='4bit',
delete_original=True,
layer_shards_saving_path='/mnt/fast-ssd/airllm-shards',
hf_token='hf_xxxxxxxxxxxxxxxxxxxx',
)
Un NVMe per gli shard fa una differenza notevole sulla velocità di generazione.
Risoluzione dei problemi più comuni
Gli errori che incontrerai più facilmente, e cosa li provoca davvero.
- MetadataIncompleteBuffer — Quasi sempre significa spazio su disco esaurito durante lo splitting. Svuota
~/.cache/huggingface, libera spazio, valutadelete_original=Trueo puntalayer_shards_saving_pathsu un disco più capiente - ValueError: max() arg is an empty sequence — Hai usato una classe specifica (come
AirLLMLlama2) con un modello incompatibile. Usa sempreAutoModel - 401 Client Error — Il modello è ad accesso limitato su Hugging Face. Accetta la licenza sulla pagina del modello e passa il tuo token con
hf_token - Errore per token di padding mancante — Alcuni tokenizer non hanno un pad token. Disattiva il padding:
model.tokenizer(input_text, padding=False) - torch.cuda.is_available() restituisce False — Build PyTorch solo CPU. Reinstalla con l’index URL CUDA corretto
- macOS: l’import di MLX fallisce — Python x86 sotto Rosetta. Reinstalla un Python arm64 nativo
La consulenza di Ace Spagni sull’Umanesimo Tecnologico parte proprio da qui: la capacità di diagnosticare un problema tecnico è una competenza metacognitiva. Non si tratta solo di copiare comandi, ma di comprendere la catena causale tra errore e soluzione.
Come verificare che tutto funzioni correttamente
Il processo è completato con successo quando:
import airllmnon genera errori e stampa la versione corretta (v3.1.0)- L’acceleratore hardware è rilevato (
torch.cuda.is_available()restituisceTruesu NVIDIA, oppuretorch.backends.mps.is_available()su Apple Silicon) - Lo script di prima esecuzione genera testo coerente dopo il download e lo splitting del modello
- Le esecuzioni successive partono senza riscaricare né rieseguire lo splitting
Se tutti e quattro i punti sono soddisfatti, l’installazione è completa e l’ambiente è pronto per l’uso in produzione o per la sperimentazione.
Disinstallazione
Rimuovere il pacchetto è banale; recuperare lo spazio su disco è la parte che conta.
pip uninstall airllm
Poi elimina la cache dei modelli:
## Linux / macOS / WSL
rm -rf ~/.cache/huggingface
## Windows
Remove-Item -Recurse -Force $env:USERPROFILE\.cache\huggingface
Elimina infine la cartella airllm-env se l’ambiente virtuale non ti serve più.
Domande frequenti
Quanta VRAM serve per eseguire un modello da 70B con AirLLM?
Un modello denso da 70B come Llama 3.x richiede circa 4 GB di VRAM con AirLLM. La memoria GPU necessaria dipende dalla dimensione del singolo layer più grande, non dal numero totale di parametri. I modelli mixture-of-experts richiedono ancora meno: Kimi K3 da 2,8 trilioni di parametri entra in 3,72 GB.
AirLLM funziona senza GPU?
Sì, dalla versione 2.10.1 AirLLM supporta l’inferenza solo su CPU. Tuttavia le prestazioni sono significativamente inferiori rispetto all’esecuzione con GPU. Per un uso pratico, una GPU NVIDIA con almeno 4 GB di VRAM o un Mac con Apple Silicon sono fortemente consigliati.
Posso usare AirLLM su Mac con processore Intel?
No. Il supporto macOS di AirLLM è limitato ad Apple Silicon (M1, M2, M3, M4) tramite il framework MLX. I Mac con processore Intel non sono supportati.
Quanto spazio su disco serve per un modello da 70B?
Serve circa la dimensione completa del modello in FP16 — circa 140 GB per un 70B — più lo spazio per il download originale. Impostando delete_original=True si eliminano i file originali dopo lo splitting, dimezzando all’incirca il fabbisogno totale di disco.
La compressione 4-bit riduce la qualità dell’output?
La perdita di accuratezza è contenuta perché vengono quantizzati solo i pesi, mentre le attivazioni restano a precisione piena. Il vantaggio principale è una velocità circa tripla, dato che si riducono i dati spostati dal disco alla GPU a ogni layer.

