Guide Complet de Colibri — Exécuter un modèle à 744B de paramètres avec 25 Go de RAM

TL;DR : Colibri est un moteur d'inférence MoE (Mixture of Experts) révolutionnaire, écrit en pur C. Il ne nécessite aucun GPU, juste 25 Go de RAM, pour exécuter fluidement des modèles massifs comme GLM-5.2 (744B de paramètres) sur une machine grand public. Grâce à une technique innovante de « streaming d'experts », il considère la VRAM, la RAM et le disque comme une hiérarchie mémoire unifiée, trouvant l'équilibre parfait entre performance et ressources.

Qu'est-ce que Colibri ?

Colibri (le colibri, oiseau-mouche) est un projet open source développé par JustVugg, conçu pour résoudre le problème ultime du déploiement des grands modèles de langage (LLM) : comment exécuter un modèle ultra-massif avec des ressources matérielles limitées ?

Traditionnellement, faire tourner un modèle de 744B de paramètres exige plusieurs téraoctets de mémoire GPU et des clusters coûteux de puces A100/H100. Colibri propose un paradigme radicalement différent :

  • Tiny Engine, Immense Model (petit moteur, modèle immense) : Le moteur entier tient dans un seul fichier C (c/glm.c, environ 2400 lignes), sans aucune dépendance externe (pas de BLAS, pas de Python à l'exécution).
  • Streaming d'experts (Expert Streaming) : Les 21 504 experts de routage du modèle (environ 19 Mo chacun) ne sont pas chargés en mémoire d'un coup. Ils sont chargés depuis le disque à la demande, avec un cache LRU et le cache de pages du système d'exploitation pour optimiser les accès.
  • Hiérarchie mémoire (Memory Hierarchy) : La VRAM (si disponible), la RAM et le SSD sont vus comme un seul pool mémoire unifié et gérable. Le modèle dégrade automatiquement ses performances quand les ressources manquent, mais sans jamais sacrifier la précision ni la justesse des résultats.

Points techniques clés

Technique Description Avantage
Attention MLA Architecture MLA (Multi-Layer Attention) native de GLM-5.2, avec un KV-Cache compressé (576 floats/token contre 32 768). Le KV-Cache est réduit de 57×, économie de mémoire massive.
Router style DeepSeek-V3 Adopte le même router sigmoid que DeepSeek-V3, avec support des experts partagés et des 3 premières couches denses. Routage d'experts plus précis, meilleures performances du modèle.
Décodage spéculatif MTP Utilise les têtes Multi-Token Prediction (MTP) intégrées à GLM-5.2 pour le décodage spéculatif. Taux d'acceptation mesuré : 39-59 %, moyenne de 2,2-2,8 tokens/forward. Accélère significativement la génération.
Grammar-Forced Speculation Support des contraintes grammaticales GBNF pour les sorties structurées (JSON, appels de fonctions). Taux d'acceptation spéculative proche de 100 %. Efficacité extrême sur des tâches ciblées.
Noyau de produit scalaire entier Implémente la multiplication matricielle en int8 et int4 compacté via AVX2 maddubs, 1,4 à 2,5× plus rapide que le calcul flottant. Exploitation optimale du CPU pour accélérer l'inférence.
Attention clairsemée DSA Implémentation complète de l'indexeur DSA (Dynamic Sparse Attention) de GLM-5.2 : chaque couche ne sélectionne que les Top-2048 clés causales. Complexité de calcul fortement réduite tout en préservant la qualité.

Mise en route rapide : trois étapes

1. Préparer l'environnement

Colibri exige très peu : un système Linux/macOS moderne et un compilateur GCC suffisent.

BASH 
# Ubuntu/Debian
sudo apt update && sudo apt install -y build-essential curl git

# macOS (Homebrew)
brew install gcc git

2. Télécharger et compiler

BASH 
# Cloner le dépôt
git clone https://github.com/JustVugg/colibri
cd colibri

# Compiler (version CPU par défaut)
make

# Ou, si vous avez un GPU NVIDIA et souhaitez activer l'accélération CUDA (optionnel)
# make COLI_CUDA=1

3. Exécuter le modèle

BASH 
# Lancer le chat interactif
./coli chat

# Ou exécuter une inférence par lots
./coli batch --prompt "Écrivez un poème en français sur le printemps."

💡 Astuce : La première exécution nécessite de télécharger les poids du modèle (~370 Go). Prévoyez-le à l'avance. Les exécutions suivantes seront très rapides.

4. Télécharger les poids du modèle

Colibri utilise des modèles quantifiés int4 pré-convertis, disponibles directement sur Hugging Face :

BASH 
# Version recommandée (tête MTP int8, support du décodage spéculatif)
# https://huggingface.co/mateogrgic/GLM-5.2-colibri-int4-with-int8-mtp

# Télécharger avec huggingface-cli
pip install huggingface_hub
huggingface-cli download mateogrgic/GLM-5.2-colibri-int4-with-int8-mtp \
  --local-dir ./glm52-int4

⚠️ Avertissement important : la tête MTP doit être en version int8 !

Le problème le plus fréquent dans la communauté — « pourquoi le taux d'acceptation MTP est de 0 % ? » — vient d'une mauvaise version du modèle téléchargée. La version originale (jlnsrk/GLM-5.2-colibri-int4) a une tête MTP quantifiée en int4, ce qui rend le décodage spéculatif complètement inopérant (0 % d'acceptation) et coûte environ 2× en performance.

Comment vérifier : regardez la taille des fichiers out-mtp-* - int8 (correct) : 3527131672 / 5366238584 / 1065950496 - int4 (incorrect) : 1765523544 / 2686077736 / 536747200

Analyse approfondie : comment fonctionne Colibri ?

La magie de Colibri réside dans sa gestion mémoire et son architecture algorithmique. Décomposons son flux de travail principal :

  1. Lancement et initialisation : Au démarrage, le moteur calcule automatiquement la taille du cache d'experts en fonction de MemAvailable du système, pour éviter tout déclenchement de l'OOM Killer.
  2. Chargement des experts : Quand le modèle a besoin d'un expert, le moteur lit ses poids depuis le disque. Pour réduire l'attente I/O, il utilise le syscall WILLNEED pour faire de la prélecture asynchrone (async expert readahead).
  3. Exécution du calcul : Les poids chargés sont envoyés au noyau optimisé de produit scalaire entier. Pour le decode d'un seul token, on utilise le calcul f32 ; pour le prefill par lots, le noyau int4, plus rapide.
  4. Persistance du KV-Cache : Le KV-Cache de la conversation est compressé et persisté dans un fichier .coli_kv. Concrètement, vous pouvez fermer le programme et le rouvrir : le contexte de la conversation reste « chaud », sans avoir besoin de recalculer l'historique.

Cette conception garantit que, en cas de ressources limitées, les performances de Colibri se dégradent progressivement, mais jamais de manière catastrophique ni erronée.

Persistance du KV-Cache : ne plus perdre ses conversations

Une fonctionnalité phare de Colibri : le KV-Cache persistant. Après chaque conversation, le KV-Cache MLA compressé est ajouté au fichier .coli_kv (environ 182 Ko/token, crash-safe). Au prochain lancement, il est automatiquement restauré — pas besoin de refaire le prefill du contexte historique.

BASH 
# Persistance du KV-Cache activée par défaut
./coli chat

# Pour la désactiver
KVSAVE=0 ./coli chat

Router-Lookahead prefetch (expérimental)

Colibri implémente une optimisation astucieuse : le routage des experts de la couche suivante est prévisible à 71,6 % (à partir de l'état post-attention de la couche courante). Avec PILOT=1, un thread I/O dédié précharge les experts nécessaires à la couche suivante pendant que la couche courante calcule.

BASH 
# Activer le prefetch par anticipation du router
PILOT=1 ./coli chat

Référence rapide des paramètres

Variable d'environnement Valeur par défaut Description
DRAFT 1 Activation du décodage spéculatif MTP (0=désactivé)
DSA 1 Activation de l'attention clairsemée DSA (0=désactivé, attention dense)
DSA_TOPK 2048 Nombre de clés causales Top-K sélectionnées par couche DSA
PILOT 0 Activation du prefetch Router-Lookahead
KVSAVE 1 Activation de la persistance du KV-Cache
IDOT 1 Activation du noyau de produit scalaire entier
COLI_CUDA 0 Activation de l'accélération CUDA (nécessite la compilation avec)
GRAMMAR - Chemin du fichier de grammaire GBNF (pour les sorties structurées)
GRAMMAR_DRAFT 24 Limite maximale de跨度 de contrainte grammaticale par forward

Benchmarks de performance : données réelles

Selon les tests officiels sur WSL2 (12 cœurs, 25 Go de RAM, NVMe) :

  • Temps de démarrage à froid : environ 32 secondes (chargement du modèle, initialisation du cache).
  • Mémoire résidente : environ 9,9 Go (partie dense int4).
  • Pic d'utilisation disque : environ 370 Go (tous les poids d'experts).
  • Vitesse de génération : avec MTP activé et cache préchauffé, entre 2,2 et 2,8 tokens/forward.

📊 Comparaison : C'est comparable à la vitesse d'un modèle 7B sur un GPU haut de gamme, alors que Colibri exécute un modèle 100 fois plus massif à 744B de paramètres !

Accélération GPU : test avec 6× RTX 5090

Selon le rapport expérimental officiel du 2026-07-12, avec 6 cartes RTX 5090 permettant de résider tous les experts en VRAM+RAM, la vitesse de decode par requête atteint 6,84 tok/s. Cela démontre l'architecture élastique de Colibri — du CPU pur au multi-GPU, le même code s'étend de manière transparente.

Démarrage à froid vs cache chaud

Scénario Lecture disque/token Description
Cache froid ~11 Go (75 couches × 8 experts) Première inférence, tous les experts doivent être lus depuis le disque
Cache chaud Réduction significative Les experts fréquents sont déjà en RAM
Résidence GPU totale ~0 Tous les experts en VRAM, aucun I/O disque

💡 Note sur les SSD : Le streaming de Colibri est une opération en lecture seule, il n'use pas significativement le SSD. Les vrais points de vigilance : (1) le trafic de swap quand la mémoire système est insuffisante (les écritures usent le SSD) ; (2) la température du SSD en lecture soutenue et prolongée. Le mécanisme de budgétisation mémoire automatique de Colibri évite naturellement le swap.

Comparaison avec d'autres moteurs d'inférence

Fonctionnalité Colibri llama.cpp Ollama
Langage Pur C (~2400 lignes) C/C++ Go + llama.cpp
Modèle cible GLM-5.2 (744B MoE) Généraliste (série LLaMA) Généraliste
GPU requis Non (CUDA optionnel) Recommandé Recommandé
Mémoire requise 25 Go de RAM Dépend de la taille du modèle Dépend de la taille du modèle
Streaming d'experts ✅ Fonctionnalité centrale ❌ ❌
Persistance KV-Cache ✅ ❌ ❌
Décodage spéculatif MTP ✅ Support natif Certains modèles Certains modèles
Attention clairsemée DSA ✅ ❌ ❌
Dépendances externes Zéro BLAS, etc. Nombreuses

🔍 Différence de positionnement : Colibri ne remplace pas llama.cpp, c'est une solution spécialisée pour un scénario spécifique. Si vous devez exécuter un modèle MoE ultra-massif sur du matériel grand public, Colibri est actuellement la seule option viable.

Scénarios pratiques

Scénario 1 : Assistant AI local (CPU pur)

Idéal pour les développeurs sans GPU, sur un laptop ou un PC de bureau :

BASH 
# Lancer une conversation interactive
./coli chat

# Sortie JSON avec contraintes grammaticales
./coli chat --grammar schemas/response.gbnf

Scénario 2 : Extraction de données structurées

Utilisez Grammar-Forced Speculation pour obtenir des performances extrêmes sur du JSON ou des appels de fonctions :

BASH 
# Définir un fichier de grammaire GBNF
cat > schema.gbnf << 'EOF'
root ::= "{" ws "\"name\"" ws ":" ws string "," ws "\"age\"" ws ":" ws number ws "}"
string ::= "\"" [^"]* "\""
number ::= [0-9]+
ws ::= [ \t\n]*
EOF

# Exécuter l'inférence avec contrainte grammaticale
GRAMMAR=schema.gbnf ./coli batch \
  --prompt "Extraire les informations du texte suivant : Jean Dupont, 28 ans, ingénieur logiciel"

Scénario 3 : Inférence sur cluster multi-GPU

Pour les utilisateurs disposant de ressources GPU, Colibri supporte un déploiement hybride :

BASH 
# Compiler la version CUDA
make COLI_CUDA=1

# Exécuter (épingle automatiquement les experts populaires en VRAM GPU)
COLI_CUDA=1 ./coli chat

Questions fréquentes (FAQ)

Q : Ma machine n'a que 16 Go de RAM, est-ce que ça marche ? R : Oui, mais l'expérience sera limitée. Le minimum de Colibri est de pouvoir contenir la partie dense (~9,9 Go en int4), plus le KV-Cache et les tampons de travail. Avec 16 Go, ça tourne, mais le cache d'experts est plus petit et les démarrages à froid seront plus fréquents.

Q : Quelle taille de SSD faut-il ? R : Les poids du modèle font environ 370 Go (quantifiés int4). Avec le KV-Cache et les fichiers temporaires, comptez au moins 500 Go d'espace libre. Un SSD NVMe est fortement recommandé ; un SSD SATA fonctionne aussi, mais plus lentement.

Q : Est-ce compatible Windows ? R : Support officiel via WSL2 (Windows Subsystem for Linux). La compilation native Windows n'est pas encore fournie, mais le code C devrait théoriquement compiler sous MSVC/MinGW.

Q : Est-ce compatible avec le format GGUF de llama.cpp ? R : Non. Colibri utilise son propre format conteneur int4, optimisé spécifiquement pour le streaming d'experts MoE. Il faut utiliser l'outil de conversion FP8→int4 officiel.

Conclusion : une étape majeure vers la démocratisation de l'IA

Colibri n'est pas qu'un jouet technique. Il représente une direction importante dans l'évolution de l'IA : décentralisation et démocratisation. Il nous prouve que les capacités d'IA les plus avancées ne sont plus le monopole de quelques géants technologiques et de leur matériel hors de prix. Un développeur ordinaire, avec simplement un ordinateur portable, peut désormais explorer et exploiter les modèles de langage les plus sophistiqués.

Le succès de Colibri est la conjugaison parfaite de l'esthétique ingénieuse et de la sagesse algorithmique. Il n'a pas cherché à faire « plus gros », mais « plus malin ». Il nous rappelle que la véritable innovation naît souvent du respect des ressources et de la poursuite implacable de l'efficacité.

Liens de référence

Cet article a été rédigé sur la base de Colibri v1.0 (2026-07-01), sous licence Apache 2.0.