Ternary-Bonsai-2-27B-MTP Linux部署教程:4条命令启动32K上下文OpenAI兼容API

原创2026-11-10 12:40:452,183 阅读

Ternary-Bonsai-2-27B-MTP Linux部署教程:4条命令启动32K上下文OpenAI兼容API

Ternary-Bonsai-2-27B-MTP 是一款内置 MTP 投机解码加速的开源本地大语言模型,基于 Ternary Bonsai 2 27B(PQ2_0 三值量化底座)加训了 Q8_0 量化的 MTP 预测头。在 Linux + NVIDIA 显卡上,只需 4 条命令即可部署,启动后默认提供 32768 token 上下文、OpenAI 兼容的 /v1 API,可直接对接 OpenAI SDK 及各类兼容客户端。

📋 部署前:环境要求一览

项目 要求
系统 Linux x86-64
显卡 NVIDIA Blackwell 架构(SM120,如 RTX PRO 6000)
CUDA 13.3 运行时 / 兼容的 NVIDIA 驱动
磁盘 ≥ 20 GB(模型约 7.1 GB + 运行时与缓存空间)

⚠️ 预编译 Linux 运行时 runtime/llama-bonsai-mtp-linux-cuda13.3-sm120.tar.gz 针对 SM120 Blackwell 编译。其他 GPU 需用仓库内精确源码自行构建:bash runtime/build-runtime.sh(源码见 runtime/prism-dflash2-source.tar.gz)。

🚀 四条核心部署命令

第1步:一键下载完整模型包

hf download ProCreations/Ternary-Bonsai-2-27B-MTP --local-dir bonsai-mtp

该命令会下载整合模型 Ternary-Bonsai-2-27B-PQ2_0-MTP-Q8_0.gguf(约 7.1 GB,已包含原始 PQ2_0 底座 + Q8_0 MTP 头,导出时校验过全部 851 个原始张量未被改动),以及 BF16 权重 model_mtp.safetensors、配置 mtp_config.json 和运行时压缩包。

💡 如果不方便使用 hf 命令,也可以改用 git clone https://gitcode.com/hf_mirrors/ProCreations/Ternary-Bonsai-2-27B-MTP 获取整个仓库。

第2步:SHA256 校验文件完整性

cd bonsai-mtp
sha256sum -c SHA256SUMS

SHA256SUMS 包含仓库内每个文件的官方校验值。建议首次启动前执行一次,确认模型权重与运行时文件完整无损。

第3步:解压 CUDA 13.3 运行时

tar -xzf runtime/llama-bonsai-mtp-linux-cuda13.3-sm120.tar.gz -C runtime

解压出预编译的 llama-server 可执行文件与依赖库到 runtime/bin/。该运行时已内置 Bonsai MTP 嵌入修复,无需 Python、无需编译器、无需安装 CUDA 工具包。

第4步:一条命令启动 OpenAI 兼容 API

bash serve.sh

启动脚本 serve.sh 已配置好推荐参数:

  • --spec-type draft-mtp --spec-draft-n-max 2:开启 MTP 投机解码,最多 2 个草稿 token
  • -c 32768:32K 上下文
  • --reasoning-effort medium:中等推理强度,不限制思考 token
  • -ngl 999 -fa on:全部层卸载到 GPU 并开启 Flash Attention
  • --temp 1 --top-p 0.95 --top-k 20:与官方测试一致的采样参数

启动完成后,服务监听 http://127.0.0.1:8080/v1,用任意 OpenAI 兼容客户端即可调用。curl 快速验证:

curl http://127.0.0.1:8080/v1/chat/completions \
  -H "Content-Type: application/json" \
  -d '{"model":"bonsai2-mtp","messages":[{"role":"user","content":"你好,介绍一下你自己"}]}'

模型别名 bonsai2-mtp 由 serve.sh 中的 --alias 参数指定。

⚡ MTP 加速实测效果

这个模型的亮点是 MTP(Multi-Token Prediction)预测头:约 4.2 亿参数的单预测层,由 Qwen3.8-27B 蒸馏而来(结构详见 mtp_config.json)。它先快速"起草"最多 2 个 token,再由主模型一次性验证,显著减少逐 token 生成耗时:

测试环境 实测结果
官方环境(RTX PRO 6000 96GB,32K 上下文) 169.25 decode tok/s,草稿接受率 58.58%
社区复现(RTX 4080 SUPER 16GB,WSL2/CUDA 13.3) 比同模型关闭 MTP 快 1.338 倍,整体草稿接受率 68.1%

详细数据可查阅 reports/community-reproduction-20260919.json 与 README.md。

🛠️ 常用配置:环境变量速查

serve.sh 通过环境变量覆盖默认启动设置,无需改脚本:

环境变量 作用 默认值
PORT API 端口 8080
CONTEXT 上下文长度(token) 32768
DRAFT_TOKENS MTP 最大草稿 token 数 2
LLAMA_BIN_DIR 运行时目录 runtime/bin
BONSAI_MODEL 自定义模型文件路径 内置 GGUF
MMPROJ 视觉投影器文件路径 不加载

显存吃紧时降低上下文:

CONTEXT=8192 PORT=9090 bash serve.sh

🖼️ 可选:启用视觉能力

默认不捆绑视觉投影器。如需图片理解,先下载并校验 mmproj 文件,再通过 MMPROJ 传入:

python download-vision.py
MMPROJ=./Ternary-Bonsai-2-27B-mmproj-Q8_0.gguf bash serve.sh

download-vision.py 会自动拉取官方 Q8_0 mmproj 并做 SHA256 断言校验。

❓ 常见问题

Q1:其他机器能访问这个 API 吗? 服务默认只绑定 127.0.0.1 回环地址(安全考虑)。远程使用建议走 SSH 端口转发:ssh -L 8080:127.0.0.1:8080 user@服务器。

Q2:显卡不是 Blackwell(SM120)怎么办? 执行 bash runtime/build-runtime.sh 从内置精确源码构建运行时,再按脚本打印的路径设置 LLAMA_BIN_DIR 后运行 bash serve.sh。

Q3:显存大概需要多少? 模型本体约 7.1 GB,加上 32K 上下文的 KV 缓存与计算缓冲,建议 20 GB 以上显存以保证全 GPU 卸载;显存不足时可将部分层卸载到 CPU,但速度会明显下降。

Q4:MTP 会影响输出质量吗? 不会。MTP 只加速解码:每个被接受的 token 都由底座模型最终采样/验证,851 个原始底座张量在导出后逐一校验保持字节级不变。

📁 关键文件索引

文件 说明
Ternary-Bonsai-2-27B-PQ2_0-MTP-Q8_0.gguf 整合推理模型(底座 + MTP 头,Q8_0)
model_mtp.safetensors / mtp_config.json BF16 主权重与 MTP 头配置
serve.sh Linux 启动脚本(本教程主角)
SHA256SUMS / manifest.json 文件校验清单与完整文件列表
download-vision.py 视觉投影器下载与校验
TRAINING.md MTP 头训练方法与复现指南
reports/ 基准测试、数值一致性、数据来源报告

四步部署完成,你已经拥有一个 32K 上下文、带 MTP 加速、开箱即用的 OpenAI 兼容本地模型 API,祝使用愉快 🎉

登录后查看全文
Ternary-Bonsai-2-27B-MTP