繁體中文文件

Pi 的配置、擴充、平台設定和 API 參考。

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 並設定 Provider：

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