colibri 로컬에서 돌리는 법

큰 MoE(Mixture of Experts, 전문가 혼합) 모델을 로컬에서 쓰고 싶은데, VRAM에 통째로 올리기는 부담될 때가 많죠. colibri(JustVugg/colibri)는 그런 상황을 위해 나온 pure C 추론 엔진입니다. 런타임 의존성 없이 디스크·RAM·VRAM을 하나의 메모리 계층처럼 쓰고, 라우터가 고른 전문가(expert)만 디스크에서 스트리밍합니다. 이 글은 설치부터 coli chat / coli serve / coli web까지, 공식 문서에 적힌 순서만 따라가 봅니다.

할 수 있는 일

• Linux / macOS / Windows에서 prebuilt 릴리스를 풀거나, 소스에서 ./setup.sh로 엔진을 빌드합니다.
• GLM-5.2/5.3, GLM-5.3-Flash, Inkling, Kimi K3, DeepSeek V4/V4.1 Flash, Qwen3.8-Flash-Next, Qwen3.6, OLMoE 등 모델 패밀리마다 하나의 C 엔진을 쓰고, 프론트엔드는 같은 coli chat / serve / web입니다.
• 터미널 채팅뿐 아니라 OpenAI 호환 API(127.0.0.1:8000 기본), 웹 대시보드, Brio 모드(닫힌 선택지 확률만 읽기)를 쓸 수 있습니다.
• GPU는 필수가 아닙니다. CUDA / Metal / Vulkan은 있으면 빨라지고, 없으면 CPU-only로 동작합니다.

필요한 것

수치는 공식 Quick Start·README에 적힌 값만 옮겼습니다. 모델마다 디스크·RAM이 크게 다르니, 처음이면 작은 OLMoE(~7 GB)나 Qwen3.6(~20 GB 컨테이너)부터 잡는 편이 안전합니다.

단계

1) 엔진 받기 — prebuilt 또는 소스

가장 빠른 길: Releases에서 플랫폼 아카이브를 받아 풉니다. Python 3만 있으면 됩니다.

mkdir colibri && tar xzf colibri-v1.12.0-linux-x86_64.tar.gz -C colibri && cd colibri
python3 coli info                         # engine ready ✓

Windows는 colibri-v1.12.0-windows-x86_64.zip을 풀고 Python 3를 설치한 뒤, 같은 폴더에서 coli / coli.cmd를 쓰면 됩니다. ARM64 Linux는 공식 x86_64 아카이브가 없으니 소스 빌드가 필요합니다.

소스 빌드:

git clone https://github.com/JustVugg/colibri.git
cd colibri/c
./setup.sh                                # gcc/OpenMP 확인 → 빌드 → self-test

self-test가 32/32(또는 툴체인에 따라 ~30–32/32)를 찍으면 엔진이 정상입니다. PATH에 올리고 싶으면 클론 루트에서 pip install -e .로 coli를 등록할 수 있습니다(엔진 바이너리는 여전히 c/에 둡니다).

2) 모델 받기

공식 권장 시작점은 GLM-5.2의 group-scaled(gs64) int4 + int8 MTP 컨테이너입니다.

• HF: mastouri/GLM-5.2-colibri-int4-g64-with-int8-mtp (약 372 GB)
• 또는 GLM-5.3: Justvugg/GLM-5.3-colibri-int4-g64 (약 419 GB, MTP 없음 → 스펙큘레이션 기본 off)

# Hugging Face CLI 예시 (사이트·README에 안내된 경로)
hf download mastouri/GLM-5.2-colibri-int4-g64-with-int8-mtp --local-dir ~/Models/glm52_i4

구버전 per-row int4 미러는 품질·루프 이슈가 있어, README는 gs64 컨테이너를 쓰라고 못 박아 둡니다. FP8 원본에서 직접 변환하려면:

./coli convert --model /nvme/glm52_i4     # 샤드 단위 재개 가능, 일회성

디스크가 빡세면 OLMoE(변환 후 ~7 GB)나 Qwen3.6 int4-gs64(~20 GB)부터 연습하는 게 현실적입니다.

3) 상태 확인 → 채팅

COLI_MODEL=/nvme/glm52_i4 ./coli doctor   # 읽기 전용 readiness
COLI_MODEL=/nvme/glm52_i4 ./coli plan     # VRAM/RAM/디스크 배치 계획 확인
COLI_MODEL=/nvme/glm52_i4 ./coli chat     # TUI 채팅

디스크가 병목이면 README·Quick Start가 권하는 --topp 0.85로 expert 읽기량을 줄여 볼 수 있습니다. Windows(UCRT64) 예시는 COLI_MODEL=/d/glm52_i4 ./coli chat입니다.

4) API 서버 / 웹 UI

./coli serve --model /nvme/glm52_i4
# 또는 키·바인딩을 명시:
COLI_MODEL=/nvme/glm52_i4 COLI_API_KEY=local-secret ./coli serve \
  --host 127.0.0.1 --port 8000 --model-id glm-5.2-colibri

./coli web --model /nvme/glm52_i4         # API + 대시보드, 준비되면 브라우저 오픈

기본은 http://127.0.0.1:8000입니다. /v1/chat/completions뿐 아니라 Anthropic Messages(/v1/messages), Brio(/v1/brio)도 같은 포트에 붙습니다. 외부에 열 때는 COLI_API_KEY와 허용 호스트 설정을 문서대로 챙기세요.

# TUI에서
./coli chat --model /nvme/qwen36_i4_gs64
> /brio merge | request changes | close

# 서버에 JSON 한 방
curl -s http://127.0.0.1:8000/v1/brio -H 'Content-Type: application/json' -d '{
  "model": "qwen36",
  "state": "340 lines, 8 files, no tests.",
  "question": "What should the reviewer do?",
  "options": ["merge", "request changes", "close"]}'

막히는 지점

모델별 디스크·RAM 범위(README 표 요약): OLMoE ~7 GB / RAM 8 GB 안내부터, Kimi K3 ~1.6 TB / 32 GB+까지 폭이 큽니다. “고정 VRAM N GB 필수” 같은 한 줄 숫자는 없고, GPU는 가속 옵션으로만 적혀 있습니다.

마치며

정리하면, colibri는 전문가 가중치를 디스크에서 읽어 오는 pure C MoE 엔진이고, 로컬에서 할 일은 (1) v1.12.0 바이너리 또는 setup.sh 빌드 → (2) 모델 디렉터리 준비 → (3) coli doctor/chat/serve/web 순입니다. 자세한 튜닝·벤치·백엔드는 저장소의 docs/quickstart.md, docs/api.md, docs/tuning.md를 보면 됩니다. 사이트: justvugg.github.io/colibri, 코드: github.com/JustVugg/colibri.

이 글은 AI가 작성하여 자동 발행된 콘텐츠입니다.