測驗：llama.cpp 架設 OpenAI 相容 API Server
共 5 題，點選答案後會立即顯示結果
1. llama-server 啟動後，預設監聽的位址和埠號是什麼？
2. 使用 Python OpenAI 套件連接本地 llama-server 時，需要修改哪個參數？
3. 參數 -ngl 的作用是什麼？
4. 如果要讓其他電腦能夠連線到 llama-server，應該將 --host 參數設定為什麼？
5. 使用 -np 4 參數啟動 server 後，記憶體用量會有什麼變化？
一句話說明
把本地模型變成 API 服務，讓任何支援 OpenAI API 的程式都能用。
這篇教什麼
前三篇我們學會了下載、轉換模型，以及用命令列跑推論。但如果你想讓多個程式同時使用同一個模型，或是讓現有的 AI 工具連接本地模型，就需要架設 API Server。
llama-server 就是幹這個的：把模型包成 HTTP API，而且相容 OpenAI 格式，幾乎不用改程式碼就能切換。
最小範例：啟動 Server
llama-server -m qwen2.5-coder-7b-instruct-q4_k_m.gguf
Code language: CSS (css)這行在幹嘛：啟動一個 HTTP server，載入指定模型，預設在 http://127.0.0.1:8080 提供服務。
啟動後你會看到：
main: server is listening on http://127.0.0.1:8080 - starting the main loop
Code language: JavaScript (javascript)打開瀏覽器訪問 http://127.0.0.1:8080，會看到內建的 Web 聊天介面。
用 curl 測試 API
在另一個終端機測試：
curl http://localhost:8080/v1/chat/completions \
-H "Content-Type: application/json" \
-d '{
"model": "gpt-3.5-turbo",
"messages": [
{"role": "user", "content": "用一句話解釋什麼是 API"}
]
}'
Code language: PHP (php)逐行翻譯：
curl http://localhost:8080/v1/chat/completions \ # 呼叫聊天補全 API
-H "Content-Type: application/json" \ # 告訴 server 我們送 JSON
-d '{ # 以下是請求內容
"model": "gpt-3.5-turbo", # model 名稱（本地會忽略，填什麼都行）
"messages": [ # 對話紀錄
{"role": "user", "content": "..."} # 使用者說的話
]
}'
Code language: PHP (php)回應會是這樣：
{
"choices": [
{
"message": {
"role": "assistant",
"content": "API 是讓不同程式互相溝通的介面，就像餐廳的菜單讓你點餐。"
}
}
]
}
Code language: JSON / JSON with Comments (json)Python 整合範例
用 OpenAI 官方套件連接本地 Server：
from openai import OpenAI
# 建立客戶端，指向本地 server
client = OpenAI(
base_url="http://localhost:8080/v1", # 改成本地位址
api_key="no-key-needed" # 本地不需要 API key
)
# 跟平常用 OpenAI 一模一樣
response = client.chat.completions.create(
model="local-model", # 名稱隨便填
messages=[
{"role": "user", "content": "Hello!"}
]
)
print(response.choices[0].message.content)
Code language: PHP (php)這段代碼做了什麼：
- 建立 OpenAI 客戶端，但把
base_url改成本地 server - 呼叫
chat.completions.create()，跟呼叫 OpenAI API 一樣 - 印出模型的回應
重點：只要改 base_url，原本用 OpenAI API 的程式碼幾乎不用動。
常用 Server 參數
基本設定
llama-server \
-m model.gguf \ # 模型檔案路徑
--host 0.0.0.0 \ # 監聽位址（0.0.0.0 允許外部連線）
--port 8080 \ # 埠號
-c 4096 # context 長度（可處理的最大 token 數）
Code language: CSS (css)| 參數 | 說明 | 預設值 |
|---|---|---|
-m, --model |
模型檔案路徑 | 必填 |
--host |
監聽的 IP 位址 | 127.0.0.1 |
--port |
監聽的埠號 | 8080 |
-c, --ctx-size |
context 長度 | 從模型讀取 |
效能調校
llama-server \
-m model.gguf \
-ngl 35 \ # GPU 層數
-np 4 \ # 平行處理數
-t 8 # CPU 執行緒數
Code language: PHP (php)| 參數 | 說明 | 預設值 |
|---|---|---|
-ngl, --n-gpu-layers |
放到 GPU 的層數（越多越快） | 0 |
-np, --parallel |
同時處理幾個請求 | 自動 |
-t, --threads |
CPU 執行緒數量 | 自動 |
重要 API 端點對照表
| 端點 | 說明 | OpenAI 對應 |
|---|---|---|
POST /v1/chat/completions |
聊天補全 | chat.completions.create() |
POST /v1/completions |
文字補全 | completions.create() |
GET /v1/models |
列出可用模型 | models.list() |
POST /v1/embeddings |
生成 embeddings | embeddings.create() |
GET /health |
檢查 server 狀態 | 無 |
實戰：多使用者存取設定
要讓其他電腦連線，需要：
llama-server \
-m model.gguf \
--host 0.0.0.0 \ # 監聽所有網路介面
--api-key your-secret # 設定 API key（可選但建議）
Code language: CSS (css)解釋：
--host 127.0.0.1：只有本機能連（預設）--host 0.0.0.0：任何人都能連--api-key：設定後，請求必須帶上這個 key
Python 端要加上 API key：
client = OpenAI(
base_url="http://192.168.1.100:8080/v1",
api_key="your-secret" # 要跟 server 設定一致
)
Code language: PHP (php)平行處理：同時服務多人
llama-server -m model.gguf -np 4
Code language: CSS (css)-np 4 表示同時處理 4 個請求。每個「slot」獨立維護自己的 context。
注意：slot 越多，記憶體用量越大。4 個 slot 大約需要 4 倍的 context 記憶體。
查看目前 slot 狀態：
curl http://localhost:8080/slots
Code language: JavaScript (javascript)常見變化
變化 1：使用 Hugging Face 模型 ID
llama-server -hf Qwen/Qwen2.5-Coder-7B-Instruct-GGUF
翻譯：從 Hugging Face 自動下載並載入模型，不用手動下載。
變化 2：開啟 metrics 監控
llama-server -m model.gguf --metrics
Code language: CSS (css)然後訪問 http://localhost:8080/metrics 查看 Prometheus 格式的效能指標。
變化 3：Docker 部署
docker run -p 8080:8080 -v ./models:/models \
ghcr.io/ggml-org/llama.cpp:server \
-m /models/model.gguf --host 0.0.0.0
Code language: JavaScript (javascript)翻譯：用 Docker 跑 server，把本地的 models 資料夾掛進去。
Vibe Coder 檢查點
看到 llama-server 指令時確認：
- [ ] 模型路徑正確嗎？（-m 參數）
- [ ] 需要外部連線嗎？（–host 0.0.0.0）
- [ ] context 長度夠用嗎？（-c 參數）
- [ ] GPU 有開嗎？（-ngl 參數）
- [ ] 需要同時服務多人嗎？（-np 參數）
系列回顧
恭喜！完成這系列後，你已經學會：
| 篇數 | 主題 | 你學會的事 |
|---|---|---|
| #01 | 認識 llama.cpp | 知道它是什麼、能做什麼 |
| #02 | 下載 GGUF 模型 | 從 Hugging Face 下載量化模型 |
| #03 | 命令列推論 | 用 llama-cli 跑模型、調參數 |
| #04 | API Server | 架設服務、整合到程式中 |
延伸學習資源
想深入了解，可以參考：
- llama.cpp GitHub – 官方專案
- llama-server README – 完整參數說明
- llama-cpp-python – Python 封裝版本
- Open WebUI – 漂亮的聊天介面，可接 llama-server
小結
| 你學會的 | 一句話說明 |
|---|---|
| 啟動 server | llama-server -m model.gguf |
| curl 測試 | 呼叫 /v1/chat/completions 端點 |
| Python 整合 | 改 base_url 就能用 OpenAI 套件 |
| 效能調校 | -ngl 開 GPU、-np 設平行數 |
| 外部存取 | --host 0.0.0.0 加 --api-key |
現在你可以把本地 LLM 整合到任何支援 OpenAI API 的工具了！
進階測驗：llama.cpp 架設 OpenAI 相容 API Server
測驗目標：驗證你是否能在實際情境中應用所學。
共 5 題，包含情境題與錯誤診斷題。
共 5 題，包含情境題與錯誤診斷題。
1. 你正在開發一個 AI 聊天機器人，需要讓團隊成員（在同一網路內的不同電腦）都能連線測試。目前你的 server 啟動指令如下：情境題
llama-server -m qwen2.5-coder-7b-instruct-q4_k_m.gguf -ngl 35
團隊成員回報無法連線，你應該如何修改指令？
2. 同事想用既有的 Python 程式連接你架設的本地 llama-server，但他的程式原本是連接 OpenAI API 的。以下是他原本的程式碼：錯誤診斷
from openai import OpenAI
client = OpenAI()
response = client.chat.completions.create(
model=”gpt-4″,
messages=[{“role”: “user”, “content”: “Hello!”}]
)
print(response.choices[0].message.content)
他需要修改什麼才能連接到本地 server（假設在 localhost:8080）？
3. 你部署了一個 llama-server 給公司內部使用，但發現當多人同時查詢時，響應速度明顯變慢。目前的啟動指令是：情境題
llama-server -m model.gguf –host 0.0.0.0 -ngl 35
在不升級硬體的情況下，哪個做法最能改善多人同時使用的體驗？
4. 你用 curl 測試本地 server，但收到以下錯誤訊息：錯誤診斷
$ curl http://localhost:8080/v1/chat/completions \
-H “Content-Type: application/json” \
-d ‘{“messages”: [{“role”: “user”, “content”: “Hello”}]}’
curl: (7) Failed to connect to localhost port 8080: Connection refused
最可能的原因是什麼？
5. 你想讓 llama-server 對外提供服務，但擔心安全問題。你目前的指令是：情境題
llama-server -m model.gguf –host 0.0.0.0 –port 8080
哪個做法最能增加基本的安全防護？