Skip to content

Run frontier MoE models on hardware you already own โ€” pure C, zero deps, experts streamed from disk. Tiny engine, immense model. ๐Ÿฆ

C
16.7 KB
Raw Blame

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รฌ?

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)

  1. Installa la libreria per Hugging Face:

    python -m pip install -U huggingface_hub[cli]
    

    Su Linux, usa python3 al posto di python.

  2. 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รฌ

  1. Vai a: https://github.com/JustVugg/colibri/blob/main/docker/Dockerfile
  2. Clicca il pulsante Download (icona โฌ‡๏ธ) in alto a destra
  3. 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-i e 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 risposta
  • Ctrl + 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:

  1. Reinstalla Docker Desktop
  2. Riavvia il computer
  3. 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):

  1. Apri PowerShell e controlla la memoria disponibile a WSL:

    wsl
    cat /proc/meminfo | grep MemTotal
    exit
    

    Dividi il numero per 1.073.741.824 (รจ 1024ยณ) per averlo in GB.

  2. 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\
  3. Riavvia WSL da PowerShell:

    wsl --shutdown
    wsl
    
  4. Controlla 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:

  1. Il disco รจ lento
  2. Hai poca RAM
  3. 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:

  1. Verifica che il Dockerfile sia nella cartella dove apri il terminale:
    ls Dockerfile  # Mac/Linux
    dir Dockerfile # Windows
    
  2. Riscarica il Dockerfile dal repository GitHub
  3. Elimina l'immagine vecchia: docker rmi colibri-i
  4. 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:

  1. Attendi e riprova il comando hf_download
  2. Se continua, scarica manualmente da qui
  3. 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 :reset per 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

  โ•ญโ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ•ฎ
  โ”‚ โ€บ