Added Dockerfile and instructions for using Colibrì through a docker container

2026-07-19 16:49:29 +02:00
parent 72874f38a2
commit 27b4c4263a
3 changed files with 957 additions and 0 deletions
@@ -0,0 +1,454 @@
+_Read the read me in [English](README.md)._
+
+
+# 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-è-colibrì)
+- [Cosa serve](#cosa-serve)
+    - [Hardware](#hardware)
+    - [Software](#software)
+- [Come iniziare](#come-iniziare)
+    - [Passo 1: Scarica il modello](#passo-1-scarica-il-modello)
+    - [Passo 2: Scarica il Dockerfile di Colibrì](#passo-2-scarica-il-dockerfile-di-colibrì)
+    - [Passo 3: Compila l'immagine Docker](#passo-3-compila-limmagine-docker)
+    - [Passo 4: Avvia Colibrì](#passo-4-avvia-colibr%C3%AC)
+    - [Cosa significa quel comando?](#cosa-significa-quel-comando)
+    - [Usare Colibrì](#usare-colibrì)
+- [Entrare in una console Linux dentro il container](#entrare-in-una-console-linux-dentro-il-container)
+- [Risoluzione dei problemi](#risoluzione-dei-problemi)
+- [Note tecniche](#note-tecniche)
+- [Domande frequenti](#domande-frequenti)
+- [Supporto e contributi](#supporto-e-contributi)
+- [Test sul mio PC](#test-sul-mio-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](https://www.docker.com/products/docker-desktop/)
+- **Python** (solo se vuoi scaricare il modello da casa tua)
+  - Windows: [python.org](https://www.python.org) oppure Microsoft Store
+  - Linux: `apt-get install python3 python3-pip`
+  - Mac: [python.org](https://www.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:**
+   ```bash
+   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):
+   ```bash
+   hf_download mateogrgic/GLM-5.2-colibri-int4-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](https://huggingface.co/mateogrgic/GLM-5.2-colibri-int4-with-int8-mtp)
+- 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:**
+```bash
+docker build -t colibri-i .
+```
+
+**Linux/Mac:**
+```bash
+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):
+```bash
+$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):
+```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:**
+```bash
+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 in una console Linux dentro il container
+
+Se vuoi esplorare il container come fosse una macchina Linux normale:
+
+```bash
+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](https://www.docker.com/products/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:
+   ```bash
+   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:
+     ```ini
+     [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:
+   ```bash
+   wsl --shutdown
+   wsl
+   ```
+
+4. Controlla di nuovo:
+   ```bash
+   # 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):
+```bash
+winsat disk -drive C
+```
+Cambia `C` con la lettera del tuo disco.
+
+**Linux/Mac** (Terminal):
+```bash
+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):
+```bash
+sudo docker build -t colibri-i .
+sudo docker run ... (come sopra, con sudo davanti)
+```
+
+**Soluzione - Opzione 2** (permanente):
+```bash
+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:
+   ```bash
+   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**:
+```bash
+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](https://huggingface.co/mateogrgic/GLM-5.2-colibri-int4-with-int8-mtp)
+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](#risoluzione-dei-problemi) . Nel mio caso ho adottato questa configurazione:
+```ini
+[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 sul mio PC
+
+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
+
+  ╭────────────────────────────────────────────────────────────────────────────────────────────────╮
+  │ ›
+  ```