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

| 2026-08-302026-08-31

在體驗 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 參數：

set MODEL=models\Qwen3.8-27B-UD-IQ1_S.gguf
set EXE=llama-server.exe

REM Large context for long code.
set CTX=16384
set BATCH=512
set NP=1

"%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

上面參數微調, 參考看看: 「思維鏈坍塌」超低位元量化模型遇到無休止內部思考、自我糾正
https://stackoverflow.max-everyday.com/2026/08/chain-of-thought-collapse/

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

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

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

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

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

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

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

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

{
  "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 執行模型清單檢視指令：

pi --list-models

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

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

@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 大語言模型！

選 llama.cpp 比較好的感覺, 可以設定的參數比較多.

ollama 與 llama.cpp 底層皆基於 C/C++ 的推論引擎，但兩者的定位、使用對象與專案目標有著本質上的不同：

特性	llama.cpp	Ollama
主要定位	底層推論核心 / 開發者工具	上層封裝與管理工具 / 終端使用者應用
使用門檻	較高（需熟悉指令列參數、自行下載模型與設定）	極低（一鍵安裝，具備類似 Docker 的指令與體驗）
模型格式	GGUF	Modelfile（內部打包並調用 GGUF）
服務架構	原生編譯後為單一可執行檔或 C++ 函式庫	後台背景服務 (Daemon) + CLI 前端
生態系統	提供各種綁定 (Python, Rust 等) 與低階 API	提供相容 OpenAI 的 REST API，整合開源 UI 極佳

關鍵差異解析

1. llama.cpp：極致效能與底層控制

核心價值：由 Georgi Gerganov 開發，旨在讓大型語言模型能在無 GPU 或硬體受限的普通消費級設備（如 Mac Apple Silicon、普通 PC）上高效運行。
優勢：
- 細粒度控制：可直接調整 KV 快取、GPU 層數分流 (-ngl)、Context 長度、Sampler 參數等。
- 高擴充性：身為基礎架構，被無數上層工具（如 Python 庫 llama-cpp-python、text-generation-webui 等）整合。
劣勢：設定繁瑣，下載的模型需要手動管理檔案路徑與參數設定。

2. Ollama：極簡體驗與模型生態

核心價值：將 llama.cpp 包裝成極簡化的桌面/伺服器工具，核心體驗借鑑了 Docker。
優勢：
- 開箱即用：只需執行 ollama run llama3，就會自動下載模型並直接啟動對話。
- 模型庫管理：擁有官方模型庫 (library)，下載與更新非常方便。
- 標準化 API：預設提供開箱即用的 REST API，能 seamlessly 介接 Open WebUI、AnythingLLM 或各類本地插件。
劣勢：預設封裝隱藏了許多底層參數，若要高度客製化推論細節，需要透過編輯 Modelfile 完成。

該如何選擇？

選 Ollama：如果你想要快速在本地端跑起 LLM、連結現成的 Web UI，或是為自己的應用程式快速接上本地 API。
選 llama.cpp：如果你是 C/C++ 開發者、需要整合嵌入式系統、或者需要對硬體推論細節進行極致優化與自訂。

Max的程式語言筆記