개요
colibri는 약 25GB RAM의 소비자급 머신에서 Z.ai의 GLM-5.2 744B Mixture-of-Experts(MoE)를 실행하려는 순수 C 로컬 추론 엔진이다. 모델 전체를 RAM에 올리는 대신 dense 부분은 상주시키고, 라우팅되는 expert를 약 370GB의 로컬 디스크에서 필요할 때 읽는다. 저장소 설명·README·GitHub API 메타데이터를 2026-07-12에 확인했다.
핵심 아이디어
- GLM-5.2는 토큰마다 약 40B 파라미터만 활성화하는 MoE 구조를 사용한다는 전제다.
- attention·embedding·shared expert 등 약 17B 파라미터의 dense 부분은 int4로 RAM에 상주하며, README 기준 약 9.9GB를 차지한다.
- 75개 MoE 레이어의 256개 routed expert와 MTP head를 합친 21,504개 expert는 디스크에 둔다. int4 변환본에서 expert 하나는 약 19MB이고 모델 저장공간은 약 370GB다.
- 따라서 병목은 일반적인 GPU 메모리보다 랜덤 디스크 읽기·RAM 캐시 적중률·CPU 양자화 커널이다. cold decode에서는 토큰당 약 11GB의 expert read가 발생한다고 보고한다.
구현 범위
모델 실행과 메모리 계층
- GLM-5.2
glm_moe_dsaforward를 transformers oracle과 teacher-forcing 32/32, greedy generation 20/20으로 token-exact 검증했다고 설명한다. - MLA attention의 q/kv-LoRA와 부분 RoPE를 구현하고, compressed KV-cache를 토큰당 576 floats로 저장한다. README는 32,768 floats 대비 57배 작다고 주장한다.
- DSA sparse attention에서 레이어별 causal key 중 top-2048을 선택하며,
DSA=0또는DSA_TOPK로 조정할 수 있다. - int8·packed int4·packed int2 양자화, per-row scale, AVX2 integer-dot kernel을 제공한다. 단일 행 decode에서는 측정 결과 int4가 느려 f32 경로를 선택할 수 있다.
- per-layer LRU, RAM 여유분 기반 자동 cache sizing, 사용량 학습형 hot expert pinning, async readahead를 결합한다.
PILOT=1은 다음 레이어의 라우팅을 미리 예측해 prefetch하는 실험 기능이다.
Speculative decoding과 지속성
- GLM-5.2의 native MTP head가 draft token을 만들고 main model이 batched forward로 검증한다. 저장소가 인용한 커뮤니티 측정에서는 int8 MTP head가 39–59% acceptance, 2.2–2.8 tokens/forward를 보였고, int4 head는 acceptance가 0–4%로 speculation이 사실상 작동하지 않는다고 한다.
- cold cache에서는 speculative verification이 추가 expert load를 유발해 오히려 느려질 수 있으므로 adaptive guard와
DRAFT=0을 제공한다. - GBNF의 제한된 byte-level 문법에서 다음 토큰이 하나로 결정되는 구간을 강제 draft로 넣는 grammar-forced speculative decoding을 추가했다. 강제 구간도 같은 batch 검증을 거치므로 문법 오류가 출력 샘플링을 바꾸지는 않는다고 설명한다.
.coli_kv에 compressed MLA KV-cache를 turn마다 crash-safe로 저장해 재시작 후 prefill 없이 대화를 재개한다.KVSAVE=0으로 끌 수 있다.
사용 표면
cd c && ./setup.sh: GCC/OpenMP 확인, 빌드와 self-test 실행.coli convert: GLM-5.2 FP8 shard를 한 번에 하나씩 내려받아 int4 container로 변환하고 MTP head를 변환한다. 전체 756GB FP8 checkpoint를 동시에 보관하지 않는 resumable converter다.coli plan: safetensors header만 읽어 dense/expert footprint, RAM reserve, 안전한 cache cap, VRAM tier 계획을 JSON으로 출력한다.coli doctor: 모델 경로·config·tokenizer·shard·RAM·GPU·CUDA linkage를 읽기 전용으로 점검하며, 2026-07-11 커밋에서 추가됐다.coli chat: 터미널 대화 인터페이스.coli serve는 Python 표준 라이브러리 gateway를 통해/v1/models,/v1/chat/completions,/v1/completions,/health등을 제공하는 text-only OpenAI-compatible API다.- API는 한 번에 하나의 generation을 실행하고 FIFO admission queue로 요청을 제한한다.
--kv-slots로 최대 16개의 독립 KV context를 설정할 수 있지만 continuous batching은 아니다. web/은 OpenAI Chat Completions/SSE를 사용하는 React + TypeScript 브라우저 UI이며,desktop/에는 Tauri 셸이 있다. 둘 다 엔진에 직접 결합하기보다 호환 API를 소비하는 구조다.
성능과 현실적인 요구사항
README의 저장소 측정·커뮤니티 제보를 그대로 옮기면 다음과 같다. 이는 독립 재현 결과가 아닌 프로젝트 측 보고값이다.
| 환경 | 설정/측정값 | 보고 성능 |
|---|---|---|
| WSL2, 12 cores, 25GB RAM, 약 1GB/s VHDX | cold baseline | 0.05–0.1 tok/s |
| Apple M5 Max, macOS, 128GB, 14.2GB/s SSD | MTP off | 1.06 tok/s |
| Ryzen AI 9 HX 370, 128GB | int8 MTP + 46.7GB learned pin | 0.37 tok/s |
| Ryzen AI Max+ 395, 128GB | learned pin 47.6GB, topp=0.7 | 0.40 tok/s |
| Ryzen 9 9950X, PCIe 5 SSD | 동일 머신에서 SSD만 교체 | 0.28 tok/s |
실행에는 최소 16GB RAM, AVX2, GCC/OpenMP, 약 370GB int4 모델과 로컬 NVMe가 필요하다고 안내한다. 변환은 실제 ext4/NVMe 경로에서 약 400GB의 여유공간을 요구한다. 네트워크/9p mount는 피해야 하며, RAM이 작으면 디스크 속도보다 cache cap이 더 강한 병목이 된다.
현재 상태와 주의점
- 2026-07-12 API snapshot: 4,434 stars, 390 forks, 26 open issues, C/Apache-2.0, default branch
main; 별도 GitHub release는 확인되지 않았다. - 2026-07-11~12 사이에 Windows 11 native MinGW-w64 포트,
coli doctor, grammar-forced drafts, Nix flake, Tauri desktop shell이 빠르게 추가됐다. - 열린 이슈에는 ARM64에서 oracle과 다른 generation 결과(#76), Apple Silicon Metal backend(#72), RAM 과다 사용(#74), 대형 메모리 호스트에서 full-resident expert 배치(#80), NVMe와 matmul overlap(#79) 등이 있다. 따라서 “모든 소비자 기기에서 안정적으로 빠른 GLM-5.2 실행기”라기보다, 디스크 스트리밍 추론의 가능성과 최적화 방향을 매우 공격적으로 실험하는 프로젝트로 보는 편이 정확하다.
- CUDA backend는 resident quantized tensor와 선택된 hot expert를 위한 opt-in 실험 계층이다. 스트리밍 expert를 매번 GPU로 복사하면 PCIe가 디스크 병목을 대체할 수 있어 기본 경로는 CPU로 남겨둔다는 설계다.
- README는 GLM-5.2 weights가 Z.ai의 MIT 라이선스로 공개됐다고 적고, Hugging Face의 int4 변환본과 별도 int8 MTP head를 안내한다. 실제 모델 파일의 배포 상태·라이선스는 모델 저장소를 별도로 확인해야 한다.
평가
colibri의 중요한 점은 744B 모델을 “더 작은 양자화 파일로 GPU에 올린다”가 아니라, MoE의 sparse activation을 이용해 상주 메모리 / 디스크 expert store / 학습형 cache / 추론 커널을 하나의 계층형 시스템으로 설계했다는 데 있다. 이 접근은 llama-cpp 같은 범용 로컬 추론 엔진과 직접 경쟁하기보다, RAM이 부족해도 거대한 MoE를 실행하려는 특수한 지점에 최적화된다.
다만 토큰당 수 GB의 random read와 약 370GB 저장공간은 일반적인 로컬 LLM 사용성의 문턱을 크게 높인다. 따라서 현재의 실용적 가치는 범용 챗봇 배포보다는 (1) 충분한 RAM/NVMe를 가진 사용자의 frontier MoE 실험, (2) 디스크·캐시·양자화 커널 연구, (3) 대규모 모델을 위한 새로운 inference tier 설계의 참고 구현에 있다.
관련 노트
- glm-5.2 — 실행 대상 모델의 기존 모델·배포 맥락
- local-llm — 저장공간·메모리·로컬 실행 병목
- llama-cpp — C/C++ 기반 양자화 로컬 추론 엔진과의 인접 비교
- moc-ai-models — 모델·로컬 추론 MOC
- moc-dev-tools — 개발 도구·로컬 AI 인프라 MOC
출처
- GitHub 저장소 — README, 파일 구조, 사용법, 성능표
- GitHub REST repository API — 메타데이터·snapshot metrics
- GitHub commits API — 최신 변경 흐름
- 원문 캡처:
raw source:github-justvugg-colibri“