使用 llama.cpp 运行本地模型

本页面是 Pi 官方文档的中文翻译。仅供学习参考。

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

安装 llama.cpp

curl -LsSf https://llama.app/install.sh | sh

验证安装：

llama --version

其他安装方式（包括包管理器和从源码构建）见 llama.app。

启动 router

启动 llama serve 时不要传 --model、-m 或 -hf。传入模型会启动单模型模式而不是 router 模式。router 配置见 llama.cpp server 指南。

llama serve \
  --no-models-autoload \
  -ngl all \
  -c 32768

重要选项：

--no-models-autoload 让加载只通过 /llama 显式进行。
-ngl all 把所有层卸载到 GPU。省略它则使用自动 GPU 卸载。
-c 32768 以 Token 为单位设置上下文大小。用 -c 0 表示模型的完整上下文窗口，这可能显著增加内存需求。上下文在并行的 server slot 之间共享。

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

~/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

手动添加文件后重启 router。router 还通过 --models-preset 支持缓存模型和预设文件，见 server 指南。

配置 Pi

启动 Pi 并配置 Provider：

/login llama.cpp

输入 router URL 和可选的 API Key。默认 URL 是 http://127.0.0.1:9931。

如果你用 --no-models-autoload 启动 router，/login llama.cpp 只保存连接。运行 /llama 加载模型，然后用 /model 为当前会话选择已加载的模型。

不用 /login 也可以用环境变量配置相同的值：

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

如果服务器使用 API Key，请用匹配的 --api-key 值启动 llama serve。只在本机访问时保留 --host 127.0.0.1。

管理模型

运行：

/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 不会静默卸载模型，也从不删除模型文件。Router 可能与其他客户端共用，所以 /llama 总是显示 router 的当前状态。

已加载和休眠的模型都会出现在 /model 中。休眠模型在被选中时自动唤醒。启用 router 自动加载时，未加载的预设模型也会出现，并在选中时加载。使用 --no-models-autoload 时，先通过 /llama 加载模型再选择它。

如果 router 断开连接，/llama 会显示 Retry 和 Close。Retry 会重新连接并刷新模型状态，而不重放被中断的操作。

分类

分类器模型回答关于 JSON 状态的带类型 choice、bool 和 score 问题，类似 TypeSafe 的 Jev 模型。模型通过 codemode 脚本以及扩展的 ctx.modelRegistry.classify() 到达它们；见分类器模型。Pi 以两种方式把 llama.cpp 模型列为分类器：

决策模型，例如 Julia-1、Laya、Kev、lev 和 OpenJev，通过 llama.cpp 的 /v1/systemone 端点原生作答。它们只作为分类器出现，API 为 typesafe-system-one，不出现在 /model 中。
聊天模型也会以相同 ID 和 llama-cpp-classify API 列为分类器，该 API 按下文所述从下一个 Token 的概率读取答案。

llama.cpp 0.6.0 及之后版本会在 router 的模型列表中报告决策模型：它们的 architecture.output_modalities 包含 decisions。router 从 GGUF 元数据读取这一信息，无需加载模型，因此 Pi 也能识别未加载和休眠的决策模型。更早的 llama.cpp 构建不会报告它，Pi 会把它们的决策模型列为聊天模型。

聊天模型作为分类器

模型并不生成答案。每个问题变成一条 chat Prompt：状态、该请求的全部问题、状态再出现一次，然后是该问题及其答案（用单 Token 标签）。choice 的标签是字母（最多 62 个选项），bool 是 Yes/No，score 是数字（最多 10 级）。第二份状态是在已看到问题的情况下读取的，这在 JevBench 上提高了小模型的准确率。Pi 读取这些标签作为下一个 Token 的概率并做归一化。choice 返回每个选项的概率，以及置信度 (n * peak - 1) / (n - 1)；score 返回期望等级。

原始标签概率通常过于自信。每次请求的 temperature 选项在归一化之前除标签 logits；大于 1 的值会软化分布。它不改变答案。
问题依次运行。最后一问之前的内容对同一次请求的所有问题都相同，所以服务器的 Prompt 缓存只评估一次。状态出现两次，因此需要两倍大小的上下文。
小模型可能遵循写在状态内部的指令。Prompt 告诉模型把状态当作数据来判断，但这不是保证。
像 Qwen3.5 这样的混合模型，没有上下文检查点就无法回退部分缓存的 Prompt。如果每个问题都会重新处理整个状态，启动 router 时加上 --ctx-checkpoints 32 --checkpoint-min-step 0。

排查问题

检查 router 是否可达：

curl http://127.0.0.1:9931/health
curl http://127.0.0.1:9931/models

/llama 中没有模型： 检查 --models-dir、目录布局，并重启 router。
使用 --no-models-autoload 时 /model 中缺少模型： 先用 /llama 加载它。
加载失败或占用内存过多： 降低 -c，或卸载另一个模型。
服务器不在 router 模式： 启动时不要传 --model、-m 或 -hf。

要移除 llama.cpp Provider 和 /llama，在 pi config 的 Built-in 下禁用 llama.cpp，或在设置中设 "extensions": ["-builtin:llama.cpp"]。

法律声明：本页面是 pi.dev 官方文档的中文翻译版本，仅供学习参考。本网站与 pi.dev 及 Earendil Inc. 无任何法律关系。

#使用 llama.cpp 运行本地模型

#安装 llama.cpp

#启动 router

#配置 Pi

#管理模型

#分类

#聊天模型作为分类器

#排查问题