PrismML-Eng/Bonsai-demo

# Bonsai 演示

官网  |  GitHub  |  Discord

HF 合集： Bonsai 27B · Bonsai (1-bit) · Ternary-Bonsai

白皮书： Bonsai 27B · 1-bit Bonsai 8B · Ternary-Bonsai 8B

使用此演示代码库，您可以在 Mac (Metal)、Linux/Windows (CUDA, Vulkan, ROCm) 或 CPU 上本地运行 **Bonsai** (1-bit) 和 **Ternary-Bonsai** 语言模型。 ## 🌱 最新：Bonsai 27B 该系列最新且最大的一代，也是其首个**视觉语言**模型（[Bonsai 27B 合集](https://huggingface.co/collections/prism-ml/bonsai-27b)）： - **视觉：** 发送照片、截图和 PDF；对其进行提问（参见 [VISION.md](VISION.md)）。 - **智能体工具调用：** 原生支持 OpenAI 风格的 `tool_calls` 并实现完整的往返交互，此外两个演示 UI 均支持 MCP server（参见 [TOOLS.md](TOOLS.md)）。 - **思考：** 这是一个推理模型；可以在 UI 中为每次聊天选择推理力度，或针对每个请求设定预算。 - **长上下文：** 支持 256k+ token 的对话。 - **极小体积：** 1-bit Bonsai-27B 压缩后每个权重仅约 1.125 bit：无需内存卸载即可适配现代 iPhone。Ternary-Bonsai-27B（每个权重约 1.7 bit，打包为 2-bit 以实现快速加速内核）是更高质量的选择，也是此演示的默认选项。 下方的快速入门只需两条命令即可带您上手：`./setup.sh` 默认下载 Ternary-Bonsai-27B，然后 `./scripts/start_llama_server.sh` 将在 http://localhost:8080 为您提供聊天、视觉和工具功能。 ## 快速入门 正在使用 AI 编程智能体进行设置？请将其引导至 [AGENTS.md](AGENTS.md)，这是一份专为智能体编写的指南（包含特定硬件的配置项、默认值以及需要向用户询问的内容）。 ### macOS / Linux ``` git clone https://github.com/PrismML-Eng/Bonsai-demo.git cd Bonsai-demo # （可选）选择模型大小：27B（默认）、8B、4B 或 1.7B export BONSAI_MODEL=27B # 设置你的 HuggingFace token（仅当其 repos 为私有时，27B 才需要） export BONSAI_TOKEN="hf_your_token_here" # 一条命令完成所有操作：安装 deps、下载 models + binaries ./setup.sh ``` ### Windows (PowerShell) ``` git clone https://github.com/PrismML-Eng/Bonsai-demo.git cd Bonsai-demo # （可选）选择模型大小：27B（默认）、8B、4B 或 1.7B $env:BONSAI_MODEL = "27B" # 设置你的 HuggingFace token（仅当其 repos 为私有时，27B 才需要） $env:BONSAI_TOKEN = "hf_your_token_here" # 运行 setup Set-ExecutionPolicy -Scope Process -ExecutionPolicy Bypass .\setup.ps1 ``` ### 切换系列和大小 您可以瞬间在 Ternary（默认）和 1-bit 系列之间，以及不同的模型大小之间进行切换： ``` # 运行 Ternary-Bonsai 4B BONSAI_FAMILY=ternary BONSAI_MODEL=4B ./scripts/download_models.sh BONSAI_FAMILY=ternary BONSAI_MODEL=4B ./scripts/run_llama.sh -p "Hello!" ``` 对于 Windows： ``` $env:BONSAI_FAMILY="ternary"; $env:BONSAI_MODEL="4B" .\setup.ps1 .\scripts\run_llama.ps1 -p "Hello!" ``` ## 速度基准测试 有关不同硬件上的测试结果以及提交您自己测试结果的模板，请参见 [community-benchmarks/](community-benchmarks/)。 ## 模型 提供两个模型系列，每个系列都有 **27B**、**8B**、**4B** 和 **1.7B** 大小。27B 模型是视觉语言模型：它们可以接受图像和文本；所有 27B 仓库均汇集在 [Bonsai 27B HF 合集](https://huggingface.co/collections/prism-ml/bonsai-27b) 中。 这两种格式都已并入 llama.cpp 主线：**Q1_0 (1-bit) 已完全合并至上游**，且 **Q2_0 (ternary) 现已支持在主线 CPU 和 Metal 上运行**，Vulkan 支持正在审核中。详情及兼容主线的文件：下方的[二进制状态](#upstream-status-for-binary)和[三进制状态](#upstream-status-for-ternary)。 ### Bonsai (1-bit) 提供 GGUF (llama.cpp) 和 MLX 1-bit 格式。 | 模型 | 格式 | HuggingFace 仓库 | |---------------------|----------|-------------------------------------------------------------------------------------------| | Bonsai-27B | GGUF | [prism-ml/Bonsai-27B-gguf](https://huggingface.co/prism-ml/Bonsai-27B-gguf) | | Bonsai-27B | MLX | [prism-ml/Bonsai-27B-mlx-1bit](https://huggingface.co/prism-ml/Bonsai-27B-mlx-1bit) | | Bonsai-8B | GGUF | [prism-ml/Bonsai-8B-gguf](https://huggingface.co/prism-ml/Bonsai-8B-gguf) | | Bonsai-8B | MLX | [prism-ml/Bonsai-8B-mlx-1bit](https://huggingface.co/prism-ml/Bonsai-8B-mlx-1bit) | | Bonsai-4B | GGUF | [prism-ml/Bonsai-4B-gguf](https://huggingface.co/prism-ml/Bonsai-4B-gguf) | | Bonsai-4B | MLX | [prism-ml/Bonsai-4B-mlx-1bit](https://huggingface.co/prism-ml/Bonsai-4B-mlx-1bit) | | Bonsai-1.7B | GGUF | [prism-ml/Bonsai-1.7B-gguf](https://huggingface.co/prism-ml/Bonsai-1.7B-gguf) | | Bonsai-1.7B | MLX | [prism-ml/Bonsai-1.7B-mlx-1bit](https://huggingface.co/prism-ml/Bonsai-1.7B-mlx-1bit) | 设置 `BONSAI_MODEL` 以选择要下载和运行的大小（默认：`27B`）。 ### Ternary-Bonsai 提供 GGUF (llama.cpp) 和 MLX 2-bit 格式。 | 模型 | 格式 | HuggingFace 仓库 | |------------------------|---------------|---------------------------------------------------------------------------------------------------------| | Ternary-Bonsai-27B | GGUF | [prism-ml/Ternary-Bonsai-27B-gguf](https://huggingface.co/prism-ml/Ternary-Bonsai-27B-gguf) | | Ternary-Bonsai-27B | MLX (2-bit) | [prism-ml/Ternary-Bonsai-27B-mlx-2bit](https://huggingface.co/prism-ml/Ternary-Bonsai-27B-mlx-2bit) | | Ternary-Bonsai-8B | GGUF | [prism-ml/Ternary-Bonsai-8B-gguf](https://huggingface.co/prism-ml/Ternary-Bonsai-8B-gguf) | | Ternary-Bonsai-8B | MLX (2-bit) | [prism-ml/Ternary-Bonsai-8B-mlx-2bit](https://huggingface.co/prism-ml/Ternary-Bonsai-8B-mlx-2bit) | | Ternary-Bonsai-4B | GGUF | [prism-ml/Ternary-Bonsai-4B-gguf](https://huggingface.co/prism-ml/Ternary-Bonsai-4B-gguf) | | Ternary-Bonsai-4B | MLX (2-bit) | [prism-ml/Ternary-Bonsai-4B-mlx-2bit](https://huggingface.co/prism-ml/Ternary-Bonsai-4B-mlx-2bit) | | Ternary-Bonsai-1.7B | GGUF | [prism-ml/Ternary-Bonsai-1.7B-gguf](https://huggingface.co/prism-ml/Ternary-Bonsai-1.7B-gguf) | | Ternary-Bonsai-1.7B | MLX (2-bit) | [prism-ml/Ternary-Bonsai-1.7B-mlx-2bit](https://huggingface.co/prism-ml/Ternary-Bonsai-1.7B-mlx-2bit) | 这是默认的模型系列。设置 `BONSAI_FAMILY=bonsai` 可改用 1-bit Bonsai 系列。 ### 环境变量 这两个变量都是可选的。**如果您都不设置，默认值为 `Ternary-Bonsai-27B`：** 这正是普通的 `./setup.sh` 会下载并运行的模型。它们会被 `setup.sh`、`setup.ps1`、`download_models.sh` 以及所有 `run_*` / `start_*` 脚本（Linux、macOS 和 Windows）读取。 | 变量 | 默认值 | 有效值 | 用途 | |-----------------|-----------|------------------------------------|---------| | `BONSAI_FAMILY` | `ternary` | `ternary`, `bonsai`, `all` | 模型系列。`ternary` = Ternary-Bonsai；`bonsai` = 1-bit Bonsai。`all` 扩展为两个系列（仅限设置/下载）。 | | `BONSAI_MODEL` | `27B` | `27B`, `8B`, `4B`, `1.7B`, `all` | 模型大小。`all` 扩展为所有四个大小（仅限设置/下载）。 | | `BONSAI_TOKEN` | — | HF 只读 token | 仅在其仓库处于私有状态时 27B 模型需要（发布时将移除）。 | `all` 仅对 `setup.sh` / `setup.ps1` / `download_models.sh` 有效 —— 运行/server 脚本需要具体的系列/大小。 您可以自由组合它们： ``` ./setup.sh # Ternary-Bonsai-27B (default) BONSAI_MODEL=1.7B ./setup.sh # Ternary-Bonsai-1.7B BONSAI_FAMILY=bonsai ./setup.sh # Bonsai-27B (1-bit) BONSAI_FAMILY=bonsai BONSAI_MODEL=4B ./setup.sh # Bonsai-4B BONSAI_MODEL=all ./setup.sh # All 4 Ternary-Bonsai sizes BONSAI_FAMILY=all BONSAI_MODEL=all ./setup.sh # Full matrix (8 downloads) ``` ## 1-bit 上游状态 上游 [llama.cpp](https://github.com/ggml-org/llama.cpp) 在许多后端中开箱即用地支持 Q1_0：CPU（通用、NEON 和优化的 x86）、Metal、CUDA 和 Vulkan。 | 运行时 | 状态 | |---------|--------| | llama.cpp (CPU, Metal, CUDA, Vulkan) | ✅ 已合并至上游，开箱即用 | | MLX (1-bit) | ⏳ 待处理上游合并：[mlx#3161](https://github.com/ml-explore/mlx/pull/3161)；在合并之前，请使用 [PrismML-Eng/mlx](https://github.com/PrismML-Eng/mlx)（`prism` 分支，由 `setup.sh` 自动构建） | ## Ternary 上游状态 Ternary 支持正处于迁移到 [llama.cpp](https://github.com/ggml-org/llama.cpp) 主线的过程中：各个后端正陆续并入，因此目前它是主线和我们 fork 版本的混合体。先说实际影响：**我们目前提供三种 ternary GGUF 变体，每一种都需要在正确的位置运行。** | 文件 | 格式 | 运行于 | |------|--------|---------| | `*-Q2_0.gguf` | 分组大小 128。**本演示使用的格式**，与我们的 fork 兼容。一旦 llama.cpp 迁移完成，这些文件将被弃用并由 `PQ2_0` gguf 替换 | 本演示 / fork 二进制文件。无法在主线上加载（类型 ID 相同，块大小不同） | | `*-Q2_0_g64.gguf` | 分组大小 64 (2.25 bpw)。llama.cpp 官方格式；这些文件将被重命名为普通的 `Q2_0`，替换当前文件 | llama.cpp 主线（目前支持 CPU 和 Metal） | | `*-PQ2_0.gguf` | 暂不支持。计划作为未来的 fork 格式：与当前 group-128 的 `Q2_0` 格式相同，只是使用独立的 ggml type id，以便能与上游的 `Q2_0` 共存 | 暂无（计划在 fork 中支持） | 各后端的迁移状态： | 后端 | 状态 | 位置 | |---------|--------|-------| | CPU (ARM NEON + 通用标量) | ✅ 已合并至 llama.cpp 主线 | [ggml-org/llama.cpp#24448](https://github.com/ggml-org/llama.cpp/pull/24448) | | Metal | ✅ 已合并至 llama.cpp 主线 | [ggml-org/llama.cpp#25419](https://github.com/ggml-org/llama.cpp/pull/25419) | | Vulkan | 🔄 上游正在进行中（独立的 PR，非我们提交） | [ggml-org/llama.cpp#25430](https://github.com/ggml-org/llama.cpp/pull/25430) | | CUDA | 🔄 目前仅限 fork（等待基于上游 MMQ 重构进行 rebase） | [PrismML-Eng/llama.cpp](https://github.com/PrismML-Eng/llama.cpp) `pr/q2_0-cuda` 分支 | | x86 (AVX-512-VNNI) | ⏳ 待处理 | 待定 | **CPU 和 Metal 现已支持在 llama.cpp 主线上运行 `Q2_0`，无需 fork**（请使用最近的 `ggml-org/llama.cpp` 构建版本以及 `Q2_0_g64.gguf` 文件）。对于 CUDA 和其他后端，请使用本演示：它内置了 fork 的[预编译二进制文件](https://github.com/PrismML-Eng/llama.cpp/releases/tag/prism-b9591-62061f9)，因此它下载的 group-128 `*-Q2_0.gguf` 文件可以直接开箱即用。原生的 [MLX](https://github.com/ml-explore/mlx) 支持 MLX 2-bit，无需使用 fork。 要直接在原生的 `ggml-org/llama.cpp`（CPU 或 Metal）上运行较小的 ternary 模型，请使用 group-64 文件： | 模型 | 仓库 | 文件（兼容主线） | |-------|------|----------------------------| | 1.7B | [prism-ml/Ternary-Bonsai-1.7B-gguf](https://huggingface.co/prism-ml/Ternary-Bonsai-1.7B-gguf) | `Ternary-Bonsai-1.7B-Q2_0_g64.gguf` | | 4B | [prism-ml/Ternary-Bonsai-4B-gguf](https://huggingface.co/prism-ml/Ternary-Bonsai-4B-gguf) | `Ternary-Bonsai-4B-Q2_0_g64.gguf` | | 8B | [prism-ml/Ternary-Bonsai-8B-gguf](https://huggingface.co/prism-ml/Ternary-Bonsai-8B-gguf) | `Ternary-Bonsai-8B-Q2_0_g64.gguf` | ``` hf download prism-ml/Ternary-Bonsai-1.7B-gguf Ternary-Bonsai-1.7B-Q2_0_g64.gguf --local-dir models hf download prism-ml/Ternary-Bonsai-4B-gguf Ternary-Bonsai-4B-Q2_0_g64.gguf --local-dir models hf download prism-ml/Ternary-Bonsai-8B-gguf Ternary-Bonsai-8B-Q2_0_g64.gguf --local-dir models ``` ## `setup.sh` 的作用 设置脚本会为您处理一切，即使是在一台全新的机器上： 1. **检查/安装系统依赖：** macOS 上的 Xcode CLT，Linux 上的 build-essential 2. **安装 [uv](https://docs.astral.sh/uv/)：** 快速的 Python 包管理器（用户本地安装，非全局） 3. **创建 Python venv** 并运行 `uv sync` —— 从 `pyproject.toml` 安装 cmake、ninja、huggingface-cli 4. **从 HuggingFace 下载模型**（在其仓库处于私有状态时，27B 模型需要 `BONSAI_TOKEN`） 5. **从 [GitHub Release](https://github.com/PrismML-Eng/llama.cpp/releases/tag/prism-b9591-62061f9) 下载预构建的二进制文件**（如果您愿意，也可以从源码构建） 6. **从源码构建 MLX**（仅限 macOS）：克隆我们的 fork 版本，将其构建到 venv 中，安装 ML 技术栈（mlx-lm、torch、transformers） 7. **将 Open WebUI 安装**到 venv 中以进行智能体演示（使用 `BONSAI_OPENWEBUI=0` 跳过） 8. **构建代码解释器 venv**（`.venv-jupyter`）：为 Open WebUI 代码解释器提供 Jupyter + matplotlib / pandas / numpy / scipy / sympy / yfinance（使用 `BONSAI_CODE_INTERPRETER=0` 跳过） 重新运行 `setup.sh` 是安全的 —— 它会跳过已完成的步骤。 ## 运行模型 所有运行脚本均遵循 `BONSAI_MODEL`（默认为 `27B`）。设置它以运行不同的大小： ### llama.cpp (Mac / Linux — 自动检测平台) ``` ./scripts/run_llama.sh -p "What is the capital of France?" # 运行不同的模型大小 BONSAI_MODEL=4B ./scripts/run_llama.sh -p "Write a haiku about bonsai trees" ``` ### llama.cpp (Windows PowerShell) ``` .\scripts\run_llama.ps1 -p "What is the capital of France?" # 运行不同的模型大小 $env:BONSAI_MODEL = "4B" .\scripts\run_llama.ps1 -p "Write a haiku about bonsai trees" ``` ### MLX — Mac (Apple Silicon) ``` source .venv/bin/activate ./scripts/run_mlx.sh -p "What is the capital of France?" ``` ### 聊天服务器 启动 llama-server 及其内置的聊天 UI： ``` ./scripts/start_llama_server.sh # http://localhost:8080 # 提供不同模型大小的服务 BONSAI_MODEL=4B ./scripts/start_llama_server.sh ``` 对于 Windows PowerShell： ``` .\scripts\start_llama_server.ps1 ``` #### 思考 27B 是一个思考模型，并在提供服务时默认**开启**了思考功能。要在聊天 UI 中针对每次对话进行调整（无需重启）：点击消息框中的灯泡图标，并选择**推理力度**（Reasoning effort）：Off（关闭）、Low（低，512 token）、Medium（中，2,048）、High（高，8,192）或 Max（最大，无限制）。该选择会在浏览器中保留，并随每个请求发送。 在较慢的硬件上，思考通常是等待时间的主要部分；请在 UI 中选择较低的力度。对于未指定推理力度的 API 客户端，您可以通过在启动脚本中直接传递 llama-server 标志来限制全服务器的默认值： ``` ./scripts/start_llama_server.sh --reasoning-budget 2048 ``` #### 工具调用与 MCP 27B 支持通过 API 进行原生的 OpenAI 风格工具调用，并且聊天 UI 具有预配置了 Hugging Face + DeepWiki 的 MCP 客户端（在消息框的 MCP 选择器中针对每次聊天开启，在您开启之前不会产生提示词成本）。详情、成本以及如何添加您自己的服务器：[TOOLS.md](TOOLS.md)。 #### 视觉 在聊天 UI 中（消息框中的 `+`）上传图像，或通过 API 发送 `image_url` 部分；脚本会自动加载视觉投影器，并在较慢的后端上缩小非常大的图像。成本、图像 token 上限和 OCR 提示：[VISION.md](VISION.md)。 #### 可选附加功能 llama.cpp 聊天服务器的两个默认关闭的实验性功能： - **推测解码**（Speculative decoding）：`BONSAI_SPECULATIVE=1` 将 27B 与其 dspark 起草模型配对，在代码和推理方面可实现约 1.8-2 倍的解码速度提升（CUDA；Apple Silicon 支持将在日后改进）。权衡与验证：[SPECULATIVE.md](SPECULATIVE.md)。 - **4-bit KV cache**：`BONSAI_KV4=1` 将超长上下文的 KV 缓存内存减少约 3.5 倍，并带有可选的校准偏差以获得更好的质量（`./scripts/make_kv_bias.sh`）。详情：[KV-CACHE.md](KV-CACHE.md)。 ### 上下文大小 27B 模型支持高达 **262,144 token** 的上下文。FP16 KV cache 每 token 消耗 64 KiB（100K 时约为 6.3 GiB），因此**即使没有 KV cache 量化，100K 上下文也能在许多消费级设备上运行**。该模型的混合注意力机制使其缓存对于同等规模的模型来说相对较小。 使用可选的 [4-bit KV cache](KV-CACHE.md)（`BONSAI_KV4=1`），缓存将降至每 token 约 18 KiB，100K 时约为 **1.8 GiB**，从下方的 100K 数据中削减了约 4.5 GiB（例如，llama.cpp 上的 Ternary-Bonsai-27B 从约 13.7 GiB 降至约 9.2 GiB）。 *27B 的峰值内存（权重 + 激活 + FP16 KV cache + 约 1.2 GiB 开销；仅文本，视觉投影器需额外增加约 0.9 GiB）：* | 模型 | 格式 | 权重 | 4K 上下文 | 10K 上下文 | 100K 上下文 | |---|---|---|---|---|---| | Bonsai-27B (1-bit) | llama.cpp `Q1_0` | 3.53 GiB | 4.8 GiB | 5.2 GiB | 10.8 GiB | | Bonsai-27B (1-bit) | MLX 1-bit | 3.92 GiB | 5.5 GiB | 5.9 GiB | 11.4 GiB | | Ternary-Bonsai-27B | llama.cpp `Q2_0` | 6.66 GiB | 7.8 GiB | 8.1 GiB | 13.7 GiB | | Ternary-Bonsai-27B | MLX 2-bit | 7.05 GiB | 8.6 GiB | 8.9 GiB | 14.4 GiB | | *参考：27B 16-bit* | GGUF BF16 | 47.73 GiB | 49 GiB | 49.6 GiB | 55.2 GiB | | *参考：27B "4-bit"* | llama.cpp `UD Q4_K_M` | 15.73 GiB | 17.2 GiB | 17.6 GiB | 23.2 GiB | | *参考：27B "4-bit"* | MLX 4-bit | 13.3 GiB | 17.0 GiB | 17.3 GiB | 22 GiB | （MLX 打包文件比 GGUF 大约 400 MiB，因为 MLX 同时存储了缩放比例和偏差，而 GGUF 仅存储缩放比例。） 默认情况下，脚本会传递 `-c 0`，这让 llama.cpp 的 `--fit` 能够根据您的可用内存自动调整 KV cache 的大小（无预分配浪费）。如果您的构建版本不支持 `-c 0`，脚本将根据系统 RAM 回退到一个安全的值。使用以下命令覆盖：`./scripts/run_llama.sh -c 8192 -p "Your prompt"` 较早的纯文本大小全面较小；8B 支持高达 65,536 token 的上下文： *Bonsai-8B 的估算值（权重 + KV cache + 激活）：* | 上下文大小 | 预估内存使用量 | |---------------------|-------------------| | 8,192 token | ~2.5 GB | | 32,768 token | ~5.9 GB | | 65,536 token | ~10.5 GB | ## Open WebUI（可选）：完整的智能体演示 [Open WebUI](https://github.com/open-webui/open-webui) 为本地的 27B 提供了一个类似 ChatGPT 的界面：支持与图像聊天、针对实时工具的调用、服务端代码解释器（绘图 + 市场数据），以及一个供调查的隐藏故事销售数据库。一切都会自动配置，无需点击设置： ``` ./scripts/start_openwebui.sh ``` `setup.sh` 会为您安装它；该脚本会启动后端，初始化演示数据（工具、模型设置、演示数据库），并打开 **http://localhost:9090**。后端、尝试方法及自定义：[OPENWEBUI.md](OPENWEBUI.md)。 ## 从源码构建 如果您想从源码构建 llama.cpp 而不是使用预构建的二进制文件： ### Mac (Apple Silicon — Metal) ``` ./scripts/build_mac.sh ``` 克隆 [PrismML-Eng/llama.cpp](https://github.com/PrismML-Eng/llama.cpp)，使用 Metal 构建，输出到 `bin/mac/`。 ### Mac (Intel — 仅限 CPU) ``` ./scripts/build_mac.sh ``` 该脚本会自动检测是 Intel 还是 Apple Silicon。在 Intel Mac 上，它使用 `-DGGML_METAL=OFF`（仅限 CPU）构建。由于需要 Apple Silicon，MLX 也会被自动跳过。 ### Linux（仅限 CPU） ``` ./scripts/build_cpu_linux.sh ``` 构建无 GPU 依赖的纯 CPU 二进制文件。同时适用于 x64 和 arm64。输出到 `bin/cpu/`。 ### Linux (CUDA) ``` ./scripts/build_cuda_linux.sh ``` 自动检测 CUDA 版本。传递 `--cuda-path /usr/local/cuda-12.8` 以使用特定的工具包。 ### Linux (Vulkan) ``` # 首先安装 Vulkan SDK（例如 sudo apt install libvulkan-dev glslc） git clone -b prism https://github.com/PrismML-Eng/llama.cpp.git cd llama.cpp cmake -B build -DCMAKE_BUILD_TYPE=Release -DGGML_VULKAN=ON cmake --build build -j$(nproc) # 位于 build/bin/ 中的 binaries ``` ### Linux (ROCm / AMD GPU) ``` # 需要 ROCm toolkit (hipcc) git clone -b prism https://github.com/PrismML-Eng/llama.cpp.git cd llama.cpp cmake -B build -DCMAKE_BUILD_TYPE=Release -DGGML_HIP=ON cmake --build build -j$(nproc) # 位于 build/bin/ 中的 binaries ``` ### Windows (CUDA) ``` .\scripts\build_cuda_windows.ps1 ``` 自动检测 CUDA 工具包。传递 `-CudaPath "C:\path\to\cuda"` 以使用特定版本。 需要 Visual Studio Build Tools（或完整的 Visual Studio）和 CUDA 工具包。 ### Windows（仅限 CPU） ``` git clone -b prism https://github.com/PrismML-Eng/llama.cpp.git cd llama.cpp cmake -B build -DCMAKE_BUILD_TYPE=Release cmake --build build --config Release # 位于 build\bin\Release\ 中的 binaries ``` 需要 Visual Studio Build Tools 或带有 C++ 工作负载的完整 Visual Studio。 ## llama.cpp 预构建二进制文件下载 所有二进制文件均可从 [GitHub Release](https://github.com/PrismML-Eng/llama.cpp/releases/tag/prism-b9591-62061f9) 获取： | 平台 | |-----------------------------------| | macOS Apple Silicon (arm64) | | macOS Apple Silicon (KleidiAI) | | macOS Intel (x64) | | Linux x64 (CPU) | | Linux arm64 (CPU) | | Linux x64 (CUDA 12.4) | | Linux x64 (CUDA 12.8) | | Linux x64 (Vulkan) | | Linux arm64 (Vulkan) | | Linux x64 (ROCm 7.2) | | Windows x64 (CPU) | | Windows arm64 (CPU) | | Windows x64 (CUDA 12.4) | | Windows x64 (Vulkan) | | Windows x64 (HIP/ROCm) | | iOS (XCFramework) | ## 文件夹结构 设置完成后，目录如下所示： ``` Bonsai-demo/ ├── README.md ├── TOOLS.md # Tool calling & MCP guide ├── OPENWEBUI.md # Open WebUI agentic demo guide ├── VISION.md # Image input: costs, caps, OCR tips ├── SPECULATIVE.md # Speculative decoding (experimental) ├── KV-CACHE.md # 4-bit KV cache (experimental) ├── AGENTS.md # Agent guide (hardware tuning knobs) ├── setup.sh # macOS/Linux setup ├── setup.ps1 # Windows setup ├── pyproject.toml # Python dependencies ├── scripts/ │ ├── common.sh # Shared helpers + BONSAI_MODEL │ ├── download_models.sh # HuggingFace download │ ├── download_binaries.sh # GitHub release download │ ├── run_llama.sh # llama.cpp (auto-detects Mac/Linux) │ ├── run_llama.ps1 # llama.cpp (Windows PowerShell) │ ├── run_mlx.sh # MLX inference │ ├── mlx_generate.py # MLX Python script │ ├── start_llama_server.sh # llama.cpp server (port 8080) │ ├── start_llama_server.ps1 # llama.cpp server (Windows PowerShell) │ ├── start_mlx_server.sh # MLX server (port 8081) │ ├── start_openwebui.sh # Open WebUI + auto-starts backends │ ├── openwebui/ # Open WebUI demo tools + seeding │ ├── build_mac.sh # Build llama.cpp for Mac │ ├── build_cpu_linux.sh # Build llama.cpp for Linux (CPU only) │ ├── build_cuda_linux.sh # Build llama.cpp for Linux CUDA │ └── build_cuda_windows.ps1 # Build llama.cpp for Windows CUDA ├── models/ # ← downloaded by setup │ ├── gguf/ │ │ ├── 27B/ # GGUF 27B model (+ mmproj for vision) │ │ ├── 8B/ # GGUF 8B model │ │ ├── 4B/ # GGUF 4B model │ │ └── 1.7B/ # GGUF 1.7B model │ ├── Bonsai-27B-mlx/ # MLX 27B model (macOS) │ ├── Bonsai-8B-mlx/ # MLX 8B model (macOS) │ ├── Bonsai-4B-mlx/ # MLX 4B model (macOS) │ └── Bonsai-1.7B-mlx/ # MLX 1.7B model (macOS) ├── bin/ # ← downloaded or built by setup │ ├── mac/ # macOS binaries (Metal or CPU) │ ├── cuda/ # CUDA binaries (Linux/Windows) │ ├── cpu/ # CPU-only binaries (Linux/Windows) │ ├── vulkan/ # Vulkan binaries │ ├── rocm/ # ROCm binaries (AMD Linux) │ └── hip/ # HIP binaries (AMD Windows) ├── mlx/ # ← cloned by setup (macOS) └── .venv/ # ← created by setup ``` 标有 ← 的项目是在设置时创建的，并被 git 排除。 ## 附录 — 常见问题 ### CUDA 源码构建内存不足或卡死 **症状：** 在启用 CUDA 的情况下从源码构建 llama.cpp 时，`cmake --build` 卡住、系统无响应，或者构建进程因 OOM（内存不足）错误被终止。 **原因：** 编译 CUDA 内核非常耗费内存 —— 每个编译任务都可能消耗几 GB 的 GPU VRAM 和/或系统 RAM。在配备低显存 GPU（< 16 GB）或有限系统 RAM 的机器上运行 `make -j$(nproc)` 可能会耗尽可用内存。 **构建脚本如何处理此问题：** `build_cuda_linux.sh` 和 `build_cuda_windows.ps1` 会在构建前自动检测 GPU 的 VRAM。如果检测到的最大 VRAM 小于 16 GB，这些脚本会将并行度限制为 `-j 2`，而不是使用所有逻辑 CPU 核心。您将看到如下消息： ``` Detected GPU VRAM: 8.0 GB (< 16 GB) -- limiting CUDA build to -j 2 ``` **手动覆盖：** 如果您仍然遇到 OOM 错误，请通过编辑相关脚本中的构建调用来进一步降低并行度，或者在构建前关闭其他消耗 GPU 资源较大的应用程序。

标签：Agent, AI合规, DLL 劫持, Vectored Exception Handling, 大语言模型, 实时告警, 应用安全, 本地部署, 模型量化, 视觉语言模型, 长上下文