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 家族。