Bonsai-demo上下文长度调优：BONSAI_CTX自动RAM分层机制解析

Bonsai-demo上下文长度调优：BONSAI_CTX自动RAM分层机制解析

【免费下载链接】Bonsai-demoBonsai Demo项目地址: https://gitcode.com/GitHub_Trending/bo/Bonsai-demo

Bonsai-demo 让你在本地运行 Bonsai / Ternary-Bonsai 系列小模型（最高 27B，支持 262K 上下文），它的启动脚本通过BONSAI_CTX环境变量自动按你的内存大小分层选择上下文长度，无需手动配置即可保持内存占用可预测。本文带你拆解这套自动 RAM 分层机制的工作原理、分层档位表，以及如何手动调优上下文长度。

为什么上下文长度需要“自动分层”

上下文越长，KV 缓存占用的内存越大。以 27B 模型为例：

• 27B 支持最高262,144 tokens的训练上下文（混合注意力架构）
• FP16 KV 缓存每 token 约64 KiB，100K 上下文就需要约6.3 GiB
• 老的 8B 模型是全注意力结构，每 token 约 140 KiB，同样档位的内存代价最高约为 27B 的 2.2 倍

旧版本脚本曾直接传 llama.cpp 的-c 0（意为“使用模型完整训练上下文”），完全不感知内存，在配置有限的机器上会直接 OOM。现在的脚本改为按系统 RAM 自动分层，既安全又实用。

自动 RAM 分层的 5 档上下文表

核心逻辑在 scripts/common.sh 的bonsai_ctx_default()函数中，启动脚本 scripts/start_llama_server.sh 与 Windows 版 scripts/start_llama_server.ps1 都遵循同一套档位：

设计要点：

• 每个档位都经过最坏情况验证——例如 8B 在 65,536 上下文时总内存约 10.5 GB，仍安全落在 36 GB+ 机器之内
• 131,072 是27B 专属顶档，旧型号文档上限为 65,536
• 内存检测跨平台：macOS 用sysctl hw.memsize，Linux 读/proc/meminfo，Windows 用 WMI 查询物理内存

BONSAI_CTX 的三种取值含义

完整变量说明见 environment_variables.md，核心速记如下：

• 不设置 或BONSAI_CTX=0→ 自动模式，解析为上表对应的 RAM 分层值（注意：0不会被当作-c 0传给 llama.cpp）
• BONSAI_CTX=N（N ≤ 262144）→ 强制指定该上下文长度
• BONSAI_CTX=262144→ 强制启用 27B 的完整训练上下文，仅推荐给内存充裕的机器

日常使用的三个典型命令：

# 默认自动分层，什么都不用改 ./scripts/start_llama_server.sh # 内存紧张时手动钉住一个小上下文 BONSAI_CTX=8192 ./scripts/start_llama_server.sh # 一次性覆盖（参数直接透传给 llama.cpp） ./scripts/run_llama.sh -c 8192 -p "你的问题"

🔍 一个容易忽略的细节：开启投机解码（BONSAI_SPECULATIVE=1，仅 27B）时，由于 dspark 会重复预填充，自动模式会把上下文下限提到16,384，但显式的非零BONSAI_CTX仍然优先——详见 scripts/start_llama_server.ps1 中的注释。

极限长上下文：262144 与 4-bit KV 缓存

如果你确实需要跑满 27B 的 256K 训练上下文，脚本不会擅自替你这么做。推荐组合：

1. BONSAI_CTX=262144强制全量上下文
2. BONSAI_KV4=1启用 4-bit KV 缓存：每 token 从 64 KiB 降到约 18 KiB，100K 上下文从 6.3 GiB 降到约 1.8 GiB（约 3.5 倍节省）
3. 可选运行 scripts/make_kv_bias.sh 生成均值校准偏置文件，找回 4-bit 量化损失的精度

27B 的完整内存账本（权重 + KV 缓存 + 开销）和 KV4 的详细背景分别见 README.md 与 KV-CACHE.md。

遇到问题怎么办？

• 启动时机器卡死 / 内存爆满：钉住更小的上下文，如BONSAI_CTX=8192 ./scripts/start_llama_server.sh（README.md FAQ 收录了这一修复）
• 显存不够又要长上下文：BONSAI_MMPROJ_CPU=1把视觉投影器移到系统内存，释放约 0.9 GiB 显存给 KV 缓存
• AI 代理协作调参：AGENTS.md 中记录了BONSAI_CTX的设计约定，供 AI 编程助手参考

总结

自动 RAM 分层机制让 Bonsai-demo 在不同硬件上都能给出可预测的内存占用：小内存机器不会被默认设置拖垮，大内存机器又能自动解锁更长的上下文——这正是它相对裸跑 llama.cpp-c 0的关键改进。

【免费下载链接】Bonsai-demoBonsai Demo项目地址: https://gitcode.com/GitHub_Trending/bo/Bonsai-demo