# llama.cpp

> 让 pi 通过 llama.cpp 路由服务器加载和切换多个本地 GGUF 模型。

---

LLMS 索引： [llms.txt](/llms.txt)

---

Pi 支持 [llama.cpp](https://github.com/ggml-org/llama.cpp) 路由服务器。路由器会发现多个 GGUF 模型，并按需加载或卸载它们。

请使用支持路由器功能的较新版本 llama.cpp。可以按照[构建说明](https://github.com/ggml-org/llama.cpp/blob/master/docs/build.md)自行构建，或为你的平台安装[预编译版本](https://github.com/ggml-org/llama.cpp/releases)。

## 启动路由器 {#start-the-router}

启动 `llama-server` 时不要带 `--model` 或 `-m`。如果传入模型，则会进入单模型模式而非路由器模式。

```bash
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` 为每个已加载的模型设置上下文窗口。如果省略，则使用模型的原生上下文，这可能会显著增加内存占用。

单文件模型可以直接放在模型目录中。多模态和多分片模型请放在单独的子目录中：

```text
~/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 模型预设](https://github.com/ggml-org/llama.cpp/blob/master/tools/server/README.md#model-presets)。

## 配置 Pi {#configure-pi}

启动 Pi 并配置提供商：

```text
/login llama.cpp
```

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

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

也可以通过环境变量配置相同的值，无需 `/login`：

```bash
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` 可将访问限制在本地。

## 管理模型 {#manage-models}

运行：

```text
/llama
```

- 选择一个未加载的模型即可加载它。
- 选择一个已加载的模型即可卸载它。
- 选择 **Download model…**，搜索 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` 会显示 **Retry** 和 **Close**。重试会重新连接并刷新模型状态，但不会重放被中断的操作。

## 故障排除 {#troubleshooting}

检查路由器是否可达：

```bash
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`。

---

反链：

- [提供商](/book/pi/providers/)
- [使用 Pi](/book/pi/usage/)