使用本地 llama.cpp 模型运行 Bub

让 Bub 应用调用本机的 llama.cpp 服务。本指南启动一个 GGUF Gemma 模型，检查其 OpenAI 兼容端点，再设置应用的模型地址。

示例使用 ggml-org/gemma-4-E2B-it-GGUF，这是 Google Gemma 4 E2B 经过指令微调的模型的 GGUF 版本。Google 的 Gemma 4 overview 把 E2B 和 E4B 描述为适合移动和边缘设备的高效模型；Gemma 4 model card 记录了能力、限制和负责任使用相关注意事项。

开始前

你需要：

Bub 已安装，且 bub --help 可以运行。
已安装 Docker。
~/.cache/llama.cpp/ 下有 GGUF 模型文件。
系统内存足够运行所选量化版本。Gemma 4 E2B 的 Q8 GGUF 文件约 5 GB；实际运行内存还会受上下文长度、批处理、GPU 卸载等设置影响。

本教程使用下面两个文件名：

~/.cache/llama.cpp/ggml-org_gemma-4-E2B-it-GGUF_gemma-4-E2B-it-Q8_0.gguf
~/.cache/llama.cpp/ggml-org_gemma-4-E2B-it-GGUF_mmproj-gemma-4-E2B-it-Q8_0.gguf

如果你的文件名不同，需要相应修改 Docker 命令里的 -m 和 --mmproj 路径。

1. 启动本地 server

先为本地服务设置一个 API 密钥：

export LLAMA_API_KEY="${LLAMA_API_KEY:-test}"

启动 llama-server：

sudo docker run --rm -it \
  --security-opt label=disable \
  -p 127.0.0.1:8080:8080 \
  -v "$HOME/.cache/llama.cpp:/root/.cache/llama.cpp:ro" \
  ghcr.m.daocloud.io/ggml-org/llama.cpp:full \
  --server \
  --host 0.0.0.0 \
  --port 8080 \
  --api-key "$LLAMA_API_KEY" \
  -m /root/.cache/llama.cpp/ggml-org_gemma-4-E2B-it-GGUF_gemma-4-E2B-it-Q8_0.gguf \
  --mmproj /root/.cache/llama.cpp/ggml-org_gemma-4-E2B-it-GGUF_mmproj-gemma-4-E2B-it-Q8_0.gguf

Docker 端口绑定到 127.0.0.1，因此这个服务只在本机可访问。只有在明确需要其他机器访问时，才调整端口绑定。

在 SELinux 系统上，--security-opt label=disable 可以避免容器读取 ~/.cache/llama.cpp 下模型文件时遇到 bind mount 权限问题。如果只需要文本输入，可以删除 --mmproj 那一行。

如果 Docker 输出 no ROCm-capable device is detected，容器仍然可能回退到 CPU 推理。这足够验证接入路径，但响应速度会更慢。

2. 测试 OpenAI-compatible API

在另一个终端发送一个小 chat 请求：

curl http://localhost:8080/v1/chat/completions \
  -H "Authorization: Bearer $LLAMA_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "gemma-4-E2B-it",
    "messages": [
      {"role": "user", "content": "hello"}
    ]
  }'

正常工作的服务会返回一个 chat.completion JSON 对象，其中包含助手消息。

3. 配置 Bub

把 Bub 指向本地服务：

export BUB_API_BASE="http://localhost:8080/v1"
export BUB_API_KEY="$LLAMA_API_KEY"
export BUB_MODEL="openai:gemma-4-E2B-it"

运行一个 Bub 轮次：

bub run "Reply with one short sentence: hello from a local model."

现在 Bub 会通过本地 OpenAI 兼容端点进行模型调用。应用轮次流程、渠道、tools 和 Tape 都不需要改变。

~/bubbuild/bub$ bub run "Reply with one short sentence: hello from a local model."
2026-05-19 01:32:40.601 | INFO     | bub.builtin.agent:_run_tools_with_auto_handoff:271 - loop.step step=1 tape=becda04eb9f7369c__0b871d5e50e7c192 model=openai:gemma-4-E2B-it
2026-05-19 01:32:46.747 | INFO     | bub.builtin.store:fork:122 - Merged 7 entries into tape "becda04eb9f7369c__0b871d5e50e7c192"
[cli:local]
hello from a local model.

4. 更换工作负载前检查模型文档

当你切换模型或量化版本时，先检查上游模型文档：

Hugging Face GGUF card 会列出支持的本地运行方式和可用量化文件。
Gemma 4 model card 会说明输入模态、上下文窗口、预期用途、许可和风险。
用有代表性的任务评估模型，检查回答中的错误、偏见和安全问题。

如果任务更看重延迟、隐私、成本或离线能力，可以先尝试小型本地模型。面向用户上线前，用实际任务确认回答质量。

清理

用 Ctrl-C 停止 Docker 容器。

如果要恢复到之前的提供商，清理 Bub 覆盖配置：

unset BUB_API_BASE BUB_API_KEY BUB_MODEL LLAMA_API_KEY