Run frontier MoE models on hardware you already own โ pure C, zero deps, experts streamed from disk. Tiny engine, immense model. ๐ฆ
Read the read me in English.
Guida a Colibrรฌ - Motore di Inferenza Locale
Una guida semplice per eseguire Colibrรฌ, un motore di inferenza locale basato su GLM 5.2, senza conoscenze di programmazione. Se hai giร Docker installato, sei a buon punto.
๐ Sommario
- Cosa รจ Colibrรฌ?
- Cosa serve
- Come iniziare
- Entrare nel container
- Risoluzione dei problemi
- Note tecniche
- Domande frequenti
- Supporto e contributi
- Testing on a low resource PC
Cosa รจ Colibrรฌ?
Colibrรฌ รจ un'applicazione che ti permette di eseguire un modello di intelligenza artificiale (GLM 5.2) direttamente sul tuo computer, senza connettersi a server esterni. ร possbile anche farlo girare in Docker, che isola l'applicazione dal resto del sistema.
Nota importante: Il modello รจ molto grande. Attendi anche diversi minuti per una risposta a una domanda semplice, specialmente con poca RAM. Alla fine di questo readme vedrai il risultato sul mio PC (senza scheda grafica discreta) e arrivo a 0.01 token al secondo.
Cosa serve
Hardware
| Memoria RAM | Funziona? | Note |
|---|---|---|
| < 16 GB | โ No | Memoria insufficiente |
| 24 GB | โ ๏ธ Forse | Possibile, da testare |
| 32 GB | โ Sรฌ | Il minimo (ma vedi sezione memoria su Windows) |
| 48+ GB | โ Sรฌ | Meglio |
Inoltre: un disco SSD veloce รจ essenziale. Colibrรฌ usa il disco come memoria aggiuntiva. Con una scheda grafica NVidia รจ ancora meglio.
Software
- Docker Desktop (Windows, Mac, Linux) โ scarica qui
- Python (solo se vuoi scaricare il modello da casa tua)
- Windows: python.org oppure Microsoft Store
- Linux:
apt-get install python3 python3-pip - Mac: python.org oppure Homebrew
Non serve nessun ambiente di compilazione. Tutto avviene dentro il container Docker.
Come iniziare
Passo 1: Scarica il modello
Il modello GLM 5.2 รจ circa 360 GB. Scegli uno di questi metodi:
Metodo A: Con Python (consigliato)
Installa la libreria per Hugging Face:
python -m pip install -U huggingface_hub[cli]Su Linux, usa
python3al posto dipython.Scarica il modello (apri il terminale nella cartella dove lo vuoi salvare):
hf_download mastouri/GLM-5.2-colibri-int4-g64-with-int8-mtp --local-dir .Esempio: se vuoi salvarlo in
C:\LLM\models\glm-5.2(Windows):- Apri PowerShell in quella cartella
- Copia e incolla il comando sopra
- Attendi (molto)
Metodo B: Senza Python (solo se necessario)
Se sei su Windows e non riesci con Python:
- Scarica manualmente da Hugging Face
- Decomprimi in una cartella (es.
C:\LLM\models\glm-5.2)
Passo 2: Scarica il Dockerfile di Colibrรฌ
- Vai a: https://github.com/JustVugg/colibri/blob/main/docker/Dockerfile
- Clicca il pulsante Download (icona โฌ๏ธ) in alto a destra
- Salva il file in una cartella (es.
C:\LLM\Colibrรฌ)
Passo 3: Compila l'immagine Docker
Apri il terminale (PowerShell su Windows, Terminal su Mac/Linux) nella cartella dove hai salvato il Dockerfile e digita:
Windows:
docker build -t colibri-i .
Linux/Mac:
sudo docker build -t colibri-i .
Attendi che finisca (pochi minuti). Se tutto va bene, vedrai: Successfully tagged colibri-i:latest
Se vuoi recepire gli aggiornamenti del repository: Cancella prima l'immagine vecchia con
docker rmi colibri-ie ricompila.
Passo 4: Avvia Colibrรฌ
Apri il terminale e digita il comando sottostante (sostituisci C:\LLM\models\glm-5.2 con il percorso reale del tuo PC):
Windows (PowerShell):
$MODEL_PATH="C:\LLM\models\glm-5.2"
docker run --rm -it --name colibri-c `
-v "$MODEL_PATH`:/app/glm-5.2" `
-e COLI_MODEL=/app/glm-5.2 `
colibri-i ./coli chat
Mac/Linux (Terminal/Bash):
MODEL_PATH="/path/to/glm-5.2"
docker run --rm -it --name colibri-c \
-v "$MODEL_PATH:/app/glm-5.2" \
-e COLI_MODEL=/app/glm-5.2 \
colibri-i ./coli chat
Esempio per Linux:
MODEL_PATH="/home/user/LLM/glm-5.2"
docker run --rm -it --name colibri-c \
-v "$MODEL_PATH:/app/glm-5.2" \
-e COLI_MODEL=/app/glm-5.2 \
colibri-i ./coli chat
Cosa significa quel comando?
| Parte | Spiegazione |
|---|---|
docker run |
Avvia un container |
--rm |
Cancella il container quando chiudi |
-it |
Modalitร interattiva (puoi scrivere e leggere) |
-v "PERCORSO:/app/glm-5.2" |
Collega il tuo modello dentro il container |
-e COLI_MODEL=/app/glm-5.2 |
Dice a Colibrรฌ dove trovare il modello |
colibri-i |
Nome dell'immagine Docker |
./coli chat |
Avvia Colibrรฌ in modalitร chat |
Usare Colibrรฌ
Una volta avviato, vedrai un prompt come questo:
โโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโ
type and press Enter ยท Ctrl-C stops the answer ยท :more continues ยท :reset clears memory ยท :q exits
Comandi utili:
Scrivi una domanda + Invioโ Ricevi la rispostaCtrl + Cโ Interrompi la risposta:resetโ Cancella la memoria della conversazione:qโ Esci
Esempio di uso:
โบ Quanti abitanti ha la Cina?
La Cina รจ attualmente il paese piรน popoloso al mondo.
La popolazione รจ di circa 1,41 miliardi di abitanti.
Il modello capisce italiano, inglese, cinese e altre lingue, anche se รจ ottimizzato per inglese e cinese.
Entrare nel container
Se vuoi esplorare il container come fosse una macchina Linux normale:
docker run --rm -it --name colibri-c \
-v "PERCORSO_MODELLO:/app/glm-5.2" \
-e COLI_MODEL=/app/glm-5.2 \
colibri-i /bin/bash
Ora sei dentro Linux. Digita exit per uscire.
Risoluzione dei problemi
โ "Docker non trovato"
Causa: Docker non รจ installato o il terminale non lo riconosce.
Soluzione:
- Reinstalla Docker Desktop
- Riavvia il computer
- Apri un nuovo terminale e riprova
โ "Out of memory" (memoria insufficiente) o container che si chiude subito
Causa: Il tuo computer non ha abbastanza RAM, oppure su Windows, WSL usa meno memoria di quella disponibile.
Soluzione per Windows (WSL):
Apri PowerShell e controlla la memoria disponibile a WSL:
wsl cat /proc/meminfo | grep MemTotal exitDividi il numero per 1.073.741.824 (รจ 1024ยณ) per averlo in GB.
Se WSL usa meno di quello che hai, crea un file di configurazione:
- Apri un editor di testo (Notepad va bene)
- Copia questo:
[wsl2] memory=24GB processors=12 swap=16GB - Salva il file con il nome:
.wslconfig(con il punto) - Posizionalo in:
C:\Users\TuoNomeUtente\
Riavvia WSL da PowerShell:
wsl --shutdown wslControlla di nuovo:
# cat /proc/meminfo | grep MemTotal # exit
Soluzione per Mac/Linux: Aumenta la RAM disponibile a Docker dalle impostazioni di Docker Desktop, oppure aggiungi piรน RAM al computer.
โ La risposta รจ molto lenta
Cause possibili:
- Il disco รจ lento
- Hai poca RAM
- Colibrรฌ sta usando il disco come memoria aggiuntiva (normale)
Come controllare la velocitร del disco:
Windows (PowerShell da amministratore):
winsat disk -drive C
Cambia C con la lettera del tuo disco.
Linux/Mac (Terminal):
sudo hdparm -Tt /dev/sda
Cambia /dev/sda con il tuo disco (vedi con lsblk per Linux).
Un SSD NVMe moderno arriva a 15 GB/sec. Se il tuo รจ sotto 2-3 GB/sec, รจ lento.
โ "Permission denied" su Linux
Causa: Docker richiede permessi da amministratore.
Soluzione - Opzione 1 (rapida):
sudo docker build -t colibri-i .
sudo docker run ... (come sopra, con sudo davanti)
Soluzione - Opzione 2 (permanente):
sudo usermod -aG docker $USER
# Riavvia il computer
docker run ... (senza sudo)
โ "Image not found" o errore durante il build
Causa: Il Dockerfile รจ corrotto o non nella cartella giusta.
Soluzione:
- Verifica che il Dockerfile sia nella cartella dove apri il terminale:
ls Dockerfile # Mac/Linux dir Dockerfile # Windows - Riscarica il Dockerfile dal repository GitHub
- Elimina l'immagine vecchia:
docker rmi colibri-i - Riprova il build
โ "hf_download: command not found"
Causa: La libreria Hugging Face non รจ installata correttamente.
Soluzione:
pip install -U huggingface_hub[cli]
# oppure su Linux/Mac:
pip3 install -U huggingface_hub[cli]
Poi riprova il comando hf_download.
โ Il modello non si scarica (timeout o errori di rete)
Cause: Connessione lenta o instabile, Hugging Face temporaneamente non disponibile.
Soluzione:
- Attendi e riprova il comando
hf_download - Se continua, scarica manualmente da qui
- Decomprimi il file ZIP nella cartella desiderata
Note tecniche
Perchรฉ il disco รจ importante?
Colibrรฌ usa il disco come "RAM aggiuntiva" virtuale (paging). Un disco veloce รจ cruciale per prestazioni decenti.
- SSD NVMe (consigliato): 1-15 GB/sec
- SSD SATA: 0.5-1 GB/sec
- Hard disk meccanico: 0.05-0.1 GB/sec โ (troppo lento)
Se il tuo disco รจ lento, le risposte saranno molto lente anche con molta RAM.
Configurazione di default consigliata per WLS su Windows
Se hai esattamente 32 GB di RAM e usi Windows, รจ molto probabile che WLS di default sia settato per non consumare piรน di 16 GB di RAM. Bisogna aumentare questo limite Risoluzione dei problemi . Nel mio caso ho adottato questa configurazione:
[wsl2]
memory=24GB
processors=12
swap=16GB
Ovvero, nel mio caso, ho lasciato 8 GB di RAM e 4 CPU a Windows e dato 24 GB e 12 processori a WSL + Linux.
Domande frequenti
D: E se ho meno di 32 GB di RAM?
R: Probabile che non funzioni bene. Puoi provare se hai 24 GB, ma non รจ garantito.
D: Posso aumentare la velocitร di risposta?
R: Sรฌ, in parte:
- Usa un SSD NVMe veloce
- Aumenta la RAM
- Riduci la complessitร delle domande
- Usa
:resetper cancellare la memoria e alleggerire il carico
D: Posso usare Colibrรฌ senza Docker?
R: Colibrรฌ รจ nato cosรฌ, ma questa guida assume Docker. Per compilare da sorgente, vedi il repository GitHub.
D: Quanta connessione internet mi serve dopo aver scaricato il modello?
R: Zero. Colibrรฌ funziona completamente offline.
Supporto e contributi
Se trovi errori o hai suggerimenti per migliorare questa guida, aprici una issue o una pull request sul repository GitHub di Colibrรฌ.
Buon divertimento! ๐ฆ
Test su un PC con poche risorse
Nel primo caso ho fatto una domanda in italiano, nel secondo in giapponese, e nel terzo ho rifatto la domanda in giapponese ma ho richiesto una risposta in italiano.
PS C:\quack\llm\colibri\docker> docker run --rm -it --name colibri-c -v "C:\quack\llm\models\glm-5.2:/app/glm-5.2" -e COLI_MODEL=/app/glm-5.2 colibri-i ./coli chat
โโโโโ โ colibrรฌ v1.0
โโโโโโโโโโโ tiny engine, immense model
โโโโโโโ GLM-5.2 ยท 744B MoE ยท int4 ยท streaming CPU
โโโโ chat ยท glm-5.2 ยท ram -GB ยท topp off
โ
โโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโ
type and press Enter ยท Ctrl-C stops the answer ยท :more continues ยท :reset clears memory ยท :q exits
โญโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโฎ
โ โบ Quanti abitanti ha la Cina? โ
โฐโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโฏ
โ colibrรฌ
La Cina รจ attualmente il paese piรน popoloso al mondo (sebbene, secondo alcune stime recenti, sia stata ormai superata dall'India).
La popolazione totale della Repubblica Popolare Cinese รจ di circa 1,41 miliardi di abitanti (dati del 2020-2022 circa).
โโ 76 tok ยท 0.04 tok/s ยท hit 3% ยท RSS 15.9 GB ยท 2012s
โญโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโฎ
โ โบ ๆผซ็ปใใฏใณใใผในใใฎไธปไบบๅ
ฌใฎๅๅใๆใใฆใใ ใใใๅๅใ ใใงใใใไปฅไธใฎใณใกใณใใฏใใใพใใใ โ
โฐโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโฏ
โ colibrรฌ
ใซใใฃ
โโ 2 tok ยท 0.01 tok/s ยท hit 1% ยท RSS 16.7 GB ยท 260s
โญโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโฎ
โ โบ ๆผซ็ปใใฏใณใใผในใใฎไธปไบบๅ
ฌใฎๅๅใๆใใฆใใ ใใใๅๅใ ใใงใใใไปฅไธใฎใณใกใณใใฏใใใพใใใใคใฟใชใข่ชใง่ฟไฟก โ
โฐโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโฏ
โ colibrรฌ
Il nome del protagonista di One Piece รจ Monkey D. Luffy.
โโ 14 tok ยท 0.02 tok/s ยท hit 2% ยท RSS 17.3 GB ยท 593s
โญโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโฎ
โ โบ