讀完本模組後，你應該能在自己的 Mac 上裝好一個本地 LLM 工作流，並知道它的能力邊界、什麼時候該切回雲端。

章節列表

推論伺服器選型總表

模組零已建立的三層架構視角告訴你 Ollama、LM Studio、llama.cpp 都屬於伺服器層。本模組要回答的是這三者的具體差異：

讀完本表後的決策建議是：先裝 Ollama，跑穩後再評估其他。LM Studio 可以同時裝來探索模型，但日常主力建議 Ollama；llama.cpp 暫時不需要直接接觸（Ollama 內部已經用 llama.cpp）。

為什麼這個順序

本模組章節順序的設計脈絡：

1. 先 1.0 Ollama：學習曲線最低、生態最成熟、Gemma 4 MTP 一鍵支援。多數讀者裝完這個就能開始用。
2. 再 1.1 LM Studio：給「想要可視化探索」的讀者另一條路；也可以跟 Ollama 並存。
3. 接 1.2 llama.cpp：澄清網路上「llama.cpp 才是真本地」的迷思，給進階讀者完整背景。
4. 再 1.3 VS Code + Continue.dev：把伺服器接到日常工作環境，這才是寫 code 的真正起點。
5. 然後 1.4 模型選型：伺服器跑起來後該裝哪個模型，給優先順序。
6. 再 1.5 期望管理：用一週後該怎麼判斷「值不值得繼續用」「什麼時候切雲端」。
7. 最後 1.6 延伸方向：日常路徑穩了再玩 Web UI、coding agent、產圖。

每一章可以單獨讀，但若你是第一次接觸本地 LLM，照順序讀最不容易迷路。

一個小時的最短路徑

如果你沒時間讀完整本模組、只想用一小時搞定本地 LLM 寫 code 的最基本工作流，下面是最短路徑：

 1# 1. 裝 Ollama（5 分鐘）
 2brew install ollama
 3ollama serve &
 4
 5# 2. 拉模型（首次下載約 20 ~ 30 分鐘，看網速）
 6ollama run gemma4:31b-coding-mtp-bf16
 7
 8# 3. 在 VS Code 裝 Continue 擴充套件（2 分鐘）
 9# 4. 設定 ~/.continue/config.json（5 分鐘）
10# 5. 試用 Cmd+L（對話）、Cmd+I（行內編輯）（剩下時間）

需要 32GB+ Mac 才能流暢跑這個 model；16GB / 24GB 請改用 1.4 模型選型 的對照表選對應大小的模型。完整步驟在 1.0 Ollama 跟 1.3 VS Code + Continue.dev。

跑穩之後該做什麼

裝完不是終點。本地 LLM 跟雲端的差別在於「需要持續調教」。跑穩後建議的後續工作：

1. 用一週實測：把日常工作流真實餵進去、記錄通過率與痛點、用真實任務當判讀依據而非示範任務。
2. 建立切換習慣：明確哪些任務交給本地、哪些切雲端。詳見 1.5 期望管理。
3. 觀察記憶體與發熱：開 Activity Monitor 看記憶體 swap 狀態、機殼溫度是否過高。
4. 追新模型：本地模型發布速度很快、每 2 ~ 3 個月會有新候選、值得追蹤。
5. 判斷是否升級硬體：用一個月後若限制都來自記憶體、再評估升級 Mac；先確認痛點再投資硬體。

不在本模組內的主題

本模組不討論：

1. 訓練、fine-tuning、LoRA 微調 — 跟「跑現成模型」是不同的工程問題。
2. 部署到雲端 GPU、Linux server — 本指南範圍只在 Apple Silicon Mac。
3. Cursor、Windsurf、Cline 等其他 IDE 整合 — Continue.dev 是與本地 LLM 整合最成熟的選擇，其他工具的整合度視版本而定。
4. 詳細的 benchmark 跑分方法 — 本指南只引用官方數據，自己跑分屬於另一個工程主題。

需要這些主題時請另尋專門資源；硬塞進來只會讓「Mac 本地寫 code」這條最短路徑被淹沒。

驗證日期：2026-05-12 環境：macOS、Ollama 0.23.2、nomic-embed-text、gemma3:1b Corpus：本 blog 的 content/llm/、71 個 markdown 檔 結果：22 秒索引 463 個 chunk、retrieval 命中率好、generation 受 1B 模型能力限制——剛好示範「retrieval 跟 generation 各自會失敗」的兩段式失敗模式

前置設定

驗證 embedding API 可用

1curl -s http://localhost:11434/api/embeddings \
2  -d '{"model":"nomic-embed-text","prompt":"hello world"}' \
3  | python3 -c "import json,sys; r=json.load(sys.stdin); print('dim:', len(r['embedding']))"

逐項說明：

• curl -s：-s 是 silent 模式、不顯示下載進度條（不然會混進 stdout、後面 python parse 會炸）。
• http://localhost:11434/api/embeddings：用 Ollama 原生 embedding endpoint。也有 /v1/embeddings（OpenAI 相容）、但原生回應結構較簡（直接 {"embedding": [...]}、不是 OpenAI 那種 {"data": [{"embedding": [...]}]} 巢狀）。本 demo 用原生、parse 更直接。
• -d '{"model":"...","prompt":"..."}'：JSON payload。model 是 Ollama tag、prompt 是要 embed 的文字。
• python3 -c "..."：stdin 接 curl 輸出、parse JSON、印 embedding 長度。
• 為什麼測 dim: 768：nomic-embed-text 模型架構決定 embedding 維度是 768。每次 embed 任何文字都會回固定 768 維向量、是 retrieval 的基本資料形狀。看到 dim: 768 表示：API 通了、模型載入了、輸出形狀對。

設計取捨

實作前先對齊 4.1 RAG 原理 提的設計取捨、決定每段怎麼做：

這些選擇都對應到 4.0 章節的「會變的部分」清單——可預期半年後 embedding 模型有新選擇、chunking 有更好策略、re-ranker 變主流。但骨架（retrieval + augmentation 兩段式）不變。

Ingest：把 corpus 變索引

完整檔案：scripts/rag-demo/ingest.py（本 repo 下）。三段 function：切 chunk、embed、走訪 + 持久化。

1. slice_markdown：段落感知的 chunk 切割

 1def slice_markdown(text: str, soft_token_cap: int = 400) -> list[str]:
 2    paragraphs = [p.strip() for p in re.split(r"\n\s*\n", text) if p.strip()]
 3    chunks = []
 4    buf, buf_len = [], 0
 5    for p in paragraphs:
 6        plen = len(p) / 2  # char-count / 2 ≈ token (CJK + English heuristic)
 7        if buf and buf_len + plen > soft_token_cap:
 8            chunks.append("\n\n".join(buf))
 9            buf, buf_len = [], 0
10        buf.append(p)
11        buf_len += plen
12    if buf:
13        chunks.append("\n\n".join(buf))
14    return chunks

每段做什麼：

1. re.split(r"\n\s*\n", text)：用「空白行」當分隔符切段落。\n\s*\n 比 \n\n 寬一點、允許中間有 whitespace（空白、tab）。Markdown 段落的標準分隔是空白行、這個 regex 捕捉所有段落邊界。
2. [p.strip() for ... if p.strip()]：每段去除前後空白、過濾掉純空段落。
3. buf, buf_len = [], 0：累積一個正在構建的 chunk。buf 是段落 list、buf_len 是該 chunk 的 token 累計估算。
4. plen = len(p) / 2：估算這段的 token 數。
5. if buf and buf_len + plen > soft_token_cap：「greedy pack」邏輯——如果加上這段就會超過 cap、把目前 buffer flush 成一個 chunk、再開新 buffer 裝這段。
6. if buf: chunks.append(...)：迴圈結束後、最後一個 buffer 還沒 flush、補上。

為什麼這樣設計：

• 為什麼 paragraph-aware、不是固定 token cap：4.1 RAG 原理 提的 chunking 設計取捨——固定 token cap 容易切過句子或段落中間、語意被截斷。Paragraph-aware 切在自然邊界、保留段落內語意完整。
• 為什麼 soft token cap（軟限制）而不是硬切：硬切會把一個 800-token 段落切成兩半；軟切讓「目前 chunk + 下一段超過 cap」時 flush 目前 chunk、下一段獨立成新 chunk（即使超過 cap 也保留段落完整）。代價：個別 chunk 可能超過 cap、retrieval 拿到的塊較大、但內容完整。
• 為什麼 len(p) / 2 估 token：英文約 4 字元 / token、中文約 1.5 字元 / token、混合平均 / 2 在兩種場景都合理。要精確用 tokenizer（如 tiktoken）、但 demo 不需要——這個 heuristic 在 ±20% 內、夠用來做 chunking 決策。
• 為什麼 \n\n.join(buf)`：flush 成 chunk 時、段落間保留空白行分隔、讀者看到 chunk 仍是合法 markdown 結構、不是平鋪文字。

2. embed：呼叫 Ollama embedding API

1def embed(text: str) -> list[float]:
2    payload = json.dumps({"model": "nomic-embed-text", "prompt": text}).encode()
3    req = urllib.request.Request(
4        "http://localhost:11434/api/embeddings",
5        data=payload,
6        headers={"Content-Type": "application/json"},
7    )
8    with urllib.request.urlopen(req, timeout=60) as resp:
9        return json.loads(resp.read())["embedding"]

每行做什麼：

1. payload = json.dumps(...).encode()：把 dict 轉成 JSON 字串、再 encode 成 bytes。HTTP body 必須是 bytes、不能直接傳 str。
2. urllib.request.Request(...)：建立 HTTP request 物件。沒寫 method 預設是 GET、但有 data 參數會自動變 POST。
3. headers={"Content-Type": "application/json"}：告訴 server payload 是 JSON。少了這個、Ollama 可能 parse 不出 body。
4. urlopen(req, timeout=60)：發送 request、timeout=60 是 socket-level timeout（連線 + 讀取總共最多 60 秒）。
5. json.loads(resp.read())["embedding"]：讀回應 body、parse JSON、取 embedding 欄位（768 維 list of float）。

為什麼這樣設計：

• 為什麼用 stdlib urllib 而不是 requests：完全沒有外部 dependency、urllib 是 Python stdlib 內建。requests 較友善但要 pip install、本 demo 想 minimal。
• 為什麼 timeout=60：embed 一段文字通常 < 200ms、60 秒夠 buffer 意外（首次 model 載入記憶體可能 5-10 秒）。設無限會在 Ollama 掛掉時整個 script hang。
• 為什麼 /api/embeddings、不是 /v1/embeddings：兩者都可。原生 endpoint 回應結構平、parse 直接（r["embedding"]）；OpenAI 相容回應較巢狀（r["data"][0]["embedding"]）。對 demo、寫法簡單較重要。

3. 走訪 + 持久化

 1md_files = sorted(args.content_root.rglob("*.md"))
 2records = []
 3for md in md_files:
 4    text = md.read_text(encoding="utf-8")
 5    text = re.sub(r"^---\n.*?\n---\n", "", text, count=1, flags=re.DOTALL)  # 去掉 frontmatter
 6    chunks = slice_markdown(text)
 7    for j, chunk in enumerate(chunks):
 8        vec = embed(chunk)
 9        records.append({
10            "source": str(md.relative_to(args.content_root.parent)),
11            "chunk_index": j,
12            "text": chunk,
13            "embedding": vec,
14        })
15with open("scripts/rag-demo/index.pkl", "wb") as f:
16    pickle.dump(records, f)

每段做什麼：

1. args.content_root.rglob("*.md")：recursive glob、回 Path iterator、找出 content_root 下所有 .md 檔（含子目錄）。
2. sorted(...)：排序、讓每次 ingest 順序穩定（git diff 比較友善、retrieval 結果可重現）。
3. text.read_text(encoding="utf-8")：讀檔、明確指定 UTF-8（中文 markdown 必要、否則 macOS / Linux 預設可能不一致）。
4. re.sub(r"^---\n.*?\n---\n", "", text, count=1, flags=re.DOTALL)：去掉 Hugo frontmatter。
   • ^---\n：開頭 ---\n。
   • .*?：non-greedy match、配到下一個 --- 就停。
   • \n---\n：closing fence。
   • count=1：只 strip 第一個（檔案中可能有其他 --- 是水平分隔線、不要誤殺）。
   • flags=re.DOTALL：讓 . 也匹配換行符（預設 . 不匹配 \n、規 frontmatter 跨行就吃不到）。
5. records.append({...})：每個 chunk 一個 record、含 source path、chunk index、原文、embedding。
6. md.relative_to(args.content_root.parent)：把絕對 path 變成 llm/00-foundations/xxx.md 形式、retrieval 顯示時短、跨機器可移植。
7. pickle.dump(records, f)：把整個 records list 序列化到 binary 檔。

為什麼這樣設計：

• 為什麼要 strip frontmatter：Frontmatter 是 title、date、tags 等 metadata、不是文章正文。embed 進去會稀釋向量語意（讓「date」「2026-05-11」等 keyword 影響相似度計算）。Strip 後 embedding 只 capture 內容語意。
• 為什麼 records 是 list of dict 而不是 numpy array：兩個原因。(1) 每個 record 含 source / chunk_index / text / embedding 四種異質欄位、numpy 處理不直接。(2) 463 chunks 規模、純 Python list 跑 cosine 也只是毫秒級、不需要 vectorize。十萬 chunk 以上才考慮 numpy array + batched dot product。
• 為什麼 pickle 而不是 JSON：embedding 是 768-float list、JSON 序列化會把每個 float 變成 ASCII 字串（每個 ~20 bytes）、檔案大很多、parse 也慢。Pickle 是 binary format、保留原本資料結構、檔案小、loader 快。代價：pickle 有 Python 版本相依、跨語言不能讀——但本 demo 索引只給自家 query.py / mcp_server.py 用、可接受。
• 為什麼存 text 跟 embedding、不只 embedding：retrieval 要回 chunk 原文給 LLM 看、不能只有 source path（不然每次 query 還要再讀檔）。這裡的 corpus 檔案就是 retrieval source；Pickle 多存原文成本低（~100 byte / chunk）、查詢時方便很多。

跑 ingest

1cd ~/Projects/blog
2python3 scripts/rag-demo/ingest.py

• cd ~/Projects/blog：切到 repo 根、讓相對路徑 content/llm 對得到 corpus、scripts/rag-demo/index.pkl 對得到 output 位置。
• python3 scripts/rag-demo/ingest.py：跑 ingest script、預設讀 content/llm/、寫 scripts/rag-demo/index.pkl。

實測輸出：

1Found 71 markdown files under content/llm
2  [10/71] 86 chunks in 4.5s
3  [20/71] 181 chunks in 8.6s
4  ...
5  [70/71] 461 chunks in 22.2s
6Wrote 463 records to scripts/rag-demo/index.pkl (22.3s)

463 chunks、22 秒、平均 ~21 chunks/sec。瓶頸是 sequential API call、用 async / batch 能快 5-10 倍、但這個量級不值得。

Query：retrieval + augmentation + generation

完整檔案：scripts/rag-demo/query.py。三段。

1. Cosine similarity + top-K retrieval

 1def cosine(a, b):
 2    dot = sum(x * y for x, y in zip(a, b))
 3    na = math.sqrt(sum(x * x for x in a))
 4    nb = math.sqrt(sum(y * y for y in b))
 5    return dot / (na * nb) if na and nb else 0.0
 6
 7def retrieve(records, query_vec, top_k):
 8    scored = [(cosine(query_vec, r["embedding"]), r) for r in records]
 9    scored.sort(key=lambda x: x[0], reverse=True)
10    return scored[:top_k]

每行做什麼：

1. dot = sum(x * y for x, y in zip(a, b))：兩個向量的內積（dot product）。zip(a, b) 把兩個 list 對位配對、generator expression 算每對相乘、sum 加起來。
2. na = math.sqrt(sum(x * x for x in a))：a 的 L2 norm（歐氏範數）—— sqrt(x1² + x2² + ... + xn²)。
3. nb = math.sqrt(sum(y * y for y in b))：b 的 L2 norm。
4. return dot / (na * nb) if na and nb else 0.0：cosine = dot / (||a|| × ||b||)。三元運算子防 zero division——若任一向量是零向量、na 或 nb 為 0、回 0.0 而不是 crash。
5. scored = [(cosine(query_vec, r["embedding"]), r) for r in records]：對每個 record 算相似度、組成 (score, record) tuple 的 list。
6. scored.sort(key=lambda x: x[0], reverse=True)：按 score 從大到小排序。key=lambda x: x[0] 取 tuple 第一個元素（score）當排序 key。
7. return scored[:top_k]：取前 K 個。

為什麼這樣設計：

• 為什麼 cosine 而不是純 dot product：純 dot product 受向量長度影響——長向量自動拿高分、跟「相似度」無關。Cosine 把向量正規化到單位長度、純看方向、是「語意相似」的標準衡量。語意相似 embedding 應該方向相近、長度差異不重要。
• 為什麼用 math.sqrt 而不是 **0.5：兩者數學等價、但 math.sqrt 用 C-level 實作、CPython 中比 Python 級 **0.5 快幾倍。對 463 chunks 影響不大、但 production scale 會放大差異——習慣寫 math.sqrt 的好。
• 為什麼 if na and nb else 0.0：防禦性程式設計。理論上 embedding 不會是零向量（模型架構保證有非零權重）、但邊界情況（空輸入、API 出錯回 placeholder）可能出現、避免 ZeroDivisionError 整個 query 失敗。回 0.0 表示「無法判斷相似度」、retrieval 排序時自然排到最後。
• 為什麼 sort 全部、不用 heap：463 records、Python sort 是 O(n log n)、毫秒級。heapq.nlargest(top_k, ...) 是 O(n log k)、在 k=4、n=463 上實測幾乎沒差。十萬 record 以上才看到顯著差別。
• 為什麼用 list of tuple、不用 numpy：跟 ingest 同樣的理由——小規模不需要 vectorize、純 Python 清楚。

2. 建 augmented prompt

 1context_blocks = []
 2for score, r in retrieved:
 3    context_blocks.append(
 4        f"[來源：{r['source']}#chunk{r['chunk_index']} 相似度：{score:.3f}]\n{r['text']}"
 5    )
 6
 7system = (
 8    "你是一個技術文件問答助手。"
 9    "依下方 context 內容回答問題、不要編造 context 外的事實。"
10    "若 context 不足以回答、明確說『資料不足』。"
11    "回答末尾列出引用的來源 path。"
12)
13user = "## Context\n\n" + "\n\n---\n\n".join(context_blocks) + f"\n\n## Question\n\n{question}"
14
15messages = [
16    {"role": "system", "content": system},
17    {"role": "user", "content": user},
18]

每行做什麼：

1. f"[來源：{...} 相似度：{score:.3f}]\n{r['text']}"：每個 retrieved chunk 加 header 標明出處跟相似度、再接原文。:.3f 是 score 格式化到三位小數。
2. "\n\n---\n\n".join(context_blocks)：用 --- 水平分隔線分隔各 chunk、視覺上清楚。
3. {"role": "system", "content": system}：system message 給 LLM 設定角色 + 約束。
4. {"role": "user", "content": user}：user message 含 context 跟 question、是 LLM 實際讀的內容。

為什麼這樣設計：

• 為什麼 system prompt 約束四件事（角色、忠於 context、資料不足時明說、引用來源）：
  • 角色：「技術文件問答助手」框定模型行為、減少 off-topic 回應。
  • 忠於 context：對抗 RAG 最常見的失敗模式——LLM 看到 context 但用自己訓練的 knowledge 補完、結果跟 corpus 不一致。明確要求 follow context 能降低（雖然不能完全消除、見實測 1）。
  • 資料不足時明說：避免 LLM「硬要回答」造成 hallucination。對 weak model 這條 follow 度差、但對 large model 有效。
  • 引用來源：traceability。讀者能回查 corpus、驗證模型答案。
• 為什麼 ## Context / ## Question 結構：用 markdown heading 結構幫助 LLM 區分「我要讀什麼」「我要回答什麼」。比平鋪文字穩定（即使對小模型）。
• 為什麼把 retrieved chunks 全塞 user message、不分開：MCP / function calling 的更現代做法是把 retrieved 結果做成 tool response、模型主動 call retrieval tool。本 demo 不引入 tool use、直接塞 prompt 較單純——能說明 RAG 核心（augmentation）不必牽扯 tool use。

3. 呼叫 chat completions

1def chat(messages, model):
2    payload = json.dumps({"model": model, "messages": messages, "stream": False}).encode()
3    req = urllib.request.Request(
4        "http://localhost:11434/v1/chat/completions",
5        data=payload,
6        headers={"Content-Type": "application/json"},
7    )
8    with urllib.request.urlopen(req, timeout=180) as resp:
9        return json.loads(resp.read())["choices"][0]["message"]["content"]

每行做什麼：

1. json.dumps({"model": ..., "messages": ..., "stream": False}).encode()：構造 OpenAI 相容 chat completions request body。stream: False 讓 server 等生成完再一次回、不要 SSE 串流。
2. /v1/chat/completions：OpenAI 相容 endpoint、跟雲端 OpenAI 完全同樣 schema。
3. timeout=180：3 分鐘、給長 context + 慢模型空間。
4. ["choices"][0]["message"]["content"]：parse OpenAI 標準 response 結構、取第一個 choice 的 content。

為什麼這樣設計：

• 為什麼 stream: False：demo 要把完整 answer 印出、不需要 incremental display。stream: True 要寫 SSE parser、複雜。Production 互動式 UI 才需要 streaming。
• 為什麼 timeout=180、不是 60：1B 模型 + 4 個 retrieved chunks 的 context、prefill 可能要 5-30 秒、生成 100-500 token 又要 5-20 秒、保守設 3 分鐘。embed function 用 60 是因為 embedding 是純 forward pass、單一 token 量級操作、不需要這麼長。
• 為什麼 /v1/... 而不是 /api/...：chat completions 走 OpenAI 相容 endpoint、生態都用這個格式（Continue.dev、Cursor、各家 SDK）。embedding 用 /api/... 是因為原生 schema 簡單；chat 用 /v1/... 是因為 message-based 結構是 OpenAI 標準、跨工具互通。

實測結果：retrieval 對、generation 弱

測試 1：「什麼是 MTP？為什麼對寫 code 場景特別有效？」

1python3 scripts/rag-demo/query.py --show-retrieved "什麼是 MTP？為什麼對寫 code 場景特別有效？"

--show-retrieved 是個 flag、開啟後在 stderr 印 retrieved chunks 跟 score、答案還是進 stdout。是 debug 跟教學用、不會影響 LLM 看到的 prompt。

Retrieval：

10.870  llm/knowledge-cards/transformer.md#chunk2
20.825  llm/03-theoretical-foundations/sampling-and-decoding.md#chunk8
30.782  llm/knowledge-cards/ttft.md#chunk1
40.771  llm/knowledge-cards/mtp.md#chunk2

四個 chunk 都跟問題相關、相似度合理。MTP 卡確實被命中（雖然不是 top-1、是因為 transformer.md 該段提到 MTP）。

Generation（1B 模型）：

MTP 僅指使用 Ollama 進行 Coding 模型訓練與部署、它是一種系統性的方式… 來源：llm.dev

錯：1B 模型編造了「MTP 僅指使用 Ollama」這個事實（不對、MTP 是 Google 為 Gemma 釋出的、跟 Ollama 沒直接關係）、來源 URL 也是 hallucination。

測試 2：「MCP 跟 function calling 有什麼差別？」

Retrieval：

10.721  llm/04-applications/application-protocols.md#chunk2
20.704  llm/04-applications/application-protocols.md#chunk1
30.702  llm/04-applications/application-protocols.md#chunk0
40.693  llm/knowledge-cards/function-calling.md#chunk1

完美命中——4.3 應用層協議章節三個 chunk + function-calling 卡。

Generation：模型把幾段重複拼接、framing 跟原文有出入、但比測試 1 好（因為 context 涵蓋直接答案）。

觀察跟原理對應

這個 demo 剛好示範 4.1 RAG 原理 提的兩段式失敗模式：

換 31B+ 模型 generation 會改善很多——這也是 4.0 章節提到「retrieval 跟下游 LLM 訓練分佈不一致」會放大失敗的具體例子。寫 RAG 系統時、generation 失敗不一定是「retrieval 沒給對 context」、可能是「模型不夠強」。

何時這份 demo 會過時

• Ollama API 形狀：短期內不會變（生態都依賴）。
• nomic-embed-text / gemma3:1b 具體 tag：預期會被新模型取代、但 retrieval + augmentation 結構不變。
• Chunking heuristic：簡單 char-count / 2 很粗、半年後若有便宜的 token counter 直接接會更準。
• Pickle 儲存：production 場景建議換 vector DB、本 demo 是教學用。

實作換代時、保留 ingest / retrieve / augment / generate 四段、各段內部換工具即可——這四段是 RAG 的骨架、跨工具世代不變。

跑這個 demo 的指令總結

1# 一次性建索引（每次 corpus 變動才需要重建）
2cd ~/Projects/blog
3python3 scripts/rag-demo/ingest.py

• cd：切到 repo 根、relative path 對得到。
• python3 ingest.py：跑索引、預設讀 content/llm/、寫 scripts/rag-demo/index.pkl。每次 corpus 變動才需要重跑、不變的話 index 就一直用。

1# 查詢（任意次）
2python3 scripts/rag-demo/query.py --show-retrieved "你的問題"
3python3 scripts/rag-demo/query.py --top-k 5 --model gemma3:1b "問題"

• --show-retrieved：教學 / debug 用、列 retrieved chunks 跟 score 到 stderr。
• --top-k 5：取 top 5 instead of 預設 4。chunks 越多 context 越長、TTFT 越久、但訊息越完整。
• --model gemma3:1b：指定 chat model。換 gemma3:4b、gemma4:31b-coding-mtp-bf16 等 generation 品質會大幅改善。

完整 source 在 scripts/rag-demo/ 下、200 行 Python、無外部 dependency。

跟其他 hands-on 章節的關係：完整 hands-on 系列見 Hands-on 章節索引、把 retrieval 包成 MCP server 暴露給 LLM application 見 MCP demo、RAG + MCP 同跑的記憶體 / 程序預算見 RAG + MCP resource footprint、術語見 RAG 跟 embedding model。

本篇用四組對照實驗證明這個事實、再展開 wrapper 三檔審查粒度的設計取捨。這跟 4.3 副作用範圍設計、4.4 Agent 跟人類審查的協作模型、0.7 隱私資料流原理 三個原則章節對應、實作層的權限與供應鏈判讀對應 6.2 tool use 與 MCP server 的權限模型 跟 6.0 模型供應鏈與信任邊界。

驗證日期：2026-05-12 環境：Ollama 0.23.2、gemma3:1b、Python stdlib 檔案位置：scripts/permission-demo/edit_with_llm.py

為什麼這個問題重要

直覺常見的誤判：

• 「LLM 寫了 rm -rf 我電腦會壞」——錯。LLM 寫指令不代表執行。
• 「Ollama API 改我檔案要 sudo」——錯。Ollama API 根本碰不到檔案。
• 「我跑 wrapper 就讓 LLM 改檔案、應該有 confirm 機制吧」——錯。Confirm 機制完全是 wrapper 開發者自己決定要不要寫、LLM 不知道、不在乎。

理解這個邊界、後續設計 LLM 應用的權限模型才有 ground truth。錯誤的 mental model 會導致兩種 failure：

1. 過度恐懼：因為怕 LLM「亂改」、把所有 LLM 互動關起來、放棄自動化收益。
2. 過度信任：相信 LLM「不會做壞事」、給 wrapper 自動執行權限、結果小模型亂解 instruction 把資料毀掉。

實際上權限設計的判讀錨點是：這個動作有沒有副作用、誰執行。LLM 永遠不執行、所以權限不在 LLM 層；wrapper 執行、所以權限完全在 wrapper 設計。

Test 1：直接 API 問改檔案、看會發生什麼

挑一個檔案（token 卡片）、用 curl 送 chat completions、prompt 寫「修改這個檔案」、然後 check 檔案 mtime 跟 md5：

 1# 修改前 snapshot
 2stat -f "%m %N" content/llm/knowledge-cards/token.md
 3md5 -q content/llm/knowledge-cards/token.md
 4
 5# 用 system prompt「假裝你有 file 權限」、user 直接指明路徑
 6curl -s http://localhost:11434/v1/chat/completions \
 7  -H "Content-Type: application/json" \
 8  -d '{
 9    "model":"gemma3:1b",
10    "messages":[
11      {"role":"system","content":"You can modify files. The user provides a file. You modify it."},
12      {"role":"user","content":"Please modify /Users/.../token.md to add a sentence..."}
13    ],
14    "stream":false
15  }'
16
17# 修改後 snapshot
18stat -f "%m %N" content/llm/knowledge-cards/token.md
19md5 -q content/llm/knowledge-cards/token.md

實測結果：

 1=== Before ===
 21778508712 content/llm/knowledge-cards/token.md
 3d9f2d822f7458af62399076a94ef20f6
 4
 5=== LLM response ===
 6Okay, here's the modified content of `/Users/.../token.md`...
 7
 8=== After ===
 91778508712 content/llm/knowledge-cards/token.md  ← mtime same
10d9f2d822f7458af62399076a94ef20f6                  ← md5 same

mtime 沒變、md5 沒變、檔案內容完全沒動。但 LLM 用「Okay, here’s the modified content」這種口氣回答——它以為自己改了、實際上只生成了一段 markdown 文字。

結論：Ollama HTTP API 是 stateless、pure function。輸入 messages、輸出 message content。整個過程沒寫進 socket 以外的任何地方。

為什麼會這樣設計：

• 沙箱本來就在 API 邊界：HTTP server 接 request、跑 forward pass、回 response。期間沒呼叫 fs.write() / subprocess.run() / 任何 effectful API。
• system prompt 不是權限授予：「You can modify files」這句話對模型來說只是文字 context、不會真的給它 file access。Prompt 是「LLM 內部的 context」、不是「runtime capability」。
• 訓練資料讓 LLM 「以為」自己有能力：LLM 訓練資料含大量「使用者問問題、AI 改檔案」的範例（如 GitHub Copilot agent traces、tool-use SFT 資料）、模型學會用「我已經改了」這種語氣回答——是 mimic、不是真正的 action。

Test 2：寫 wrapper 用 –dry-run 模式安全處理

權限不在 LLM、在 wrapper。寫一個 100 行的 wrapper、看怎麼設計 permission gates。完整檔案：scripts/permission-demo/edit_with_llm.py。

核心 architecture：

 1def main():
 2    # 1. 讀檔（wrapper 用自己的 fs 權限）
 3    original = args.file.read_text(encoding="utf-8")
 4
 5    # 2. 送 LLM、拿回提議的新內容
 6    response = chat([
 7        {"role": "system", "content": "You modify text files. Output ONLY ..."},
 8        {"role": "user", "content": f"File: {args.file}\nContent:\n{original}\nInstruction: {args.instruction}"},
 9    ])
10    new_content = extract_code_block(response)
11
12    # 3. Diff（純讀、永遠 safe、不需 gate）
13    diff = list(difflib.unified_diff(original.splitlines(...), new_content.splitlines(...)))
14    sys.stdout.writelines(diff)
15
16    # 4. PERMISSION GATE：wrapper 決定要不要 apply
17    if args.auto:
18        args.file.write_text(new_content)
19    elif args.confirm:
20        if input("Apply? [y/N] ").lower() == "y":
21            args.file.write_text(new_content)
22    else:  # --dry-run，預設
23        pass  # 不寫

為什麼這樣設計：

• extract_code_block：嘗試 well-formed ```lang\n...\n``` regex、失敗 fallback 到 ```lang\n...$ 寬鬆版。小模型（1B）常忘記結尾 fence、寬鬆才能用。寫嚴格 regex 失敗時直接 abort、是另一種 permission gate（不應用 = 安全）。
• 永遠先印 diff：diff 是純讀操作、無副作用、永遠 safe。讓使用者先看 LLM 提議了什麼、再決定要不要 apply。
• args.auto 在 elif 鏈最前面、dry-run 預設：強迫使用者明示 opt-in 才會寫檔。預設不寫、是「safe default」設計原則。

跑 --dry-run 預設、看實際發生：

1python3 scripts/permission-demo/edit_with_llm.py \
2  content/llm/knowledge-cards/token.md \
3  "把開頭第一段最後加一句『Token 是 embedding 的輸入單位』"

實測輸出（1B 模型）：

 1[+] Asking gemma3:1b to: '把開頭第一段最後加一句「Token 是 embedding 的輸入單位」'
 2[+] Proposed diff:
 3--- a/token.md
 4+++ b/token.md
 5@@ -6,16 +6,4 @@
 6 tags: ["llm", "knowledge-cards"]
 7 ---
 8
 9-Token 的核心概念是「LLM 內部處理文字的最小單位」...（整段刪除）
10-
11-## 概念位置
12-...（整段刪除）
13-...（後面所有段落都刪除）
14+Token 是 embedding 的輸入單位。
15
16[+] --dry-run: file unchanged. Use --confirm or --auto to apply.

驚悚發現：1B 模型完全沒理解「加一句」、把整篇刪掉只剩一行。但 --dry-run 不寫檔、檔案安全。

重點：

• LLM 行為糟、但 wrapper 設計安全、結果 OK。
• 把同樣 instruction 餵 31B+ 模型結果會合理——模型能力決定 LLM 端品質、wrapper 設計決定最差情況的後果。
• 在 wrapper 端永遠假設 LLM 會亂改、設計 safe default、是 defensive programming。

Test 3：--confirm 模式、step-by-step 審查

--confirm mode 印 diff、問 y/N、user 確認才寫：

1python3 scripts/permission-demo/edit_with_llm.py \
2  content/llm/knowledge-cards/token.md \
3  "加一句說明" \
4  --confirm

互動流程：

1[+] Proposed diff:
2--- a/token.md
3+++ b/token.md
4@@ ... 整段刪除 ...
5
6[?] Apply this change to content/llm/.../token.md? [y/N] _

使用者看 diff 發現「整篇被刪了」、按 N、檔案安全。

這個 mode 對應的副作用範圍：4.3 工具的副作用範圍設計 提的 spectrum：

本 demo 改 markdown 是等級 3（寫本地檔）、--confirm 是合適粒度。改 production code 或 git push 是等級 4 / 5、--confirm 該強制不該 optional。

Test 4：--auto 模式、危險自動化

--auto 不問直接寫：

1cp /tmp/token-orig.md content/llm/knowledge-cards/token.md  # 還原
2python3 scripts/permission-demo/edit_with_llm.py \
3  content/llm/knowledge-cards/token.md \
4  "加一句說明" \
5  --auto

實測：

1[!] --auto mode: writing without confirmation
2[+] wrote content/llm/knowledge-cards/token.md

檔案內容變成：

1---
2title: "Token"
3...
4---
5
6Token 是 embedding 的輸入單位。

整篇刪光、只剩一句。沒人 catch 到、commit + push 出去就是 production 災難。

--auto mode 適合什麼場景：

• LLM 任務範圍狹窄、可預測（如 format JSON、補 type annotation 給已有 type stub）。
• 配合 git workflow（每次 auto edit 都自動 commit、出問題 git revert）。
• CI / batch processing、人類事後審 PR。

--auto mode 不適合什麼場景：

• 任務開放性高（「改寫這段讓它更清楚」）。
• 不可逆環境（直接寫 production DB / 發 email）。
• 用弱模型（< 14B）跑、行為不穩。

設計 wrapper 時、把 --auto 設成顯式 opt-in、預設保持 dry-run / confirm 等較保守模式。本 demo 的 mutually_exclusive 設計（-g.add_mutually_exclusive_group()）保證三種 mode 只能擇一、避免歧義。

Test 5：LLM 寫 shell command、誰執行？

改檔案是「直接副作用」、寫 shell command 是「間接副作用」——同樣的問題：誰真的執行？

1curl -s http://localhost:11434/v1/chat/completions \
2  -H "Content-Type: application/json" \
3  -d '{
4    "model":"gemma3:1b",
5    "messages":[{"role":"user","content":"Give me a single shell command to find and delete all .log files in my home directory."}],
6    "stream":false
7  }' | python3 -c "import json,sys; print(json.load(sys.stdin)['choices'][0]['message']['content'])"

LLM 回：

1```bash
2find ~ -name "*.log" -delete
3```

這是個有破壞性的指令。檢查 home 下 .log 還在不在：

1find ~ -maxdepth 3 -name "*.log" 2>/dev/null | head -5
2# /Users/tarragon/.npm/_logs/2026-05-11T15_33_34_348Z-debug-0.log
3# /Users/tarragon/.npm/_logs/2026-05-11T11_58_08_827Z-debug-0.log
4# ...

都還在。LLM「給了」rm 指令、但沒人執行。

執行路徑只有兩種：

1. 人類 paste 到 shell：人是執行者、權限是 user’s shell session permission。Audit trail：terminal history。
2. Wrapper 程式 subprocess.run(...)：wrapper 是執行者、權限是 wrapper process 的 capability。Audit trail：wrapper 的 log。

LLM 永遠不是執行者。所以「LLM 寫了 rm -rf」這個句子不能成立——它只能「生成了 rm -rf 字串」。

Agent 場景的 stake：4.4 Agent 架構 提到 agent loop = 「LLM 提議 → tool 執行 → 結果回 LLM → 下一輪」。Tool 執行那一步是 wrapper 做的、LLM 只看到結果。Agent 框架是否安全、完全看 tool 怎麼設計：

• Tool 限制範圍：read-only file system access、不暴露 shell→ 即使 LLM 想跑 rm -rf 也沒對應 tool、無法執行。
• Tool 暴露 bash tool：給 LLM 一個「執行任意 shell command」的 tool。LLM 提議什麼 wrapper 都跑——這時 wrapper 設計失誤等同把鑰匙直接交給 LLM。
• Tool 暴露 bash tool + per-command confirm：每個 shell 呼叫前 wrapper 暫停、問人類「該不該執行」。對開發 / 探索環境合理、production 自動化流程會被互動卡住、不適用。

對照：Claude Code / Cursor / aider 的權限模型

不同 LLM application 在權限 gate 上的設計選擇：

共通 pattern：所有「自動 edit / exec」的 app 都有某種 confirm 或 hook 機制。沒有 confirm 的 app 等於把寫 production 的鑰匙交給 LLM。

選 application 時看的維度：

• 預設 mode 是什麼？（auto / confirm / dry-run）
• 哪些動作會自動執行、哪些會 prompt？
• 有沒有 audit log、能不能 review LLM 改了什麼？
• 萬一 LLM 行為崩、怎麼 rollback？（git revert、snapshot、undo stack）

設計自家 wrapper 的權限模型

如果你寫的是「LLM 自動處理 X」這種 wrapper、權限設計的 checklist：

1. 副作用分級：把可能的動作分到 4.3 spectrum 等級 1-5。
2. 預設 dry-run：不確定就不寫。Apply 必須 opt-in。
3. 永遠印 diff / preview：用戶才能 catch LLM 亂改。
4. Confirm 在不可逆操作：等級 3+ 永遠 prompt、等級 4+ 強制 prompt + 額外 audit。
5. Audit log：每個 wrapper 動作寫 log（時間、user、action、result）。出問題能追溯。
6. Rollback path：git commit、backup、snapshot 任選一種、必有。
7. 限制 tool 範圍：給 LLM 暴露最少 tool、不暴露 shell。需要 shell 限制白名單。
8. 小模型加更保守 gate：1B 模型亂改機率高、保留 --dry-run 或 --confirm 即可、避免 --auto；31B+ 較穩、可給 auto + audit。

跑這份 demo 的完整指令

 1# 前置：Ollama 跑著、gemma3:1b 已 pull
 2ollama list | grep gemma3:1b
 3
 4# 備份要測試的檔案
 5cp content/llm/knowledge-cards/token.md /tmp/token-orig.md
 6
 7# Mode 1：dry-run（預設、最安全）
 8python3 scripts/permission-demo/edit_with_llm.py \
 9  content/llm/knowledge-cards/token.md \
10  "加一句說明"
11
12# Mode 2：confirm（互動審查、適合中等風險）
13python3 scripts/permission-demo/edit_with_llm.py \
14  content/llm/knowledge-cards/token.md \
15  "加一句說明" \
16  --confirm
17
18# Mode 3：auto（無確認、危險、僅 batch 用）
19python3 scripts/permission-demo/edit_with_llm.py \
20  content/llm/knowledge-cards/token.md \
21  "加一句說明" \
22  --auto
23
24# 還原
25cp /tmp/token-orig.md content/llm/knowledge-cards/token.md

何時這篇會過時

不會過時的部分：

• LLM HTTP API 是 pure function、無副作用——這個事實在所有「分離 inference server / wrapper / client」的架構都成立。
• 權限 gate 在 wrapper / application 層——是 software architecture invariant、不是 LLM 特性。
• 副作用範圍 spectrum 跟人類審查粒度的對應。
• --dry-run / --confirm / --auto 三檔的設計取捨。

會變的部分：

• 具體 LLM application 的 default mode（Cursor / aider / Claude Code 都會持續調整）。
• 哪個模型「不會亂改」的 ranking（隨模型能力提升而變）。
• MCP / tool spec 細節（會持續演化、但「tool 是 wrapper 暴露」的本質不變）。

讀這篇若指令跑不過、可能是 wrapper script API 微調、但「測試 LLM 是不是 pure function」這個方法本身永遠成立——拿任何 LLM API、送任何 prompt、check 檔案 mtime / md5、就能驗證。

跟其他 hands-on 章節的關係：完整 hands-on 系列見 Hands-on 章節索引、副作用範圍 spectrum 原理見 4.3 Tool use 原理、Agent loop 跟人類審查的協作見 4.4 Agent 架構、Tool use / MCP server 權限模型的個人 dev 視角見 6.2、術語見 Sandbox。

實驗跑了四個本地模型對比：

• gemma3:1b（815 MB、舊代 / 小）
• gemma3:4b（3.3 GB、舊代 / 中）
• qwen3:8b（5.2 GB、跨家族 / 大）
• gemma4:e4b（9.6 GB、新代 / 中、bf16）

對應 4.4 Agent 架構 「規劃能力是雲端旗艦的明顯強項、本地小模型的明顯弱項」這條觀察、用具體 structural metrics 驗證、並揭示**「最新世代 + 較大 size」未必比「跨家族 / 較強訓練」勝出**。

驗證日期：2026-05-12 環境：Ollama 0.23.2、Apple Silicon、MPS backend 任務：讀資料夾 A（風格參考、5 章已寫完）+ 資料夾 B（同類型、5 章已寫完、需寫 v06）→ 為 B 生成 v06 評估方式：純 structural metrics、不評論內容品質

任務設計

兩個資料夾結構：

1A/                          B/
2├── README.md               ├── README.md
3├── v01_XXX.md              ├── v01_XXX.md
4├── v02_XXX.md              ├── v02_XXX.md
5├── v03_XXX.md              ├── v03_XXX.md
6├── v04_XXX.md              ├── v04_XXX.md
7└── v05_XXX.md              └── v05_XXX.md
8                            └── v06_XXX.md  ← 要生成

兩個資料夾用不同 markdown 格式：

• A 風格：# 標題（H1）+ ## 場景設定 段 + 結尾 **【本章結束】**
• B 風格：## v0X｜<主題>（<角色1>×<角色2>）（H2）+ 直接敘事、無結尾 marker

LLM 看完 A + B 後、要寫 B 的 v06——必須 follow B 的格式、不是 A 的。是個 format discrimination 測試。

評估維度

純 structural、不涉內容：

不評估的：

• 內容品質、文筆好壞
• 敘事邏輯是否合理
• 角色塑造是否生動

純 structural 評估的好處是 reproducible、不需 reviewer 主觀判斷、可自動跑。

Baseline：B 既有 v01-v05 的 metrics

B 資料夾 5 個既有章節的平均：

這是 LLM 該模仿的目標。

四個模型的結果

四個 model 跑同樣 prompt、同樣輸入內容。

對比表

各模型觀察

gemma3:1b（815 MB）：

• 篇幅 4.6× 失控、段落數 4.5× 超標、用 H1 而不是 H2。
• 顯示 1B 模型對「2000-3000 字」這種 numeric instruction 沒有有效執行能力、會一直生成到 context 限制。
• 但 cross leak 0、結尾 marker 也沒誤加——「不要 X」這類 negative instruction follow 較成功。

gemma3:4b（3.3 GB）：

• 篇幅 / 段落 / heading 結構全 OK、明顯比 1B 大幅改善。
• dialogue lines = 0：完全沒寫對話、整篇純敘事。表示 4B 抓到字面 structural feature、但沒抓到「對話 driven 敘事」這個 stylistic feature。
• 主角名提及 24 次（baseline ~60）—內容偏短、提及次數偏低、但比例合理。

qwen3:8b（5.2 GB、跨家族）：

• 唯一 7/7 全 pass 的模型——篇幅完美匹配（951 vs ~933）、段落數合理（36 vs ~32）、heading 對、對話 7 行完全等於 baseline。
• 跨家族 + 大一級的組合表現質變，比同家族下一級的 4B 模型大幅提升。
• 代價：生成時間 97.5s、約是 4B 模型的 2.7×。

gemma4:e4b（9.6 GB、新代）：

• 驚人的 1/7、最差表現——比 1B 還少通過項目。
• 主角名提及 0：完全沒寫角色名、純抽象敘述「某一方」「另一方」。
• dialogue 0：沒對話。
• 生成內容是「劇情大綱建議」而非實際章節：含「劇情核心思路」「預計情緒強度」「寫作切入點建議」等 meta-text。
• 輸出末尾「（此為結構化建議、等待具體的指令後、將會生成與風格一致的劇情內容。）」——明示它把 prompt 理解成「給建議框架、等下一步」。

Strict prompt retest：揭示 internal alignment

懷疑 1/7 可能是「prompt 不夠強硬」、用 strict prompt 重跑 gemma4:e4b。Strict 加了八條規則、明示：

1- 直接從 `## v06｜...` 開頭、不寫前言
2- 絕對不可寫「劇情核心思路」「預計情緒強度」「寫作切入點」等 meta-text
3- 必須直接寫敘事內容、含對話、動作、感受描寫
4- 強制提到角色名多次、不要用「某一方」「另一人」抽象稱呼
5- ...

Strict prompt 結果：

從 1/7 → 4/7、prompt 強化明顯有用。但主角名提及兩次都 0、即使 strict prompt 明示「強制提到角色名」、模型仍用「兩人」「彼此」「對方」抽象稱呼。

這比「模型不會 follow」更精確、是兩個層次的 follow 差別：

• Surface level instruction（heading 格式、不要 meta-text、要對話）：model 願意 follow strict prompt。
• Semantic level instruction（在這個情境用具名角色）：model 有 internal alignment 抗拒、即使 prompt 明示也不 follow。

Gemma 4 e4b 是 device-deployable edge variant、RLHF 可能特別針對「敏感情境下的人物識別」做 alignment。這個 alignment 比 prompt-level instruction follow 更深、是 hard line、不能用 prompt engineering 繞過。

關鍵觀察

Model size 不是唯一因素、訓練 alignment 更重要

最反直覺的結果：

• gemma4:e4b（9.6 GB、最新世代）原 prompt 通過 1/7、strict prompt 通過 4/7。
• gemma3:4b（3.3 GB、舊一代）通過 6/7。
• qwen3:8b（5.2 GB、跨家族）通過 7/7。

「最大 + 最新」不等於「最好 follow instruction」。在這個任務上、ranking 是：

1qwen3:8b > gemma3:4b > gemma3:1b ≈ gemma4:e4b (strict) > gemma4:e4b (default)

可能因素：

1. 訓練資料分佈差異：Qwen 系列訓練資料含大量中文、對中文 instruction follow 更穩。
2. Edge variant 的 alignment 設計：gemma4:e4b 是 device-deployable edge variant、RLHF 可能特別在敏感情境用 conservative output。Strict prompt 能改善 surface-level（heading、meta-text、對話）、但 semantic-level（具名角色）有 hard line 不能繞過。
3. 跨家族效應 > 跨代效應：Qwen vs Gemma（不同家族）比 Gemma 3 vs Gemma 4（同家族跨代）影響更大。

兩層 instruction follow

gemma4:e4b 的 strict prompt retest 揭示一個重要區分：

• Surface-level instruction（heading 格式、不要 meta-text、要對話）：可以用 strict prompt 改善、prompt engineering 有效。
• Semantic-level alignment（特定情境的角色處理、敏感主題的表述方式）：是 RLHF 階段建立的 hard line、prompt engineering 繞不過。

設計應用時要意識：「LLM follow 不了 instruction」可能不是能力問題、是 alignment 問題。模型訓練時被刻意 align 不做某些事、即使 prompt 明示也不會做。發現這種情況、改換 model（或 less-aligned variant）會比繼續調 prompt 更省時間。

「最新世代」的標籤可能誤導

Gemma 4 是 2026/4/2 才發布的最新代、size 也夠大、但在這個 instruction following 任務上輸給 6 個月前發布的 Gemma 3 4b。

設計應用 / 選模型時、實測對自己 task 的表現比「最新 / 最大」標籤可靠。Benchmark ranking（如 LMSYS Chatbot Arena）反映平均表現、未必 reflect 你的 narrow 任務。本實驗示範了「自己跑一次」比「看 benchmark」更可靠的判讀方法。

Structural feature 跟 stylistic feature 兩層

跨四個模型一致觀察：

• Structural feature（heading level、結尾 marker、不要 cross leak）：所有模型多少都抓到。
• Stylistic feature（對話 driven 敘事、篇幅精準）：差異極大、Qwen3 8B 完美、其他三個都有明顯失分。

這對應 4.4 Agent 的「規劃 vs 字面 follow」差距——字面 instruction 容易、stylistic mimic 困難。寫應用時、預期 follow「形式約束」（output JSON、結尾 signature）跟 follow「風格約束」（用簡潔口吻、bullet 而非段落）兩種 instruction 的成功率不同。

Cross-pairing leak：全 0

四個模型 cross leak 都 0——表示「不要混角色」這個 instruction 兩個都 follow 成功。可能因素：

• 角色名是名詞、模型 generation 時容易 constrain。
• Prompt 已明示「為 B 寫」、模型沒被 A 角色名干擾。

如果改成模糊 instruction（「混合 A、B 風格」）、leak 可能會出現——本實驗沒涵蓋這個 case。

生成時間：size ≠ 時間

四個模型的生成時間：

意外發現：

1. 1B 比 4B 慢：因為 1B 生成 4324 字、4B 生成 1330 字、總 token 量決定總時間、不是 model size。
2. qwen3:8b 慢 2.7×：8B 的 forward pass 較慢、加上 generation 量級正常、總時間最長。
3. gemma4:e4b 跟 1B 相近：generation 短（679 字）、抵消 model 較大的開銷。

tokens per second 跟 total latency 是兩件事——decode 速度快但生成太多 token、未必更快完成任務。

對寫應用的啟示

1. 「最新最大」≠ 「最好 follow」：選模型實測自己 task、benchmark / size 只是輔助訊號。
2. 本地小模型（< 3B）做需要 follow 結構規則的任務、要嚴格驗證：用 structural metrics 自動 check、目視判斷模型「看起來有做到」的可靠度低。
3. Edge variant 可能有 special behavior：device-deployable variant 可能 RLHF 偏向 conservative、不一定適合所有任務。
4. 跨家族對比比同家族升 size 收益大：Qwen3 8B vs Gemma3 4B 比 Gemma3 4B vs Gemma3 1B 改善更明顯。
5. 「形式跟風格」分開驗證：應用層的 validation 分維度 score、比一次評全部更可解讀。

跑這個實驗的 framework

通用流程（不放具體 script、會綁定 corpus 內容）：

11. 準備兩個資料夾、A 是風格參考、B 是 work-in-progress
22. 寫 helper script 把兩個資料夾完整內容 + 任務說明做成 prompt
33. 跑多個 model 各一次（同 prompt、不同 model）
44. 對輸出計算 structural metrics（char count、paragraph、heading、dialogue lines）
55. 跟 B 既有章節的 baseline metrics 對比
66. 列通過 / 失敗矩陣

關鍵設計選擇：

• A 跟 B 風格故意不一樣：才能驗證 LLM 是否分辨「該 follow 哪個」。
• 不評估內容品質：純 structural 評估 reproducible、不需 reviewer 主觀判斷。
• baseline 用既有章節算：B 自己的 v01-v05 是「正確答案」的 reference。
• 跑多個跨家族 / 跨世代 / 跨 size 模型：避免「只測一個就下結論」的偏差。

何時這份對比會過時

• 具體模型 ranking：新模型發布後 ranking 會變、特別是新版 Gemma 4 / Qwen 4 / Llama 4 等推出時。
• 「Gemma 4 edge 表現差」這個觀察：可能隨後續 fine-tune 或新版改善。

不會過時的部分：

• Model size 不是 instruction following 的唯一因素——這個現象在所有 LLM 都存在。
• Structural vs stylistic 兩層 follow 難度不同。
• 跨家族對比比同家族升 size 收益大、這個現象可能持續。
• 純 metrics-based 評估比主觀判斷可重現。
• 「自己跑一次」比「看 benchmark」更可靠的判讀邏輯。

未來想擴展、可以加入更多維度（如反向 retrieval：把生成內容當 query、看能不能找回原資料夾；或 perplexity-based 評估）。

跟其他 hands-on 章節的關係：完整 hands-on 系列見 Hands-on 章節索引、選模型的優先序策略見 Model selection priority、模型 tag 命名規則見 Model tag、跑多模型的記憶體預算見 Resource management。

本篇紀錄三個 dimension（RAM / 磁碟 / port）的觀察工具跟釋放姿勢、對比 Ollama 跟 ComfyUI 兩種典型 lifecycle、加上實測釋放數字。對應 0.7 隱私資料流原理「每個 hop 都要 audit」這條思維——資源管理也是 hop 級的 audit、不是「裝完就忘」。

驗證日期：2026-05-12 環境：macOS 14、Apple Silicon、Ollama 0.23.2、ComfyUI 0.21.0、SDXL base 1.0

為什麼這事重要

雲端 inference：

1Container start → load model → serve requests → container stop → 所有 RAM / 磁碟 / port 自動回收

本地 inference：

1brew services start → load model on demand → serve → ??? → 你忘記 stop
2                                              → RAM / 磁碟一直被佔
3                                              → 下次重開機才釋放

具體會踩到的問題：

• RAM：18 GB SDXL 模型載入後不會自動卸、即使 ComfyUI idle、Python process 仍占 RAM
• 磁碟：ollama pull 累積、~/.ollama/models/blobs 半年可長到 50 GB+、不主動清不會減
• Port：上次 crash 的 ollama serve 進程沒乾淨清、port 11434 還占著、下次啟動報「address already in use」
• GPU / Metal：模型載入後 Metal context 佔住、跟其他 GPU-using app（影片剪輯、遊戲）競爭

三個 dimension + 觀察工具

實測：剛 kill 完 ComfyUI（SDXL + Python venv）後、vm_stat 看到 free pages 從 619K 變 1090K（每 page 16 KB）、約 +7.5 GB RAM 釋放——這就是 SDXL + ComfyUI process 一直占的記憶體量。

Ollama 的 lifecycle（auto-unload 模式）

Ollama 走「按需 load / idle unload」設計：

1brew services start ollama          → daemon 啟動、沒 model 載入、RAM 占用 ~200 MB
2                                     port 11434 listening
3ollama run gemma3:4b "hello"        → 把 model 載入 RAM (~4-5 GB)
4                                     立刻 generate response
5                                     model 留在 RAM
6(idle 5 分鐘、無新 request)         → Ollama 自動 unload model
7                                     RAM 釋放、daemon 仍跑著
8ollama run gemma3:4b "next"         → 重新 load model（~5-10 秒）、generate
9brew services stop ollama           → daemon 結束、port 釋放

關鍵參數 OLLAMA_KEEP_ALIVE（環境變數、預設 5m）：

 1# 看當前 loaded models
 2ollama ps
 3# NAME         ID              SIZE      PROCESSOR    UNTIL
 4# gemma3:4b    a2af6cc3eb7f    5.5 GB    100% Metal   4 minutes from now
 5
 6# 啟動時調 keep_alive（持續佔 RAM 直到 ollama 重啟）
 7OLLAMA_KEEP_ALIVE=-1 brew services restart ollama
 8
 9# 啟動時讓 model 用完立即 unload
10OLLAMA_KEEP_ALIVE=0 brew services restart ollama

選 keep_alive 的 trade-off：

主動 unload 指令：

1# 把 idle 的 model 立刻從 RAM 卸掉、但 daemon 仍跑
2curl -s http://localhost:11434/api/generate \
3  -d '{"model": "gemma3:4b", "keep_alive": 0}'
4
5# 或關掉整個 daemon
6brew services stop ollama

ComfyUI 的 lifecycle（持續占用模式）

ComfyUI 走完全不同模式：model 載入後一直在 RAM、直到 server process 結束。沒有 auto-unload 機制。

 1python main.py                      → ComfyUI server start、port 8188 listening
 2                                     RAM ~3 GB（Python venv + 框架）
 3第一次 Queue Prompt (用 SDXL)        → 載入 sd_xl_base_1.0.safetensors (~6 GB)
 4                                     RAM 跳到 ~9-10 GB
 5                                     generate 完成、model 留在 RAM
 6連續多張生成                          → 維持 ~9-10 GB、沒 unload
 7idle 1 小時                          → 仍 ~9-10 GB（沒 timer）
 8切到 ControlNet workflow             → 多載 ControlNet model (~2 GB)、ComfyUI 自動 swap
 9                                     RAM 暫升、SD 部分可能被 evict 到 disk
10Ctrl+C / pkill                       → process 結束、RAM 完全釋放

要釋放 ComfyUI 占的 RAM、唯一方法是結束 server：

 1# 找 PID
 2ps aux | grep "ComfyUI/main.py" | grep -v grep
 3
 4# 優雅關（讓它 cleanup）
 5pkill -INT -f "ComfyUI/main.py"
 6
 7# 強制 kill（如果上面沒反應、最多等 5 秒再強制）
 8pkill -KILL -f "ComfyUI/main.py"
 9
10# 確認 port 釋放
11lsof -i :8188 | head -3

實測：M4 Pro 32GB、SDXL base 載入後 ComfyUI process 占 ~8 GB RAM；pkill -9 後 vm_stat 顯示 free pages 增加 ~470K page（7.5 GB 釋放）。

為什麼 Ollama 跟 ComfyUI 設計不同

兩種設計都 valid、適合不同使用模式。理解差異後就知道 ComfyUI 一直占 RAM「不是 bug」、是設計選擇。

跟其他本地 server 對比

結論：只有 Ollama 跟 oMLX 內建 auto-unload、其他都要手動釋放。GUI server（LM Studio）通常給 user 一個「Eject」按鈕、CLI server 通常要 kill process。

標準釋放程序

寫 code 完一天結束、要釋放所有資源、按下表順序操作：

 1# 1. 確認當前狀態（記下要還回去多少 RAM）
 2vm_stat | head -3
 3df -h ~ | tail -1
 4ollama ps
 5ps aux | grep -E "ollama|ComfyUI|llama-server" | grep -v grep
 6
 7# 2. 釋放當前載入的 LLM models（Ollama）
 8brew services stop ollama
 9# 或保留 daemon、只 unload model：
10# curl -s http://localhost:11434/api/generate -d '{"model": "<your model>", "keep_alive": 0}'
11
12# 3. 結束 ComfyUI / 其他 GUI server
13pkill -INT -f "ComfyUI/main.py" 2>/dev/null
14pkill -INT -f "llama-server" 2>/dev/null
15sleep 5
16# 強制（如果上面沒清乾淨）
17pkill -KILL -f "ComfyUI/main.py" 2>/dev/null
18pkill -KILL -f "llama-server" 2>/dev/null
19
20# 4. 驗證所有 port 釋放
21lsof -i :11434 -i :1234 -i :8080 -i :8188 -i :8000 2>&1 | head
22
23# 5. 確認釋放量
24vm_stat | head -3
25# free pages 該明顯增加

容易出錯的「釋放方式」

• killall Python：會 kill 所有 Python process、包括其他 dev tool（如 jupyter、Django）。用 pkill -f "ComfyUI/main.py" 等明確 pattern。
• rm -rf ~/.ollama：會清掉所有 model registry、下次要重 pull 全部 model。Cleanup 用 ollama rm <model> 才精準。
• brew uninstall ollama：直接卸載 Ollama 本身、過 reinstall 麻煩。Stop service 就夠。
• 重開機釋放：work 但太重、會中斷其他工作。用 process-level 操作即可。

磁碟長期累積管理

Models 一旦 pull 進 ~/.ollama/models/blobs、不主動 rm 不會減少。半年累積可長到 50 GB+。

Ollama models 只是磁碟大戶之一。整台 Mac 突然被吃光、要從哪裡查起的全機診斷順序（先排除快照浮動、再用實際佔用值逐層找大戶），見 macOS 磁碟空間診斷流程——那篇的佔用大戶表也會把 ollama 列為其中一項、再連回本篇的專屬清理 idiom。

觀察累積

 1# Ollama models 總占用
 2du -sh ~/.ollama/models/blobs
 3# 4.1G    /Users/tarragon/.ollama/models/blobs
 4
 5# 逐 model 看大小
 6ollama list
 7# NAME                       ID              SIZE      MODIFIED
 8# gemma4:e4b                 c6eb396dbd59    9.6 GB    Less than a second ago
 9# nomic-embed-text:latest    0a109f422b47    274 MB    3 hours ago
10
11# ComfyUI checkpoints 累積
12du -sh ~/.ollama ~/Projects/ComfyUI/models 2>/dev/null
13# 4.2G    /Users/tarragon/.ollama
14# 7.0G    /Users/tarragon/Projects/ComfyUI/models

清理策略

 1# 刪掉很久沒用的 model
 2ollama rm <model-tag>
 3
 4# 一次清掉所有 Ollama models（保留 daemon）
 5ollama list | tail -n +2 | awk '{print $1}' | xargs -I {} ollama rm {}
 6
 7# 看 ComfyUI checkpoints 哪些可清
 8ls -lh ~/Projects/ComfyUI/models/checkpoints/
 9
10# 手動刪不要的 .safetensors（小心、不能 undo）
11rm ~/Projects/ComfyUI/models/checkpoints/<old-model>.safetensors

磁碟管理 idiom

定期（每月或磁碟剩 < 20% 時）做：

1. du -sh ~/.ollama ~/Projects/ComfyUI/models 看當前累積
2. ollama list 看哪些 model 沒在用（看 MODIFIED 欄、太舊的考慮刪）
3. 刪實驗用的 model、保留 daily-driver
4. ComfyUI checkpoints 同樣 review

Port / Process 排錯

啟動報「address already in use」

 1# 找誰占
 2lsof -i :11434
 3# COMMAND  PID  USER   ...   NAME
 4# ollama   xxx  ...    ...   TCP localhost:11434 (LISTEN)
 5
 6# 看是不是 zombie process
 7ps aux | grep $(lsof -ti :11434 | head -1)
 8
 9# 清掉
10kill -9 $(lsof -ti :11434)
11
12# 或重啟 service（會自動清舊 instance）
13brew services restart ollama

Ollama daemon 掛了不知道

 1# 健康檢查
 2curl -s http://localhost:11434/api/version
 3
 4# 沒回應、看 service 狀態
 5brew services list | grep ollama
 6
 7# 沒在跑、重啟
 8brew services start ollama
 9
10# 看 log
11tail -50 /opt/homebrew/var/log/ollama.log

ComfyUI 看似跑著但 Queue 不動

1# 看 stdout / stderr log
2tail -30 /tmp/comfyui.log  # 如果啟動時 redirect 到 log
3
4# 看是不是 GPU / Metal stuck（極少見、但 SDXL 大量並發可能踩到）
5# 解法：kill + 重啟
6pkill -9 -f "ComfyUI/main.py"

完整排錯流程跟「先確認哪一層壞」見 1.7 排錯方法論。

觀察記憶體佔用：實測對照

跑這幾步紀錄 baseline → load model → kill 的 RAM 變化：

 1# Baseline
 2vm_stat | grep "Pages free"
 3# Pages free:                              1090076.   ← ~17 GB free
 4
 5# 啟動 Ollama + load 4B model
 6brew services start ollama
 7ollama run gemma3:4b "hello"
 8ollama ps
 9# NAME       SIZE     PROCESSOR    UNTIL
10# gemma3:4b  5.5 GB   100% Metal   4 minutes from now
11
12vm_stat | grep "Pages free"
13# Pages free:                               750000.   ← 跌 ~5 GB（model 載入）
14
15# 額外啟動 ComfyUI + load SDXL
16nohup python main.py > /tmp/comfyui.log 2>&1 &
17# 在 GUI 上 Queue Prompt 跑一次 SDXL generation
18vm_stat | grep "Pages free"
19# Pages free:                               280000.   ← 再跌 ~7.5 GB（SDXL 載入 + Python venv）
20
21# kill 全部
22brew services stop ollama
23pkill -9 -f "ComfyUI/main.py"
24sleep 3
25vm_stat | grep "Pages free"
26# Pages free:                              1090000.   ← 回到 baseline

每 page 16 KB、所以 free pages 數字 × 16 KB = 實際 free RAM bytes。

自動化釋放：launchd / shell alias

寫個 shell function 一鍵 cleanup：

 1# 加進 ~/.zshrc
 2llm-cleanup() {
 3  echo "[*] Stopping Ollama..."
 4  brew services stop ollama 2>/dev/null
 5
 6  echo "[*] Killing ComfyUI..."
 7  pkill -INT -f "ComfyUI/main.py" 2>/dev/null
 8  sleep 3
 9  pkill -KILL -f "ComfyUI/main.py" 2>/dev/null
10
11  echo "[*] Killing other model servers..."
12  pkill -KILL -f "llama-server" 2>/dev/null
13  pkill -KILL -f "lm-studio-server" 2>/dev/null
14
15  echo "[*] Verifying ports..."
16  for p in 11434 1234 8080 8188 8000; do
17    lsof -i :$p 2>/dev/null | head -2
18  done
19
20  echo "[*] Free RAM:"
21  vm_stat | grep "Pages free"
22}

完事打 llm-cleanup 一鍵釋放、不用記每個 process 怎麼 kill。

何時這篇會過時

不會過時的部分：

• RAM / 磁碟 / port 三個 dimension 是長期 invariant、用什麼 LLM server 都成立。
• 「Mac 是 shared resource、需要主動管理」這個 framing。
• Ollama 跟 ComfyUI 兩種典型 lifecycle 對比（auto-unload vs persistent）。
• 觀察工具（vm_stat、lsof、ps、du、Activity Monitor）是 macOS 系統 API、不會 deprecate。
• 標準釋放程序、自動化 shell function 模式。

會變的部分：

• 具體 model size / RAM 占用數字（隨模型架構演化）。
• OLLAMA_KEEP_ALIVE 等具體環境變數名（Ollama API 演化）。
• ComfyUI 可能加 auto-unload feature（社群有 issue 在討論）。

讀的時候若指令跑不過、先 --help 看當前版本 flag；釋放 RAM 的「kill process」這個機制本身永遠成立。

跟其他 hands-on 章節的關係

• Ollama 安裝：介紹 brew services start/stop、本篇延伸 lifecycle 細節
• ComfyUI 安裝：介紹 ComfyUI 啟動、本篇延伸 RAM 占用 + 釋放
• 1.7 排錯方法論：用三層架構定位故障、本篇是 lifecycle 視角的補完
• 0.7 隱私資料流原理：「每個 hop 都要 audit」延伸到資源層

整體心法：本地 LLM 工作流跟雲端不一樣、要主動管理 lifecycle、不能裝完就忘。

本篇 framing 是「真的能跑、不只跑 demo」、所以包含：硬體預算估算、judge model 選型、bias 緩解、calibration 流程、跟 production trace 串接的延伸；術語對應 LLM-as-Judge 與 LLM Tracing。

驗證日期：2026-05-12 環境：M4 Max 64GB / 或 24GB+ VRAM PC + Ollama Judge model：DeepSeek-R1-Distill-Qwen-32B 或 QwQ-32B（reasoning model 當 judge 更穩）

為什麼用本地 LLM 當 judge

跟雲端 judge（GPT-5 / Claude 4）對比：

判讀：

• 大量 production trace eval（千筆以上）+ 隱私敏感 → 本地 judge
• 少量 high-stake eval（< 50 筆） → 雲端旗艦 judge
• A/B test 快速 iterate → 雲端（latency 重要）

硬體預算

Judge model 選擇看硬體：

注意：reasoning model 的 thinking trace 拉長 latency、跑大量 batch 要規劃時間（100 item × 60s = 100 min）。

何時不適合用本地 judge：

1. 硬體低於 M4 Pro 24GB / 4090 16GB（如 M1/M2 16GB、無獨立 GPU PC）：跑 32B reasoning model 太緊、強行跑會 swap、latency 爆 5-10×。改用 14B instruct model（如 Qwen2.5-14B Q4）作 judge、或直接走雲端 judge
2. Batch × latency > 你可接受的等待時間：100 item × 60s/item = 100 min；500 item × 120s = 17 hr。預估超過 4 hr 時改雲端 batch API
3. eval 任務太 nuanced：細粒度倫理 / 法律 / 高 stake 判讀、本地 32B distill 能力不夠、用雲端旗艦 judge 或人工 review
4. calibration 階段：第一次跑、要快速 iterate rubric、雲端 judge latency 短（5-30s）更適合 iterate

整體流程

11. 蒐集 eval dataset    → JSONL：每行一個 (input, output) 待評
22. 設計 rubric         → 評分維度、scale、明確 anti-pattern
33. 寫 judge prompt     → 4 段式（task / input-output / rubric / format）
44. 跑 harness          → 對每筆 input call judge、parse JSON output
55. Aggregate 結果      → 算平均分數、找 outlier、看 reasoning
66. Calibration（可選）  → 跟 human eval 比對、調 rubric
77. 跟 production trace 串接 → 定期跑 production sample

Step 1：蒐集 eval dataset

JSONL format（每行一筆）：

1{"id": "001", "input": "用 Python 寫 fibonacci function", "output": "def fib(n):\n    if n <= 1:\n        return n\n    return fib(n-1) + fib(n-2)"}
2{"id": "002", "input": "解釋這段 code 在做什麼：[code]", "output": "這段 code 實作了 ..."}
3{"id": "003", "input": "[bug 描述]", "output": "[suggested fix]"}

來源：

• 過往 Continue.dev / Cursor 跟 LLM 的對話 log
• Production agent 的 trace（手動 export 或 LangSmith / Phoenix dump）
• 自己 hand-craft 30-100 個典型 case

放在 data/eval.jsonl。

Step 2：設計 rubric

依任務類型設計、coding 任務的範例 rubric：

 1評分維度：
 21. Correctness（程式碼能否運作、邏輯是否正確）：1-5
 32. Style（是否符合 codebase convention、習慣命名）：1-5
 43. Completeness（是否完整解決 user request）：1-5
 5
 6評分規則：
 7- 5：完美無瑕、可直接 merge
 8- 4：小修可用、整體正確
 9- 3：方向正確、需 substantial 修改
10- 2：部分對、主要邏輯有錯
11- 1：完全錯、誤導使用者
12
13明確不加分（緩解 verbosity bias）：
14- 冗長 / verbose（同樣正確的短答 = 長答）
15- 道歉 / 開場白
16- 「我希望這有幫助」這類禮貌話
17- 過多 markdown 修飾（不加分）

Step 3：Judge prompt 模板

寫成 file prompts/judge.txt：

 1你是 LLM 輸出品質評估員、要評估 coding assistant 對使用者請求的回答品質。
 2重要：請保持公正、忽略風格偏好、聚焦在實質品質。
 3
 4User request:
 5{input}
 6
 7Assistant response:
 8{output}
 9
10評分維度（每維 1-5、加總用 overall）：
11
121. Correctness：程式碼能否運作、邏輯正確
13   5: 完美無瑕
14   4: 小修可用
15   3: 方向正確、需 substantial 修改
16   2: 部分對、主要邏輯有錯
17   1: 完全錯
18
192. Style：符合 codebase convention
20   1-5 同 scale
21
223. Completeness：完整解決 user request
23   1-5 同 scale
24
25明確不加分項：
26- 冗長 / verbose（同樣正確的短答 = 長答）
27- 道歉 / 開場白
28- 「我希望這有幫助」這類禮貌話
29- 過多 markdown 修飾
30
31請依下列 JSON 輸出（不要加額外文字、不要 markdown code fence）：
32{
33  "correctness": <1-5>,
34  "style": <1-5>,
35  "completeness": <1-5>,
36  "reasoning": "<簡短解釋、< 100 字>",
37  "overall": <1-5>
38}

Step 4：跑 harness

Python 最小可行版：

 1# judge_harness.py
 2import json
 3import requests
 4from pathlib import Path
 5
 6JUDGE_MODEL = "deepseek-r1:32b"  # 或 qwq:32b
 7OLLAMA_URL = "http://localhost:11434/v1/chat/completions"
 8
 9def load_dataset(path):
10    """Load JSONL eval dataset."""
11    with open(path) as f:
12        return [json.loads(line) for line in f if line.strip()]
13
14def load_prompt_template(path):
15    return Path(path).read_text()
16
17def call_judge(prompt):
18    """Call Ollama judge model、回 raw response text."""
19    resp = requests.post(OLLAMA_URL, json={
20        "model": JUDGE_MODEL,
21        "messages": [{"role": "user", "content": prompt}],
22        "temperature": 0.1,  # judge 用低 temperature 穩定
23        "stream": False,
24    }, timeout=600)
25    return resp.json()["choices"][0]["message"]["content"]
26
27def parse_judge_output(text):
28    """Parse judge 回的 JSON、容錯處理（reasoning model 可能加 <think> 標記）。"""
29    # 跳過 reasoning trace
30    if "</think>" in text:
31        text = text.split("</think>")[-1]
32
33    # 找 JSON 區塊
34    start = text.find("{")
35    end = text.rfind("}") + 1
36    if start == -1 or end == 0:
37        return None
38    try:
39        return json.loads(text[start:end])
40    except json.JSONDecodeError:
41        return None
42
43def run_harness(dataset_path, prompt_template_path, output_path):
44    dataset = load_dataset(dataset_path)
45    template = load_prompt_template(prompt_template_path)
46
47    results = []
48    for i, item in enumerate(dataset):
49        prompt = template.format(input=item["input"], output=item["output"])
50        raw = call_judge(prompt)
51        parsed = parse_judge_output(raw)
52
53        result = {
54            "id": item["id"],
55            "scores": parsed,
56            "raw_judge_output": raw[:500],  # 保留前 500 字便於 debug
57        }
58        results.append(result)
59        print(f"[{i+1}/{len(dataset)}] id={item['id']} overall={parsed.get('overall') if parsed else 'FAIL'}")
60
61    # 寫出 JSONL
62    with open(output_path, "w") as f:
63        for r in results:
64            f.write(json.dumps(r) + "\n")
65
66    # Aggregate
67    valid = [r for r in results if r["scores"]]
68    if valid:
69        avg = sum(r["scores"]["overall"] for r in valid) / len(valid)
70        print(f"\nAggregate: {len(valid)}/{len(results)} valid、avg overall = {avg:.2f}")
71
72if __name__ == "__main__":
73    run_harness("data/eval.jsonl", "prompts/judge.txt", "results/eval.jsonl")

跑：

1# 先確認 judge model 已 pull
2ollama pull deepseek-r1:32b
3
4# 跑 harness
5python judge_harness.py

Step 5：Aggregate 跟看 outlier

跑完後 results/eval.jsonl 含每筆評分跟 reasoning。看哪些是 outlier：

1# 找 overall < 3 的 case（低分、值得 review）
2jq 'select(.scores.overall < 3)' results/eval.jsonl
3
4# 看 reasoning 找系統性問題
5jq '.scores.reasoning' results/eval.jsonl | sort -u

判讀：

• 多數 score 4-5、少數 1-2：整體品質好、focus 在低分 case 找 fix
• 多數 score 2-3：系統性問題、改 prompt / model / agent design
• 分數分佈兩極（很多 5 很多 1）：可能是 task difficulty 分群、stratified analysis

Step 6：Calibration（可選但推薦）

跟 human eval 比對、確認 judge 對齊：

11. 從 dataset 抽 30 個（覆蓋 difficulty / score 分佈）
22. 自己 human eval（依同樣 rubric）
33. 對比 judge 跟 human 的 overall score
44. 算 Spearman correlation
5   - > 0.7：judge 對齊夠好、可信
6   - 0.5-0.7：部分問題、改 rubric
7   - < 0.5：judge 不可信、換 model 或重寫 rubric

低 correlation 的常見原因：

• Rubric 太 vague、judge 自由發揮
• Judge model 能力不夠（換更強 judge）
• Verbosity / position bias 沒緩解
• Eval task 跟 judge 訓練分佈差距大

Step 7：跟 production trace 串接（延伸）

把 4.20 LLM tracing 蒐集的 production trace export 成 JSONL、定期跑 judge：

1# 假設用 Langfuse self-host
2langfuse export --filter "user_feedback=negative" --output traces.jsonl
3
4# 轉成 eval format
5python convert_trace_to_eval.py traces.jsonl > data/eval-from-prod.jsonl
6
7# 跑 judge
8python judge_harness.py

這是 production quality engineering 閉環的本地版本、隱私敏感場景的 cost-free alternative。

失敗模式

1. Judge 不輸出合法 JSON：reasoning model 可能在 <think>...</think> 後仍加 markdown / 解釋

緩解：parse 時跳 <think> 段、容錯處理、或開 constrained decoding（llama.cpp grammar）

2. Latency 太長、batch 跑不完：reasoning model 32B 每 item 60-120s、100 item 要 2 小時

緩解：用較小 judge model（如 Qwen2.5-32B instruct、非 reasoning）、或拆 batch 並行

3. Judge bias 沒緩解：本地 judge 跟雲端 judge 都會有 verbosity / position bias

緩解：rubric 寫明、pairwise 換位置跑 2 次

4. 本地 judge 能力上限：30B distill 對 nuanced case 判讀不如雲端旗艦

緩解：critical case 加 spot human review、或混用本地（量大）+ 雲端（精選 sample）

跟其他章節的關係

• 原理層的 LLM-as-judge 設計見 4.21
• Production trace 串接見 4.20 tracing
• Reasoning model 選型見 3.8
• 隱私 / 跨雲端邊界判讀見 6.4
• Benchmark 跟 in-house eval 的層次見 4.14

本指南預設讀者已經會用過雲端 LLM（ChatGPT、Claude）、熟悉終端機操作、想以工程視角理解 LLM。寫 code 場景是主要使用例、但模組二 / 三 / 四 / 六多數章節跨場景通用：想懂 reasoning model / RAG / embedding model 內部、即使不裝本地 LLM 也能讀。硬體前提分兩條路線：Apple Silicon Mac（M1 ~ M4、統一記憶體）走模組一；Windows / Linux + 獨立 GPU（NVIDIA / AMD、獨立 VRAM + 系統 RAM）走模組五。文章不販賣 LLM 焦慮、也不誇大本地能取代雲端的程度；它的責任是給每條讀者旅程的最短可行路徑、並標出每個階段的取捨。

模組零（心智模型）是所有讀者旅程的共同前置。模組一跟模組五是「裝本地 LLM」的兩條硬體路線、依平台選一條；想懂底層走模組二跟模組三（跟硬體無關、含 reasoning model / speculative decoding 等推論細節）；想看 LLM 作為系統元件走模組四（12 章涵蓋 RAG、tool use、agent、應用層協議、workflow、production resource、long context、embedding model、benchmarking、vision、靜態 deployment）；本地工作流跑穩想看安全議題走模組六（個人 dev 視角的供應鏈、伺服器綁定、tool use 權限、prompt injection、跨雲端邊界、production routing）。

教材邊界

學習路線

本指南分成七個模組加一組前置卡片（111 張）。讀者依目的選讀、不需要從頭到尾全讀：

• 想用 Apple Silicon Mac 裝本地 LLM 寫 code：讀模組零 + 模組一（最短路徑）
• 想用 Windows / Linux + 獨立 GPU 裝：讀模組零 + 模組五
• 想懂 LLM 內部原理：模組二（數學） + 模組三（理論、含 reasoning models / speculative decoding）— 跟硬體無關
• 想做 LLM 應用開發（含 RAG / agent / VLM / 靜態 deployment）：模組四（12 章、跨工具世代不變的原理）— 跟硬體無關
• 想懂本地工作流的安全議題：模組一 / 五跑穩後接模組六（個人 dev 視角）
• 想選 RAG 的 storage 方案（pickle / vector DB / hosted SaaS）：直接看 4.22 RAG storage 工程
• 想在靜態網站加 RAG / 智能搜尋：直接看 4.16 靜態 / serverless RAG deployment
• 想在本機 fine-tune 模型：模組三 3.4 訓練流程原理 → 本機 QLoRA hands-on
• 想跟最新進展接軌：讀完模組後進推薦的公開課程跟 paper（模組二 2.4 + 模組三 3.10）

前置知識卡片

用原子化卡片整理 token、自回歸、KV cache、量化、speculative decoding、MTP、MLX、推論伺服器、OpenAI 相容 API、memory bandwidth、統一記憶體、TTFT、prefill、context window、Transformer、Diffusion 等核心概念。章節文章專注情境推導、術語背景交由卡片維持一致。

模組零：基礎知識與心智模型

整理本地 vs 雲端 LLM 的差異、自回歸架構與記憶體頻寬瓶頸、介面 / 伺服器 / 模型三層心智模型、OpenAI 相容 API 為何重要、MLX / MTP / oMLX 三個容易搞混的術語、Apple Silicon Mac 記憶體與模型大小的對應關係、判讀本地 LLM 資訊的五個框架。

模組一：本地 LLM 服務的安裝與應用

整理 Ollama、LM Studio、llama.cpp 三個主流推論伺服器的現況差異與安裝路徑、用 Continue.dev 把本地 LLM 接到 VS Code 的完整步驟、寫 code 場景下模型選型的優先順序、本地模型的期望管理、想進一步玩 coding agent、Web UI、產圖時的延伸方向。

模組二：LLM 的數學基礎

整理 LLM 推論背後的數學工具：線性代數（向量、矩陣、空間）、機率與資訊論（softmax、cross-entropy、KL、perplexity）、微積分與最佳化（gradient、SGD / Adam）、數值精度（fp32 / bf16 / Q4 / Q8 的取捨）。每章末尾接到公開課推薦。

模組三：LLM 的理論基礎

整理 LLM 內部運作機制、共 11 章：神經網路基礎、embedding 空間、attention 機制、Transformer 架構、訓練流程（pre-train → SFT → RLHF / DPO）、sampling 策略、tokenization 算法、跨語言場景原理、Reasoning models（o1 / R1 / QwQ 等 test-time compute paradigm）、Speculative decoding 內部（drafter / MTP / EAGLE）。每章末尾接到公開課推薦（Karpathy、Stanford CS224N / CS25 / CS336、DeepLearning.AI）。

模組四：LLM 應用層原理

整理 LLM 作為系統元件的設計原理、共 12 章：RAG、tool use、agent 架構、應用層協議、workflow 編排模式、Production resource planning、衍生產物管理、Long context engineering、Embedding model 內部、Benchmarking 方法論、Vision in coding workflow（本地 VLM 接 IDE）、靜態 / serverless RAG deployment（沒 backend 場景）。本模組刻意只寫跨工具世代不變的原理、避開 LangChain / LlamaIndex 等具體 framework 教學。

模組五：Windows / Linux + 獨立 GPU

整理消費級 PC（Windows / Linux + NVIDIA / AMD 獨立 GPU）跑本地 LLM 的硬體判讀模型與工程選項：VRAM + RAM 分層預算、MoE 模型的 CPU 卸載策略（--n-cpu-moe）、KV cache 量化（K=Q8 / V=Q4）跟 context 長度的權衡、llama.cpp 在 PC 上的調參空間。本模組跟模組一是平行的硬體路線、共用模組零的心智模型跟卡片。

模組六：本地 LLM 的安全與權限

整理個人 dev 在自己機器上跑本地 LLM 的安全議題：模型供應鏈與信任邊界、推論伺服器的綁定與暴露範圍、tool use 與 MCP server 的權限模型、IDE 場景的 prompt injection、跨雲端 / 本地的資料邊界、跨進 production 的 routing 中樞。framing 是個人 dev 視角、不是 enterprise 資安管理；production / 多租戶 LLM 服務的特殊資安議題見 Backend 模組七 資安與資料保護 的 LLM 相關章節。

模組之間怎麼配合

模組二跟模組三可並讀。閱讀模組三遇到陌生數學詞時跳回模組二補完、再回模組三繼續。模組四在前面模組之上、但讀者熟悉 LLM 應用詞彙也可直接從這裡讀起。模組一跟模組五依硬體選一條主路線、共用模組零的心智模型與 knowledge-cards。模組六在模組一 / 五跑穩後接、處理「跑起來後該注意什麼」。

適合的讀者

用語約定

本指南使用的關鍵術語在第一次出現時都附原文。為避免歧義，下列詞彙在本指南內固定指涉：

1. 本地 LLM：跑在使用者自己機器（Mac 或 PC）上的大型語言模型推論、prompt 留在本機。
2. 推論伺服器（inference server）：負責載入模型權重、處理 prompt、產生 token 的常駐程式、例如 Ollama、LM Studio 內建 server、llama.cpp server。
3. 介面層：使用者實際打字互動的工具、例如 VS Code + Continue.dev、CLI、Web UI。介面層透過 API 跟推論伺服器溝通。
4. 模型（model）：權重檔本身、例如 gemma4:31b、qwen3-coder:30b。模型可以在不同推論伺服器之間共用、前提是格式相容。
5. 量化（quantization）：把模型權重從高精度（如 bf16）壓成低精度（如 Q4）以減少記憶體佔用、代價是少許品質下降。

不在本指南內的主題

本指南不討論：

• Speech / audio LLM：跟核心文字 LLM 是不同方向、本指南不涵蓋。Vision（VLM）原本不放、但因 coding 工作流的 vision use case 進入主流、補上 4.15 Vision in coding workflow；video LLM 仍不放。
• 資料中心訓練的工程細節：data parallelism、ZeRO、tensor parallelism 等屬於專門課程的範圍。
• 向量資料庫的 vendor 比較（Pinecone vs Weaviate vs Chroma 等）：vendor 格局半年一變、不適合寫入教材。RAG 的 storage 工程原理（升級判讀、index 生命週期、dependency 約束）見 4.22 RAG storage 工程。
• Kubernetes / 資料中心級分散式推論：跟個人機器本地 LLM 方向不同、需另尋專門教材。
• 多卡 NVLink、tensor parallelism：消費級 PC 場景通常單卡、本指南不涵蓋多卡分散式推論。

若讀完本指南後想往這些方向走：

1. 想做 RAG 應用：先把 Ollama + Continue.dev 跑穩、再讀 模組四 4.1 RAG 原理 建立設計取捨判讀、或 模組三 3.8 推薦 的 DeepLearning.AI short courses。
2. 想跑 coding agent：先讀 4.4 Agent 架構原理 建立判讀、再看 1.6 延伸方向 了解 aider、Cline 等工具的定位差異。
3. 想跑產圖模型：Diffusion 跟 Transformer 是不同架構、請另尋 ComfyUI / Draw Things / Diffusers 教材。
4. 想自己訓練 / fine-tune：讀完模組三、進入 Karpathy zero-to-hero、Stanford CS336、Hugging Face NLP Course 等推薦資源。

文件版本：v0.7.0 最後更新：2026-05-12 系列狀態：七個模組 + 125 張知識卡片。模組零（9 章）/ 一（10 章 + hands-on、含 QLoRA + judge harness）/ 二（5 章）/ 三（12 章、含 reasoning / speculative / constrained decoding）/ 四（17 章、含 long context / embedding / benchmarking / VLM / 靜態 deployment / coding agent harness / prompt caching / agent memory / tracing / LLM-as-judge）/ 五（7 章）/ 六（7 章、含 OWASP 對照）。

本資料夾的內容會隨工具版本演化：指令、目錄結構、相依套件版本都會變。寫的時間戳記在每篇開頭、版本資訊在 frontmatter。跟 1.x 原理章節的差別是「原理跨工具世代不變、實作筆記是當下這版的快照」。

章節列表

通用前置

所有工具都假設你的 Mac 滿足：

• Apple Silicon Mac（M1 / M2 / M3 / M4）
• macOS 14 (Sonoma) 或以上
• Homebrew 安裝完成（brew --version 可看版本）
• 至少 16 GB 統一記憶體（24 GB+ 較順）
• 至少 20 GB 可用磁碟空間（本系列總共會佔約 15 GB）

需要 Python 環境的工具（ComfyUI、Whisper）會用 venv 隔離、不污染系統 Python。

驗證紀錄環境

本系列的指令在以下環境驗證：

換 Mac 規格、換 macOS 版本、半年後再讀本系列、指令可能要小調整、但前置設定的種類跟驗證步驟的結構通常不變。看到指令跑不過時、回 1.7 排錯方法論 的三層架構定位、不要把錯誤訊息當絕對。

對「在 VS Code 接本地 LLM 寫 code」這條最短路徑、Ollama 多半是唯一需要的伺服器層。本章先給 5 分鐘可跑通的最短路徑、再展開日常使用所需的模型管理跟 API 細節、最後才進階主題（背景常駐、MTP 加速、安全暴露、版本升級）。已經把 Ollama 跑起來的讀者可以直接跳到日常使用或排錯。

本章目標

讀完本章後、你應該能：

1. 裝好 Ollama 並驗證它正在跑。
2. 用 CLI 拉一個模型並開始對話。
3. 用 curl 驗證 OpenAI 相容 API 在 11434 正常回應。
4. 看懂 model tag 命名規則、選對 Gemma 4 MTP 版本。
5. 排查 port 撞、記憶體不足、模型載入慢、cache 過大等情境。

最短路徑：5 分鐘把 Ollama 跑起來

最短路徑的設計目標是「裝、跑、驗證三步、其他細節留到日常使用段」。三個指令用到的 macOS 工具分別是 Homebrew 套件管理器（brew install）跟 shell 前景 process（ollama serve 預設前景跑、Ctrl+C 結束）。

1# 1. 安裝
2brew install ollama
3
4# 2. 啟動 server（前景跑、Ctrl+C 結束）
5ollama serve
6
7# 3. 在另一個 terminal 拉一個小模型驗證
8ollama run gemma3:1b

第三步首次執行會下載權重（約 815 MB、頻寬足夠的話 1 ~ 3 分鐘）、下載完自動進入 REPL：

1>>> 寫一個 Python function 計算 fibonacci
2def fibonacci(n):
3    if n <= 1:
4        return n
5    return fibonacci(n - 1) + fibonacci(n - 2)
6>>> /bye

驗證 server 正常聽 11434：

1curl http://localhost:11434/api/version
2# 回 {"version":"0.23.x"}

驗證 OpenAI 相容 API 可以做 chat completion：

1curl http://localhost:11434/v1/chat/completions \
2  -H "Content-Type: application/json" \
3  -d '{
4    "model": "gemma3:1b",
5    "messages": [{"role": "user", "content": "Hello"}],
6    "stream": false
7  }'

回應 JSON 包含 choices[0].message.content、最短路徑就完成。實際寫 code 用的模型大小通常是 14B / 31B 級、選型詳見 1.4 模型選型優先順序；完整安裝紀錄含 launchd service 設定見 Hands-on：Ollama 安裝。

日常使用：模型管理與 API 形狀

模型管理指令

Ollama 用四個指令覆蓋日常模型管理。每個指令承擔一個語意責任：

模型權重存在 ~/.ollama/models/、單一大模型（30B+）可能佔 18 ~ 30 GB、累積超過 100 GB 很常見。清理路徑統一用 ollama rm、Ollama 會同步更新 registry metadata、後續 ollama list 與 ollama pull 才能正確判斷既存模型狀態。

Model tag 命名規則

Model tag 是 Ollama 的模型定位符、形式為 family:size-variant-quantization。同一個 model family 可能有十幾個 tag、對應不同參數量、訓練變體跟量化等級。

選 tag 時的兩個判讀重點：variant（instruct / coding 等用途特化、影響回應風格）、quantization（量化等級、影響記憶體佔用與品質、見 1.2 llama.cpp 的量化標籤對照）。完整 tag 清單在 ollama.com/library。寫 code 場景的推薦選擇詳見 1.4 模型選型。

兩套 API：選哪一套

Ollama 在 11434 同時提供兩套 API、用途互補：

寫 code 場景多半用 /v1/…、因為 IDE plugin 預設講這套形狀。詳細協定背景見 0.3 OpenAI 相容 API。

驗證 streaming 回應：

1curl http://localhost:11434/v1/chat/completions \
2  -H "Content-Type: application/json" \
3  -d '{
4    "model": "gemma3:1b",
5    "messages": [{"role": "user", "content": "Count 1 to 5"}],
6    "stream": true
7  }'

Streaming 回應是一連串 data: {...} 行、每行一個 token chunk。Ollama 原生 /api/generate 還支援 num_predict、temperature、stop 等細項、IDE plugin 內部會自行轉換、終端使用者通常用不到。

進階主題（按需閱讀）

進階段的特色是「沒有它最短路徑仍能跑、但搞懂後體驗大幅提升」。最短路徑只想跑通的讀者可以先跳到排錯、需要時再回來。

背景常駐：launchd service

ollama serve 預設在前景跑、terminal 關掉就停。日常使用建議讓 Ollama 開機自動啟動、用 macOS 的 launchd service 機制：

1brew services start ollama

這個指令做兩件事、決定 Ollama 之後的行為：

1. 寫一個 launchd plist 到 ~/Library/LaunchAgents/homebrew.mxcl.ollama.plist
2. 立刻啟動 ollama serve、之後重開機自動拉起

launchd 是 macOS 原生的服務管理機制、把 process 註冊成 daemon / agent、由系統負責生命週期。brew services 是 Homebrew 對 launchd 的封裝、把 plist 模板跟啟動指令簡化成一行。Log 統一寫到 /opt/homebrew/var/log/ollama.log（Apple Silicon Mac）、出問題第一步先看這個檔。

對應的服務管理指令：

1brew services stop ollama      # 停掉、保留 plist
2brew services restart ollama   # 升級後重啟

完整 plist 內容與 log 範例見 Hands-on：Ollama 安裝。

Gemma 4 MTP 一鍵加速

Multi-Token Prediction（MTP） 是 speculative decoding 的具體實作、用一個小 drafter 預測多個 token、再由 target model 驗證、coding 任務有 2 ~ 3 倍加速。Ollama v0.23.1（2026/5/7 釋出）內建 Gemma 4 的 MTP 一鍵支援、啟用方式只需要 pull 對應 model tag：

1ollama run gemma4:31b-coding-mtp-bf16

這個 tag 內含 target model（31B）跟 drafter（Google 釋出的官方小模型）、Ollama 自動把兩個 model 載入記憶體、推論時並行驗證。記憶體佔用約 18 GB（drafter 約 1 GB、其餘為 target）、適合 32GB+ Mac。詳細原理見 0.4 MLX / MTP / oMLX。

判讀 MTP tag 時的三個重點：

1. Tag 裡的 bf16 描述的是 drafter 精度。Target model 內部已套用量化、實際佔用約 18 GB、跟「整個 31B 用 bf16 跑、要 60+ GB」是兩件事。
2. 加速幅度跟任務 pattern 預測度成正比。Coding（pattern 強）2 ~ 3 倍、純創意寫作或隨機字串生成大約 1.5 倍。
3. 品質由 target model 保證。Drafter 猜錯時 target 會拒絕該預測、最終輸出跟「直接由 target 生成」一致、drafter 只影響速度。

模型常駐：keep_alive

ollama run 第一次跑某個 model 時、需要 30 ~ 60 秒把權重從 SSD 載入記憶體；後續對話則用 cached 權重、快得多。Ollama 預設把載入的 model 留在記憶體 5 分鐘（keep_alive 預設值）、長時間不用會被 unload 釋放記憶體。

長時間穩定使用的場景可以延長 keep_alive：

1OLLAMA_KEEP_ALIVE=-1 ollama serve     # 永久保留
2OLLAMA_KEEP_ALIVE=2h ollama serve     # 保留 2 小時

-1 設定會持續佔用記憶體、適合「整天頻繁用」的工作流；偶爾用一次的場景保持預設、讓系統自動釋放更省記憶體。

對外暴露與信任邊界

預設 Ollama 只聽 127.0.0.1、外部裝置連不上。讓 LAN 內其他機器（例如桌機跑 server、筆電當 client）能用、把 listen address 改成 0.0.0.0：

1OLLAMA_HOST=0.0.0.0:11434 ollama serve

這個設定把 Ollama 暴露在整個區網、任何同網路裝置都能呼叫 API。信任邊界的三種典型情境：

• 家用 / 信任的辦公網路：風險低、可以直接開
• 公共 Wi-Fi、共用網路：透過 SSH tunnel 把 11434 隧道到遠端、或加防火牆規則限制 source IP
• 暴露到 Internet：需要 reverse proxy 加 auth、Ollama 本身沒有內建身分認證

完整資料流判讀見 0.7 隱私 / 資安資料流、綁定模式（loopback / LAN / reverse proxy + auth）跟誤開放後的具體後果見 6.1 推論伺服器的綁定與暴露範圍。

版本管理

Ollama 釋出節奏快、每兩三週可能加新功能或修嚴重 bug。升級流程：

1brew upgrade ollama
2brew services restart ollama   # 若用 launchd service 跑

升級前先看 release notes、確認三件事：

1. 是否引入 breaking API change（IDE plugin 可能要對應更新）
2. 是否棄用舊 model tag（拉新 tag 取代）
3. 是否帶來想要的新功能（例如新模型支援、加速優化）

排錯快速判讀

排錯段的設計是「先給操作原則、再列觸發條件」、讓讀者快速定位現象屬於哪一類。

Port 11434 已被佔用

操作原則：先檢查是不是舊 Ollama 還在跑、再決定 kill 或換 port。lsof / pkill 的角色是找出佔用方並送終止訊號。

1lsof -i :11434          # 看誰佔 11434
2pkill -f "ollama serve" # 確認是舊 Ollama 才 kill
3ollama serve &          # 重啟、& 是把 process 丟背景

需要兩個 Ollama 並存的場景、改 port 啟動：

1OLLAMA_HOST=127.0.0.1:11435 ollama serve

IDE plugin 的 apiBase 也要對應改成 11435。

記憶體不足、模型崩潰

操作原則：先用 ollama ps 看實際載入了什麼、再對照 0.5 記憶體預算 決定降級。

1ollama ps
2# NAME           ID      SIZE     PROCESSOR    UNTIL
3# gemma4:31b...  abc123  18 GB    100% GPU     5 minutes from now

模型大小超過 Mac 記憶體預算時的可選路徑：

• 換較小 model（例如 31B → 14B）
• 換較激進量化（例如 Q5_K_M → Q4_K_M）
• 縮短 context window（在 IDE plugin 端設定）

模型載入很慢

操作原則：第一次載入慢屬於正常、後續呼叫如果還是慢、檢查 keep_alive 設定。

第一次載入 18 GB 權重需要 30 ~ 60 秒、屬於 SSD → RAM 的真實 I/O 時間。如果發現「每次第一個請求都慢」、表示 keep_alive 太短、模型每次被 unload 又重新載入。延長 keep_alive 解決：

1OLLAMA_KEEP_ALIVE=1h ollama serve

代價是模型常駐記憶體、其他應用可用記憶體變少。

Model cache 過大佔滿 SSD

操作原則：清理用 ollama rm <tag>、Ollama 才會同步更新 registry metadata。

1ollama list             # 看哪些 model 佔空間
2ollama rm <tag>         # 刪除單一 model

手動 rm -rf ~/.ollama/models/ 會留下 registry metadata 不一致、後續 ollama list 出錯、ollama pull 也可能誤判已存在。需要完全重置的場景、用：

1brew services stop ollama
2rm -rf ~/.ollama
3brew services start ollama

這會清掉所有 model 跟設定、重新從零開始。

跟其他伺服器並存

Ollama 設計上可以跟 LM Studio、llama.cpp 同時在一台 Mac 跑、預設 port 不同：

並存的好處是「主力穩定跑 Ollama、實驗模型用 LM Studio」、Continue.dev 等介面層可以同時設多個 model、UI 上下拉切換。並存設定範例見 1.1 LM Studio。

下一章

下一章可選擇：

• 想對比 GUI 派的選擇：1.1 LM Studio
• 想了解底層 / Ollama 跟 llama.cpp 的關係：1.2 llama.cpp
• 直接進入 VS Code 整合：1.3 VS Code + Continue.dev

驗證日期：2026-05-11 Ollama 版本：0.23.2 示範模型：gemma3:1b（約 815 MB、選最小可運行的 Gemma 變體當驗證對象）

前置設定

表中 brew --version 這關若還沒過、代表 Homebrew 沒裝。新機從零的安裝順序（Homebrew、PATH、bash）見 macOS 新機基礎建設。

選 1B 模型只是為了驗證流程、能力很弱、實際寫 code 場景請用 14B / 31B 級。模型大小跟記憶體 / 磁碟對應關係見 0.5 Apple Silicon 記憶體預算。

安裝 Ollama

用 Homebrew 安裝、是 macOS 上最直接的路徑：

1brew install ollama

執行時間在 broadband 大約 30 秒到 2 分鐘、視 dependency cache 是否已有（Ollama 依賴 mlx-c 等 Apple Silicon 加速函式庫、首次裝較久）。

裝完看到的 caveat 訊息：

1To start ollama now and restart at login:
2  brew services start ollama
3Or, if you don't want/need a background service you can just run:
4  OLLAMA_FLASH_ATTENTION="1" OLLAMA_KV_CACHE_TYPE="q8_0" /opt/homebrew/opt/ollama/bin/ollama serve

兩種啟動模式：

• launchd service（推薦日常用）：開機自動啟動、跑在背景。
• 前景手動跑：terminal 開著、關掉就停。

驗證 binary 路徑：

1which ollama
2# 應該回 /opt/homebrew/bin/ollama

啟動 Ollama Service

選 launchd service 模式：

1brew services start ollama

預期輸出：

1==> Successfully started `ollama` (label: homebrew.mxcl.ollama)

這個動作做兩件事：

1. 註冊一個 launchd plist（macOS 開機自啟動 / 背景服務的設定檔、見 launchd-service 卡片）到 ~/Library/LaunchAgents/homebrew.mxcl.ollama.plist。
2. 立刻啟動 ollama serve、之後重開機自動啟動。

驗證 server 真的在跑：

1curl -s http://localhost:11434/api/version

預期回：

1{"version":"0.23.2"}

看到這個 JSON 就證明三件事：Ollama daemon 跑了、port 11434 通了、API 結構正確。

拉第一個模型

Ollama 用 ollama pull 從官方 registry 下載模型：

1ollama pull gemma3:1b

Gemma 3 1B 約 815 MB、broadband 約 1-2 分鐘下載。下載過程顯示多階段：

1pulling 7cd4618c1faf: 100% ▕██████████████████▏ 815 MB
2pulling e0a42594d802: 100% ▕██████████████████▏  358 B
3pulling dd084c7d92a3: 100% ▕██████████████████▏  8.4 KB
4pulling 3116c5225075: 100% ▕██████████████████▏   77 B
5pulling 120007c81bf8: 100% ▕██████████████████▏  492 B
6verifying sha256 digest
7writing manifest
8success

幾個 hash blob 分別是：模型權重（最大那個）、tokenizer、template、license metadata 等。Ollama 把這些統一管理、放在 ~/.ollama/models/。

驗證模型已下載：

1ollama list

預期：

1NAME         ID              SIZE      MODIFIED
2gemma3:1b    8648f39daa8f    815 MB    35 seconds ago

驗證 OpenAI 相容 API

OpenAI 相容 API 是下游所有工具（IDE plugin、RAG pipeline、MCP server、Continue.dev 等）依賴的介面 contract、驗證它能正常回應、整個 stack 才走得通：

1curl -s http://localhost:11434/v1/chat/completions \
2  -H "Content-Type: application/json" \
3  -d '{
4    "model": "gemma3:1b",
5    "messages": [{"role":"user","content":"Reply in one short sentence: what is 2+2?"}],
6    "stream": false
7  }'

預期回 JSON、choices[0].message.content 是模型回答（如 "2 + 2 = 4"）。看到合理回答就證明：

1. Ollama 跟模型權重對接好。
2. OpenAI 相容 API 格式正常（IDE plugin 可以接）。
3. 推論流程整條通。

常見的失敗回應跟下一步：

• {"error":"model 'gemma3:1b' not found, try pulling it first"}：先跑 ollama pull gemma3:1b、確認 ollama list 看到該 tag。
• curl: (7) Failed to connect to localhost port 11434: Connection refused：server 沒在跑、回 brew services list 看 status、若是 stopped 跑 brew services start ollama。
• {"error":"json: cannot unmarshal ..."}：請求格式錯（例如 messages 寫成 string 不是 array）、檢查 JSON body。
• 連得上但長時間沒回應：第一次載入大 model 需要 30 ~ 60 秒、看 ~/.ollama/logs/server.log 確認是否還在 loading。

用內建 CLI 互動模式也行：

1ollama run gemma3:1b

進入 REPL、可以打字對話。/bye 離開。

第一次跑 ollama run 會把模型載入記憶體（1B 模型大約 1-2 秒）、之後對話延遲低。如果幾分鐘沒用、模型會被 unload 釋放記憶體、下次 run 又要等載入。控制行為的環境變數是 OLLAMA_KEEP_ALIVE（預設 5 分鐘）。

常見前置設定問題

Port 11434 被佔用

1lsof -i :11434

若已有 process 占用、可能是先前手動跑過 ollama serve 沒關。kill 後再 start service：

1pkill -f "ollama serve"
2brew services restart ollama

ollama: command not found（裝完還是找不到）

Homebrew 在 Apple Silicon 預設裝到 /opt/homebrew/bin、shell PATH 應該已含。若沒含：

1echo $PATH | tr ':' '\n' | grep homebrew
2# 若沒看到 /opt/homebrew/bin、要加進 ~/.zshrc：
3echo 'export PATH="/opt/homebrew/bin:$PATH"' >> ~/.zshrc
4source ~/.zshrc

Server 啟動但 curl 失敗

1brew services list | grep ollama

若 status 不是 started、看 log：

1tail -50 /opt/homebrew/var/log/ollama.log

常見原因：port 衝突、權限問題、上次 crash 沒清乾淨。

完整排錯流程見 1.7 排錯方法論。

之後想做的事

• 接 VS Code：見 1.3 VS Code + Continue.dev 整合。設定 apiBase: http://localhost:11434 就能用。
• 跑更大模型：32GB+ Mac 推薦 gemma4:31b-coding-mtp-bf16（18 GB）。模型選擇見 1.4 模型選型優先順序。
• 加 embedding：codebase 索引要 embedding 模型：ollama pull nomic-embed-text（274 MB）、見 4.1 RAG 原理。

升級 / 移除

升級：

1brew upgrade ollama
2brew services restart ollama

完整移除：

1brew services stop ollama
2brew uninstall ollama
3rm -rf ~/.ollama  # 清模型 cache（可選）

何時這篇會過時

• brew install ollama 安裝方式跟 OpenAI 相容 API 形狀短期內不會變（生態都依賴）。
• gemma3:1b 這個具體 tag 預期會被新模型取代、但「拉一個小模型驗證流程」的方法不變。
• launchd service 機制是 macOS 系統 API、不會 deprecate。

讀的時候若 brew install 跑失敗、查 Ollama GitHub release notes；其餘驗證步驟結構通用。