將 Pi Coding Agent 無縫對接本地 llama-server 自訂模型

| 2026-08-302026-08-30

在體驗 LLM 驅動的命令列開發工具時，許多人喜歡在本地使用 llama-server.exe 載入 GGUF 模型（如 Qwen 系列），既能節省 API 費用又能保護隱私。

不過，當嘗試將 Pi Coding Agent 連接到本地伺服器時，常會遇到 Server is not running in llama.cpp router mode 或 OpenAI API 401 Incorrect API key 等驗證錯誤。

這篇文章記錄了完整的除錯過程與最終解決方案，幫助你快速完成本地環境設定。

問題解析

為什麼預設情況下會連線失敗？

端點路由不符：Pi Agent 預設對接 llama.cpp 時，期待對方開啟多模型路由（Router Mode）。如果本地只是單純啟動單一 GGUF 模型，會無法通過驗證。
API Key 驗證攔截：如果 llama-server 開啟了 --api-key，Pi Agent 若未帶入對應金鑰，或是被預設路徑引導至 OpenAI 官方伺服器，就會觸發 401 Unauthorized 錯誤。

解決步驟

步驟一：修改 llama-server 啟動批次檔

首先，確保你的 llama-server.exe 啟動時明確設定了 API Key。

在你的批次檔（例如 start-server.bat）中加入 --api-key 參數：

DOS

"%EXE%" ^
  -m %MODEL% ^
  -c %CTX% ^
  -np %NP% ^
  -cmoe ^
  -b %BATCH% -ub %BATCH% ^
  -ngl 999 ^
  --port 8080 ^
  --host 127.0.0.1 ^
  --api-key 12345678 ^
  -fa on ^
  -rea off ^
  --reasoning-format none ^
  --temp 0.3 ^
  --top-p 0.8 ^
  --top-k 30 ^
  --repeat-penalty 1.08 ^
  --context-shift

啟動後，可以使用 CMD 的 curl 測試 OpenAI 相容端點是否正常運作：

DOS

curl http://127.0.0.1:8080/v1/models -H "Authorization: Bearer 12345678"

若有正確返回 JSON 格式的模型清單，代表伺服器端設定完成。

步驟二：配置 Pi Agent 的自訂 Provider

Pi Agent 允許透過設定檔擴充自訂的 Provider。

在 CMD 中建立並開啟設定檔：

DOS

if not exist "%USERPROFILE%\.pi\agent" mkdir "%USERPROFILE%\.pi\agent"
notepad "%USERPROFILE%\.pi\agent\models.json"

貼上以下 JSON 設定。重點在於要明確指定 "api": "openai-completions"，否則 Pi 會因為缺少通訊協定設定而報錯：

JSON

{
  "providers": {
    "local-llama": {
      "baseUrl": "http://127.0.0.1:8080/v1",
      "apiKey": "12345678",
      "api": "openai-completions",
      "models": [
        {
          "id": "models\\Qwen3.8-27B-UD-IQ1_S.gguf",
          "name": "Qwen3.8-Local",
          "contextWindow": 16384,
          "maxTokens": 4096
        },
        {
          "id": "models\\gemma-4-12B-it-qat-UD-Q4_K_XL.gguf",
          "name": "Gemma-4-12B-Local",
          "contextWindow": 16384,
          "maxTokens": 4096
        }
      ]
    }
  }
}

步驟三：驗證並啟動 Pi Agent

設定完成後，在 CMD 執行模型清單檢視指令：

DOS

pi --list-models

確認列表中出現了 local-llama 相關模型。

接著建立一個專用的啟動批次檔 run-pi.bat：

DOS

@echo off
pi --model "local-llama/models\Qwen3.8-27B-UD-IQ1_S.gguf"

執行 run-pi.bat 即可順利在 Pi Agent 中與本地模型進行對話！

總結

解決此問題的核心在於：

本地伺服器需顯式指定 API Key 並提供 OpenAI 相容端點。
Pi Agent 的 models.json 必須完整填寫 api: "openai-completions" 規範。

透過自訂 Provider 機制，不僅能繞過官方 API 限制，還能靈活切換各種在地端運行的 GGUF 大語言模型！

Max的程式語言筆記