Bonsai Windows 本地執行教程：1-bit 模型、視覺與 MCP 工具呼叫

Bonsai 是一組低位元本地模型。官方演示倉庫提供 1.7B、4B、8B 和 27B 等尺寸，並整合聊天、視覺、推理強度、OpenAI 風格工具呼叫與 MCP。

專案地址：

https://github.com/PrismML-Eng/Bonsai-demo

“1-bit”不代表模型執行時只佔引數量除以八那麼簡單。權重可以壓得很小，但推理仍需要 KV Cache、執行時、上下文和影象編碼等額外記憶體。選擇模型時要看整機可用記憶體，而不是隻看下載檔案大小。

先選 1-bit 還是三值模型

官方演示提供兩個模型家族：

第一次執行建議選擇預設的 Ternary-Bonsai，不要只因為“1-bit”更醒目就預設它效果更好。

Windows 安裝前準備

建議準備：

• 64 位 Windows 11；
• Git；
• PowerShell；
• 足夠的記憶體和磁碟空間；
• 可訪問 Hugging Face 的網路；
• 27B 模型所需的 Hugging Face Token。

不同版本的指令碼和模型開放狀態可能變化。執行前應檢視倉庫 README，不要把舊教程裡的模型地址永久寫死。

克隆專案

1
2

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

先檢視可用空間：

1

Get-PSDrive -PSProvider FileSystem

模型、快取和二進位制檔案可能佔用數 GB 到數十 GB，系統盤空間不足時不要直接開始下載。

選擇模型尺寸

預設使用 27B：

1

$env:BONSAI_MODEL = "27B"

普通電腦建議先從 4B 或 8B 開始：

1

$env:BONSAI_MODEL = "4B"

選擇三值模型家族：

1

$env:BONSAI_FAMILY = "ternary"

如果要測試 1-bit：

1

$env:BONSAI_FAMILY = "1bit"

環境變數只對當前 PowerShell 會話有效，關閉視窗後需要重新設定。

配置 Hugging Face Token

如果所選模型倉庫需要授權：

1

$env:BONSAI_TOKEN = "hf_your_token_here"

不要把真實 Token 寫進文章、指令碼、Git 倉庫或終端截圖。使用完可以清除：

1

Remove-Item Env:BONSAI_TOKEN

若出現 401 或 403，先確認已經在 Hugging Face 頁面接受模型許可，再檢查 Token 是否擁有讀取許可權。

執行安裝指令碼

官方 Windows 流程：

1
2

Set-ExecutionPolicy -Scope Process -ExecutionPolicy Bypass
.\setup.ps1

-Scope Process 隻影響當前 PowerShell 程序，關閉終端後恢復原策略，比永久降低系統執行策略更穩妥。

指令碼會根據環境變數安裝依賴、下載模型和準備執行所需的二進位制檔案。下載中斷時不要反覆刪除整個目錄，先檢查快取和指令碼是否支援繼續下載。

命令列測試

安裝完成後可直接傳送提示詞：

1

.\scripts\run_llama.ps1 -p "请用三句话解释什么是低比特大模型"

如果只想確認模型能載入，先使用短提示詞和短上下文。長上下文會顯著增加 KV Cache，可能讓原本能啟動的模型突然記憶體不足。

啟動 Web 聊天介面

官方演示可以啟動本地 llama server，預設提供聊天、視覺與工具呼叫介面。倉庫當前 Windows 指令碼可能隨版本調整，可先檢視：

1

Get-ChildItem .\scripts\*server*

啟動後通常訪問：

1

http://localhost:8080

若埠無法訪問，依次檢查程序是否仍在執行、防火牆提示是否被拒絕，以及 8080 是否已被其他程式佔用。

視覺能力怎麼用

Bonsai 演示支援傳送照片、截圖和 PDF。實際使用時要注意：

• 影象會額外佔用記憶體；
• 高解析度截圖不一定帶來更準確的文字識別；
• PDF 頁數多時應先拆分或只傳送相關頁面；
• 私密文件雖然在本地推理，也要確認介面、日誌和臨時檔案儲存位置。

可先用一張簡單截圖測試：要求模型列出頁面按鈕、解釋錯誤資訊，再檢查它有沒有編造不可見內容。

工具呼叫和 MCP

演示支援 OpenAI 風格 tool_calls，並能在演示介面連線 MCP Server。模型會提出工具呼叫，但真正執行工具的是宿主程式。

接入檔案、終端或瀏覽器 MCP 前，應先確認：

1. Server 會暴露哪些工具；
2. 是否限制到指定工作目錄；
3. 危險命令是否需要人工確認；
4. 工具輸出是否寫入聊天日誌；
5. 模型失敗時會不會重複呼叫。

低位元模型體積小，不代表工具呼叫判斷一定可靠。涉及刪除檔案、執行 Shell、傳送訊息或修改外部系統時，必須保留審批和最小許可權。

電腦能跑多大的模型

下面只能作為保守起點，實際需求會受模型格式、上下文長度、執行後端和視覺輸入影響：

即使 27B 權重能裝進記憶體，速度也可能受記憶體頻寬和 CPU 指令集限制。能載入不等於互動體驗流暢。

常見問題

PowerShell 禁止執行指令碼

只為當前程序放行：

1

Set-ExecutionPolicy -Scope Process -ExecutionPolicy Bypass

不要直接修改整臺電腦的永久執行策略。

模型下載報 401 或 403

檢查模型是否需要接受許可、BONSAI_TOKEN 是否存在，以及 Token 是否有讀取許可權：

1

Test-Path Env:BONSAI_TOKEN

載入時記憶體不足

換成更小模型：

1
2

$env:BONSAI_MODEL = "4B"
.\setup.ps1

同時縮短上下文、關閉視覺輸入和其他佔用記憶體的軟體。不要依賴 Windows 頁面檔案把嚴重超出實體記憶體的模型“硬跑起來”，速度通常會非常差。

生成速度很慢

確認實際使用的後端、CPU 指令集和執行緒設定。首次執行還可能包含模型載入、快取或核心準備時間，應把首輪延遲與後續生成速度分開觀察。

MCP 能連線但工具呼叫不穩定

先用只有一個、引數簡單且只讀的工具測試。若小模型經常填錯引數，應減少工具數量、補充明確描述，或換質量更高的模型家族和尺寸。

Bonsai 和 Ollama 怎麼選

Ollama 是模型執行與管理工具，Bonsai 是模型及其演示環境，兩者不是同一層產品。

• 想統一管理多個常見模型、快速提供 API：優先 Ollama；
• 想研究 1-bit/三值權重、測試官方視覺和工具鏈：使用 Bonsai Demo；
• 想把 Bonsai 放進現有應用：先確認當前格式能否被你的執行時直接載入；
• 只看“模型檔案更小”不足以決定方案，還要比較質量、速度、上下文和工具呼叫可靠性。

建議先用 4B Ternary-Bonsai 完成文字、視覺和一個只讀 MCP 工具的閉環，再決定是否下載 27B 或切換 1-bit 家族。