Davide Quack
454 lines
16 KiB
Markdown
454 lines
16 KiB
Markdown
_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
|
||
|
||
╭────────────────────────────────────────────────────────────────────────────────────────────────╮
|
||
│ ›
|
||
``` |