colibri

Colibri

Colibri を活用しましょう。Colibri は、エキスパートのディスクストリーミング、MLA アテンション、ネイティブの投機的デコーディング（MTP）を備え、約 25 GB の RAM を搭載したコンシューマー向けマシンで GLM-5.2（744B Mixture-of-Experts）を実行するための、純粋な C 製推論エンジンです。

このスキルを使う場面

• セットアップとビルド：C ビルドツールのインストール、setup.sh の実行、OpenMP の設定、クロスプラットフォームでのコンパイル（Linux、macOS、WSL 経由の Windows）
• モデルのダウンロードと変換：coli convert を実行して GLM-5.2-FP8 のシャードを取得し、int4 コンテナーに変換して、MTP ヘッドを準備（int8 量子化）
• 推論モード：チャットモード（coli chat）の実行、API サーバーのセットアップ、バッチ推論、サンプリングと温度の設定
• エキスパートのキャッシュとストレージ：LRU キャッシュサイズ、pin-hot-store の設定、ディスク I/O の最適化、熱管理の調整
• 投機的デコーディング（MTP）：マルチトークン予測の有効化／無効化、ドラフト受け入れ率の測定、検証レイテンシーの最適化
• GPU アクセラレーション：CUDA ピン留めエキスパートの設定、GPU vRAM の割り当て、CPU と GPU のハイブリッド推論
• パフォーマンスのプロファイリング：トークン／秒の測定、エキスパート読み込みパターンの分析、メモリー常駐の調整
• 統合とデプロイ：Colibri のアプリケーションへの組み込み、推論 API のラッピング、ローカル優先の LLM パイプライン

このスキルを使わない場面

• Python 中心の LLM フレームワーク：高水準の抽象化には llama-index、crewai-multi-agent、または pydantic-ai を使います
• 分散／クラウド推論：マルチ GPU／マルチノードのトレーニングには、クラウド LLM API または deepspeed を使います
• LLM のファインチューニング：トレーニングのワークフローには dspy、openrlhf-training、または moe-training を使います
• 一般的な AI インフラ：関連のない開発環境には system-environment-setup を使います

コアアーキテクチャ

主なコンポーネント：

1. glm.c（約 2,400 行）— MLA アテンション、MTP 投機的デコーディング、DeepSeek-V3 シグモイドルーターを備えた、忠実な GLM-5.2（glm_moe_dsa）のフォワードパス
2. エキスパートストリーミング — 21,504 個のルーティングエキスパート（75 個の MoE レイヤー × 256 個のエキスパート）をディスク上に保存（int4 で合計約 370 GB）。レイヤーごとの LRU キャッシュを使って、必要に応じてストリーミングします
3. ストレージ階層 — 高密度レイヤー（アテンション、共有エキスパート、埋め込み）を RAM に格納（int4 で約 9.9 GB）。エキスパートは NVMe／HDD に格納し、OS のページキャッシュを L2 として使用します
4. MTP 投機的デコーディング — GLM-5.2 のネイティブなマルチトークン予測ヘッド（レイヤー 78、損失なしでドラフト受け入れ率 39～59% を実現する int8）がドラフトを生成し、メインモデルが 1 回のフォワードパスで検証します
5. MLA アテンション — 圧縮 KV キャッシュ（トークンあたり 576 個の浮動小数点数。高密度の場合は 32,768 個で、57 倍小さい）を用いた q/kv-LoRA とインターリーブされた部分 RoPE

CLI モード：

• coli chat — ストリーミング対応の対話型チャット。RAM／キャッシュ／MTP を自動検出
• coli convert — GLM-5.2-FP8 をダウンロードし、int4 に量子化して、MTP int8 ヘッドを準備
• coli plan — 読み込み前にストレージ階層、vRAM の割り当て、エキスパートの配置を確認

主なパラメーター

パラメーター	対象	デフォルト	備考
COLI_MODEL	環境変数	（必須）	変換済み int4 モデルディレクトリーのパス
--ram <GB>	plan/chat	自動検出	高密度レイヤー用の RAM 割り当て（最小 10 GB）
--vram <GB>	plan/chat	0（CPU のみ）	ピン留めエキスパート用の GPU vRAM（CUDA ビルドが必要）
--cache <MB>	plan/chat	自動検出	ルーティングエキスパート用のレイヤーごとの LRU キャッシュサイズ
--mtp on/off	chat	自動検出	投機的デコーディングの有効化／無効化（off = シングルトークンモード）
--temperature <0–2>	chat	0.95	サンプリング温度（0 = 貪欲法）
--top-p <0–1>	chat	0.9	Nucleus サンプリングのしきい値

パフォーマンス指標（コミュニティのベンチマーク）

• トークン/秒（CPU、int4 キャッシュがウォーム状態）：
  • 単一トークン：約1.2 tok/s（キャッシュミスは最小限）
  • MTP 有効時：約2.2～2.8 tok/s（2.2～2.8倍の高速化、ドラフト受け入れ率39～59％）
  • MTP とコールドキャッシュの併用：エキスパートの追加読み込みにより性能が低下する場合があります（トークンあたり約660 → 約1100）
• 常駐容量：高密度レイヤーは約9.9 GBのRAM、エキスパートはディスク上で370 GB
• メモリーオーバーヘッド：ルーティングされたエキスパートによるトークンあたり約11 GB。KVキャッシュは高密度アテンションより57倍小さくなります
• 変換時間：約30～60分（初回のみ。ディスク速度とインターネット接続に依存します）

統合パターン

• ローカルチャットUI：coli chat をターミナルまたはウェブインターフェイスでラップします
• API サーバー：推論出力をHTTP/gRPC経由でストリーミングします
• バッチ処理：モデルを読み込んだ状態を維持しながら、複数のプロンプトを実行します
• CPUとGPUのハイブリッド：よく使うエキスパートをGPU vRAMに固定し、ほかのエキスパートはディスクからストリーミングします
• エッジ／モバイル：int4モデルのサイズ（約370 GB）にはローカルNVMeが必要です。小型デバイスではプルーニングや蒸留を検討してください