1-bit量子化で27B VLMをローカル実行する「Bonsai-demo」の仕組み

「27B クラスの LLM を自分のマシンで動かしたい」「iPhone や MacBook で試したい」——生成 AI の実装検討をしていると、必ずこの壁にぶつかります。VRAM は足りず、モデル本体は数十 GiB、推論エンジンや UI・ツール連携は別々のリポジトリを継ぎ足す必要があります。

そこで注目されているのが、モデルの重みを 1-bit や 3 値（ternary）まで極限圧縮する量子化技術です。ただし、実務では「モデル本体」「推論エンジン」「UI」「ツール連携」がバラバラで、環境構築のコストが依然として高く、採用可否の判断材料も揃いにくいのが実情です。

こうした課題に対して PrismML が公開しているのが Bonsai-demo です。1-bit / Ternary 量子化 LLM である Bonsai 一族（27B / 8B / 4B / 1.7B）を、Mac・Linux・Windows でワンコマンド起動できる公式デモリポジトリで、モデルダウンロード・フォーク版 llama.cpp / MLX バイナリのセットアップ・Open WebUI までを一括で構築します。

本記事では、初見のエンジニアが自プロジェクトへの採用可否を判断できるよう、Bonsai-demo の位置づけ、対応モデルの選び方、実行アーキテクチャの仕組み、類似 OSS との違い、採用判断のポイントを、公式ドキュメントと GitHub 上の情報のみを根拠に整理します。

Bonsai-demo とは — PrismML が公開する Bonsai 実行用デモリポジトリ

リポジトリの位置づけ

Bonsai-demo は、量子化 LLM「Bonsai」および「Ternary-Bonsai」をローカル環境で実行するための PrismML 公式デモリポジトリです。モデルの重み自体は Hugging Face 上の prism-ml 組織に置かれており、本リポジトリはそれらをダウンロードして推論バイナリ・UI・ツール群を組み合わせて起動する「配布ラッパー」として機能します（GitHub: PrismML-Eng/Bonsai-demo）。

具体的には次の 3 レイヤーが単一リポジトリ内で完結します。

• モデル: Hugging Face の Bonsai / Ternary-Bonsai 各 GGUF・MLX リポジトリを自動ダウンロード
• 推論エンジン: PrismML フォーク版の llama.cpp バイナリ（GitHub Release 経由）と、macOS 向け MLX ソースビルド
• UI・ツール連携: Open WebUI、コードインタプリタ用 Python venv、MCP プリセット（Hugging Face / DeepWiki）

基本情報

執筆時点でのリポジトリメタデータは以下のとおりです（gh api /repos/PrismML-Eng/Bonsai-demo から取得。以下の数値は 2026-08-09 時点）。

archived=false かつ fork=false であり、直近 push も執筆時点の 4 日前と、アクティブなオリジナルリポジトリです。ライセンスも商用利用可能な Apache-2.0 であるため、社内 PoC・製品組み込みの検討に載せる際のライセンス上の障壁は小さいと言えます。

開発元 PrismML の背景

開発元の PrismML は、Caltech 発の研究成果を基盤に「Ultra dense intelligence（超高密度知能）」を掲げる企業です（PrismML 公式サイト）。「Large models can't fit on smartphones. Datacenters can't sustain them.」という問題意識のもと、"intelligence per bit"（1 ビットあたりの知能）を追求し、その最初の成果として 2026 年 7 月 14 日に Bonsai 27B を発表しました。

対応モデル — Bonsai（1-bit）と Ternary-Bonsai の 2 ファミリー

2 ファミリー × 4 サイズのラインアップ

Bonsai-demo から起動できるモデルは、2 ファミリー × 4 サイズの合計 8 種です。27B のみビジョン言語モデル（VLM）で、8B 以下はテキスト専用となります。

環境変数 BONSAI_FAMILY と BONSAI_MODEL を切り替えるだけで、いずれの組み合わせも同じコマンドで起動できます。既定では Ternary-Bonsai-27B がダウンロード対象となります。

各モデルの Hugging Face リポジトリは Bonsai 27B HF Collection にまとまっており、モデル選定時はここから重み・トークナイザ・mmproj（VLM 用画像投影モデル）を参照できます。

圧縮率 — FP16 の 47.73 GiB を最小 3.53 GiB まで

Bonsai-demo の中核的な差別化ポイントは、量子化による圧縮率です。27B モデルの GGUF 重みは、フル精度 FP16 と比較して次のように圧縮されます（公式ドキュメント: Bonsai 27B の公表値）。

1-bit 27B は約 3.9 GB でモバイル端末クラスのメモリに収まる規模、Ternary 27B は約 5.9 GB でラップトップに収まる規模とされます（PrismML news: Bonsai 27B）。

性能維持率と推論速度（公式公表値）

品質面では、フル精度 Qwen3.6 27B の平均性能を Ternary-Bonsai-27B が約 95%、1-bit Bonsai-27B が約 90% 保持したと公表されています（15 ベンチマーク・thinking モード評価）。数学・コーディングはほぼ精度低下がなく、ビジョンは圧縮アーチファクトが目立つことが公式に明記されています（PrismML news: Bonsai 27B）。

推論速度の公式公表値は以下のとおりです（第三者計測ではなく、あくまで開発元による代表ハードウェア上の公表値）。

なお、これらの数値は特定条件下での上限値であり、実運用ではコンテキスト長・並列度・KV cache 設定などによって変動します。導入前には自環境で ./scripts/run_llama.sh -p "..." を用いた計測を推奨します（コマンドは README 記載のもの）。

実行の仕組み — llama.cpp と MLX のマルチバックエンド構成

setup.sh / setup.ps1 — 8 ステップを冪等に実行

Bonsai-demo の起動フローは、README の Quick Start に従って 1 コマンドで完結します。macOS / Linux の場合は次のとおりです（出典: Bonsai-demo README「Quick Start」）。

git clone https://github.com/PrismML-Eng/Bonsai-demo.git
cd Bonsai-demo

# (Optional) Choose a model size: 27B (default), 8B, 4B, or 1.7B
export BONSAI_MODEL=27B

# Set your HuggingFace token (only required for 27B while its repos are private)
export BONSAI_TOKEN="hf_your_token_here"

# One command does everything: installs deps, downloads models + binaries
./setup.sh

setup.sh（Windows は setup.ps1）は次の 8 ステップを順に実行します。各ステップは冪等で、完了済みステップは自動的にスキップされます。

1. システム依存確認・導入（macOS では Xcode Command Line Tools、Linux では build-essential）
2. Python パッケージマネージャ uv の導入
3. Python 仮想環境の作成と uv sync
4. Hugging Face からモデルダウンロード（27B は private 期間中に BONSAI_TOKEN が必要）
5. GitHub Release から PrismML-Eng/llama.cpp の pre-built バイナリを取得（またはソースビルド）
6. MLX のソースビルド（macOS のみ）
7. Open WebUI の導入
8. コードインタプリタ用の Python venv（.venv-jupyter）構築

セットアップ完了後は、./scripts/start_llama_server.sh で llama.cpp サーバー（http://localhost:8080）、./scripts/start_openwebui.sh で Open WebUI（http://localhost:9090）を起動できます（Bonsai-demo README）。

llama.cpp 本流との関係 — Q1_0 はマージ済み、Q2_0 は移行中

Bonsai-demo が同梱する推論エンジンは、ggml-org/llama.cpp 本流の PrismML フォーク（PrismML-Eng/llama.cpp）です。ただし量子化フォーマットの上流マージは進行中で、状況は以下のようになっています（出典: Bonsai-demo README「Upstream Status for Binary」「Upstream Status for Ternary」）。

MLX 1-bit は上流 PR（ml-explore/mlx#3161）のマージ待ちで、当面は PrismML-Eng/mlx の prism ブランチを setup.sh が自動ビルドします。

GGUF ファイルの 3 バリアント — 実行環境ごとに使い分ける

Ternary（Q2_0）については、上流移行の過渡期にあるため 3 種類の GGUF ファイルが Hugging Face 上に併存しています。実行環境に応じて正しいファイルを選ぶ必要があります。

Bonsai-demo のスクリプトから起動する場合は自動的に *-Q2_0.gguf（group 128）が選択されるため、通常はこの選択を意識する必要はありません。本流の llama.cpp と組み合わせて使う場合のみ、*-Q2_0_g64.gguf を明示的に選ぶ必要があります。

対応プラットフォーム

Bonsai-demo は次のプラットフォーム・バックエンドをカバーします（README「Bonsai Demo」冒頭記載）。

主要機能 — Vision / Thinking / Tool calling / 長コンテキスト

Vision 入力 — 画像・スクリーンショット・PDF

Bonsai 27B は VLM のため、OpenAI 互換 API の image_url パーツで画像・スクリーンショット・PDF を送信できます。Open WebUI からのファイルアップロードにも対応し、大サイズ画像は自動でダウンスケールされます。mmproj（画像投影モデル）は同一 HF リポジトリから自動取得されます（VISION.md）。

Thinking — 5 段階の動的推論深度

Bonsai 27B は reasoning model として動作し、chat ごと・request ごとに推論深度（reasoning effort）を選択できます。API では thinking_budget_tokens パラメータで制御します。

浅い問い合わせでは低モードを、複雑な多段推論には高モードを選ぶことで、レイテンシとコストの調整が可能です。

Tool calling & MCP — プロンプトハック不要

Bonsai 27B は OpenAI 互換の tools 配列を受け取り、ネイティブに tool_calls レスポンスを返します。プロンプトへの JSON 命令埋め込みなど、いわゆる「プロンプトハック」なしで関数呼び出しが可能です。MCP サーバーとして Hugging Face・DeepWiki がプリセット同梱されており、独自 MCP サーバーの追加も可能です（TOOLS.md）。

長コンテキストと KV cache 最適化

Bonsai 27B のコンテキスト長は最大 262,144 tokens（256K+）です。Bonsai-demo の起動スクリプトは、実行環境の RAM 容量に応じて自動的に安全なコンテキスト長を決定します。長コンテキスト時のメモリ削減として BONSAI_KV4=1 を指定すると、4-bit KV cache が有効化され、KV cache のメモリ消費が約 3.5x 削減されます。品質補正のためのキャリブレーションバイアスも同梱されています。

Speculative decoding — DSpark ドラフター（フォーク限定）

BONSAI_SPECULATIVE=1 を指定すると、DSpark ドラフターによる speculative decoding が有効化され、CUDA 環境で約 1.8〜2 倍の高速化が報告されています。ただしこの機能は PrismML フォーク限定であり、本流 llama.cpp のパッキング形式では読み込めない点に注意が必要です（README「Bonsai-demo」および SPECULATIVE.md 記載）。

類似 OSS との違い — BitNet / llama.cpp / Ollama との比較

1. microsoft/BitNet との違い

microsoft/BitNet は Microsoft が公開する 1-bit LLM 公式推論フレームワークで、llama.cpp をベースに CPU 最適化に特化しています。ARM CPU で 1.37x〜5.07x の高速化と 55.4%〜70.0% のエネルギー消費削減、x86 CPU で 2.37x〜6.17x の高速化と 71.9%〜82.2% のエネルギー消費削減がプラットフォーム別に公表されており、100B クラスの BitNet b1.58 モデルを単一 CPU で読める速度で動作させることを目指しています。

Bonsai-demo との主な差分は次のとおりです。

• 対応モデル: BitNet は BitNet b1.58 系専用。Bonsai-demo は Qwen3.6 27B ベースの量子化モデル（Bonsai / Ternary-Bonsai）専用
• バックエンド: BitNet は CPU 最適化に特化し GPU バックエンドは非対応。Bonsai-demo は Metal / CUDA / Vulkan / ROCm に対応
• 機能統合: BitNet は vision / tool calling / thinking / MCP を含みません。Bonsai-demo はこれらを一体化して提供

2. ggml-org/llama.cpp との関係

Bonsai-demo は llama.cpp 本流に対抗する存在ではなく、llama.cpp の PrismML フォーク版バイナリを利用してモデルダウンロード〜UI 起動までをワンコマンド化した「配布ラッパー」です。

• 本流 llama.cpp: 汎用ローカル推論エンジンとして、多数のモデル・量子化フォーマット・バックエンドに対応
• Bonsai-demo: Bonsai / Ternary-Bonsai に特化した「モデル + セットアップ + UI + 拡張機能」のワンストップパッケージ

Q2_0 の group-128 形式（現行 Bonsai-demo 版）はフォークバイナリでのみ動作し、group-64 形式（*-Q2_0_g64.gguf）は本流で動作するという棲み分けになっています。DSpark speculative decoding は本流のパッキング形式では読み込めず、フォーク限定機能です。

3. ollama/ollama との違い

Ollama は幅広いモデルカタログを扱うユーザーフレンドリーなランナーで、多数のモデルを切り替えて試す用途に強みがあります。

• モデルカタログ: Ollama は多数のモデルを提供、Bonsai-demo は Bonsai 一族に特化
• 量子化サポート: Ollama は 1-bit（Q1_0）/ ternary（Q2_0）のカスタムカーネルを公式にはまだフルサポートしていません（Q1_0 の llama.cpp 本流マージにより将来的取り込みは可能性があります）
• 導線: Ollama はモデル切替の簡便性で優位、Bonsai-demo は「Bonsai を最速で起動する導線」で優位

4. 比較表 — 6 軸で並べる

採用判断のポイント — どんなプロジェクトに向くか

向いているケース

• ローカルで 27B クラスの VLM を動かしたい: 1-bit Bonsai-27B は約 3.9 GB、Ternary-Bonsai-27B は約 5.9 GB でロード可能で、GPU リソースが限られたラップトップでも VLM のプロトタイピングが可能
• エージェント機能（thinking + tool calling + MCP）を最短で試したい: setup.sh 1 コマンドで Open WebUI と MCP プリセットまで揃うため、エージェント PoC の立ち上げコストが小さい
• Mac・Linux・Windows で同一の起動体験を得たい: setup.sh / setup.ps1 により OS 間差分を吸収した起動フローが提供されている

向かないケース

• 本番運用でスループット・分散推論を最重視する場合: Bonsai-demo はローカル・単一ノード実行向け。プロダクション級のスループットや分散推論には別の推論サーバー（vLLM / TGI 等）の検討が適切
• BitNet b1.58 系の研究に集中したい場合: 1-bit LLM の研究フレームワークとしては microsoft/BitNet の方が該当領域に密着
• 多数モデルの切り替え運用が主目的の場合: Ollama や本流 llama.cpp の方が汎用性で優位

導入・運用時の留意点

1. 27B 重みは private 期間中 BONSAI_TOKEN が必要: launched 直後は 27B の Hugging Face リポジトリの一部が private であり、HF トークンの環境変数指定が必須
2. Ternary GGUF は 3 バリアントの選択が必要: *-Q2_0.gguf（group 128、フォーク互換）/ *-Q2_0_g64.gguf（group 64、本流互換）/ *-PQ2_0.gguf（実験的、使用非推奨）を実行環境に応じて選ぶ
3. M5 Mac の Metal コンパイル: macOS 26.2〜26.4 で Metal コンパイルエラーが報告されており、GGML_METAL_TENSOR_DISABLE=1 で回避可能
4. DSpark speculative は本流非互換: BONSAI_SPECULATIVE=1 はフォーク限定機能のため、本流 llama.cpp に置き換える場合は無効化する必要がある

ライセンス・メンテナンス状況

• ライセンス: Apache-2.0（商用利用・再配布が可能な緩やかなライセンス）
• アクティブ性: 直近 push は 2026-08-05、スター数 2,184、フォーク数 220、archived=false かつ fork=false のオリジナルリポジトリ
• 上流動向: Q1_0 は llama.cpp 本流マージ済み、Q2_0 は CPU / Metal / Vulkan / CUDA まで本流マージ完了・x86 AVX-512-VNNI は pending という順調な移行状況

これらから、執筆時点における Bonsai-demo は「上流依存の解消が進みつつあるアクティブなオリジナルリポジトリ」と評価できます。

まとめ — Bonsai-demo の読み進め方

本記事の要点は次の 3 点です。

1. Bonsai-demo は Bonsai / Ternary-Bonsai（Qwen3.6 27B ベースの 1-bit・ternary 量子化 LLM）をローカル環境でワンコマンド起動する PrismML 公式デモリポジトリ
2. 27B は VLM で、GGUF 3.53〜6.66 GiB という圧縮率とフル精度の 90〜95% の性能維持を両立
3. microsoft/BitNet（1-bit LLM 研究）・ggml-org/llama.cpp（汎用エンジン）・ollama/ollama（多モデルランナー）とは棲み分けがあり、Bonsai-demo は「Bonsai 一族に最適化された最速起動導線」に強みがある

自プロジェクトへの採用検討を進める際は、次の順で公式ドキュメントを参照することをおすすめします。

1. README の「Quick Start」でセットアップの全体像を把握
2. AGENTS.md でハードウェア別の設定項目と既定値を確認
3. VISION.md と TOOLS.md で VLM・エージェント用途の API 仕様を確認
4. OPENWEBUI.md で UI・コードインタプリタ統合の詳細を確認
5. SPECULATIVE.md / KV-CACHE.md で長コンテキスト・スループット最適化のオプションを確認

関連情報

社内での LLM 実行環境の選定や、AI 基盤の受託開発をご検討中の方は、お問い合わせフォーム からご相談ください。要件の整理段階からお話をお伺いいたします。