【2026 最新】llama.cpp 1.0 升級教學：C API、CLI 與 Server 怎麼分？六步相容性驗收與回退

你昨天還能啟動本機 AI，今天把執行檔換成新版，服務卻停在「不認得參數」。另一位朋友只改 HTTP 伺服器網址，聊天仍正常。這篇 llama.cpp 1.0 升級教學，要先替你分清：你碰到的是函式庫、啟動命令，還是伺服器的行為？

前半專為沒有 C/C++ 背景的讀者寫；操作段給已經有可用 llama.cpp 與 GGUF 模型、能複製終端機指令的新手。讀完你會留下版本收據、分層相容性清單，以及能切回舊版的驗收紀錄，不必先重做安裝入門。

以下依 2026 年 11 月 15 日查閱的官方公告、v1.0.0 文件、變更差異與測試程式整理。v1.0.0 發布於 11 月 13 日；本篇提供遷移方法，未執行新舊模型推論，效能與任務結果由你的相同條件測試填寫。

先說結論：可回復升級＝分清接點＋同條件驗收＋保留退路

把 llama.cpp 想成餐廳：C API 是廚房零件的插頭，CLI 是開店清單，HTTP 是點餐窗口。換掉廚房設備，三個地方都值得檢查，但不會因為一個插頭改型，就自動證明點餐窗口的菜單全壞了。

• 程式直接載入 libllama：先走 C API／binding 路線，重新建置並核對實際載入的函式庫。
• 用命令啟動 llama-server：先掃啟動參數，再走 HTTP 回歸測試；不少人同時屬於這兩層。
• 只有使用桌面 App：先查 App 內附的引擎與升級說明；終端機裡另一份 llama.cpp 版本，不能替 App 作證。

一、llama.cpp 1.0 升級前，先認清三個接點

API 是程式之間約定好的叫法；binding 是讓 Python 等語言接到 C/C++ 函式庫的轉接器。ABI 則涉及編譯後的二進位接合規則，像插頭不只名字相同，針腳也要對上。HTTP 客戶端透過網路送 JSON，與直接載入函式庫是不同路徑。

ggml-org 官方公告把 major 版本變動連到公開 C API／ABI 的不相容邊界；版本規則表以 ./include 的公開 C API 破壞性變更為 major。這個規則幫下游辨認相容性，並不是「每個人都要重寫程式」或「所有介面永久穩定」的承諾。

先寫一行現況，例如：「聊天前端 → HTTP → 我用 Docker 啟動的 llama-server」。這一行決定你要查映像版本、容器命令與 HTTP 回應；若前端沒有載入 libllama，C 函式改名就交由真正使用函式庫的元件處理。可用 Agent Harness 的模型與執行層分工補上整張系統圖。

二、六步完成 llama.cpp 1.0 升級驗收

第 1 步：「我到底跑哪一份？」留下版本收據

先固定身分，再取得新包。從原本的工作目錄，執行實際路徑的 ./llama-server --version 與 ./llama-server --help，分別保存輸出。再抄下作業系統、CPU／GPU backend、完整啟動命令、容器映像 digest 或套件版本；API 金鑰另行安全保管，不放進公開紀錄。

舊的 b12359 這類 nightly 標籤，與 v1.0.0 的語義版本各有用途。本次官方 release 附的 nightly-tag.txt 指向 b12359。下列兩行只讀取標籤對應，不會下載模型或安裝程式：

curl -fL --retry 3 -o nightly-tag.txt \
  https://github.com/ggml-org/llama.cpp/releases/download/v1.0.0/nightly-tag.txt
cat nightly-tag.txt

選用該 nightly 頁面符合自己平台及 backend 的資產，核對頁面提供的 SHA-256，再解壓到新目錄；不要覆蓋舊目錄或混放共享函式庫。依 官方建置版本說明，開發建置可帶 -dev，所以要連同 build 與 commit 一起核對，而非只看一段版本字串。

第 2 步：「我的轉接器會壞嗎？」走 C API／binding 路線

先掃舊呼叫，再重新建置。官方清理變更 #30565移除 llama_set_warmup、llama.h 中 35 個已棄用函式，以及 context 的 defrag_thold 欄位；NextN／speculative 相關 API 移到 llama.h，其中 llama_set_embd_state_src 改名為 llama_set_ctx_state_src。

在你自己的原始碼與啟動設定目錄執行以下搜尋；有 rg 才用這條，否則以編輯器搜尋同樣字串。這只是代表性掃描，完整清單仍要逐項對照差異檔：

rg -n -- 'llama_set_warmup|defrag_thold|defrag-thold|llama_set_embd_state_src|llama-ext\.h|clip\.h|llama_load_model_from_file|llama_new_context_with_model' .

例如舊的 llama_load_model_from_file 與 llama_new_context_with_model，要按 v1.0.0 公開標頭核對 llama_model_load_from_file 與 llama_init_from_model 的簽名與生命週期。多模態使用者另查 clip.h 整併到 mtmd 的變更。不要只把名字大量取代，就跳過參數與資源釋放檢查。

用語言套件的人，先固定 binding 版本、查它對應的上游 commit，再在獨立環境重裝或建置。驗收依序是 import／連結成功、載入既有模型、建立 context、生成短答案並正常釋放；還要確認載入的 libllama 路徑。套件能 import，只過了第一關。

第 3 步：「為何重啟就倒？」走 CLI 啟動路線

清除已移除的開店項目。#30565 同時移除 -dt／--defrag-thold。檢查服務設定、Compose、容器 command、shell wrapper 與環境設定，從新版命令拿掉該參數及它的值，再讀新版 --help。C API 的 llama_set_warmup 與名稱含 warmup 的 CLI 選項要分開核對，別按相似字眼一起刪。

第一次測試沿用舊版已可工作的模型、Context、槽數、KV 型別、offload、模板與採樣設定；只修必須改的項目。先不要同時開 FP8 KV、新增 MoE cache 或換量化檔。若兩件事一起變，出錯時就多一組嫌疑。多槽與 Context 分配教學可用來補查並行設定。

第 4 步：「視窗回字就算過關？」走 HTTP 對照路線

同一考卷，只換引擎。以下是 POSIX shell 的隔離練習；把兩份完整發行包放在 ./old、./new，模型放 ./models/test.gguf。兩輪依序執行，先正常停止舊程序才啟動新程序，避免雙載入超出記憶體。這個縮小配置先驗接線，之後必須再用正式服務原設定重跑。

./old/llama-server -m ./models/test.gguf --host 127.0.0.1 --port 18080 -c 2048 -np 1 --alias migration-test
# 在另一個終端機完成測試；回到此視窗按 Ctrl-C 正常停止，再跑下一行
./new/llama-server -m ./models/test.gguf --host 127.0.0.1 --port 18081 -c 2048 -np 1 --alias migration-test

模型必須是你已可運行的聊天 GGUF，且能容納這個 Context；原有模板與 backend 選項也要在兩輪一致。到 同版 Server 文件核對參數與端點。先執行 curl -fS http://127.0.0.1:18080/health，讀到 HTTP 200 與 status: ok 才送題；載入中的 503 與正式請求失敗分開記。

curl -fS http://127.0.0.1:18080/v1/chat/completions \
  -H 'Content-Type: application/json' \
  --data '{"model":"migration-test","messages":[{"role":"user","content":"只回覆這筆工單的交付日：原訂週五，已取消週五交付，改為週一。"}],"temperature":0,"seed":42,"max_tokens":128,"stream":false}' \
  -o old-answer.json

新版把連接埠改為 18081、輸出改為 new-answer.json。先寫好通過條件：「答案是週一，沒有把週五當成有效交期」，再核對 HTTP 狀態、choices[0].message、結束原因與錯誤。固定 seed 有助追蹤；不同版本仍要按任務正確性驗收，不要求每個字相同。

接著加兩張考卷：一張用原本的 response_format 驗 JSON 欄位、值與解析；一張送同一份唯讀 tools 描述，核對工具名、參數、呼叫 ID，再回填相同的假工具結果，驗最後答案。用你既有的 SDK 與完整請求重播，比只打 curl 更能抓到客戶端相容性。

第 5 步：「舊網址突然被拒？」把三道安全門分開

先診斷限制在哪，再決定怎麼接。#32113將非 loopback 位址、未設 API key、又啟用工具／MCP 的組合改成啟動時拒絕，除非明確選用 --allow-unauthenticated-tools。升級首輪保留 127.0.0.1 與關閉工具；需要遠端服務時，先設驗證與適當的網路邊界，不把放寬旗標當成一般修復指令。

第二道是媒體抓取。#32115讓 HTTP(S) 媒體 URL 預設拒絕本機／私網目的地；--media-allow-private-urls 是特別放行媒體的開關。先用你有權使用、無私人資料的圖片測試，保存狀態碼；不要把正式內網服務拿來當測試靶。

第三道是 Web UI 的 --ui-mcp-proxy：同版文件明列它服務公共 MCP 位址，拒絕 loopback、LAN、link-local；本機服務應從 Web UI 直接連接並處理該路徑的設定。媒體放行旗標不等於 MCP proxy 私網通行證。CORS（瀏覽器跨來源存取規則）的來源還包含協定與連接埠；同一台電腦、不同 port 也要按實際 Origin 核對。

最後驗取消。官方開發文件說明：客戶端在 MCP 呼叫期間斷線或超過 timeout_ms，Server 會送 notifications/cancelled 並回報錯誤。用沒有外部副作用的慢工具測試，核對通知的 request ID、工具端紀錄與下一次請求；通知送達、工具停止、外部動作回復是不同驗收項目。

第 6 步：「新版失敗怎麼退？」先寫切回條件

回退要能照單操作。升級前保存舊發行包、完整依賴、模型指紋、啟動設定與客戶端套件鎖定檔。若新版啟動失敗、既有必過題退步、工具格式不合或存取邊界不符，就先停止測試程序，把客戶端 endpoint、服務路徑與設定切回已知可工作的舊組合，再重跑那張工單。

共用的聊天資料、快取或其他可寫狀態，先留測試前備份；測試用副本隔離。切回執行檔不能替你復原已改寫的檔案，工具已產生的外部動作也要另外確認。因此第一輪只接假資料與唯讀工具。Ollama 遷移 A/B 方法補的是跨引擎比較，本篇新增的則是 1.0 相容性接點與安全行為。

三、三個常見坑：升級、調校與換模型同時發生

第一個坑是把新增功能當成升級必選。FP8 KV、MoE cache 等變更值得另開實驗；先通過相容性基線，再一次開一個選項，才知道收益與代價來自哪裡。第二個坑是只留一個平均 Token／秒。把啟動、首字等待、完成時間、記憶體與逐題錯誤分開保存，速度改善才有上下文。

第三個坑是把 OpenAI-compatible 當成所有行為完全相同。同版 Server 文件本身就限定其相容性說法；回歸考卷要含你真正用到的欄位與工具回合。若同時想換 GGUF，先完成本輪，再依 逐檔雜湊與模型更新流程另測，不把兩筆更新混在一張成績單。

常見問題：八個先講答案的判斷

1. 版本變 1.0，模型需要重下載嗎？

先保留原檔。這次遷移先驗原本的 GGUF 與設定；只有另有檔案更新或具體相容性需求，才把下載列為另一項變更。

2. 只用 HTTP，也要改 C 函式名稱嗎？

按接點分工。HTTP 客戶端先驗端點與 JSON；真正連結 libllama 的元件才處理 C API。自行啟動 Server 的人仍要檢查 CLI。

3. binding import 成功就完成了嗎？

還要載入與生成。保留函式庫路徑、模型載入、context 建立、生成與正常釋放的紀錄，才能判斷整條路有沒有走完。

4. 看到 -dev 就下載錯了嗎？

不能只憑這段判斷。開發建置會加此尾綴；對照 release 的 nightly 指標、build 與 commit 再確認。

5. 為了恢復服務，直接開兩個 allow 旗標？

先找原因。未驗證工具與私網媒體是不同放寬範圍；預設練習保持本機綁定、不開工具、不放行私網抓取。

6. 取消通知代表工具已經復原嗎？

還要看工具結果。先驗對應 request ID 的通知，再查工具是否停止與狀態是否改變；外部副作用有自己的恢復流程。

7. 新版一定比較快嗎？

先量自己的任務。本篇未提供新舊推論成績；相容性過關後，再用同模型、同設定與同題目比較。

8. 今天只做一件事，該做哪一步？

先留版本收據。寫出「誰呼叫誰」，保存舊命令與設定，再替那張改期工單訂好通過條件。

給新手的三個重點

• 先問接在哪裡：C API、CLI、HTTP 各自需要不同證據。
• 先驗能繼續交件：文字、JSON、工具回合與取消分開過關，再談新功能。
• 先保留能回去的組合：舊包、依賴、設定、模型與可寫狀態，一起列入退路。