llama.cpp

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

使用支持路由器功能的当前 llama.cpp 构建版本。请遵循构建说明或安装适用于您平台的预构建版本。

启动路由器

启动 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 模型预设.

配置 Pi

启动 Pi 并配置提供商：

/login llama.cpp

输入路由器 URL 和可选的 API 密钥。默认 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 密钥，请使用匹配的 llama-server 值启动 --api-key。对于仅本地访问，请保留 --host 127.0.0.1。

管理模型

运行：

/llama

选择一个未加载的模型以加载它。
选择一个已加载的模型以卸载它。
选择 下载模型…，搜索 Hugging Face，然后选择一个仓库和量化方式。也可以使用精确的 owner/repository[:quant] 值。
在加载或下载过程中按 Escape 键确认取消。

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.