Pi Agent 与 llama.cpp 本地模型
Pi Agent 内置了对 llama.cpp 的支持，让你可以在本地运行开源大模型，无需云端 API。
什么是 llama.cpp
llama.cpp 是一个高性能的 LLM 推理引擎，可以在消费级硬件上运行开源大语言模型。
它支持 CPU 推理（通过量化技术大幅降低内存需求）和 GPU 加速（CUDA、Metal、Vulkan 等）。
Pi Agent 通过 llama.cpp 路由器服务器 与本地模型通信。
配置 llama.cpp
登录 llama.cpp
在 Pi Agent 交互模式中：
/login llama.cpp
管理本地模型
使用 /llama 命令管理本地模型：
# 下载模型 /llama download # 加载模型到内存 /llama load # 卸载模型 /llama unload # 查看已加载的模型 /llama list
切换到本地模型
使用 /model 命令或 Ctrl+L 选择已加载的本地模型。
推荐的开源模型
以下是一些适合本地运行的开源编码模型：
| 模型 | 参数量 | 最低显存/内存 | 适用场景 |
|---|---|---|---|
| Qwen 2.5 Coder | 7B / 14B / 32B | 8G / 16G / 32G | 通用编码、多语言 |
| DeepSeek Coder V2 | 16B / 236B | 16G / 很大 | 复杂编程任务 |
| CodeLlama | 7B / 13B / 34B | 8G / 16G / 32G | 代码补全、通用编码 |
| Mistral | 7B | 8G | 轻量级编码助手 |
本地模型的编码能力通常弱于云端顶级模型（如 Claude Sonnet、GPT-4o），但在网络受限、数据敏感性要求高或需要频繁使用的场景下是非常好的替代方案。
模型存储
下载的模型文件默认存储在 ~/.pi/agent/models/ 目录中。
模型文件通常较大（几 GB 到几十 GB），请确保有足够的磁盘空间。
自定义 llama.cpp 服务器
如果你的 llama.cpp 服务器运行在非默认端口或远程机器上，可以创建自定义提供商配置。
在扩展中注册 llama.cpp 提供商：
实例
pi.registerProvider("llama.cpp", {
name: "本地 llama.cpp",
baseUrl: "http://localhost:8080/v1",
apiKey: "local",
api: "openai-completions",
// 动态发现已加载的模型
async refreshModels({ signal }) {
const response = await fetch(
"http://localhost:8080/v1/models",
{ signal }
);
const { data } = await response.json();
return data.map(({ id }) => ({
id,
name: id,
reasoning: false,
input: ["text"],
cost: {
input: 0,
output: 0,
cacheRead: 0,
cacheWrite: 0,
},
contextWindow: 128000,
maxTokens: 16384,
}));
},
});
name: "本地 llama.cpp",
baseUrl: "http://localhost:8080/v1",
apiKey: "local",
api: "openai-completions",
// 动态发现已加载的模型
async refreshModels({ signal }) {
const response = await fetch(
"http://localhost:8080/v1/models",
{ signal }
);
const { data } = await response.json();
return data.map(({ id }) => ({
id,
name: id,
reasoning: false,
input: ["text"],
cost: {
input: 0,
output: 0,
cacheRead: 0,
cacheWrite: 0,
},
contextWindow: 128000,
maxTokens: 16384,
}));
},
});
这个动态发现模式让 Pi Agent 能实时获取 llama.cpp 服务器上当前已加载的模型列表。
本地模型的局限性
使用本地模型时需要注意以下几点：
- 工具调用能力：部分开源模型的工具调用（tool calling）能力较弱，可能无法正确使用 Pi Agent 的内置工具
- 推理速度：在没有 GPU 加速的情况下，推理速度可能较慢
- 上下文长度：本地模型的有效上下文窗口通常小于云端模型
- 推理等级：非推理型模型始终以 off 运行，无法使用推理等级功能
推荐的混合策略：在需要深度推理和复杂编码时使用云端模型（如 Claude Sonnet），在日常简单任务或网络受限时切换到本地模型。使用 Ctrl+P 可以快速在两个模型间切换。