llama.cpp

Pi 支持 llama.cpp 模型路由器（model router）服务器。该模型路由器能发现多个 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 密钥，请用匹配的 --api-key 值启动 llama-server。保持 --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。