JustVugg/colibri

<img src="https://raw.githubusercontent.com/JustVugg/colibri/HEAD/assets/colibri-logo.svg" width="560" alt="colibrì: 작은 엔진, 거대한 모델"> <a href="https://justvugg.github.io/colibri"><img src="https://img.shields.io/badge/website-justvugg.github.io%2Fcolibri-1f6feb" alt="웹사이트"></a> <a href="https://github.com/JustVugg/colibri/releases"><img src="https://img.shields.io/github/v/release/JustVugg/colibri?color=2ea043" alt="최신 릴리스"></a> <a href="https://justvugg.github.io/colibri">웹사이트</a> · <a href="https://discord.gg/RXV83nSZdk">디스코드</a> · English · <a href="README.zh-CN.md">간체 중국어</a> · <a href="README.zh-TW.md">번체 중국어</a> · <a href="README.it.md">이탈리아어</a> · <a href="README.ja.md">일본어</a> · <a href="README.id.md">인도네시아어</a> · <a href="README.pt-BR.md">포르투갈어 (브라질)</a>

작은 엔진, 거대한 모델. colibri는 사용자가 이미 가지고 있는 기기에서 매우 큰 오픈 모델(open models)을 실행합니다. 수천억 개의 파라미터를 가진 Mixture-of-Experts (MoE) 모델은 각 토큰에 대해 자신만의 작은 부분만을 사용합니다. 따라서 colibri는 그 부분을 RAM에 유지하고, 모델이 요청할 때 나머지 전문가(experts) 부분은 디스크에서 읽어옵니다. 순수 C 언어로 작성되었으며, 모델 패밀리별로 하나의 파일만 필요하며, GPU가 요구되지 않습니다.

오늘날 13개의 엔진이 작동합니다. 그중 10개는 언어 모델(language models)을 위한 것입니다: GLM-5.2/5.3 (여기서는 Mistral-Large-4도 실행), GLM-5.3-Flash, Inkling, Kimi K3, DeepSeek V4 Flash, DeepSeek V4.1 Flash, MiMo-V2.6 Flash (및 Pro), Qwen3.8-Flash-Next, Qwen3.6 (여기서는 Qwen3-Coder, Dense Qwen3.8-27B도 실행), Flint, Muse Spark Open, LFM3-VL) 및 OLMoE. 그림을 그리는 엔진은 하나입니다: Qwen-Image-2.1. 결정에 답하는 엔진은 두 개이며, Laya와 GLiNER2.5-Decide가 있으며, 세 번째 의사 결정 모델인 Clef는 Qwen3.6 엔진에서 작동합니다. 또한 언어 모델들은 이미 공개된 GGUF 파일로부터 실행할 수 있습니다. 이는 원래의 형식(GGUF)으로 읽히며, CPU에서, Vulkan을 통해 모든 GPU에서, 그리고 CUDA를 통해 NVIDIA 카드에서 실행됩니다. 내 기기에 적합한 것은?

$ ./coli chat
  colibri v2.1.0 · GLM-5.2 · 744B MoE · int4 · streaming CPU
  ✓ ready in 32s · resident 9.9 GB
...

<a href="https://www.buymeacoffee.com/justvugg"><img src="https://img.buymeacoffee.com/button-api/?text=Buy%20me%20a%20coffee&emoji=&slug=justvugg&button_colour=FFDD00&font_colour=000000&font_family=Poppins&outline_colour=000000&coffee_colour=ffffff" alt="Buy me a coffee" height="40"></a> colibri는 무료 오픈 소스입니다. 만약 colibri가 당신의 기기에 자리를 잡았다면, 커피 한 잔이 다음 엔진과 다음 속도 향상을 위한 비용을 지불하는 데 도움이 됩니다.

단 하나의 단계로 시작하기

최소한 8 GB의 RAM을 갖춘 컴퓨터(16 GB 이상 권장), 가장 작은 모델에 필요한 디스크 공간으로 22 GB의 여유 공간, 그리고 인터넷 연결이 필요합니다. 그래픽 카드는 선택 사항입니다.

Windows

이 페이지에서 Code를 클릭한 다음, Download ZIP을 다운로드하고 압축을 해제합니다.
압축 해제된 폴더에서 **START-HERE.bat**을 더블클릭합니다. Python이 누락된 경우, 설치할지 여부를 묻습니다.

Linux (Ubuntu 및 Debian; 다른 배포판은 자체 이름으로 동일한 패키지를 가지고 있습니다)

sudo apt install git python3 build-essential
git clone https://github.com/JustVugg/colibri
cd colibri
...

macOS (with Homebrew)

xcode-select --install
brew install libomp git python
git clone https://github.com/JustVugg/colibri
...

질문 하나(어떤 모델인지)에 답하면, Enter를 누르는 것이 추천을 받습니다. 그런 다음 설정 과정은 다음과 같습니다:

사용자 기기 확인: RAM, 여유 디스크 공간, CPU 및 GPU를 살펴봅니다.
적합한 모델 추천: 항상 RAM에 머무는 모델 부분과 최소 전문가 캐시(experts)가 사용자 RAM 및 디스크 다운로드 공간에 맞는지 확인하여 적합한 모델을 추천합니다.
엔진 확보: 컴파일러가 있는 경우 사용자 기기에 맞게 빌드하고, 그렇지 않으면 미리 빌드된 버전을 다운로드합니다. 이 버전은 CPU에서 실행되며, Linux 및 Windows에서는 Vulkan GPU에서도 실행됩니다. CUDA 툴킷이 설치된 Linux의 NVIDIA 카드인 경우 GPU용으로 빌드하며, 그렇지 않은 경우에는 Vulkan을 사용합니다. 외장 GPU(discrete GPU)의 경우 항상 빌드를 수행합니다. CPU의 RAM을 공유하는 내장 GPU(integrated GPU)의 경우, 해당 환경에서 더 빠르게 측정되는 모델(Qwen3.6, Qwen3-Coder 및 Qwen3.8-Flash-Next)에 대해서만 적용됩니다. 패키지가 누락된 경우 정확한 설치 명령어를 출력하고 CPU로 계속 진행합니다. 나중에 설정을 다시 실행하면 GPU용으로 재빌드됩니다.
진행률 및 재개 기능이 있는 모델 다운로드: 원할 때 중지하고 다시 실행하면 중단된 지점부터 계속 진행됩니다.
colibri 시작 및 대시보드 열기: 브라우저에서 colibri를 시작하고 대시보드를 열며, 다른 앱들이 사용할 수 있는 주소들을 출력합니다:

Starting colibri
  Browser:             http://127.0.0.1:8000/
  OpenAI base URL:     http://127.0.0.1:8000/v1
...

다음에 다시 실행할 때는 START-HERE.bat 또는 ./start-here.sh를 실행합니다: colibri가 다운로드나 빌드 과정 없이 즉시 시작됩니다. c/coli status는 무엇이 설치되었고 작동하는지 보여주며, c/coli stop으로 중지할 수 있습니다 (Windows에서는 c\coli.cmd status 및 c\coli.cmd stop).

옵션은 ./start-here.sh 또는 START-HERE.bat 뒤에 붙입니다:

옵션	기능
`--list`	이 머신에 적합한 모든 모델과 왜 특정 모델이 적합하지 않은지 보여줍니다.
...
각 단계가 무엇을 하는지 자세히 알아보기: docs/quickstart.md.

문제가 발생했을 경우

확인 사항	조치 방법
다운로드 중 중단됨	동일한 명령을 다시 실행합니다: 이미 디스크에 있는 바이트부터 재개됩니다.
...

AI 어시스턴트에게 설정하도록 맡기기

AI 코딩 어시스턴트를 사용하면 이 모든 것을 대신 처리할 수 있습니다. 다음과 같이 요청하세요:

https://github.com/JustVugg/colibri의 docs/AI_SETUP.md에 따라 이 머신에 colibri를 설정해 줘.

docs/AI_SETUP.md는 어시스턴트에게 모든 단계를 기계가 읽을 수 있는 결과와 함께 명령으로 제공하며, 모델을 다운로드하거나 시스템 패키지를 설치하기 전에 사용자에게 물어보도록 지시합니다. Model Context Protocol(MCP)을 지원하는 어시스턴트는 대신 colibri의 MCP 서버를 사용할 수 있습니다: coli mcp는 하드웨어를 감지하고, 모델을 추천하며, 설치하고, 시작하고, 중지하고, 확인하는 도구를 제공합니다(docs/MCP_SERVER.md).

또는 수동으로

각 단계를 직접 선택하려면 (사전 빌드 릴리스 또는 소스 빌드, 아래 표의 모든 모델, 그리고 coli chat, coli web 또는 coli serve), 수동 설치를 참조하거나, 모든 플랫폼에 대한 단계별 과정은 빠른 시작 가이드를 참고하세요.

colibri란 무엇이며 왜 필요한가

전문가 혼합 모델(Mixture-of-experts, MoE)은 디스크 용량은 크지만 토큰당 사용량이 적습니다. GLM-5.2는 744B개의 파라미터를 가지고 있으며, 각 토큰에 약 40B를 사용하고, 그중 오직 라우팅된 전문가(routed experts)만이 토큰마다 약 11 GB만 변경됩니다.

따라서 모델은 빠른 메모리에 '맞춰지는' 것이 아니라 '배치되어야' 합니다. 밀집 부분(어텐션, 공유 전문가, 임베딩)은 RAM에 유지됩니다. 라우팅된 전문가들은 디스크에 보관되며, 라우터가 요청할 때 해당 작업이 어떤 전문가를 사용하는지 학습하는 캐시를 통해 읽힙니다. GPU가 있는 경우, 가장 활발하게 사용되는(hottest) 전문가들과 밀집 레이어들이 GPU에 로드됩니다. 가중치가 어디에 위치하느냐가 답변 속도를 결정하며, 어떤 가중치나 라우터 결정이 그 답변을 생성하는지를 결정하지는 않습니다.

왜냐하면: 사람들이 이미 소유한 하드웨어에서 이 크기의 모델을 실행하고, 작동 과정을 관찰할 수 있게 하며(대시보드는 전문가가 활성화될 때마다 표시합니다), 엔진 자체를 충분히 작게 유지하여 누구나 측정하고 더 빠르게 만들 수 있도록 하기 위함입니다. colibri는 또한 오픈 리서치 플랫폼이기도 합니다: 최적화는 재현 가능한 엔드투엔드 측정으로 그 자리를 얻으며, 기본 정책은 모델의 정밀도나 라우터 의미론을 조용히 변경하지 않습니다. 빠른 메모리가 부족하면 속도가 떨어질 수 있지만, 모델 자체를 은밀하게 재정의해서는 안 됩니다. 작동 방식에서 자세한 내용을 확인할 수 있습니다.

내 기기에 적합한 모델 선택

이 설정은 사용자의 장치에서 RAM으로 실행할 수 있는 가장 성능 좋은 모델을 추천하며, 그 바로 아래에 디스크에서 스트리밍되는 더 큰 모델들을 나열합니다. ./start-here.sh --list를 사용하면 모든 모델을 사용자 기기와 비교하여 볼 수 있습니다. 표들은 설정 자체의 카탈로그(c/setup_catalog.py)를 따르며, 다운로드 크기는 Hugging Face가 각 리포지토리에 나열한 크기입니다.

RAM은 두 개의 숫자로 구성됩니다: 첫 번째 숫자 이하에서는 모델이 시작되지 않으며, 두 번째 숫자부터는 측정된 속도로 실행됩니다.
GPU는 해당 엔진에 대해 설정이 구축할 수 있는 사양(GPUs)입니다. Integrated too는 통합 GPU도 사용한다는 의미이며, 이 경우 다른 엔진들보다 더 빠르게 측정되었습니다. 나머지 모델들은 전용(discrete) GPU만 사용합니다.
**측정값(Measured)**은 명시된 장치에서 채팅 모델의 디코드 속도를 측정한 값입니다. 알파벳은 표 아래에 나열된 기기들을 나타냅니다. 빈칸은 아직 아무도 측정하지 않았다는 의미입니다.

RAM에서 실행되는 소형 모델

Model	--model	Download	RAM	GPU	Measured
Qwen3.6-35B-A3B: chat with thinking and tools	`qwen36-35b`	23 GB	10 / 20 GB	CUDA, Vulkan (integrated too)	6.0 tok/s on the CPU, 9.9 with Vulkan on the integrated GPU (A); 30.0 with CUDA (C)
...
전문가(experts)를 디스크에서 스트리밍하는 대규모 모델 (속도는 디스크에 의해 결정됨: 빠른 NVMe 드라이브가 가장 도움이 됩니다)

Model	--model	Download	RAM	GPU
DeepSeek V4 Flash REAP 150B: 256개 전문가 중 132개 활성	`deepseek-v4-flash-reap`	85 GB	16 / 32 GB	CUDA, Vulkan
...
<a id="other-supported-models"></a>

수동 방식: 다운로드 후 변환 또는 준비 단계

Model	Download, then on disk	RAM	GPU	Measured
OLMoE (7B): 도구 학습용 소형 모델	14 GB, int8로 변환 후 7 GB	8 GB	Vulkan	22-23 tok/s (A, CPU)
...
<a id="from-a-gguf"></a>

GGUF 파일로부터: 그대로 읽는 공개된 파일

./coli import는 GGUF의 첫 번째 파일을 가져와(그 옆에 있는 다른 부분들 포함) 그 옆에 모델 디렉터리를 작성하고; --model은 이 디렉터리, 다른 모든 것과 마찬가지로 사용합니다(gguf.md). 어떠한 변환이나 양자화도 다시 수행되지 않습니다: 블록들은 파일이 가지고 있는 대로, IQ1_S부터 Q8_0, F16, BF16 및 MXFP4까지 실행됩니다. 위의 모든 채팅 모델 엔진들도 GGUF를 읽을 수 있습니다(the architectures); 이 네 가지 모델은 GGUF 형태로 제공됩니다:

Model	GGUF	GPU	Measured
Mistral-Large-4 (1T, 52B 활성): 텍스트, 이미지, 추론 및 도구 지원	unsloth, UD-IQ1_S 233 GB	CUDA, Vulkan	CUDA 사용 시 1.34-1.36 tok/s, Vulkan 사용 시 1.16-1.17 tok/s (D)
...
위 표의 대규모 모델들을 동일한 장치에서 GGUF로 실행할 경우: 벤치마크.

의사 결정 모델(Decision models): 질문에 답변하며(System One 시스템을 사용), 채팅은 하지 않습니다.

모델	다운로드 후 디스크 저장 용량	RAM	GPU	측정 결과
Laya (Convai Innovations), 영어	0.85 GB	1.7 GB	CPU, CUDA	질문 하나당 219 ms, 세 개당 882 ms (B); CUDA 사용 시 0.69초에 열두 개, CPU 사용 시 11.4-13.0 s (D)
...

벤치마크 장비:
A Ryzen 7 PRO 8700GE 데스크톱 (코어 8개, DDR5 메모리 61-64 GB, NVMe, 통합 Radeon 780M);
B i7-1355U 노트북;
C Threadripper 3945WX 케이스에 장착된 RTX 3070 8 GB로, 카드 상의 밀집 레이어(dense layers)와 DeltaNet 레이어를 포함하며 (행별 int4 컨테이너);
D i5-13500과 62 GB RAM, RTX PRO 4000 Blackwell SFF (24 GB), 그리고 md 어레이에 있는 두 개의 NVMe 드라이브로 구성된 장비: 벤치마크 테이블의 장비입니다.
각 수치는 해당 모델의 docs/ 페이지 또는 벤치마크 테이블에서 정확한 설정을 기반으로 가져온 것입니다.

각 패밀리는 다음 페이지를 가지고 있습니다: qwen36.md (Qwen3.6, Qwen3-Coder, Qwen3.8-27B, Flint, Muse Spark Open, LFM3-VL), mistral-large4.md, gguf.md, qwen38.md, deepseek-v4.md, deepseek-v41.md, mimo.md,
glm53-flash.md, inkling.md, kimi_k3.md, qwen-image.md,
laya.md, gliner_decide.md, clef.md 및 Quick Start의 GLM-5.2입니다.
지원되는 아키텍처와 동일한 체크포인트(예: Qwen3.6 엔진의 KAT-Coder v2.5)는 변경 없이 실행됩니다.

JustVugg/colibri

요약

핵심 포인트

단 하나의 단계로 시작하기

문제가 발생했을 경우

AI 어시스턴트에게 설정하도록 맡기기

또는 수동으로

colibri란 무엇이며 왜 필요한가

내 기기에 적합한 모델 선택

GPU

GPU 불필요

댓글

단 하나의 단계로 시작하기

문제가 발생했을 경우

AI 어시스턴트에게 설정하도록 맡기기

또는 수동으로

colibri란 무엇이며 왜 필요한가

내 기기에 적합한 모델 선택

GPU

GPU 불필요