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)

  1. Apri PowerShell come amministratore ed esegui wsl --install
  2. Riavvia, poi imposta nome utente e password di Ubuntu
  3. Installa un driver NVIDIA recente su Windows, non dentro WSL — espone la GPU automaticamente
  4. Nel terminale Ubuntu, conferma la GPU con nvidia-smi
  5. 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, valuta delete_original=True o punta layer_shards_saving_path su un disco più capiente
  • ValueError: max() arg is an empty sequence — Hai usato una classe specifica (come AirLLMLlama2) con un modello incompatibile. Usa sempre AutoModel
  • 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:

  1. import airllm non genera errori e stampa la versione corretta (v3.1.0)
  2. L’acceleratore hardware è rilevato (torch.cuda.is_available() restituisce True su NVIDIA, oppure torch.backends.mps.is_available() su Apple Silicon)
  3. Lo script di prima esecuzione genera testo coerente dopo il download e lo splitting del modello
  4. 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.

Share the Post:

Related Posts