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

docs(it): README.it.md carries every section of the English README

JustVugg00d83ccb5ece
diff --git a/README.it.md b/README.it.md
index e3cd9c2e..a8a637cf 100644
--- a/README.it.md
+++ b/README.it.md
@@ -3,6 +3,12 @@
</p>
<p align="center">
+ <a href="https://justvugg.github.io/colibri"><img src="https://img.shields.io/badge/website-justvugg.github.io%2Fcolibri-1f6feb" alt="Website"></a>
+ <a href="https://github.com/JustVugg/colibri/releases"><img src="https://img.shields.io/github/v/release/JustVugg/colibri?color=2ea043" alt="Latest release"></a>
+</p>
+
+<p align="center">
+ <a href="https://justvugg.github.io/colibri"><b>Sito web</b></a> ·
<a href="https://discord.gg/RXV83nSZdk"><b>Discord</b></a> ·
<a href="README.md">English</a> · <a href="README.zh-CN.md">简体中文</a> · <a href="README.zh-TW.md">繁體中文</a> · Italiano · <a href="README.ja.md">日本語</a>
</p>
@@ -10,7 +16,7 @@
**Motore piccolo, modello immenso.** Esegui **modelli MoE di frontiera — da 744
miliardi a 2,8 mila miliardi di parametri** — su hardware consumer ed eterogeneo,
in C puro e senza dipendenze del motore, trattando storage, RAM e VRAM come
-un'unica gerarchia di inferenza.
+un'unica gerarchia di inferenza (multitiering della memoria per l'IA).
Oggi girano dieci famiglie di modelli linguistici. Contiamo i motori, non i
checkpoint: un file C ciascuna, la stessa interfaccia `coli chat` / `coli serve` /
@@ -20,10 +26,11 @@ checkpoint: un file C ciascuna, la stessa interfaccia `coli chat` / `coli serve`
**MiMo-V2.6 Flash** (309B, con visione; lo stesso motore esegue **MiMo-V2.6 Pro**,
1,02T), **Qwen3.8-Flash-Next** (125B + 51B n-gram), **Qwen3.6** (35B-A3B; lo stesso
motore esegue **Qwen3-Coder-30B-A3B** e il denso **Qwen3.8-27B**, con visione) e
-**OLMoE** (7B). [Elenco completo](README.md#other-supported-models)
+**OLMoE** (7B).
Anche immagini: un undicesimo motore esegue **Qwen-Image-2.1**, che genera figure
da un testo, mostrate dentro al terminale da `coli chat` e servite su
`POST /v1/images/generations` ([qwen-image.md](docs/qwen-image.md)).
+[Elenco completo ↓](#other-supported-models)
> **Colibrì è un motore di inferenza che puoi usare oggi, e una piattaforma di
> ricerca aperta.** Il suo obiettivo principale è migliorare le prestazioni di
@@ -32,8 +39,9 @@ da un testo, mostrate dentro al terminale da `coli chat` e servite su
> speculazione e sovrapposizione CPU/GPU — affinché i grandi modelli dipendano
> meno da hardware raro e costino meno.
-Colibrì è intenzionalmente un luogo dove verificare idee di sistema aggressive —
-quindi **nessuno SLA sulla velocità, e una garanzia dura sulla semantica**: gli
+Colibrì tratta VRAM, RAM e storage come un'unica gerarchia multilivello ed è
+intenzionalmente un luogo dove verificare idee di sistema aggressive: quindi
+**nessuno SLA sulla velocità, e una garanzia dura sulla semantica**. Gli
esperimenti devono dimostrare il proprio valore con misure end-to-end riproducibili;
la policy predefinita **non cambia mai silenziosamente la precisione del modello né
la semantica del router**. Una memoria veloce insufficiente può ridurre la velocità,
@@ -88,23 +96,27 @@ servizio disco sovrapposti al calcolo.</em></p>
## La missione di ricerca
-L'inferenza di frontiera non dovrebbe richiedere per forza hardware da datacenter.
-L'obiettivo di Colibrì è semplice: **ridurre la dipendenza dall'hardware e il costo
-totale dell'inferenza, ottimizzando ogni parte del percorso che le misure indicano
-come limitante**.
+Con Colibrì, l'accesso privato ai modelli di frontiera non è limitato dalla
+disponibilità di hardware da hyperscaler.
+
+Con le sue funzioni di multitiering, Colibrì **rimuove le dipendenze da hardware
+proprietario ottimizzando in modo aggressivo le pipeline funzionali del motore di
+inferenza**.
-Questo comprende cambiare il modo in cui i pesi sono rappresentati e spostati,
-decidere cosa risiede in VRAM, RAM o storage, sovrapporre calcolo eterogeneo,
-ridurre i costi di avvio e sincronizzazione, sfruttare sparsità e riuso e verificare
-nuovi algoritmi di decoding. La convenzione non protegge una tecnica; un microbenchmark
-veloce non basta ad adottarla. Decide l'inferenza end-to-end su macchine reali,
-misurando correttezza e qualità insieme a throughput, latenza, memoria e costo.
+La nostra missione operativa comprende cambiare il modo in cui i pesi sono
+rappresentati e spostati, decidere cosa risiede in VRAM, RAM o storage, sovrapporre
+calcolo eterogeneo, ridurre i costi di avvio e sincronizzazione, sfruttare sparsità
+e riuso e verificare nuovi algoritmi di decoding. La convenzione non protegge una
+tecnica; un microbenchmark veloce non basta ad adottarla. Decide l'inferenza
+end-to-end su macchine reali, misurando correttezza e qualità insieme a throughput,
+latenza, memoria e costo.
-Il risultato pratico è l'accessibilità: eseguire un modello da 744B sull'hardware
-che già possiedi, osservare ogni expert in tempo reale e modificare il codice che
-lo rende possibile. Non noleggiare intelligenza dietro un'API, ma possederla,
-analizzarla, misurarla e migliorarla. Il motore resta volutamente abbastanza piccolo
-perché la prossima ottimizzazione utile possa arrivare da chiunque sia disposto a misurarla.
+Il risultato pratico è l'**accessibilità**: eseguire un modello da 744B
+sull'hardware che già possiedi, osservare ogni expert attivarsi in tempo reale e
+modificare il codice che lo fa. Non noleggiare intelligenza dietro un'API, ma
+*possederla*: analizzarla, misurarla, migliorarla. Il motore resta volutamente
+abbastanza piccolo perché la prossima ottimizzazione utile possa arrivare da
+chiunque sia disposto a misurarla.
## Tecniche fondamentali e risultati misurati
@@ -136,7 +148,7 @@ controllato non dimostra il contrario. Le domande principali sono:
| ipotesi | evidenza attuale | esperimento ancora necessario |
|---|---|---|
| La cronologia di routing può piazzare gli expert meglio di una semplice LRU | i pin appresi migliorano carichi ripetuti, ma possono sovradattarsi al prompt | A/B cross-session su set esclusi: codice, chat, multilingua e contesti lunghi |
-| Più SSD possono trasformare banda indipendente in velocità di decode | routing pesato mirror/split implementato e validato; il modello di banda è solido | GLM-5.2 a cache fredda, uno contro due dischi su controller indipendenti reali |
+| Più SSD possono trasformare banda indipendente in velocità di decode | due unità NVMe indipendenti hanno misurato +37,5% in decode; una terza unità più lenta è risultata neutra dopo lo striping pesato ([misure](docs/multidisk.md#what-has-been-measured)) | riprodurre con dischi di velocità diverse, diverse disposizioni dei controller e diversi stati della cache |
| Un planner hardware-aware può avvicinarsi automaticamente alla configurazione migliore | oggi rileva budget RAM/VRAM e diversi backend | confrontare il piano generato con sweep controllati su laptop, workstation, NUMA e multi-GPU |
| Rappresentazioni lossless o a qualità limitata possono ridurre abbastanza il movimento dei pesi | esistono ablation di formato e quantizzazione con gate di qualità | riprodurre insieme qualità, byte mossi, latenza e costo per token utile, non solo il rapporto di compressione |
| La speculazione routing-aware può convenire prima della residenza quasi completa | MTP e draft grammaticali funzionano, ma MTP ha anche perso il 32% intorno all'85% di expert hit | mappare il pareggio tra accettazione, hit rate, batch union e profondità del draft |
@@ -147,7 +159,7 @@ hardware, commit, container del modello, comando esatto, prompt, stato cache,
throughput, TTFT, expert hit, byte letti e controllo qualità; cambia una sola
variabile, ripeti e allega i log grezzi. Parti da
[CONTRIBUTING.md](CONTRIBUTING.md), confronta il
-[protocollo di benchmark](docs/benchmarks.md), quindi
+[protocollo di benchmark](docs/benchmarking.md), quindi
[apri una issue di esperimento](https://github.com/JustVugg/colibri/issues/new).
Un fallimento controllato vale più di un numero veloce senza spiegazione.
@@ -170,9 +182,54 @@ Il modello non ha bisogno di *stare* in memoria veloce — ha bisogno di essere
in streaming**, con una cache LRU per layer, un hot-store pinnato che impara,
e un livello VRAM opzionale.
+Pensa all'algoritmo di base come a **un JIT, ma per i pesi**. Un compilatore JIT
+non compila mai l'intero programma: osserva cosa viene davvero eseguito e compila i
+percorsi caldi, appena in tempo. colibrì fa la stessa scommessa su uno spazio di
+744B parametri: i parametri non sono uno stato residente da custodire, sono **dati
+da collocare** lungo una gerarchia di storage eterogenea (VRAM / RAM / NVMe),
+esattamente quando il router dimostra che servono. Il calore di routing misurato
+decide quale livello si guadagna ogni expert, il router lavora un layer in anticipo
+così il prefetch nasconde la latenza di caricamento e, come un JIT, il motore impara
+il tuo carico di lavoro: più lo usi, più si scaldano gli expert giusti. Funziona
+perché il routing ha una struttura misurabile (vedi
+l'[atlante degli expert](https://github.com/JustVugg/colibri/issues/175)), e una
+struttura si può mettere in cache.
+
Il motore è un singolo file C (`c/colibri.c`) più header piccoli. Niente BLAS,
niente Python a runtime, niente GPU obbligatoria.
+### Modalità cluster locale
+
+Il coordinatore tiene in locale la generazione dei token, il routing e lo stato KV,
+mentre worker di expert basati su disco eseguono le FFN instradate su altri Mac. La
+batch-union instradata di un layer viene inviata come un'unica richiesta TCP
+persistente, così un token non paga un round trip per ogni expert.
+
+Avvia il servizio di registrazione opzionale:
+
+```bash
+./coli cluster coordinator --host 0.0.0.0 --port 8765
+```
+
+Su ogni worker, con lo stesso modello convertito disponibile in locale:
+
+```bash
+./coli cluster worker --model /nvme/glm52_i4 --port 9100 \
+ --coordinator http://COORDINATOR:8765 --advertise-host WORKER_IP
+```
+
+Avvia il coordinatore con la discovery, oppure passa `--cluster-workers
+HOST:PORT,...` per una configurazione statica:
+
+```bash
+./coli serve --model /nvme/glm52_i4 \
+ --cluster-coordinator http://127.0.0.1:8765
+```
+
+Il trasporto resta disattivato finché non si configurano dei worker, quindi il
+percorso esistente su una sola macchina non cambia. Lo sharding dei layer densi e i
+worker browser/WebGPU sono passi successivi separati.
+
## Come funziona
### Il percorso di ogni token
@@ -192,6 +249,31 @@ dalla VRAM sia dal disco.
<img src="docs/media/tiers.png" width="880" alt="residenza expert a tre livelli: VRAM / RAM / NVMe">
</p>
+<a id="dual-ssd-two-copies-of-the-model-twice-the-read-bandwidth"></a>
+
+### Più SSD: leggere copie del modello da più di un disco
+
+Quando il decode è limitato dal disco, un **secondo SSD** può aiutare: mettici una
+copia del modello e lascia che il motore legga da entrambi i dischi. Per GLM-5.2, da
+`c/` in un checkout dei sorgenti (o da una release scompattata):
+
+```bash
+COLI_MODEL_MIRROR=/second/glm52_i4 python3 ./coli chat --model /fast/glm52_i4
+```
+
+Il motore misura i dischi all'avvio per pesare la ripartizione delle letture. Le
+letture bufferizzate usano un instradamento deterministico degli expert; le letture
+dirette idonee possono distribuire un expert tra le repliche. Dischi indipendenti
+danno margine di banda, non un moltiplicatore garantito della velocità in token:
+controller condivisi, hit in cache e calcolo possono limitare il guadagno. Vedi la
+[guida multi-disco](docs/multidisk.md) per esempi in Bash e PowerShell, guadagni e
+limiti misurati e un confronto con un solo disco. Dettagli utili:
+
+- il mirror è **validato all'avvio** (dimensione di ogni file e header safetensors devono essere identici byte per byte al primario); i file divergenti o mancanti restano sul primario, quindi un **mirror parziale va bene**: un secondo SSD più piccolo può servire gli shard che contiene;
+- il mirror **non viene mai scritto**: `.coli_usage`, `.coli_kv` e tutti i sidecar restano sul primario;
+- un errore di lettura sul mirror ripiega sul primario (un avviso, nessun crash), quindi scollegare il secondo disco durante l'esecuzione degrada le prestazioni invece di far cadere il server;
+- il routing non cambia mai i token, perché le due copie sono identiche byte per byte; attiva `PROF=1` per i contatori di profilo `MIRROR:` che mostrano i GB serviti da ciascun disco.
+
Lo stesso motore copre l'intero spettro: su un portatile da 25 GB tutto viene
caricato dal disco in streaming (lento, ma corretto); su un host grande l'intero
set di expert diventa residente (`CUDA_EXPERT_GB=auto PIN_GB=all`) e il disco
@@ -202,6 +284,27 @@ colibrì diventa letteralmente più veloce man mano che lo usi. Sugli host
multi-socket, `COLI_NUMA=1` interlaccia i pesi residenti tra i controller di
memoria ([#82](https://github.com/JustVugg/colibri/issues/82)).
+Per un secondo disco che non può contenere l'intero modello, Colibri può
+classificare un mirror parziale in base alla cronologia degli expert che già
+impara. Esegui prima qualche prompt rappresentativo, così `.coli_usage` riflette il
+carico di lavoro, poi pianifica, prepara e verifica il mirror:
+
+```bash
+./c/coli mirror plan --model /fast/glm52_i4 --mirror /second/glm52_i4 \
+ --budget-gib 200 --reserve-gib 20
+./c/coli mirror stage --model /fast/glm52_i4 --mirror /second/glm52_i4 \
+ --budget-gib 200 --reserve-gib 20
+./c/coli mirror verify --model /fast/glm52_i4 --mirror /second/glm52_i4
+```
+
+Il planner legge direttamente gli header safetensors, segue le directory di modelli
+divisi indicate in `COLI_MODEL_DIRS` e dà priorità agli shard che possono servire
+gli expert instradati più caldi. La preparazione non modifica mai il modello
+primario: copia passando per file temporanei, rispetta la riserva di spazio libero
+richiesta, verifica ogni shard con SHA-256, non cancella mai uno shard di mirror
+esistente e pubblica in modo atomico una ricevuta solo quando il mirror selezionato
+è pronto.
+
### Mai aspettare il disco due volte
I miss nella cache costano caro, quindi il motore investe la maggior parte
@@ -215,13 +318,29 @@ prefetch degli expert del layer successivo — il routing è misurabilmente
(`COLI_CUDA_PIPE=2`) mantiene il flusso residuo on-device tra i layer, così il
loop CPU degli expert procede senza interruzioni; su Apple Silicon un backend
[Metal](docs/metal.md) sperimentale esegue la matmul batch degli expert sulla
-GPU a memoria unificata.
+GPU a memoria unificata; e un [backend Vulkan](docs/vulkan.md) porta il livello
+degli expert, le proiezioni dense e il nucleo dell'attenzione MLA su qualsiasi GPU
+con un driver Vulkan 1.2, comprese le schede AMD tramite Mesa/RADV (l'unico backend
+per le schede che gli stack dei produttori non supportano più, come la RX 580, e
+competitivo con ROCm su RDNA4: vedi [le note di benchmark](docs/vulkan.md)).
+Ogni altro motore ora apre lo stesso backend per le sue matrici residenti con
+`COLI_VULKAN=1` in una build `VK=1`; in CI è verificato contro i token della CPU, ma
+sulla prima GPU reale su cui è stato misurato, una Radeon 780M integrata, oggi è più
+lento della CPU ([gli altri motori](docs/vulkan.md#the-other-engines)).
+
+> **Su NVMe reali, misura `DIRECT=1`.** O_DIRECT scavalca la page cache e spesso è
+> un grande vantaggio sui dischi con cache DRAM e margine di banda (+34% in decode
+> misurato con `PIPE=1` su una macchina Blackwell/Windows; da 4,25 a 9,69 GB/s in
+> iobench su un GB10), ma dipende dal disco: unità QLC, senza DRAM o virtualizzate
+> possono essere neutre o peggiorare. Provalo prima; tieni ciò che il tuo hardware
+> premia.
### Modello fedele, stato compresso
-Il forward pass è validato **token-esatto contro un oracle `transformers`**
-(teacher-forcing 32/32). L'attenzione MLA memorizza uno stato KV compresso — 576
-float/token invece di 32.768 (**57× più piccolo**) — e lo persiste tra i
+Il forward pass è validato contro un oracle `transformers` (teacher-forcing di
+norma 30-32/32; due posizioni dell'oracle tiny sono quasi-pareggi in virgola mobile
+e dipendono dalla toolchain). L'attenzione MLA memorizza uno stato KV compresso
+(576 float/token invece di 32.768, **57× più piccolo**) e lo persiste tra i
riavvii (`.coli_kv`): le conversazioni riaprono "calde", senza alcun re-prefill,
byte-identiche a una sessione ininterrotta. L'attenzione sparsa DSA (il
lightning indexer di GLM-5.2) è implementata fedelmente e validata forzando la
@@ -241,6 +360,17 @@ contiene l'intera indagine forense). I draft forzati da grammatica
gratuita sull'output JSON vincolato. Se la speculazione conviene dipende dalla
temperatura della cache — misura, e usa `DRAFT=0` quando non paga.
+I batch di verifica possono anche attivare un **nucleo di attenzione esatto** con
+`COLI_EXACT_VERIFY=1` ([#689](https://github.com/JustVugg/colibri/issues/689)): i
+prodotti scalari di score e di contesto dell'MLA-absorb su CPU accumulano prodotti
+interi e arrotondano una sola volta, così un quasi-pareggio in una riga di verifica
+si risolve allo stesso modo su ogni host, a circa 0,6x tok/s su un oracle tiny (il
+prodotto scalare in sé costa circa 5-7x il ciclo in float). Due limiti da
+conoscere: con una cache KV quantizzata (`tq1`, TQ o KV int8) il prodotto di
+contesto resta sul percorso float, quindi lì l'esattezza non è garantita; e un vero
+ribaltamento da quasi-pareggio è stato solo argomentato, non ancora osservato su
+GLM-5.2 a n=64.
+
## Cosa ottiene
<p align="center">
@@ -319,7 +449,10 @@ quindi la decodifica speculativa resta disattivata:
> ripetizioni o EOS starvation. Anche la testa MTP deve essere **int8, non int4**
> (int4 → 0% di accettazione dei draft,
> [#8](https://github.com/JustVugg/colibri/issues/8)):
-> `ls -l <modello>/out-mtp-*` — int8 (corretto) è `3527131672 / 5366238584 / 1065950496`.
+> `ls -l <modello>/out-mtp-*`: int8 (corretto) è `3527131672 / 5366238584 / 1065950496`
+> in tre file, oppure un solo `out-mtp-00000.safetensors` da `9959321520` byte
+> (il caricamento attuale del container consigliato lo distribuisce come un unico
+> file: stessi tensori int8, 777, a un byte per elemento).
Oppure converti tu stesso dalla sorgente FP8 — un unico comando riprendibile che
non richiede mai i 756 GB completi su disco contemporaneamente:
@@ -328,14 +461,121 @@ non richiede mai i 756 GB completi su disco contemporaneamente:
./coli convert --model /nvme/glm52_i4 # scarica e converti shard per shard (python, una tantum)
```
+<a id="other-supported-models"></a>
+#### Altri modelli supportati
+
+GLM-5.2 è il modello di riferimento, ma lo stesso approccio in streaming fa girare
+altre nove famiglie di modelli linguistici, e un motore genera immagini. Ognuna è un
+**motore fratello**: un file C, la sua architettura, la stessa interfaccia
+`coli chat` / `coli serve` / `coli web` (il launcher sceglie il binario dal
+`config.json` del modello, o da `model_index.json` per il modello di immagini):
+
+> **Cosa serve a ciascuno.** Sono molto diversi, e leggerne due insieme ha fatto
+> credere ad alcuni che i requisiti si contraddicano
+> ([#191](https://github.com/JustVugg/colibri/issues/191)). Non è così: sono
+> modelli diversi. **Nessuno di loro richiede una GPU.**
+>
+> | Modello | Disco per i pesi | RAM | GPU |
+> |---|---|---|---|
+> | **OLMoE** | ~7 GB (container int8) | 8 GB | non serve; Vulkan opzionale |
+> | **GLM-5.2/5.3** | ~372 GB (5.2) / ~419 GB (5.3) | 16 GB minimo, 24 GB comodi | non serve; Vulkan opzionale |
+> | **GLM-5.3-Flash** | ~195 GB dopo la conversione | 25 GB (12 GB di pesi a int4 + cache degli expert) | non serve; Vulkan opzionale |
+> | **Inkling** | ~469 GB | 25 GB con il container denso int4, ~120 GB senza | non serve; Vulkan opzionale |
+> | **Kimi K3** | ~1,6 TB | 32 GB+ | non serve; Vulkan opzionale |
+> | **DeepSeek V4 Flash** | ~167 GB (REAP 150B: ~85 GB) | 16 GB minimo, 32 GB comodi | opzionale; qualsiasi scheda NVIDIA dalla serie GTX 10 in su (Pascal/Turing con `CUDA_ARCH=portable-pre-ampere NO_TC=1`, al meglio su RTX 50) rende il prefill 5-10x e il decode ~2,5x più veloci; Vulkan opzionale |
+> | **DeepSeek V4.1 Flash** | ~510 GB (checkpoint ufficiale; 203 GB sono una memoria n-gram letta poche centinaia di byte alla volta) | ~18 GB residenti (parte densa, embedding, visione) più la cache degli expert dimensionata da `--ram`; 24,8 GB di RSS di picco misurati a cap 8 | non serve; Vulkan opzionale |
+> | **MiMo-V2.6 Flash** | ~178 GB (checkpoint ufficiale) | 30,1 GB residenti misurati con 32 expert in cache per layer, 49,8 GB con 64; `--ram` dimensiona la cache | non serve; Vulkan opzionale |
+> | **MiMo-V2.6 Pro** | ~574 GB (~564 GB senza i tre file che il motore non carica mai) | parte densa 30,2 GiB come rilasciata, 21,7 GiB in int8; 48,0 GB residenti misurati con 12 expert in cache per layer (parte densa come rilasciata), 50,7 GB con 20 (parte densa in int8) | non serve; Vulkan opzionale |
+> | **Qwen3.8-Flash-Next** | ~185,5 GB (checkpoint FP8 ufficiale), più 68,0 GB per il sidecar opzionale degli expert int4-g64 | 24 GB comodi al contesto predefinito con gli expert FP8 (cap 32; 16 GB sono sotto il minimo); 11,6 GB di RSS misurati a cap 32 con il sidecar int4-g64 | opzionale; il livello expert CUDA in VRAM (solo expert FP8) con il tronco denso quantizzato a int8 in VRAM; Vulkan opzionale |
+> | **Qwen3.8-27B** (denso, testo e immagini) | ~51 GB dopo la conversione (f16) | 20 GB con pesi densi int4, 30 GB in int8 | non serve; ancora nessun livello CUDA; Vulkan opzionale |
+> | **Qwen3.6-35B-A3B** | ~20 GB (container int4-gs64) | 24 GB (richiede la residenza completa in RAM) | opzionale; il livello expert CUDA in VRAM ha misurato **1,44 -> 10,05 tok/s (7,0x)** su due schede da 8 GB, output identico bit per bit alla CPU; Vulkan opzionale |
+> | **Qwen3-Coder-30B-A3B** | ~19 GB (container int4-gs64; 30 GB in int8) | 6,5 GB residenti misurati con 32 expert in cache per layer, 15,2 GB con tutti i 128 | non serve; Vulkan opzionale |
+> | **Qwen-Image-2.1** (da testo a immagine) | ~33 GB (checkpoint diffusers ufficiale) | 16,0 GB con tutto residente, 8,5 GB di picco con il text encoder caricato a ogni prompt, più i buffer di lavoro (9,0 GB di picco misurati per un'immagine 768x512) | non serve; Vulkan opzionale, non ancora cronometrato su GPU |
+>
+> Una GPU non cambia mai ciò che il modello risponde, solo dove si svolge il
+> lavoro. La velocità la decide il disco, perché gli expert vengono letti in
+> streaming da lì: aspettati una frazione di token al secondo su un disco lento e
+> qualche token al secondo su uno veloce con la cache calda.
+>
+> **Vulkan opzionale** significa una build `VK=1`. Avviato con `COLI_VULKAN=1`, il
+> motore mette le sue matrici residenti su qualsiasi GPU con un driver Vulkan 1.2
+> (GLM-5.2 ha lì un percorso di decode completo, Kimi K3 un suo livello di expert,
+> `K3_VK`), e la CI verifica quei motori contro i token della CPU su un driver
+> software ([vulkan.md](docs/vulkan.md#the-other-engines)). Corretto non vuol dire
+> ancora più veloce. Sulla prima GPU reale misurata per questi motori, una Radeon
+> 780M integrata (Ryzen 7 PRO 8700GE, stessi binari, page cache fredda), oggi è più
+> lento della CPU: Qwen3.6-35B-A3B ha fatto 3,06 tok/s in decode contro 5,97 sulla
+> CPU, con output identico, e Qwen3.8-Flash-Next con expert int4 1,53 contro 3,55.
+> Ogni matmul è una submit sincrona, circa 726 per token, e una GPU integrata legge
+> la stessa RAM della CPU.
+
+| Famiglia | Totali / attivi | Pesi | Build | Documentazione |
+|---|---|---|---|---|
+| **GLM-5.2/5.3** | 744B / 40B | [`mastouri/…-int4-g64-with-int8-mtp`](https://huggingface.co/mastouri/GLM-5.2-colibri-int4-g64-with-int8-mtp) (372 GB) o [`Justvugg/GLM-5.3-colibri-int4-g64`](https://huggingface.co/Justvugg/GLM-5.3-colibri-int4-g64) (419 GB) | `make -C c glm` | questa pagina |
+| **Inkling** (Thinking Machines) | 975B / 41B | [`nbeerbower/Inkling-colibri-int4`](https://huggingface.co/nbeerbower/Inkling-colibri-int4) (469 GB) | `make -C c inkling` | [inkling.md](docs/inkling.md) |
+| **GLM-5.3-Flash** (Z.ai) | 321B / 18B | [`zai-org/GLM-5.3-Flash`](https://huggingface.co/zai-org/GLM-5.3-Flash), convertito con gli expert instradati in **int4-gs64**; la parte densa resta BF16 e la sua precisione si sceglie al caricamento; visione inclusa | `make -C c glm53` | [glm53-flash.md](docs/glm53-flash.md) |
+| **Kimi K3** (Moonshot) | 2,8T / 104B | [`moonshotai/Kimi-K3`](https://huggingface.co/moonshotai/Kimi-K3): checkpoint originale, gli expert instradati restano **MXFP4 nativi** | `make -C c kimi_k3` | [kimi_k3.md](docs/kimi_k3.md) |
+| **DeepSeek V4 Flash** | 284B / 13B | checkpoint ufficiale in shard: gli expert instradati restano **fp4 nativi**, la parte densa resta fp8-e4m3; il **150B potato con REAP** ([`puwaer/DeepSeek-V4-Flash-0731-reap-150b`](https://huggingface.co/puwaer/DeepSeek-V4-Flash-0731-reap-150b), 85 GB, 132 expert su 256) si carica con lo stesso motore e senza conversione | `make -C c deepseek-v4` | [deepseek-v4.md](docs/deepseek-v4.md) |
+| **DeepSeek V4.1 Flash** | 552B / 16B | checkpoint ufficiale, **nessuna conversione**: gli expert sono già fp4, la parte densa è fp8-e4m3. 203 GB sono una memoria n-gram letta dal disco poche centinaia di byte alla volta, e gli expert instradati costano **4,5 GB per token** contro i 12,7 di GLM-5.2. Visione, tool calling e la testa di draft DSpark sono tutti attivi | `make -C c deepseek_v41` | [deepseek-v41.md](docs/deepseek-v41.md) |
+| **MiMo-V2.6 Flash** (Xiaomi) | 309B / 15B | [`XiaomiMiMo/MiMo-V2.6-Flash-MOPD`](https://huggingface.co/XiaomiMiMo/MiMo-V2.6-Flash-MOPD) (178 GB), checkpoint ufficiale, **nessuna conversione**: gli expert instradati restano **MXFP4 nativi**, la parte densa resta FP8/BF16. 39 dei suoi 48 layer guardano una finestra di 128 token, quindi un contesto lungo costa il KV di 9. Visione e tool calling attivi | `make -C c mimo` | [mimo.md](docs/mimo.md) |
+| **MiMo-V2.6 Pro** (Xiaomi) | 1,02T / 42B | [`XiaomiMiMo/MiMo-V2.6-Pro-MOPD`](https://huggingface.co/XiaomiMiMo/MiMo-V2.6-Pro-MOPD) (573,5 GB), checkpoint ufficiale, **nessuna conversione**, sul motore MiMo: la stessa architettura a 70 layer e 384 expert. Verificato contro il codice di modellazione di Xiaomi sui primi 32 dei suoi 70 layer. Visione e tool calling attivi | `make -C c mimo` | [mimo.md](docs/mimo.md#pro) |
+| **Qwen3.8-Flash-Next** (Alibaba) | 125B + 51B n-gram / 6B | [`Qwen/Qwen3.8-Flash-Next-FP8`](https://huggingface.co/Qwen/Qwen3.8-Flash-Next-FP8), checkpoint originale; la PLE resta paginabile e gli expert restano **block-FP8 nativi**, oppure vengono letti come **int4-g64** da un sidecar opzionale (vedi sotto). Draft MTP opt-in (`Q38_MTP=1`) | `make -C c qwen38` (`CUDA=1` per il livello expert in VRAM) | [qwen38.md](docs/qwen38.md) |
+| **Qwen3.6** (Alibaba) | 35B / 3B | [`Kreuzzelg/qwen36-35b-a3b-colibri-i4-gs64`](https://huggingface.co/Kreuzzelg/qwen36-35b-a3b-colibri-i4-gs64) (~20 GB, **consigliato**): ibrido Gated Attention + Gated DeltaNet | `make -C c qwen36` (`CUDA=1` per il livello expert in VRAM) | [qwen36.md](docs/qwen36.md) |
+| **Qwen3.8-27B** (Alibaba) | 27B, denso | [`Qwen/Qwen3.8-27B`](https://huggingface.co/Qwen/Qwen3.8-27B) convertito con `c/tools/convert_qwen36.py` in un container f16 (51 GB); il motore lo quantizza a int8, o a int4 con `COLI_DENSE_BITS=4`, durante il caricamento. Un MLP per layer e nessun router, sul motore Qwen3.6. Testo e immagini | `make -C c qwen36` | [qwen36.md](docs/qwen36.md#the-dense-27b) |
+| **Qwen3-Coder-30B-A3B** (Alibaba) | 30B / 3B | [`Justvugg/Qwen3-Coder-30B-A3B-colibri-int4`](https://huggingface.co/Justvugg/Qwen3-Coder-30B-A3B-colibri-int4) (19 GB, int4-gs64), convertito da [`Qwen/Qwen3-Coder-30B-A3B-Instruct`](https://huggingface.co/Qwen/Qwen3-Coder-30B-A3B-Instruct). MoE Qwen3 di sola attenzione sul motore Qwen3.6, 128 expert top-8, una sua forma XML per le chiamate ai tool e nessun thinking; in teacher forcing il container int4 sceglie il token top-1 della release bf16 nel 96,9% delle posizioni | `make -C c qwen36` | [qwen36.md](docs/qwen36.md#qwen3-coder-30b-a3b) |
+| **OLMoE** (AI2) | 7B / 1B | convertito con `c/tools/convert_olmoe_merged.py`: container **int8**, ~7 GB | `make -C c olmoe` | - |
+| **Qwen-Image-2.1** (Alibaba) | modello di immagini | [`Qwen/Qwen-Image-2.1`](https://huggingface.co/Qwen/Qwen-Image-2.1) (~33 GB), checkpoint diffusers ufficiale, **nessuna conversione**: il text encoder e il diffusion transformer vengono quantizzati a int8 durante il caricamento. Immagini dentro `coli chat`, `POST /v1/images/generations` su `coli serve`. Qwen Research License: solo uso non commerciale | `make -C c qwenimage` | [qwen-image.md](docs/qwen-image.md) |
+
+Qwen3.6 offre tre container pre-convertiti: **int4-gs64** (consigliato: coseno
+misurato rispetto all'ancora int8 da 0,98777 a 0,99313 e KL da 0,109 a 0,080
+rispetto al per-row, cioè ~44% di errore di quantizzazione in meno),
+[int4 per-row](https://huggingface.co/Kreuzzelg/qwen36-35b-a3b-colibri-i4) come
+baseline per gli A/B, e
+[KAT-Coder v2.5](https://huggingface.co/Kreuzzelg/kat-coder-v2.5-dev-colibri-i4-gs64),
+che lo stesso motore esegue senza modifiche: qualsiasi checkpoint con architettura
+identica funziona senza un percorso di codice dedicato. Con `CUDA=1` il livello
+expert in VRAM ha misurato **da 1,44 a 10,05 tok/s (7,0×) su due schede da 8 GB**,
+con output identico bit per bit al percorso CPU.
+
+Qwen3.8-Flash-Next legge i suoi expert instradati come rilasciati, in block-FP8. Un
+**sidecar int4-g64** opzionale (`c/tools/convert_qwen38_experts_int4.py`, 68,0 GB
+scritti accanto agli shard FP8) fa leggere a ogni miss il 56% dei byte. Misurato su
+un Ryzen 7 PRO 8700GE (16 thread, 61 GiB, NVMe), il decode è 1,4-1,5x più veloce a
+parità di cache e 1,56x più veloce a parità di RAM, per +0,017 nats per token di
+perplessità in media ([qwen38.md](docs/qwen38.md#routed-experts-as-int4-g64)). La
+decodifica speculativa con la testa MTP del checkpoint è opt-in (`Q38_MTP=1`), e
+l'output è identico alla decodifica normale. Sulla stessa macchina con gli expert
+int4, il 94-96% dei draft è stato accettato, 1,94 token per forward, per +12-14% di
+tok/s (da 3,57 a 4,01 a cap 96, da 4,15 a 4,74 a cap 170). Lì il guadagno è piccolo
+perché le letture degli expert dal disco non si riducono
+([qwen38.md](docs/qwen38.md)).
+
+Kimi K3 non richiede conversione: i suoi expert MXFP4 addestrati con QAT vengono
+letti in streaming direttamente dagli shard originali di Hugging Face, e la parte
+densa bf16 viene quantizzata al caricamento. Le sessioni lunghe degli agenti
+possono attivare i checkpoint dello stato ricorrente (`COLI_K3_CKPT=N` slot in RAM,
+o parcheggiati su disco con `COLI_K3_CKPT_DIR`): un prompt modificato o di
+follow-up ripristina il checkpoint più profondo ancora disponibile e rifà il
+prefill solo della coda, invece di ripercorrere l'intera conversazione attraverso i
+layer SSM. Sugli host Vulkan `K3_VK_UP=auto` dimensiona il caricamento del livello
+degli expert in base alla banda misurata. I percorsi KDA e MLA del motore sono
+validati token-esatti in CI contro l'implementazione del vendor.
+
+Inkling distribuisce expert int4 ma **pesi densi bf16** (49,4 GB residenti); su un
+host che non può tenerli, [inkling.md](docs/inkling.md) ha uno strumento a passata
+singola che porta la parte densa a 15,3 GB e fa girare il 975B su una macchina da
+25 GB, con il compromesso messo onestamente per iscritto.
+
### 3. Esegui
```bash
COLI_MODEL=/nvme/glm52_i4 ./coli chat # budget RAM, cache e MTP rilevati automaticamente
COLI_MODEL=/nvme/glm52_i4 ./coli plan # mostra il piazzamento pianificato VRAM/RAM/disco
COLI_MODEL=/nvme/glm52_i4 ./coli doctor # controllo di idoneità (sola lettura)
-./coli web --model /nvme/glm52_i4 # API + dashboard web sulla stessa porta
-./coli serve --model /nvme/glm52_i4 # solo API compatibile OpenAI
+COLI_MODEL=/nvme/glm52_i4 ./coli doctor --deep # controllo preliminare rigoroso di tensori/shard/indice/mirror
+COLI_MODEL=/nvme/glm52_i4 ./coli tune # misura e salva il profilo di esecuzione sicuro più veloce di questa macchina
+./coli web --model /nvme/glm52_i4 # API + dashboard, e apre un browser
+./coli serve --model /nvme/glm52_i4 # API + dashboard, senza browser (headless)
```
#### Modalità Brio: una domanda a risposta chiusa
@@ -371,24 +611,123 @@ documento. Tutta la modalità, la forma di richiesta e risposta, e dove non
serve: [docs/brio.md](docs/brio.md). Anche la dashboard ha una pagina Brio.
-Su Windows gli stessi comandi funzionano con `python coli chat --model D:\glm52_i4`.
-Il motore a runtime è puro C — python si usa solo per il convertitore (una tantum)
+Su Windows un archivio di release include `coli.cmd`: fai doppio clic per l'avvio
+rapido, oppure esegui `coli.cmd chat --model D:\glm52_i4` da cmd o PowerShell. Da
+un checkout dei sorgenti gli stessi comandi funzionano con `python coli chat --model
+D:\glm52_i4`. I file `.exe` sono i motori, non il launcher: avviati da soli non
+hanno un modello da caricare ed escono subito.
+Il motore a runtime è puro C: python si usa solo per il convertitore (una tantum)
e per il gateway API opzionale.
+#### Gli stessi comandi per tutti i modelli
+
+`coli` legge il `config.json` del modello, sceglie il binario del motore
+corrispondente e applica il chat template di quella famiglia: quindi **la riga di
+comando non cambia tra un modello e l'altro**. Compila una volta il motore che ti
+serve, poi punta `COLI_MODEL` alla directory giusta:
+
+```bash
+make -C c glm # GLM-5.2
+make -C c inkling # Inkling
+make -C c kimi_k3 # Kimi K3
+
+COLI_MODEL=/nvme/glm52_i4 ./coli chat # TUI
+COLI_MODEL=/nvme/inkling_i4 ./coli chat
+COLI_MODEL=/nvme/kimi_k3 ./coli chat
+
+./coli web --model /nvme/inkling_i4 # API + dashboard, opens a browser
+./coli web --model /nvme/kimi_k3
+./coli serve --model /nvme/inkling_i4 # API + dashboard, no browser
+```
+
+Per i motori diversi da GLM, `coli chat` avvia il gateway in locale e ci collega
+la TUI, così TUI, API e dashboard passano tutti per lo stesso chat template che
+conosce l'architettura: non devi mai passare il template a mano.
+
+Due cose cambiano da un modello all'altro, entrambe documentate nella pagina del
+modello:
+
+- **Inkling su un host con poca RAM** richiede il container denso int4 e una cache
+ degli expert piccola: `./coli chat --model /nvme/inkling_i4 --cap 2`
+ (vedi [inkling.md](docs/inkling.md): il `--cap 8` predefinito vuole ~14 GB di
+ cache oltre al set residente).
+- **Kimi K3** legge in streaming i suoi expert MXFP4 dal checkpoint originale,
+ quindi non c'è niente da convertire, ma lo snapshot è di ~1,6 TB
+ (vedi [kimi_k3.md](docs/kimi_k3.md)).
+
### 4. Approfondisci
| argomento | documento |
|---|---|
| Benchmark, dati dalla comunità, misurazioni di qualità | [docs/benchmarks.md](docs/benchmarks.md) |
+| Protocollo di benchmark riproducibile e report minimo | [docs/benchmarking.md](docs/benchmarking.md) |
| Parametri di tuning, policy, cache che impara, prefetch | [docs/tuning.md](docs/tuning.md) |
| Build nativa su Windows 11 (con CUDA DLL) | [docs/windows.md](docs/windows.md) |
| Backend CUDA, livello expert in VRAM, residenza completa | [docs/cuda.md](docs/cuda.md) |
+| Backend Vulkan (qualsiasi GPU: AMD tramite RADV, comprese le schede non più supportate da ROCm) | [docs/vulkan.md](docs/vulkan.md) |
| Backend Metal per Apple Silicon | [docs/metal.md](docs/metal.md) |
| API compatibile OpenAI, KV slot, dashboard web | [docs/api.md](docs/api.md) |
| Modalità Brio: punteggiare un insieme chiuso di opzioni invece di generare | [docs/brio.md](docs/brio.md) |
+| ABI sperimentale di embedding per segmenti di layer | [docs/segment-runtime.md](docs/segment-runtime.md) |
+| ABI Edge sperimentale per tokenizer/embedding/head | [docs/edge-runtime.md](docs/edge-runtime.md) |
| Draft forzati da grammatica (output strutturato) | [docs/grammar-draft.md](docs/grammar-draft.md) |
| Inventario delle variabili d'ambiente | [docs/ENVIRONMENT.md](docs/ENVIRONMENT.md) |
+## DeepSeek V4
+
+**DeepSeek V4 Flash** legge in streaming il checkpoint ufficiale senza conversione:
+gli expert instradati restano **fp4 nativi**, la parte densa resta **fp8-e4m3** con
+scale di blocco UE8M0. Attenzione sparsa MLA + DSA, 43 layer, 256 expert instradati
+più uno condiviso, top-6. Supportato su Linux x86-64/aarch64 e su Windows/MSYS2
+(CPU), con un livello CUDA opzionale (DLL di runtime su Windows; link diretto
+`CUDA=1` su Linux, verificato sotto WSL2) che mantiene ogni fase canonica rispetto
+alla CPU e ripiega fase per fase.
+
+```bash
+cd c
+make deepseek-v4
+python ./coli chat --model /path/to/DeepSeek-V4-Flash --ram 32
+# also: coli run / coli serve / coli web
+# Windows CUDA tier: make cuda-dsv4-dll CUDA_ARCH=portable (+ make cuda-dsv4-dg-dll on RTX 50)
+```
+
+Due leve GPU opt-in sono nuove e cercano numeri dalla comunità, entrambe disattivate
+per default e identiche byte per byte quando non impostate: `DSV4_HYBRID=1` divide i
+miss del livello VRAM tra il ramo di riempimento GPU e il ramo CPU usando le bande
+misurate a runtime, e `COLI_CUDA_MOE_DOUBLE=1` (insieme a `COLI_CUDA_MOE_BATCH=1`)
+precarica l'intero set di expert del layer successivo in un secondo banco di VRAM
+mentre il layer corrente calcola, e ripiega sul banco singolo quando la VRAM non
+basta. Il livello CUDA ora gira anche sulle schede Pascal e Turing (serie GTX 10 /
+RTX 20): compila con `CUDA_ARCH=portable-pre-ampere NO_TC=1`.
+
+Decode greedy e un solo slot KV. Il tool calling passa per il gateway HTTP con il
+prompt nativo di V4 e i blocchi di chiamata DSML; la grammatica non è supportata.
+Vedi la [matrice API per motore](docs/api.md#tool-calling-support). I checkpoint di
+prefisso (in memoria e su disco) fanno partire le sessioni degli agenti e i turni
+successivi in pochi secondi dopo il primo prefill di un system prompt. Misurato su
+una RTX 5080 + 2 NVMe: prefill di 3324 token in 90 s, primo turno di 8,3k token in
+~4 min una volta sola, sessioni e turni successivi in 6-9 s, decode ~1,6 tok/s a 3k
+di contesto: vedi [docs/deepseek-v4.md](docs/deepseek-v4.md).
+
+**Dagli RAM.** 43 × 256 expert instradati occupano ~137 GiB su disco e un token ne
+tocca 301, quindi è il tasso di hit della cache degli expert a decidere i tok/s:
+`--ram` è la manopola più preziosa in assoluto, e cambia solo la velocità, mai
+l'output.
+
+**Il drafting speculativo esiste ed è spento.** Il drafter markoviano di DSpark e
+l'MTP completo sono entrambi implementati e verificati: un draft può risparmiare
+forward pass ma non cambiare mai un token, perché ogni token accettato è comunque
+l'argmax del modello target. Misurati su vere chat a più turni, hanno accettato 1
+su 15 e 10 su 24, e il replay del suffisso rifiutato sullo stato di attenzione
+ricorrente di questo motore è costato più di quanto i draft abbiano risparmiato:
+una risposta di 14 token ha richiesto 495 secondi. Per questo `V4_DRAFT` e `V4_MTP`
+sono `0` per default e il codice resta, con i numeri accanto, per chi vorrà
+riprovarci su uno storage più veloce.
+
+Vedi [docs/deepseek-v4.md](docs/deepseek-v4.md) per il livello CUDA (build, scelta
+della DLL, copertura GPU), il riferimento delle variabili d'ambiente, i numeri di
+prestazione, la validazione del checkpoint e l'oracle tiny indipendente generato.
+
## Prossimi passi
- **La ricerca sui sistemi di inferenza è il prodotto.** La gerarchia attuale usa
@@ -423,28 +762,54 @@ Se ti è utile:
```
Makefile punto d'ingresso root per build/check
c/
-├── colibri.c motore principale
-├── quant.h kernel matmul quantizzati (SIMD multi-architettura)
-├── sample.h campionamento, RNG, set di stop
-├── kv_persist.h persistenza KV su disco (.coli_kv)
-├── telemetry.h protocollo dashboard, statistiche, usage
-├── st.h, tok.h, json.h header di runtime
-├── backend_cuda.* livello CUDA opzionale
+├── colibri.c motore GLM-5.2 (make glm)
+├── inkling.c motore Inkling (make inkling)
+├── kimi_k3.c motore Kimi K3 (make kimi_k3)
+├── glm53.c motore GLM-5.3-Flash (make glm53)
+├── deepseek_v4.c motore DeepSeek V4 Flash (make deepseek-v4)
+├── deepseek_v41.c motore DeepSeek V4.1 Flash (make deepseek_v41)
+├── mimo.c motore MiMo-V2.6 Flash e Pro (make mimo)
+├── qwen38.c motore Qwen3.8-Flash-Next (make qwen38)
+├── qwen36.c motore Qwen3.6, Qwen3-Coder, Qwen3.8-27B (make qwen36)
+├── olmoe.c motore OLMoE (make olmoe)
+├── qwenimage.c motore Qwen-Image-2.1 (make qwenimage)
+│
+├── st.h indice safetensors e letture a intervalli
+├── quant.h decoder canonici dei container
+├── expert_ffn.h kernel FFN degli expert instradati condiviso dai motori MoE (int4 planare, runner di layer)
+├── tok.h, json.h tokenizer e parser JSON
+├── compat.h shim per Windows/macOS (nomi POSIX, in un solo posto)
+├── expert_store.h cache degli expert in streaming
+├── route_trace.h telemetria di routing e .coli_usage, indipendente dal motore
+├── kv_prefix.h riuso del prefisso KV tra i turni
+│
+├── backend_cuda.* livello CUDA opzionale (CUDA=1)
+├── backend_metal.* livello Metal opzionale (METAL=1)
+├── backend_vulkan.* livello Vulkan opzionale (VK=1)
+│
├── Makefile build e check locali
├── coli CLI utente
├── openai_server.py gateway HTTP compatibile OpenAI
-├── setup.sh setup locale in un solo comando
+├── resource_plan.py planner RAM/VRAM dietro `coli plan` e `coli doctor`
├── tools/ conversione offline, fixture e benchmark
├── scripts/ helper per conversioni lunghe
└── tests/ test C e Python senza dipendenze
web/ UI browser (puro client API OpenAI)
desktop/ shell desktop Tauri v2 che racchiude la web UI
+docker/ immagini container
docs/ documentazione di riferimento, esperimenti, media
```
-Il percorso a runtime resta intenzionalmente piatto e leggibile: `colibri.c`
-più i suoi header. Dalla radice del repository, `make`, `make check` e
-`make clean` delegano al Makefile del motore.
+**Un `.c` per famiglia di modelli, sopra header singoli condivisi.** Un motore
+possiede la sua architettura e nient'altro; tutto ciò che serve a due motori (il
+lettore safetensors, i decoder dei container, il tokenizer, la cache degli expert)
+vive in un header che entrambi includono, così una correzione li raggiunge tutti
+insieme. Questa regola non è decorativa: i difetti che continuano a ripresentarsi
+qui sono quelli in cui un meccanismo è arrivato in un motore e non ha mai raggiunto
+i suoi fratelli.
+
+Dalla radice del repository, `make`, `make check` e `make clean` delegano al
+Makefile del motore.
## Perché "colibrì"
@@ -456,6 +821,64 @@ tanta pazienza col disco.
Il nome è rimasto in italiano perché questa è la lingua in cui è stato scritto
il primo prototipo — i commenti nel codice lo testimoniano ancora.
+## Ringraziamenti
+
+colibrì è un motore; le menti che fa girare sono un dono. Grazie ai team che
+rilasciano apertamente pesi di classe frontiera, **Z.ai** (GLM), **Moonshot AI**
+(Kimi), **Alibaba Qwen**, **MiniMax** e **Allen AI** (OLMoE), e a ogni
+contributore che ha fatto benchmark, bisect, replicato un'esecuzione dell'atlante o
+mandato una patch. Questo progetto è la prova di ciò che i pesi aperti rendono
+possibile.
+
+Gli esperimenti del progetto su piazzamento, compressione e routing degli expert si
+basano anche su idee ed evidenze dei seguenti lavori aperti di ricerca e di sistemi:
+
+- [REAP](https://github.com/CerebrasResearch/reap) e
+ [EASY-EP](https://github.com/RUCAIBox/EASYEP) per l'importanza degli expert
+ consapevole dell'output e specifica del dominio.
+- [SERE](https://github.com/JL-Cheng/SERE) per il re-routing degli expert basato
+ sulla similarità, e [ReMoE](https://github.com/BUAA-OSCAR/ReMoE) per il
+ fine-tuning del router consapevole della località della cache.
+- [MC-SMoE](https://github.com/UNITES-Lab/MC-SMoE) per il merging e la compressione
+ degli expert guidati dal routing.
+- [MoBE](https://github.com/inclusionAI/MoBE) e
+ [D²-MoE](https://github.com/lliai/D2MoE) per le basi di expert condivise e i
+ delta di expert a basso rango.
+- [HybriMoE](https://github.com/PKU-SEC-Lab/HybriMoE) per lo scheduling ibrido
+ CPU/GPU degli expert, [ScMoE](https://arxiv.org/abs/2404.05019) per la
+ sovrapposizione tra comunicazione degli expert e calcolo, e
+ [OD-MoE](https://arxiv.org/abs/2512.03927) per il caricamento distribuito degli
+ expert su richiesta.
+- [vLLM](https://github.com/vllm-project/vllm),
+ [llama.cpp](https://github.com/ggml-org/llama.cpp) e
+ [kTransformers](https://github.com/kvcache-ai/ktransformers) per i sistemi di
+ inferenza aperti e il lavoro sull'offload degli expert che rendono riproducibili i
+ confronti.
+
+Il motore poggia anche su lavoro di ingegneria concreto, non solo su idee. Ognuno
+di questi è usato o reimplementato oggi nel repository:
+
+- [safetensors](https://github.com/huggingface/safetensors): il container che ogni
+ motore legge (`c/st.h`), compresi i suoi dtype fp8 e I64.
+- [tiktoken](https://github.com/openai/tiktoken): `c/tok.h` reimplementa
+ esattamente il suo `byte_pair_encode`, unendo la coppia adiacente la cui
+ concatenazione ha l'id di vocabolario più basso, così un vocabolario derivato da
+ tiktoken non ha bisogno di una lista di merge.
+- [llama.cpp](https://github.com/ggml-org/llama.cpp): il sottoinsieme della
+ grammatica GBNF in `c/grammar.h` segue la sua sintassi e il suo PDA a insieme di
+ stack, e il percorso Metal prende in prestito il suo trucco di residenza
+ `newBufferWithBytesNoCopy`.
+- [vLLM](https://github.com/vllm-project/vllm): il riferimento per la semantica
+ dell'output che il motore riproduce posizione per posizione (per esempio dove cade
+ la norma finale rispetto alla LM head).
+- [transformers](https://github.com/huggingface/transformers): l'oracle; la CI
+ riproduce token per token contro di esso un modello inizializzato a caso.
+- [DietGPU](https://github.com/facebookresearch/dietgpu): il codec ANS su GPU dietro
+ il livello sperimentale di expert compressi (`COLI_ANS`).
+- [rocWMMA](https://github.com/ROCm/rocWMMA): il backend HIP mappa su di esso l'API
+ di frammenti e mma_sync `nvcuda::wmma` di CUDA (`c/backend_gpu_compat.h`), ed è
+ ciò che permette a un unico sorgente .cu di compilare per entrambi i produttori.
+
## Licenza
Apache 2.0, Copyright 2026 Vincenzo Fornaro. Vedi [LICENSE](LICENSE) e [NOTICE](NOTICE). I pesi di GLM-5.2 sono rilasciati da Z.ai sotto licenza MIT.