llama.cpp

Pi支援llama.cpp路由器伺服器。路由器發現多個GGUF模型並按需載入或卸載它們。

使用具有路由器支援的當前 llama.cpp 版本。按照 build instructions 操作或為您的平台安裝 prebuilt release。

啟動路由器

從 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 並配置提供者：

/login llama.cpp

輸入路由器 URL 和可選的 API key。預設 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 key，則以符合的 --api-key 值開始 llama-server。保留 --host 127.0.0.1 僅用於本地存取。

管理模型

跑步：

/llama

選擇一個已卸載的模型來載入它。
選擇已載入的模型將其卸載。
選擇 下載模型...，搜尋 Hugging Face，然後選擇儲存庫和量化。精確的 owner/repository[:quant] 值也有效。
在載入或下載過程中按 Esc 鍵確認取消。

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 的情況下啟動它。