llama.cpp 本地模型路由器

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

请使用支持 router 的最新版 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 model presets。

配置 Pi

启动 Pi 并配置 Provider（模型提供方）：

/login llama.cpp

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

如果启动路由器时使用了 --no-models-autoload，那么 /login llama.cpp 只会保存连接信息。运行 /llama 加载模型，再运行 /model 为当前会话选择已加载的模型。

也可以通过环境变量配置同样的值，无需使用 /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

• 选择未加载的模型以加载它。
• 选择已加载的模型以卸载它。
• 选择 Download model…，搜索 Hugging Face，然后选择仓库和量化版本。也支持精确的 owner/repository[:quant] 值。
• 在加载或下载过程中按 Escape，可确认取消操作。

如果设置了 HF_TOKEN，Hugging Face 搜索会使用它；否则依次检查 $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 会显示 Retry 和 Close。Retry 会重新连接并刷新模型状态，但不会重放被中断的操作。

故障排查

检查路由器是否可访问：

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。