Colibri 完全ガイド — 25GB のメモリで 744B パラメータの大規模モデルを動かす

TL;DR：Colibri は革命的な、純 C で書かれた MoE（Mixture of Experts）推論エンジンです。GPU なし、わずか 25GB の RAM で、消費者向けマシン上で GLM-5.2（744B パラメータ）のような超大規模モデルをスムーズに実行できます。「エキスパートのストリーミング読み込み」（expert streaming）という革新的な技術で、VRAM、RAM、ディスクを統一されたメモリ階層として扱い、パフォーマンスとリソースの完璧なバランスを実現しました。

Colibri とは？

Colibri（ハチドリ）は JustVugg が開発したオープンソースプロジェクトです。大規模言語モデル（LLM）デプロイの究極の課題に挑みます。限られたハードウェアリソースで、どう超大規模モデルを動かすか？

従来、744B パラメータのモデルを動かすには数 TB の VRAM と、高価な A100/H100 クラスタが必要でした。Colibri はまったく新しいパラダイムを提示します：

  • Tiny Engine, Immense Model（小さなエンジン、巨大なモデル）：エンジン全体が単一の C ファイル（c/glm.c、約 2400 行）で、外部依存はゼロです（BLAS なし、ランタイムで Python なし）。
  • エキスパートのストリーミング読み込み（Expert Streaming）：モデルの 21,504 個のルーティングエキスパート（それぞれ約 19MB）をすべてメモリに載せるのではなく、必要に応じてディスクからストリーミングし、LRU キャッシュと OS のページキャッシュで最適化します。
  • メモリ階層（Memory Hierarchy）：VRAM（利用可能な場合）、RAM、SSD ディスクを統一された管理可能なメモリプールとして扱い、リソースが制限されても自動的に劣化するだけで、精度や正確性を決して犠牲にしません。

コア技術のハイライト

技術 説明 優位性
MLA アテンション GLM-5.2 ネイティブの MLA（Multi-Layer Attention）アーキテクチャを使用し、圧縮された KV-Cache（576 floats/token 対 32,768）を実現。 KV-Cache を 57 倍削減、メモリを大幅に節約。
DeepSeek-V3 式 Router DeepSeek-V3 と同じ sigmoid router を採用。共有エキスパートと上位 3 層の dense 層をサポート。 より正確なエキスパートルーティングでモデル効果を向上。
MTP 推測デコード GLM-5.2 固有のマルチトークン予測（MTP）ヘッドを活用した推測デコード。実測で 39〜59% の受理率、平均 2.2〜2.8 tokens/forward。 生成速度を大幅に向上。
Grammar-Forced Speculation GBNF 構文強制をサポート。JSON や関数呼び出しなどの構造化出力シーンで、ほぼ 100% の推測受理率を実現。 特定のタスクで究極の効率を実現。
整数ドット積カーネル int8 とパック int4 の整数行列乗算カーネル（AVX2 maddubs）を実装。浮動小数点演算より 1.4〜2.5 倍高速。 CPU の計算能力を最大限に活用し、推論を加速。
DSA スパースアテンション GLM-5.2 の DSA（Dynamic Sparse Attention）インデクサーを完全実装。各層で Top-2048 の因果キーのみを選択。 モデル効果を維持しつつ、計算量を大幅に削減。

クイックスタート：3 ステップでデプロイ

1. 環境準備

Colibri の環境要件は極めて低いのです。モダンな Linux/macOS システムと GCC コンパイラがあれば十分です。

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

# macOS (Homebrew)
brew install gcc git

2. ダウンロードとコンパイル

BASH 
# リポジトリをクローン
git clone https://github.com/JustVugg/colibri
cd colibri

# コンパイル（デフォルトは CPU 版）
make

# または、NVIDIA GPU があり CUDA アクセラレーションを有効にしたい場合（オプション）
# make COLI_CUDA=1

3. モデルを実行

BASH 
# インタラクティブチャットを起動
./coli chat

# または、バッチ推論を実行
./coli batch --prompt "请用中文写一首关于春天的诗。"

💡 ヒント：初回実行にはモデルウェイトのダウンロード（約 370GB）が必要です。事前に準備しておきましょう。以降の実行は非常に高速になります。

4. モデルウェイトのダウンロード

Colibri は事前変換済みの int4 量子化モデルを使用します。Hugging Face から直接ダウンロードできます：

BASH 
# 推奨バージョン（int8 MTP ヘッド、推測デコード対応）
# https://huggingface.co/mateogrgic/GLM-5.2-colibri-int4-with-int8-mtp

# huggingface-cli でダウンロード
pip install huggingface_hub
huggingface-cli download mateogrgic/GLM-5.2-colibri-int4-with-int8-mtp \
  --local-dir ./glm52-int4

⚠️ 重要警告：MTP ヘッドは int8 バージョン必須！

コミュニティで最も多い「MTP 受理率が 0% になるのはなぜ？」という問題の原因は、間違ったモデルバージョンをダウンロードしてしまうことです。オリジナルバージョン（jlnsrk/GLM-5.2-colibri-int4）の MTP ヘッドは int4 量子化されており、推測デコードが完全に機能しなくなり（0% 受理率）、約 2 倍のパフォーマンス向上が失われます。

検証方法：out-mtp-* ファイルのサイズを確認 - int8（正解）：3527131672 / 5366238584 / 1065950496 - int4（不正解）：1765523544 / 2686077736 / 536747200

詳細解説：Colibri はどう動いているのか？

Colibri の魔法は、精巧なメモリ管理とアルゴリズム設計にあります。コアとなるワークフローを分解してみましょう：

  1. 起動と初期化：エンジン起動時、システムの MemAvailable に基づいてエキスパートキャッシュのサイズを自動計算・設定し、OOM Killer がトリガーされないようにします。
  2. エキスパートの読み込み：モデルが特定のエキスパートを必要とするとき、エンジンはディスクからそのエキスパートのウェイトを読み込みます。I/O 待ちを減らすため、WILLNEED システムコールを使って非同期プリフェッチ（async expert readahead）を行います。
  3. 計算実行：読み込まれたエキスパートウェイトは、高度に最適化された整数ドット積カーネルに送られて計算されます。単一トークンのデコードには f32 計算を使用し、バッチ prefill ではより高速な int4 カーネルを使用します。
  4. KV-Cache の永続化：对话の KV-Cache は圧縮され、.coli_kv ファイルに永続化されます。つまり、プログラムを閉じて再度開いても、对话のコンテキストは「温かい」まま残り、履歴を再計算する必要がありません。

この設計により、Colibri はリソースが制限されたとき、パフォーマンスが滑らかに低下するだけで、クラッシュしたり誤った結果を生じたりすることはありません。

KV-Cache 永続化：对话を失わない

Colibri のキラー機能のひとつが KV-Cache 永続化です。每次对话後、圧縮された MLA KV-Cache が .coli_kv ファイルに追記されます（約 182 KB/トークン、クラッシュセーフ）。次回起動時に自動復元され、過去のコンテキストを prefill し直す必要がありません。

BASH 
# KV-Cache 永続化はデフォルトで有効
./coli chat

# 無効にする場合
KVSAVE=0 ./coli chat

Router-Lookahead プリフェッチ（実験的）

Colibri は巧妙な最適化を実装しています。次層のエキスパートルーティングは 71.6% の予測可能性を持っています（現在の層の post-attention 状態に基づく）。PILOT=1 で有効にすると、専用の I/O スレッドが現在の層の計算中に次層に必要なエキスパートをプリフェッチします。

BASH 
# ルーター先読みプリフェッチを有効化
PILOT=1 ./coli chat

設定パラメータクイックリファレンス

環境変数 デフォルト値 説明
DRAFT 1 MTP 推測デコードのスイッチ（0=無効）
DSA 1 DSA スパースアテンションのスイッチ（0=無効、dense アテンションを使用）
DSA_TOPK 2048 DSA が各層で選択する Top-K 因果キーの数
PILOT 0 Router-lookahead プリフェッチのスイッチ
KVSAVE 1 KV-Cache 永続化のスイッチ
IDOT 1 整数ドット積カーネルのスイッチ
COLI_CUDA 0 CUDA アクセラレーションのスイッチ（コンパイル時に有効化が必要）
GRAMMAR - GBNF 構文ファイルのパス（構造化出力用）
GRAMMAR_DRAFT 24 1 回の forward における構文強制の最大スパン

パフォーマンスベンチマーク：実世界のデータ

公式の WSL2 環境（12 コア、25GB RAM、NVMe）でのテスト結果：

  • コールドスタート時間：約 32 秒（モデルの読み込み、キャッシュの初期化）。
  • メモリ使用量：常駐メモリ約 9.9 GB（int4 dense 部分）。
  • ピークディスク使用量：約 370 GB（すべてのエキスパートウェイト）。
  • 生成速度：MTP 推測デコードを有効にし、キャッシュウォームアップ後、2.2〜2.8 tokens/forward に到達。

📊 比較：これはハイエンド GPU で 7B パラメータモデルを動かす速度に匹敵します。一方、Colibri が動かしているのは 100 倍規模の 744B モデルなのです！

GPU アクセラレーション実測：6x RTX 5090

公式の 2026-07-12 の実験レポートによると、6 枚の RTX 5090 で全エキスパートを VRAM+RAM に常駐させた場合、単一リクエストのデコード速度は 6.84 tok/s に到達しました。Colibri の弾力的なアーキテクチャが証明されました — 純 CPU からマルチ GPU まで、同じコードベースがシームレスにスケールします。

コールドスタート vs ホットキャッシュ

シナリオ ディスク読み込み/トークン 説明
コールドキャッシュ ~11 GB（75 層 × 8 エキスパート） 初回推論、すべてのエキスパートをディスクから読み込む必要あり
ホットキャッシュ 大幅に減少 よく使うエキスパートが RAM にキャッシュ済み
全 GPU 常駐 ~0 すべてのエキスパートが VRAM にあり、ディスク I/O なし

💡 SSD の注意事項：Colibri のストリーミング読み込みは読み取り専用操作なので、SSD を大幅に摩耗させることはありません。本当に注意すべき点は：(1) システムメモリ不足時の swap トラフィック（書き込み操作が SSD を摩耗させる）；(2) 長時間の高負荷読み取りによる SSD 温度上昇。Colibri の自動メモリバジェット機能は swap を自動的に回避します。

他の推論エンジンとの比較

機能 Colibri llama.cpp Ollama
言語 純 C（約 2400 行） C/C++ Go + llama.cpp
対象モデル GLM-5.2（744B MoE） 汎用（LLaMA シリーズ中心） 汎用
GPU 要件 なし（CUDA オプション） 推奨 推奨
メモリ要件 25GB RAM モデルサイズによる モデルサイズによる
エキスパートストリーミング読み込み ✅ コア機能 ❌ ❌
KV-Cache 永続化 ✅ ❌ ❌
MTP 推測デコード ✅ ネイティブサポート 一部モデル 一部モデル
DSA スパースアテンション ✅ ❌ ❌
外部依存 ゼロ BLAS など 多数

🔍 ポジショニングの違い：Colibri は llama.cpp の代替品ではなく、特定のシナリオ向けの専用ソリューションです。消費者向けハードウェアで超大規模 MoE モデルを動かす必要があるなら、Colibri は現在唯一の実行可能な選択肢です。

実践シナリオ

シナリオ 1：ローカル AI アシスタント（純 CPU）

GPU がない開発者向け。ノートパソコンやデスクトップで強力なローカル AI アシスタントを動かします：

BASH 
# インタラクティブ对话を起動
./coli chat

# 構文制約付きの JSON 出力
./coli chat --grammar schemas/response.gbnf

シナリオ 2：構造化データ抽出

Grammar-Forced Speculation 機能を活用し、JSON/関数呼び出しのシナリオで究極のパフォーマンスを得ます：

BASH 
# 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

# 構文制約付きの推論を実行
GRAMMAR=schema.gbnf ./coli batch \
  --prompt "从以下文本提取信息：张三，28岁，软件工程师"

シナリオ 3：マルチ GPU クラスタ推論

GPU リソースを持つユーザー向けに、Colibri はハイブリッドデプロイをサポートしています：

BASH 
# CUDA 版をコンパイル
make COLI_CUDA=1

# 実行（人気のエキスパートを自動的に GPU VRAM にピン留め）
COLI_CUDA=1 ./coli chat

よくある質問 FAQ

Q: マシンの RAM が 16GB しかないけど動きますか？ A: 動きますが、体験は制限されます。Colibri の最低要件は dense 部分（約 9.9GB int4）を収容できることで、KV-Cache とワークバッファを加えると、16GB でも実行は可能ですが、エキスパートキャッシュのスペースが小さくなり、コールドスタートがより頻繁に発生します。

Q: どれくらいの容量の SSD が必要ですか？ A: モデルウェイトは約 370GB（int4 量子化）、KV-Cache と一時ファイルを含めて、少なくとも 500GB の空き容量を推奨します。NVMe SSD を強く推奨しますが、SATA SSD でも動作します（速度は落ちます）。

Q: Windows はサポートされていますか？ A: WSL2（Windows Subsystem for Linux）を公式サポートしています。ネイティブ Windows コンパイルは現時点では提供されていませんが、C コードは理論上 MSVC/MinGW でコンパイル可能です。

Q: llama.cpp の GGUF フォーマットと互換性はありますか？ A: 互換性はありません。Colibri は独自の int4 コンテナフォーマットを使用しており、MoE エキスパートのストリーミング読み込みに最適化されています。公式提供の FP8→int4 変換ツールを使用する必要があります。

まとめ：AI 民主化のマイルストーン

Colibri は単なる技術のおもちゃではありません。AI 発展の重要な方向性を示しています。脱中央集権化と民主化です。最先端の AI 能力が、もはや少数のテックジャイアントや高価なハードウェアに独占されていないことを証明しました。一般的な開発者でも、ノートパソコン 1 台で、最先端の大規模モデル技術を探索し、応用できるのです。

Colibri の成功は、エンジニアリングの美学とアルゴリズムの知恵の完璧な融合です。「より大きく」を追求するのではなく、「より巧みに」を追求しました。真のイノベーションは、リソースへの畏敬と効率への極限の追求の中から生まれるのだと教えてくれます。

参考リンク

本記事は Colibri v1.0（2026-07-01）に基づいて執筆されました。Apache License 2.0 ライセンス。