Colibrì: Ejecuta Modelos MoE de 744B en tu Propio Hardware
Motores de inferencia en C puro con multitiering de memoria: expertos en streaming desde disco, sin GPU y sin dependencias
Colibrì es un motor de inferencia escrito en C puro —un solo fichero .c por familia de modelos más una colección de cabeceras compartidas— capaz de ejecutar modelos Mixture-of-Experts (MoE) de frontera, de 744B a 2,8T parámetros, en hardware de consumo. Su truco no es comprimir el modelo: es dejar de exigir que quepa en memoria rápida y tratarlo como datos que se escenifican entre VRAM, RAM y NVMe. En este curso aprendes la arquitectura, los mecanismos de streaming, la instalación, la CLI y los backends heterogéneos de uno de los proyectos de sistemas más interesantes del ecosistema open source.
Contenido
- ¿Qué es colibrì? Un motor diminuto para modelos gigantes
- Anatomía de un MoE: 744B parámetros, 40B activos
- Multitiering: VRAM, RAM y NVMe como una sola jerarquía
- El JIT de pesos: caché LRU, hot-store aprendido y prefetch
- I/O como parte del motor: pread, O_DIRECT y dual-SSD
- Instalación y primeros pasos
- Modelos y contenedores: int4-gs64, MTP int8 y conversión
- La CLI de colibrì: chat, plan, doctor, tune, serve, web
- Backends heterogéneos: CUDA, Metal, Vulkan y NUMA
- Estado comprimido, especulación y API OpenAI-compatible
1. ¿Qué es colibrì? Un motor diminuto para modelos gigantes
Colibrì (colibrì = colibrí) parte de una idea incómoda para la industria: un modelo de frontera no necesita caber en memoria rápida, necesita estar bien colocado. Su lema lo resume: "Tiny engine, immense model". El motor pesa unos cientos de KB; el modelo puede pesar cientos de GB.
La misión declarada del proyecto es investigación en sistemas de inferencia: cambiar cómo se representan y se mueven los pesos, decidir qué vive en VRAM, RAM o disco, solapar cómputo heterogéneo, reducir el coste de lanzamiento y sincronización, explotar la esparsidad y probar algoritmos de decodificación nuevos. Y todo se mide end-to-end en máquinas reales, no en microbenchmarks.
Qué incluye el motor
- C puro en runtime: sin BLAS, sin Python en el motor, sin GPU obligatoria.
- Una jerarquía de memoria única (VRAM / RAM / NVMe) en lugar de un requisito de memoria.
- Nueve familias de modelos soportadas con la misma interfaz de línea de comandos.
- Garantía semántica: la política por defecto nunca cambia en silencio la precisión ni la semántica del router.
Así se ve un arranque real, con un GLM-5.2 de 744B en modo streaming sobre CPU:
$ ./coli chat
🐦 colibri v1.11.0 — GLM-5.2 · 744B MoE · int4 · streaming CPU
✓ ready in 32s · resident 9.9 GB
› ciao!
◆ Ciao! 😊 Come posso aiutarti oggi?Qué se consigue, por clase de hardware
El mismo motor y el mismo contenedor int4 — el hardware solo cambia dónde viven los expertos:
| Hardware | Decode medido | Notas |
|---|---|---|
| 6× RTX 5090 (residencia completa) | 5,8 – 6,8 tok/s | TTFT ~13 s, disco 0 |
| Desktop CPU-only con 128 GB RAM | ~1,8 tok/s | En caliente (warm) |
| Portátil con una RTX 5070 Ti | 1,07 tok/s | Pipeline residencia GPU |
| Dev box de 25 GB | 0,05 – 0,1 tok/s | Suelo probado: todo desde disco |
El motor es Apache 2.0 y los pesos de GLM-5.2 se publican bajo MIT. Puedes leer, medir y modificar todo el camino de inferencia: el proyecto está pensado para que la siguiente optimización la aporte cualquiera dispuesto a medirla.
No hay SLA de velocidad, y sí una garantía dura de semántica. Memoria rápida insuficiente puede reducir la velocidad, pero no debe redefinir el modelo en silencio. Si ves que la precisión o el router cambian "para ir más rápido", algo va mal.
2. Anatomía de un MoE: 744B parámetros, 40B activos
Para entender colibrì hay que entender primero qué es un modelo Mixture-of-Experts (MoE). En una capa feed-forward clásica, cada token atraviesa la misma red densa. En un MoE, esa red se sustituye por N expertos y un router que decide, token a token, a qué pocos expertos enviarlo (típicamente un top-k).
La consecuencia práctica es enorme: el modelo tiene muchísimos parámetros totales, pero solo activa una fracción pequeña por token. En GLM-5.2:
| Componente | Parámetros / tamaño | Dónde vive |
|---|---|---|
| Total del modelo | 744B | — |
| Activos por token | ~40B (~5,4 %) | — |
| Parte densa (atención, expertos compartidos, embeddings) | ~17B | Residente en RAM en int4 (~9,9 GB) |
| Expertos enrutados | 75 capas MoE × 256 + cabeza MTP = 19.456 expertos (~19 MB c/u en int4) | En disco (~370 GB), en streaming |
| Lo que cambia de un token a otro | ~11 GB | Los expertos enrutados de ese token |
Fíjate en la clave: de los 744B de parámetros, solo ~11 GB cambian entre tokens consecutivos. El resto es estado estable que puede quedarse residente o incluso en disco sin que la semántica del modelo cambie.
El error mental más frecuente es intentar hacer caber el modelo. La formulación correcta es la contraria: el modelo no necesita caber, necesita ser colocado — parte residente, expertos escenificados bajo demanda.
La analogía: un JIT, pero para pesos
Un compilador JIT nunca compila el programa entero: observa qué se ejecuta de verdad y compila los caminos calientes, justo a tiempo. Colibrì hace la misma apuesta sobre un espacio de 744B parámetros: los parámetros no son estado residente que hay que sostener, son datos que se escenifican en una jerarquía heterogénea exactamente cuando el router demuestra que se necesitan. El "calor de enrutamiento" medido decide qué expertos se ganan qué tier, y el router corre una capa por delante para que el prefetch esconda la latencia de escenificación.
3. Multitiering: VRAM, RAM y NVMe como una sola jerarquía
El mecanismo central del proyecto es el AI memory multitiering: VRAM, RAM y NVMe dejan de ser tres límites y pasan a ser tres niveles de colocación para los mismos pesos. La regla de diseño es tajante: la colocación solo decide la velocidad.
Cada capa de cada token recorre los mismos cinco pasos — route → union → place → overlap → learn:
| Paso | Qué ocurre |
|---|---|
| route | El router elige los expertos top-k para el token o el lote. |
| union | Se unen las peticiones del lote: cada experto único se lee una sola vez (batch-union). |
| place | Se decide de qué tier responde cada experto: VRAM → RAM → disco. |
| overlap | El I/O de la capa siguiente se solapa con el cómputo de la actual. |
| learn | Se registra el calor de enrutamiento para mejorar la colocación futura. |
Los tres niveles
- VRAM (opcional): el tier más rápido. Se activa con CUDA, Metal o Vulkan. Acepta residencia total o parcial del set de expertos.
- RAM: aquí vive la parte densa en int4 (~9,9 GB en GLM-5.2) y, si sobra presupuesto, una caché de expertos.
- NVMe: los ~370 GB de expertos enrutados, leídos bajo demanda con perfiles de prefetch.
El mismo motor cubre todo el espectro: en un portátil de 25 GB todo se transmite desde disco (lento pero correcto); en un host grande el set completo de expertos se vuelve residente (CUDA_EXPERT_GB=auto PIN_GB=all) y el disco sale del camino de decodificación por completo.
# Inspeccionar la colocación VRAM/RAM/disco que el motor planea para esta máquina
COLI_MODEL=/nvme/glm52_i4 ./coli plan
# Intercalar los pesos residentes entre controladores de memoria (hosts multi-socket)
COLI_NUMA=1 COLI_MODEL=/nvme/glm52_i4 ./coli chat
# Forzar residencia completa de expertos en VRAM y fijar todo en RAM
CUDA_EXPERT_GB=auto PIN_GB=all ./coli chat --model /nvme/glm52_i4Empieza siempre por ./coli plan. Te dice, sin cargar el modelo, qué colocación va a intentar el motor con tu RAM y VRAM actuales. Es la forma más rápida de saber si tu máquina podrá con el modelo antes de gastar 372 GB de descarga.
4. El JIT de pesos: caché LRU, hot-store aprendido y prefetch
Si los expertos viven en disco, la pregunta es: ¿cómo no pagar una lectura por experto y token? Aquí está la parte más ingeniosa del proyecto. Colibrì combina tres mecanismos que se refuerzan:
| Mecanismo | Qué hace | Variable |
|---|---|---|
| LRU por capa | Caché de desalojo por capa; los expertos recientes se quedan. | — |
| Hot-store aprendido | El motor registra a qué expertos enruta tu carga de trabajo y fija los más calientes de forma persistente. | .coli_usage |
| Prefetch de una capa | Un hilo router-lookahead precarga los expertos de la capa siguiente mientras se computa la actual. | PILOT=1 |
| Batch-union | Las posiciones de un lote leen cada experto único una sola vez. | — |
El prefetch funciona porque el enrutamiento tiene estructura medible: el router es predecible una capa por delante en un 71,6 % de los casos. Y como la estructura es cacheable, el motor literalmente aprende tu carga: se vuelve más rápido cuanto más lo usas.
# .coli_usage se actualiza cada turno con el calor de enrutamiento observado
COLI_MODEL=/nvme/glm52_i4 ./coli chat
# Activar el hilo de prefetch (router-lookahead, una capa por delante)
PILOT=1 COLI_MODEL=/nvme/glm52_i4 ./coli chat
# Tamaño de la caché de expertos en RAM (por defecto 8 en varias familias)
./coli chat --model /nvme/inkling_i4 --cap 2El proyecto se describe como "un JIT, pero para pesos": el hot-store aprendido gana en cargas de trabajo repetibles. Si vas a usar el modelo de forma sistemática, ejecuta antes unos cuantos prompts representativos para que .coli_usage refleje tu uso real: la caché aprenderá tus expertos, no los de un benchmark genérico.
El historial de enrutamiento puede sobreajustarse a un prompt concreto, y el lookahead puede perder en algunos hosts. El propio proyecto lo declara: ambas son políticas medibles, no promesas. Si tu carga cambia mucho entre sesiones, mide PILOT=0 contra PILOT=1 en lugar de darlo por bueno.
5. I/O como parte del motor: pread, O_DIRECT y dual-SSD
En la mayoría de las máquinas, la decodificación está limitada por el disco. Colibrì trata el I/O como parte del motor, no como un detalle del sistema operativo. Tres decisiones concretas:
- Una lectura por experto: las tres matrices de cada experto se almacenan adyacentes y se leen en un único
pread. - Pool de I/O asíncrono acotado (
PIPE=1, por defecto): carga los expertos que faltan mientras los residentes computan. - Bandwidth dual-SSD: los expertos son de solo lectura, así que si tienes un segundo SSD puedes poner una copia completa del modelo y transmitir desde ambas unidades a la vez.
Dual-SSD: dos copias del modelo, el doble de ancho de banda
Cada experto se asigna a una unidad mediante hash determinista, ponderado por el ancho de banda medido (o declarado) de cada disco. Como el reparto es determinista, el prefetch y la lectura bajo demanda siempre caen en la misma unidad y nada se cachea dos veces. El ancho de banda agregado es la suma de ambos: un par de 9 GB/s + 3 GB/s lee los expertos ~33 % más rápido que el disco rápido en solitario.
# Copia completa del modelo en un segundo SSD y streaming desde ambos
COLI_MODEL=/fast/glm52_i4 COLI_MODEL_MIRROR=/second/glm52_i4 ./coli chat
# Ratio de ancho de banda primario,mirror (si se omite, se mide al arrancar)
COLI_DISK_WEIGHTS=9,3 COLI_MODEL=/fast/glm52_i4 COLI_MODEL_MIRROR=/second/glm52_i4 ./coli chatSi el segundo disco no cabe entero, el motor puede planificar un mirror parcial a partir del historial de expertos que ya ha aprendido (.coli_usage):
# 1. Planificar qué shards copiar dentro del presupuesto
./c/coli mirror plan --model /fast/glm52_i4 --mirror /second/glm52_i4 \
--budget-gib 200 --reserve-gib 20
# 2. Copiar (nunca modifica el modelo primario, verifica cada shard con SHA-256)
./c/coli mirror stage --model /fast/glm52_i4 --mirror /second/glm52_i4 \
--budget-gib 200 --reserve-gib 20
# 3. Verificar el mirror antes de usarlo
./c/coli mirror verify --model /fast/glm52_i4 --mirror /second/glm52_i4En NVMe real, mide DIRECT=1. O_DIRECT evita la caché de páginas del sistema y suele ser una gran ganancia en unidades con caché DRAM y margen de ancho de banda: +34 % de decode medido con PIPE=1, y 4,25 → 9,69 GB/s en iobench sobre un GB10.
O_DIRECT es dependiente de la unidad: en discos QLC, sin DRAM o virtualizados puede ser neutro o incluso negativo. Pruébalo primero y quédate con lo que tu hardware premie. Lo mismo con el dual-SSD: un mirror parcial es válido (los ficheros que faltan se quedan en el primario), pero conviene medir antes de asumir la ganancia.
6. Instalación y primeros pasos
Colibrì necesita dos cosas: el programa (unos cientos de KB) y el modelo (372 GB en el caso de GLM-5.2). Vamos paso a paso.
Descarga un release precompilado
Hay binarios para Linux, macOS y Windows: no necesitas compilador. Coge el archivo de tu plataforma desde Releases y descomprímelo.
mkdir colibri && tar xzf colibri-v1.8.0-linux-x86_64.tar.gz -C colibri && cd colibri
python3 coli info # engine ready ✓Comprueba que el motor está listo
Dentro del archivo tienes el motor (colibri, colibri.exe en Windows), el lanzador coli y sus ayudantes en Python. Nada que renombrar ni configurar: coli encuentra el motor a su lado. Solo necesitas Python 3 instalado —el lanzador y el gateway de API son scripts Python; el motor es C puro sin dependencias.
O compila desde el código fuente
Necesitas gcc (o clang) con OpenMP. El script de setup verifica el compilador, construye y ejecuta los auto-tests.
git clone https://github.com/JustVugg/colibri && cd colibri/c
./setup.sh # comprueba gcc/OpenMP, compila, self-tests
# ¿Quieres `coli` en el PATH? Desde el checkout:
pip install -e . # el motor sigue viviendo en c/ (instalación editable)Consigue el modelo
Hay un contenedor GLM-5.2 int4 pre-convertido en Hugging Face. Usa la build group-scaled (gs64) con la cabeza MTP en int8. Son ~372 GB: ponlo en un disco con espacio, idealmente rápido.
https://huggingface.co/mastouri/GLM-5.2-colibri-int4-g64-with-int8-mtp
También puedes convertir desde la fuente FP8 tú mismo con un comando reanudable que nunca necesita los 756 GB enteros en disco:
./coli convert --model /nvme/glm52_i4 # descarga+convierte shard a shard (python, una sola vez)Ejecútalo
El presupuesto de RAM, la caché y MTP se autodetectan. Empieza por plan y doctor, que son de solo lectura.
COLI_MODEL=/nvme/glm52_i4 ./coli chat # TUI de chat
COLI_MODEL=/nvme/glm52_i4 ./coli plan # inspecciona la colocación planeada
COLI_MODEL=/nvme/glm52_i4 ./coli doctor # chequeo de preparación (solo lectura)
./coli web --model /nvme/glm52_i4 # API + dashboard y abre el navegador
./coli serve --model /nvme/glm52_i4 # API + dashboard, sin navegador (headless)No uses los mirrors int4 per-row antiguos: miden ~9 puntos peores en calidad y son la causa raíz de los bucles en modo think y de generaciones que nunca terminan. Usa el contenedor gs64. Y la cabeza MTP debe ser int8, no int4 (int4 → 0 % de aceptación de drafts). Comprueba con ls -l <model>/out-mtp-*: los tamaños int8 correctos son 3527131672 / 5366238584 / 1065950496.
7. Modelos y contenedores: int4-gs64, MTP int8 y conversión
GLM-5.2 es el modelo de referencia, pero el mismo enfoque de streaming ejecuta ocho familias más. Cada una es un motor hermano: un fichero .c con su propia arquitectura, el mismo front-end coli chat / serve / web (el lanzador elige el binario a partir del config.json del modelo).
| Familia | Total / activo | Disco | RAM | Build |
|---|---|---|---|---|
| OLMoE (AI2) | 7B / 1B | ~7 GB (int8) | 8 GB | make -C c olmoe |
| Qwen3.6-35B-A3B | 35B / 3B | ~20 GB (int4-gs64) | 24 GB | make -C c qwen36 |
| DeepSeek V4 Flash | 284B / 13B | ~167 GB (REAP 150B: ~85 GB) | 16 GB mín. | make -C c deepseek-v4 |
| GLM-5.3-Flash | 321B / 40B | ~195 GB | 25 GB | make -C c glm53 |
| GLM-5.2 / 5.3 | 744B / 40B | ~372 GB | 16 GB mín. / 24 GB cómodo | make -C c glm |
| Inkling (Thinking Machines) | 975B / 41B | ~469 GB | 25 GB con denso int4 | make -C c inkling |
| DeepSeek V4.1 Flash | 552B / 16B | 203 GB (n-gram, sin conversión) | 32 GB+ | make -C c deepseek_v41 |
| Kimi K3 (Moonshot) | 2,8T / 104B | ~1,6 TB (sin conversión) | 32 GB+ | make -C c kimi_k3 |
Ninguna de ellas necesita GPU para funcionar; una GPU solo lo hace más rápido. La velocidad la fija tu disco, porque los expertos se transmiten desde él.
El mismo comando ejecuta cualquier modelo
coli lee el config.json del modelo, elige el binario del motor correspondiente y aplica la plantilla de chat de esa familia. Nada de la línea de comandos cambia entre modelos: compila el motor que quieras una vez y apunta COLI_MODEL al directorio correcto.
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
COLI_MODEL=/nvme/inkling_i4 ./coli chat
COLI_MODEL=/nvme/kimi_k3 ./coli chat
./coli web --model /nvme/inkling_i4 # API + dashboard
./coli serve --model /nvme/kimi_k3 # headlessContenedores y cuantización: por qué importa gs64
Los contenedores pre-convertidos no son todos iguales. Qwen3.6 lo demuestra con números: el contenedor int4-gs64 mide coseno 0,98777 → 0,99313 frente al ancla int8 y KL 0,109 → 0,080 frente al per-row, es decir ~44 % menos de error de cuantización. Por eso gs64 es el recomendado y el per-row se queda solo como base de comparación A/B.
Cualquier checkpoint arquitectónicamente idéntico funciona sin un camino de código propio: el mismo motor ejecuta, por ejemplo, KAT-Coder v2.5 sin cambios. Y Kimi K3 no requiere conversión alguna —sus expertos MXFP4 entrenados con QAT se transmiten directamente desde los shards originales de Hugging Face—. Eso permite hacer A/B reales entre checkpoints sin tocar el motor.
8. La CLI de colibrì: chat, plan, doctor, tune, serve, web
Toda la interacción pasa por un único lanzador, coli. Estos son los subcomandos que de verdad vas a usar:
| Comando | Para qué sirve |
|---|---|
coli info | Comprobar que el motor está listo. |
coli chat | TUI de chat interactivo (presupuesto de RAM, caché y MTP autodetectados). |
coli plan | Inspeccionar la colocación VRAM/RAM/disco planeada, sin cargar el modelo. |
coli doctor | Chequeo de preparación de solo lectura. |
coli doctor --deep | Preflight estricto: tensores, shards, índice y mirror. |
coli tune | Mide y guarda el perfil de ejecución más rápido y seguro para esta máquina. |
coli web | API + dashboard, y abre el navegador. |
coli serve | API + dashboard en modo headless (sin navegador). |
coli convert | Conversión de contenedor, shard a shard y reanudable. |
coli mirror | Planificar, escenificar y verificar un mirror parcial en un segundo SSD. |
coli cluster | Coordinador/worker para modo cluster local. |
COLI_MODEL=/nvme/glm52_i4 ./coli doctor --deep # preflight estricto antes de invertir horas
COLI_MODEL=/nvme/glm52_i4 ./coli tune # perfil óptimo para ESTA máquina
# Cluster local: el coordinador mantiene generación, routing y KV en local;
# los workers ejecutan las FFN enrutadas en otros Macs.
./coli cluster coordinator --host 0.0.0.0 --port 8765
./coli cluster worker --model /nvme/glm52_i4 --port 9100 \
--coordinator http://COORDINADOR:8765 --advertise-host WORKER_IP
./coli serve --model /nvme/glm52_i4 --cluster-coordinator http://127.0.0.1:8765En el cluster mode, el batch-union de una capa se envía como una sola petición TCP persistente, de modo que un token no paga un round trip por experto. El transporte está deshabilitado salvo que configures workers, así que el camino de una sola máquina no cambia.
En Windows, el archivo release incluye coli.cmd. Ojo: los ficheros .exe son los motores, no el lanzador. Si los arrancas directamente no tienen modelo que cargar y salen inmediatamente. Desde un checkout de fuentes, usa python coli chat --model D:\glm52_i4.
9. Backends heterogéneos: CUDA, Metal, Vulkan y NUMA
Una de las afirmaciones más fuertes del proyecto es que CPU, CUDA, Metal, memoria NUMA y residencia parcial o total de expertos comparten un mismo runtime y pueden combinarse según la máquina. La combinación rentable depende de cómputo, ancho de banda, residencia y carga de trabajo.
| Backend | Cómo se activa | Qué aporta |
|---|---|---|
| CPU (base) | Por defecto | Funciona en todo; OpenMP paraleliza el bucle de expertos. |
| CUDA | CUDA=1 | Tier de expertos en VRAM, residencia completa, pipeline residente. |
| Metal | METAL=1 | Apple Silicon: matemática de expertos por lotes en la GPU de memoria unificada. |
| Vulkan | VULKAN=1 | Cualquier GPU con driver Vulkan 1.2, incluida AMD vía Mesa/RADV. |
| NUMA | COLI_NUMA=1 | Intercala los pesos residentes entre controladores de memoria. |
# Tier de expertos en VRAM: medido 1,44 -> 10,05 tok/s (7,0x) en dos tarjetas de 8 GB,
# con salida bit-idéntica al camino de CPU
make -C c qwen36 CUDA=1
CUDA_EXPERT_GB=auto COLI_MODEL=/nvme/qwen36_i4 ./coli chat
# Mantener el residual stream en el dispositivo entre capas (pipeline residente)
COLI_CUDA_PIPE=2 COLI_MODEL=/nvme/glm52_i4 ./coli chat
# Tarjetas Pascal/Turing (GTX 10 / RTX 20): build portátil sin tensor cores
CUDA_ARCH=portable-pre-ampere NO_TC=1 make -C c deepseek-v4
# Prefetch del set completo de expertos de la capa siguiente en un segundo banco de VRAM
COLI_CUDA_MOE_BATCH=1 COLI_CUDA_MOE_DOUBLE=1 ./coli chat --model /ruta/DeepSeek-V4-FlashEl backend Vulkan es especialmente interesante para hardware que el fabricante ya no soporta: es el único camino para tarjetas como la RX 580 y compite con ROCm en RDNA4.
El objetivo del diseño es que CPU/GPU solapen transferencia y sincronización en vez de limitarse a mover el cuello de botella. Pero el proyecto es honesto con el límite: CPUs rápidas y baja residencia pueden borrar las ganancias de CUDA o Metal. Mide por etapas y cambia una sola variable cada vez.
Qwen3.8-Flash-Next es CPU-only: no soporta GPU. Y DeepSeek V4 Flash solo acepta "cualquier tarjeta NVIDIA desde la GTX 10 en adelante". Antes de comprar hardware leyendo una tabla de rendimiento, lee la fila de requisitos de tu familia concreta: leer dos familias juntas ha llevado a creer que los requisitos se contradicen, y no lo hacen — son modelos distintos.
10. Estado comprimido, especulación y API OpenAI-compatible
La última capa del proyecto tiene que ver con el estado y con no pagar dos veces por lo mismo.
Estado comprimido sin cambiar de modelo
La atención MLA almacena un estado KV comprimido: 576 floats por token en lugar de 32.768, es decir 57× más pequeño. Ese estado se persiste entre reinicios (.coli_kv), de modo que las conversaciones se reabren en caliente con cero re-prefill, byte a byte idénticas a una sesión ininterrumpida. Además, la validación token-exact del forward se hace contra un oráculo de transformers (típicamente 30-32/32 posiciones), y el DSA de atención dispersa se valida forzando la selección de clave completa para reproducir la atención densa exactamente.
Decodificación especulativa, con honestidad
| Mecanismo | Qué hace | Regla dura |
|---|---|---|
| MTP nativo (GLM-5.2) | La cabeza MTP redacta tokens que el modelo principal verifica en un forward por lotes: 2,2 – 2,8 tokens/forward cuando compensa. | La cabeza debe ser int8; int4 colapsa a 0-4 % de aceptación. |
SPEC_PIN=1 | Fija draft y verificación a la misma familia de kernels. | Borrador y verificación deben computar la misma función. |
| Gramáticas GBNF | GRAMMAR=archivo.gbnf añade aceptación casi gratis en salida JSON restringida. | Subconjunto GBNF compatible con la sintaxis de llama.cpp. |
Y el interruptor que casi nadie usa: DRAFT=0. Si el cache está en caliente, la especulación puede no pagar; el proyecto documenta incluso un caso medido de 32 % de pérdida alrededor del 85 % de hit rate de expertos. La regla es simple: si no paga, desactívala.
Integrarlo en tus aplicaciones
El gateway openai_server.py expone una API compatible con OpenAI, con soporte de KV slots (varias conversaciones persistentes) y dashboard web (web/, un cliente puro de la API OpenAI). También hay un shell de escritorio Tauri v2 que envuelve la UI web.
# Servidor headless con API OpenAI-compatible + dashboard
./coli serve --model /nvme/glm52_i4
# Y desde tu propia app, apuntando al endpoint compatible con OpenAI
curl http://localhost:8000/v1/chat/completions \
-H "Content-Type: application/json" \
-d '{"model":"glm-5.2","messages":[{"role":"user","content":"Hola"}]}'El dashboard web (./coli web) muestra métricas en vivo: tok/s, TTFT, el desglose temporal por turno, la barra de tiers VRAM/RAM/disco y un "mini-cerebro" con los 19.456 expertos. La página Brain pinta el color por tier de almacenamiento y el brillo por calor de enrutamiento, y la página Atlas coloca los expertos medidos en una galaxia 3D donde la posición es afinidad de enrutamiento real, no un embedding aprendido. Es la mejor forma de ver por qué el streaming funciona.
La compresión y la especulación son propiedades de memoria, latencia y corrección, no un cheque en blanco de rendimiento. El proyecto no promete más tok/s: promete que no cambia el modelo. Si necesitas reproducir un resultado, registra hardware, commit, modelo/contenedor, comando exacto, prompt, estado de caché, throughput, TTFT, hit rate de expertos, bytes leídos y chequeo de calidad. Un fallo bien controlado vale aquí más que un número rápido sin explicación.
Preguntas frecuentes
¿Necesito una GPU para ejecutar un modelo de 744B?
No. Ninguna de las nueve familias la necesita para funcionar: una GPU solo lo hace más rápido. La velocidad la determina tu disco, porque los expertos se transmiten desde él. En un host con VRAM abundante, el set de expertos puede volverse residente y el disco sale del camino de decodificación.
¿Cuánta RAM y cuánto disco necesito para empezar?
Para probar el flujo completo, OLMoE pide ~7 GB de disco y 8 GB de RAM. Para GLM-5.2, el mínimo son 16 GB de RAM (24 GB cómodos) y ~372 GB de disco para el contenedor int4-gs64. Con 25 GB de RAM todo se transmite desde disco: lento, pero correcto.
¿Por qué el motor se vuelve más rápido con el uso?
Porque registra a qué expertos enruta tu carga de trabajo en .coli_usage y fija automáticamente los más calientes (hot-store aprendido), además del prefetch de una capa por delante. El enrutamiento es predecible una capa por delante en un 71,6 % de los casos, y la estructura es cacheable.
¿Puedo usarlo desde mi propia aplicación o agente?
Sí. coli serve levanta un gateway compatible con OpenAI, así que cualquier cliente que hable el protocolo de OpenAI puede apuntar a tu colibrì local. Soporta KV slots para varias conversaciones y tiene dashboard web; también hay API experimental de segmentos de capa y de tokenizer/embedding/head para runtimes de borde.