llama.cpp

Pi支持llama.cpp路由器服务器。路由器发现多个GGUF模型并按需加载或卸载它们。

使用具有路由器支持的当前 llama.cpp 版本。按照 build instructions 操作或为您的平台安装 prebuilt release。

启动路由器

从 llama-server 开始，没有 --model 或 -m。传递模型会启动单模型模式而不是路由器模式。

llama-server \
  --models-dir ~/models \
  --no-models-autoload \
  --jinja \
  --host 127.0.0.1 \
  --port 8080 \
  -ngl 999 \
  -c 32768

重要选项：

--models-dir ~/models 发现本地GGUF 文件。
--no-models-autoload 通过/llama 保持显式加载。
--jinja 支持兼容的聊天模板和工具调用。
-ngl 999 将尽可能多的层卸载到 GPU。
-c 32768 设置每个加载模型的上下文窗口。省略它以使用模型的本机上下文，这可能需要更多的内存。

单文件模型可以直接位于模型目录中。将多模式和多分片模型放在单独的子目录中：

~/models/
├── llama-3.2-1b-Q4_K_M.gguf
├── gemma-3-4b-it-Q4_K_M/
│   ├── gemma-3-4b-it-Q4_K_M.gguf
│   └── mmproj-F16.gguf
└── large-model-Q4_K_M/
    ├── large-model-Q4_K_M-00001-of-00003.gguf
    ├── large-model-Q4_K_M-00002-of-00003.gguf
    └── large-model-Q4_K_M-00003-of-00003.gguf

手动添加文件后重启路由器。对于每个模型的上下文大小和其他选项，请使用 llama.cpp model presets。

配置Pi

启动 Pi 并配置提供程序：

/login llama.cpp

输入路由器 URL 和可选的 API key。默认 URL 为 http://127.0.0.1:8080。

环境变量可以在没有/login的情况下配置相同的值：

export LLAMA_BASE_URL=http://127.0.0.1:8080
export LLAMA_API_KEY=optional-secret
pi

如果服务器使用 API key，则以匹配的 --api-key 值开始 llama-server。保留 --host 127.0.0.1 仅用于本地访问。

管理模型

跑步：

/llama

选择一个已卸载的模型来加载它。
选择已加载的模型将其卸载。
选择 下载模型...，搜索 Hugging Face，然后选择存储库和量化。精确的 owner/repository[:quant] 值也有效。
在加载或下载过程中按 Esc 键确认取消。

Hugging Face 搜索在设置时使用 HF_TOKEN，然后检查 $HF_TOKEN_PATH、$HF_HOME/token、$XDG_CACHE_HOME/huggingface/token 和 ~/.cache/huggingface/token。搜索也无需身份验证即可运行，但受到较低的速率限制。 Pi 在下载封闭存储库及其访问页面的链接之前发出警告。 llama.cpp 服务器执行下载，因此当所选存储库需要访问时，其进程也必须具有 HF_TOKEN。

如果加载了其他模型，Pi会询问是先卸载还是保持加载。 Pi 不会静默卸载模型，也不会删除模型文件。路由器可能与其他客户端共享，因此/llama始终显示路由器的当前状态。

仅加载的模型出现在/model中。加载模型后，运行 /model 为当前 Pi 会话选择它。

如果路由器断开连接，/llama会显示重试和关闭。重试重新连接并刷新模型状态，而不重播中断的操作。

故障排除

检查路由器是否可达：

curl http://127.0.0.1:8080/health
curl http://127.0.0.1:8080/models

**/llama中没有模型：**检查--models-dir目录布局，然后重新启动路由器。
/model 中缺少模型： 首先使用 /llama 加载它。
**加载失败或使用过多内存：**降低-c或卸载另一个模型。
服务器未处于路由器模式： 在没有 --model、-m 或 -hf 的情况下启动它。