Ternary-Bonsai-2-27B-MTP Linux部署教程:4条命令启动32K上下文OpenAI兼容API
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,祝使用愉快 🎉