Bonsai 本地大模型通用优化工程方案

1. 硬件瓶颈与设计边界

在边缘设备与消费级移动工作站（RTX 5060 Laptop，8GB VRAM）部署 27B 参数级的大语言模型并开启 65,536（64k）长上下文窗口，面临着极为苛刻的显存物理极限：

• 权重显存开销：采用三值化（Ternary/PQ2）量化后，模型静态权重占用约为 6.15 GB；
• 显存物理瓶颈：系统与桌面渲染占用约 0.4 GB，留给推理运行时（KV Cache + Scratch Buffer）的物理显存仅剩 1.45 GB；
• 单槽限制：为保证 65k 上下文不发生 CUDA OOM（显存溢出崩服），后端 llama-server 必须固定配置为单并发槽位（-np 1）。

2. 生产双层拓扑架构

为解耦“底层推理加速”与“上游网关治理”，系统构建了严格的生产双层反向代理拓扑：

[OpenAI 客户端 / IDE / Agent 网关]
         │  HTTP / SSE
         ▼
[Bonsai Proxy v3 (反向代理服务) :8080]
   ├── 1. 预算闸门检查 (56,320 token / chars_floor=1.5 拦截)
   ├── 2. 结构瘦身与提示词优化 (Prompt Sanitization)
   ├── 3. 独立增量 SSEParser 流式透传
   ├── 4. 客户端提前断开感知 (client_gone_peek 早退检测)
   └── 5. 400 异常与耗时全维度遥测埋点
         │  HTTP / Keep-Alive
         ▼
[llama-server (推理后端内核) :8081]
   ├── 权重加载: Ternary-Bonsai-2-27B
   ├── 上下文分配: -c 65536, -np 1
   └── 硬件调度: CUDA 12.8 / Flash-Attention / 无锁内存映射

3. 阶段 B: 唯一配置与防误杀启动治理

3.1 历史缺陷与根因 (P01 / P07)

优化前，系统存在 8 个分散的启动脚本，每个脚本硬编码不同的参数（如 -c 32768 vs -c 65536、--reasoning-budget 20480 丢失），导致“手册参数 ≠ 实际运行参数”。更严重的是，旧探活脚本在推理排队超过 10 秒时判定为“僵死”，直接执行 taskkill /F :8080 强杀端口，造成健康长任务被频繁误杀。

3.2 治理落地方案

• 收敛权威配置源：建立全局唯一配置 config/bonsai-agent.json，所有后端参数、代理规则、超时时间全部由 JSON 单源驱动；
• 重构启动管理器：编写 launcher/bonsai_launcher.py，启动前校验 PID 进程身份，服务繁忙时拒绝暴力重启；废除端口强杀逻辑。

4. 阶段 C: Proxy v3 零拷贝流式转发与提前早退机制

4.1 流式读取卡顿修复 (C1)

旧代理使用固定大小的 resp.read(2048) 阻塞读取，导致流式打字机效果出现严重停顿。新版全量采用 resp.read1(65536)（有数据即刻返回），彻底消除网络中间缓冲延迟。

4.2 独立增量 SSEParser

自研增量流式解析器，支持跨网络数据块的 UTF-8 多字节截断拼接、多事件同块拆解，并独立分段累计 reasoning_content（思考链）、content（正文）与 tool_calls.arguments（工具调用参数）。

4.3 客户端断开早退检测 (client_gone_peek)

def client_gone_peek(sock) -> bool:
    """通过非阻塞探测 socket 接收缓冲区，判断下游客户端是否已关闭连接"""
    try:
        r, _, _ = select.select([sock], [], [], 0)
        if r:
            buf = sock.recv(1, socket.MSG_PEEK)
            if not buf:
                return True # EOF: 客户端已正常关闭
    except (ConnectionResetError, BrokenPipeError, OSError):
        return True # RST: 客户端强制断开
    return False

在单槽推理服务中，用户若点击“停止生成”，代理立即通过该机制检测到客户端断开，瞬时断开上游后端连接，释放推理槽位，避免 GPU 继续做数万步无效推理。

5. 阶段 D/E: 56k 空间硬预算与数学推导

在总上下文为 65,536 Token 的单槽环境中，若客户端传入了 62,000 Token 的历史记录，模型仅剩 3,536 Token 空间可用于思考和输出，极易在输出中间遭遇 STOP_TYPE_LIMIT 强行截断，破坏 JSON 输出或导致代码缺失。

6. 阶段 G14: Reject 闸门模式与 Floor 保护实测

在 G14 阶段，系统正式将生产预算闸门由观测模式切换为 强制拒绝模式 (mode: reject)，并引入了字符级快速估算下界保护：

# 预算闸门核心保护逻辑
chars_floor = config.get("chars_per_token_floor", 1.5)
min_chars_limit = int(56320 * chars_floor) # = 84,480 字符

# 当请求文本总字符数超过下界且实际 token 估算超限时：
if estimated_tokens > 56320:
    return Response(
        status_code=400,
        content={"error": {"message": "input_over_budget: context exceeds 56320 limit", "type": "invalid_request_error"}}
    )

实测成效：彻底封堵了超长历史注入拖垮后端的重大风险，超限请求在 1.2 毫秒内快速返回 400 失败，保护后端零显存冲击。

7. 阶段 G15: 客户端 400 行为观测埋点与分析

为了追踪客户端（如 WorkBuddy、Pi 或自动化脚本）在面对 400 拒绝时的真实反应，代理层在 G15 阶段部署了全量观测埋点：

8. 唯一配置规范 (JSON)

生产环境权威配置路径：D:\Bonsai-demo\config\bonsai-agent.json

{
  "server": {
    "host": "127.0.0.1",
    "port": 8081,
    "model_path": "models/bonsai2-gguf/27B/Ternary-Bonsai-2-27B-PQ2_0.gguf",
    "ctx_size": 65536,
    "n_parallel": 1
  },
  "proxy": {
    "listen_port": 8080,
    "upstream_url": "http://127.0.0.1:8081",
    "budget": {
      "mode": "reject",
      "max_input_tokens": 56320,
      "chars_per_token_floor": 1.5
    },
    "timeouts": {
      "connect_s": 5,
      "first_response_s": 30,
      "stream_idle_s": 300,
      "overall_s": 3600,
      "client_write_s": 120
    }
  }
}

9. OpenAI 接口兼容使用手册

客户端应始终连接代理端口 :8080 享受保护，严禁绕过代理直连后端：

# 快速冒烟验证 (PowerShell)
Invoke-RestMethod -Method Post -Uri "http://127.0.0.1:8080/v1/chat/completions" `
  -ContentType "application/json" `
  -Body (@{
      model = "bonsai-2-27b"
      messages = @(@{ role = "user"; content = "请分析系统瓶颈。" })
      max_tokens = 512
      stream = $true
  } | ConvertTo-Json)

10. 架构工程权衡与反思 (Trade-offs)