PrismML-Eng/Bonsai-demo —— Bonsai 演示项目，一个机器学习工具的快速启动与交互演示

这是什么

PrismML-Eng/Bonsai-demo 是一个开源工具库，由 PrismML-Eng 发布，用于在个人设备上本地部署和运行 Bonsai 系列语言模型。该系列包含两个子家族：

• 1-bit Bonsai（GGUF Q1_0 格式，约 1.125 bits/weight）
• Ternary-Bonsai（GGUF Q2_0 格式，约 1.7 bits/weight，打包为 2-bit）

模型尺寸覆盖 1.7B、4B、8B 和 27B（其中 27B 为视觉‑语言模型）。项目通过 setup.sh / setup.ps1 一键完成依赖安装、模型下载和二进制文件获取，并提供了 llama-server 和 Open WebUI 两套交互界面。

解决的问题

• 极端低比特模型部署困难：传统量化方法往往止于 4‑bit，而 1‑bit / ternary 量化虽极节省显存，但主流框架支持不完整。Bonsai-demo 提供了完整的、可直接运行的 binary + 模型文件，降低了使用门槛。
• 在边缘设备运行大模型：1‑bit Bonsai‑27B 的模型权重仅 ~1.125 bits/weight，可以装入现代 iPhone 而无需内存卸载，解决了「大模型必须依赖云端或高端 GPU」的限制。
• 薄弱的推理与工具链整合：多数本地模型仅支持纯文本聊天。Bonsai‑27B 原生支持视觉（图片/截图/PDF）、OpenAI 风格 tool_calls 工具调用、MCP 服务器以及可调推理预算的「思考」模式，可直接用于构建 agent 应用。

核心功能

1. 多后端本地推理
   支持 Mac（Metal）、Linux/Windows（CUDA、Vulkan、ROCm）以及纯 CPU。所有后端均由 llama.cpp 驱动，Q1_0 已完全合并上游，Q2_0（ternary）正在分后端迁移（CPU、Metal 已支持，Vulkan 在审查中）。

2. 模型家族快速切换
   通过环境变量 BONSAI_FAMILY（ternary 或 bonsai）和 BONSAI_MODEL（27B、8B、4B、1.7B 或 all）即可切换模型，无需修改脚本。

3. 视觉能力（仅 27B）
   可上传照片、截图、PDF 并进行问答，支持原生 image_url API 方式。

4. Agent 能力
   内置 OpenAI 风格 tool_calls，支持完整的往返调用；聊天 UI 集成 MCP 客户端，已预配置 Hugging Face 和 DeepWiki，每轮对话可选开启。

5. 可调思考模型
   对话中通过 UI 灯泡图标选择推理努力度（Off / Low / Medium / High / Max），或通过 --reasoning-budget 参数设置服务器端上限。

6. 极长上下文
   支持 256k+ token 的长对话。

7. 一键部署
   ./setup.sh 自动检测系统依赖、安装 uv、创建 venv、下载模型和预编译二进制、编译 MLX（macOS）、安装 Open WebUI 和代码解释器（.venv-jupyter）。重复运行安全，会跳过已完成步骤。

8. 社区基准测试
   提供 community-benchmarks/ 目录，包含不同硬件上的性能结果和测试模板。

亮点 / 与同类相比

| 维度 | Bonsai-demo | 同类项目（如 llama.cpp、Ollama、LM Studio） | |------|-------------|---------------------------------------------| | 压缩比 | 1‑bit（1.125 bw）和 ternary（1.7 bw）是目前已落地的最高压缩比之一，27B 模型可放入手机 | 主流量化在 4‑bit ~ 8‑bit，2‑bit 以下模型极少 | | 功能完整度 | 在极端压缩下仍保留视觉、工具调用、思考模式和长上下文 | 多数低比特模型仅支持纯文本聊天，或需要额外适配 | | 开箱即用 | 单命令完成全部安装，针对 Apple Silicon 自动编译 MLX | 通常需手动选择后端、下载正确格式的 GGUF 文件 | | 生态兼容 | 与 llama.cpp 主线紧密对齐，Q1_0 已合并，Q2_0 逐步迁移中；提供 GGUF 和 MLX 双格式 | 大部分仅提供 GGUF，macOS 上需额外工具转换 | | 灵活规模 | 从 1.7B 到 27B 覆盖桌面端到移动端 | 低比特模型往往只提供单一最大尺寸 |

适合谁用 / 上手

• 本地 AI 开发者：希望在自己的 MacBook、Linux PC 甚至 Windows 笔记本上运行带 agent 和视觉能力的模型，用于原型验证或离线使用。
• 移动端与边缘设备研究者：对 1‑bit / ternary 极低比特量化感兴趣，需要实际的 Demo 和基准测试来评估实用性。
• AI 编码代理用户：项目提供了 AGENTS.md 文件，专为 AI 代理编写，说明硬件相关的参数、默认值和提问建议，便于让 AI 助手自动完成配置。

上手步骤（以 27B 为例，需 HuggingFace token 因为仓库当前为私有）：

git clone https://github.com/PrismML-Eng/Bonsai-demo.git
cd Bonsai-demo
export BONSAI_TOKEN="hf_your_token_here"
./setup.sh
./scripts/start_llama_server.sh

启动后访问 http://localhost:8080 即可使用内置聊天 UI，支持上传图片、调节思考努力度、启用 MCP 工具等。Windows 用户可使用对应 PowerShell 脚本。