用作走查的任務：PM 交派「做一個 customer support agent、能處理用戶查詢、必要時自動完成操作（如改地址）。」本案例聚焦「改地址」這個高頻 query type 走完整流程。

本案例的設計反射

整個流程分七階段：

1. 觀察人類工作流：訪談、決定 task decomposition
2. 典範定位：哪段該 deterministic、哪段該 fuzzy
3. 工作流設計：每個 step 選對應的 LLM / tool / RAG / HITL 形態
4. 協議跟自主度決定：是 single agent / multi-call / multi-agent
5. Trace instrumentation：哪些資訊要記
6. Eval 設計：先選座標、再選工具
7. Iteration loop：error analysis → 修哪一層 → 看 metric 收斂

初次設計 LLM 應用時最常省略階段 1、2、5、6、直接跳到階段 3 開始寫 prompt——這條路會走進「prompt 改了 20 版、無法判讀有沒有變好」的迭代無收斂。本案例強調的是設計反射動作的順序、不是寫 prompt 技巧。

階段 1：觀察人類工作流

PM 給的任務描述是「處理用戶查詢」、但「查詢」涵蓋的範圍可能很大。第一個反射動作是坐在客服旁邊觀察兩天、不是打開 IDE。

實際做的事：

• 統計收到的 query 類型分佈（退款 / 改地址 / 查詢訂單狀態 / 抱怨 / 開放問題各佔多少）。
• 看每類 query 的 human resolution 流程（哪幾步、要查哪些系統、要遵守哪些 policy）。
• 看哪幾類 query 是 high volume + low complexity（最值得自動化）、哪幾類是 low volume + high complexity（自動化 ROI 差）。
• 記下 human 在哪些 step 卡住、哪些 step 反覆需要查同樣資料。

訪談結束、你得到一張 task decomposition map。本案例假設聚焦在「用戶請求改地址」這個高頻 query type：

1User: 「我搬家了、訂單編號 #12345、新地址是 ___」
2   ↓
31. 解析意圖 + 抽取訊息（訂單編號、新地址）
42. 查訂單狀態（已出貨？未出貨？已送達？）
53. 查 policy（這個訂單狀態 + user tier 能不能改地址？）
64. 若可：執行改地址（呼叫物流 / 庫存 API）
75. 若不可：解釋為什麼、給替代方案
86. 草擬回覆 email、發出

引用原理：這個 decomposition 本身對應 0.8 fuzzy engineering（deterministic-vs-fuzzy 卡）的「先分解任務、再判讀每段該 deterministic 還是 fuzzy」。

階段 2：典範定位

對每個 step 做典範定位（deterministic / fuzzy）：

判讀的重點是邊界各歸各位：規則跟政策走 code、人話跟意圖解析走 LLM。

• Policy check 寫成 code（如「user tier + 訂單狀態 → 能否改地址」是 deterministic 規則）。對應反例：把規則塞進 prompt 讓 LLM 判斷、會偶爾跳過規則或誤判 tier。
• 「能不能做」這類 yes/no 走規則。對應反例：用 LLM 算判斷、debug 困難且非確定性。
• 「Helpful 的回覆」走 LLM 寫。對應反例：在 code 內 hard-code 模板、變成僵化的客服機器人腔。

最容易混的邊界在 step 6：「草擬 email」是 fuzzy（要寫人話、tailor to 情境）、「發送 email」是 deterministic（呼叫 API、處理錯誤碼）。把這兩件事拆開、草擬可以 retry / 改 prompt 不影響發送邏輯、發送有結構化 error 不被 LLM hallucinate 蓋過。Step 4「執行改地址」也類似：tool call 本身 deterministic、但是否該 call 的判讀回到 step 3 的 policy check。

引用原理：0.8 fuzzy engineering 的「哪段該 deterministic / 哪段該 fuzzy」決策框架、特別是反模式「邊界用錯」段。

階段 3：工作流設計

對每個 step 選對應的工具：

兩個容易選錯的 step 展開：

Step 1 為何要 structured output、不是純 prompt 解析：抽取結果要餵 step 2-4 的 deterministic tool、order_id 抽錯就整個流程斷。純 prompt 描述「請輸出 JSON」是弱保證、structured output / constrained decoding 是強保證（見 3.10 constrained decoding 內部）。Trade-off：強格式可能犧牲表達彈性、但這個 step 不需要彈性、要的是可靠。

Step 5 為何配 RAG 而非純 few-shot：客服 case 涵蓋多種情境（訂單已出貨 / 已送達 / VIP / 一般 user / 不同國家 policy）、固定 few-shot 範例 cover 不全。RAG 從歷史 case 庫即時 retrieve 最相似的解釋範例、屬於 4.0 prompt 技術光譜 context 軸的 retrieval-augmented prompting。

引用原理：

• Step 1 的 structured output → 4.6 應用層協議
• Step 2-4 的 tool 設計 → 4.3 tool use
• Step 4 的 pre-act HITL → 4.5 人機協作拓樸 pre-act 段。對比講座 Workera appeal 是 post-hoc、本案例選 pre-act 是因為改地址不可逆 + 物流影響大、必須在執行前審
• Step 5 的 RAG → 4.1 RAG 原理 + 4.0 prompt 技術光譜 context 軸

階段 4：協議跟自主度決定

這個工作流的控制流是線性的（1→2→3→4→5→6）、有條件分支（step 3 結果決定走 4 還是 5）、但每步順序固定。判讀：

該用什麼結構：

• 不適用 Multi-agent：步驟順序固定、角色差異不大、orchestration overhead 純增。
• 不適用 Single agent loop（model 自決下一步）：本案例假設 single-turn / 短多 turn、步驟順序明確、不需要 agent 自決。若 user 互動多輪 + turn 數不固定（如 user 中途補資訊、改主意、追問）、可考慮 agent loop。
• 採用 Multi-call pipeline + router：寫成 deterministic pipeline、step 3 後有 router 分流。

引用原理：

• 4.8 multi-agent 拓樸 的「先 multi-call、不夠再 multi-agent」反射
• 4.7 workflow patterns 的 pipeline + router 模式
• 4.4 agent 架構 的「先 single-call、不夠再 agent」反射

自主度：

• Step 1（parse）、5（解釋）、6（草擬 email）：full auto。
• Step 2、3（查訂單、查 policy）：full auto（read-only）。
• Step 4（執行改地址）：pre-act HITL（高風險 + 不可逆）、有 diff show、user 可以 reject。
• Step 6（發 email）：可選 pre-act HITL（看公司風格、保守版要審 email、激進版自動發）。

階段 5：Trace Instrumentation

工作流上線前、先設計要記哪些資訊。Eval 跟 debug 都靠 trace、沒 trace 後面什麼都做不了。

每個 step 要記：

整段 trace 要綁同一個 conversation_id、可以後面 join 起來看完整流程。

引用原理：4.20 LLM tracing。

階段 6：Eval 設計

先選座標、再選工具。對本案例的每個 eval 需求、用 4.13 三軸座標 定位。下面列的 threshold 數字（95%、80%、≥4 等）是 illustrative、實際數字隨產品 baseline、user 容忍度、業務代價而定、不是通用標準。

Eval 1：Step 1 抽取準不準

• 三軸：Objective（有 ground truth）+ Component（測單 step）+ Quantitative（accuracy）。
• 工具：寫 100 個有標註的 query、跑 step 1、看 extraction accuracy（order_id 對 + new_address 對的比例）。
• Threshold：< 95% 不上線。

Eval 2：Step 2-4 tool call 行為正確

• 三軸：Objective + Component + Quantitative。
• 工具：mock API、給 step 2-4 各 50 個 case、看 tool call 參數對不對、返回值處理對不對。
• Threshold：100%（這是 deterministic 行為、不該有錯）。

Eval 3：Step 5 解釋品質

• 三軸：Subjective（沒有單一正解）+ Component + Quantitative。
• 工具：LLM-as-judge with rubric（clarity / helpfulness / tone）、scale 1-5、aggregate average。
• Threshold：average ≥ 4、no 1-2 比例 < 5%。

Eval 4：Step 6 email 品質

• 三軸：Subjective + Component + Quantitative + 加 Qualitative human review。
• 工具：LLM judge 給分 + 每週抽 20 封 human review、看是否有 hallucinate 承諾、是否符合公司 tone。
• Threshold：judge 平均 ≥ 4、human review 沒有 critical issue。

Eval 5：E2E success rate

• 三軸：Objective + End-to-end + Quantitative。
• 工具：跑 200 個 representative case、看「完整完成 + user 沒申訴」的比例。
• Threshold：≥ 85% baseline、降到 < 80% alert。

Eval 6：User 滿意度

• 三軸：Subjective + End-to-end + Quantitative。
• 工具：每次互動結束顯示 thumbs up/down + optional 留言、追蹤 weekly。
• Threshold：thumbs up rate > 80%、appeal rate < 5%。

Eval 7：Failure mode pattern（持續做）

• 三軸：Objective / Subjective + End-to-end + Qualitative。
• 工具：每週讀 50 個 sampled traces + 100% 讀 failure / appeal traces、找 emerging pattern。
• 產出：bug ticket、prompt 修改 hypothesis、policy 補強 hypothesis。

引用原理：

• 三軸座標 → 4.13 eval design framework
• LLM judge rubric → 4.21 LLM-as-Judge
• Trace 接 eval → 4.20 LLM tracing

階段 7：Iteration Loop

上線後、不是「等出問題」、是持續 iteration。典型 iteration cycle：

 1Production trace + eval result
 2   ↓
 3[Error analysis：找 emerging pattern]
 4   ↓
 5   Hypothesis：哪一層有問題？
 6   ├── Prompt 層 → 改 prompt → A/B test → 看 eval 收斂
 7   ├── Tool 層   → 改 tool / schema → 跑 component eval → 收斂
 8   ├── RAG 層    → 改 chunking / query rewriting → 跑 [retrieval recall](/llm/knowledge-cards/retrieval-recall/) → 收斂
 9   ├── Policy 層 → 改 deterministic rule → 跑 step 3 component eval → 收斂
10   └── Model 層  → 換 model → 跑全 eval set → 收斂
11   ↓
12[改動進 production]
13   ↓
14[Frozen baseline 留著、新版本跟它比、漂移看得見]

判讀「該改哪一層」的反射：

引用原理：

• Prompt 跟 model 層的失敗診斷 → 4.0 prompt 技術光譜 systematic vs random error
• 整體 fuzzy / deterministic 邊界判讀 → 0.8

五個容易遺漏的設計反射

實務上常常省略這五個反射動作、走進無收斂迭代：

反射一：先觀察、再開 IDE

階段 1 的價值是把 task decomposition 跟真實人類工作流對齊。沒這層對齊、寫出來的 prompt 跟 tool 拆法跟 reality 偏離、三天後重做。階段 1 的兩天比階段 3 的兩週值得。對應反例：「我先寫個 prompt 試試」、跳過觀察直接寫 code。

反射二：Policy 寫成 code、LLM 只解析意圖

判斷類規則（user tier、訂單狀態、可否操作）走 deterministic code、LLM 只負責「user 想做什麼」這層意圖抽取。這條邊界讓 debug 容易、規則更新不用 prompt iteration。對應反例：「LLM、請判斷這個訂單能不能改地址、規則如下：…」——把判斷塞進 prompt、debug 困難、規則漂移無從追蹤。對應 0.8 的「邊界用錯」反模式。

反射三：Trace 是 day-1 設計

從第一天就把 input / output / latency / token / step name / decision branch / error 進 trace、綁同一個 conversation_id。Eval 跟 debug 都靠 trace、沒 trace 後面什麼都做不了。對應反例：「先讓系統跑起來、之後再加 trace」——出 bug 時 debug 從零開始、production trace 不可回溯。

反射四：Deterministic 行為用 deterministic check

有 ground truth 的行為（抽取對不對、API 參數對不對、JSON schema 合不合）用 Python 函數驗證、判斷成本低、精度高。LLM judge 留給沒 ground truth 的 subjective 行為。對應反例：用 LLM judge 測「step 1 抽取對不對」——cost 翻倍、精度反而不如 deterministic check。對應 4.13 軸誤選一。

反射五：保留 frozen baseline

Frozen baseline 是把某個特定 prompt + 特定 model 跑 production 一段時間後 freeze 起來、每次新版本都跟它比、漂移看得見。對應反例：每次只跟「上一版」比、半年後累積漂移完全不可見、「整體變好了沒」無從回答。

跟其他章節的對應總表

本案例每階段引用的原理章節彙整：

下一步

返回：模組四首頁、或回到 hands-on 索引。

驗證日期：2026-05-12 ComfyUI：main branch、shallow clone 示範模型：Stable Diffusion XL base 1.0（6.5 GB、stabilityai/stable-diffusion-xl-base-1.0） Python：3.14（venv 隔離、不污染系統）

前置設定

ComfyUI 在 Apple Silicon 跑 Diffusion 用 MPS（Metal Performance Shaders）backend、不需要 NVIDIA CUDA。但跑 SDXL 至少要 12 GB 統一記憶體留給 model + activation、16 GB Mac 跟其他 app 一起會吃緊。

Clone ComfyUI

放在 ~/Projects/ 下、跟其他 dev project 同層：

1cd ~/Projects
2git clone --depth 1 https://github.com/comfyanonymous/ComfyUI.git
3cd ComfyUI

--depth 1 只拉最新 commit、不拉全部歷史、省幾百 MB。要追歷史 / submit PR 才需要 full clone。

ComfyUI 目錄結構（核心部分）：

 1ComfyUI/
 2├── main.py              # 啟動 entry point
 3├── server.py            # HTTP server
 4├── nodes.py             # 內建節點實作
 5├── custom_nodes/        # 第三方 / 客製節點放這
 6├── models/
 7│   ├── checkpoints/     # SD / SDXL 主 model 檔放這
 8│   ├── loras/           # LoRA 微調權重
 9│   ├── vae/             # VAE 模型
10│   ├── controlnet/      # ControlNet 模型
11│   └── ...
12├── output/              # 生成的圖
13├── input/               # 拖進 ComfyUI 的圖片
14└── requirements.txt

建 venv + 裝 dependencies

ComfyUI requirements 含 PyTorch、numpy、PIL、safetensors、einops 等、套件多、版本敏感。用 venv 隔離：

1cd ~/Projects/ComfyUI
2python3 -m venv venv
3source venv/bin/activate
4python --version  # 確認在 venv 內
5pip install --upgrade pip

裝 dependencies：

1pip install -r requirements.txt

實測時間：10-15 分鐘（torch + 各種 dep）、首次跑會編譯部分 C extension。完成後預期看到：

1Successfully installed Mako-... MarkupSafe-... Pillow-... PyOpenGL-... ...
2  torch-... torchvision-... torchaudio-... ...
3  safetensors-... transformers-... ...

驗證 PyTorch + MPS：

1python -c "import torch; print('torch:', torch.__version__, 'mps:', torch.backends.mps.is_available())"
2# torch: 2.x.x mps: True

mps: True 表示 Apple Silicon GPU 加速可用。

下載 SDXL base 模型

SDXL base 約 6.5 GB、是 Stable Diffusion XL 的基礎 model。從 Hugging Face 拉到 ComfyUI 的 models/checkpoints/：

1mkdir -p ~/Projects/ComfyUI/models/checkpoints
2cd ~/Projects/ComfyUI/models/checkpoints
3
4# -L 跟 redirect、--continue-at - 支援中斷後重續、避免 6.5 GB 重下
5curl -L --continue-at - -o sd_xl_base_1.0.safetensors \
6  "https://huggingface.co/stabilityai/stable-diffusion-xl-base-1.0/resolve/main/sd_xl_base_1.0.safetensors?download=true"

下載時間視網速、10-30 分鐘 broadband 都正常。網路中斷時重跑同一個指令、--continue-at - 會從中斷處續傳、不用重下 6.5 GB。完成後：

1ls -lh sd_xl_base_1.0.safetensors
2# 6.5 GB

可選的進階模型：

SDXL 6.5 GB 是「能驗證 + 不過大」的甜蜜點。再小可以選 SD 1.5（4 GB）、跑 Flux 要 24 GB 磁碟 + 16 GB+ 統一記憶體。

啟動 ComfyUI Server

1cd ~/Projects/ComfyUI
2source venv/bin/activate
3python main.py

預期輸出：

1[Prompt Server] Starting ComfyUI...
2Total VRAM 32768 MB, total RAM 32768 MB
3pytorch version: 2.x.x
4Set vram state to: SHARED
5Device: mps
6Using sub quadratic attention for cross-attention
7...
8Starting server
9To see the GUI go to: http://127.0.0.1:8188

Apple Silicon 統一記憶體被 PyTorch 報成 VRAM 是預期、不是 bug：mps backend 把整個統一記憶體當成「GPU 可見記憶體」、所以 32GB Mac 顯示 Total VRAM 32768 MB。實際使用上 ComfyUI、其他 app 跟系統共用同一塊。

關鍵驗證：

• Device: mps → Apple Silicon GPU 啟用
• Starting server + http://127.0.0.1:8188 → server 跑了

開瀏覽器到 http://127.0.0.1:8188、看到節點式 UI 就成功。第一次開啟會載入預設 workflow（一個簡單 text-to-image）。

要對外暴露（讓 LAN 內其他機器連）：

1python main.py --listen 0.0.0.0 --port 8188

跟 0.7 隱私資料流 提的一樣、0.0.0.0 等於暴露給整個區網、家用 OK 公共網路要小心。

跑第一張圖

ComfyUI 預設 workflow 是 text-to-image：

1. CheckpointLoader 節點：選 sd_xl_base_1.0.safetensors。
2. CLIPTextEncode（Prompt）節點：輸入 prompt、例如 a photograph of a cat sitting on a wooden chair, natural lighting。
3. CLIPTextEncode（Negative）節點：輸入 negative prompt、例如 blurry, low quality, artifacts。
4. EmptyLatentImage 節點：設定 1024×1024（SDXL 最佳尺寸）。
5. KSampler 節點：steps=20、cfg=7、sampler=euler 或 dpmpp_2m。
6. VAEDecode 節點：把 latent 轉成 RGB image。
7. SaveImage 節點：存到 output/。

點右側 panel 的 Queue Prompt、開始生成。

實測時間（M4 Pro 32GB、SDXL base、1024×1024、MPS backend）：

16GB Mac 跑 SDXL：每張 60-180 秒、可能會降頻。

生成完成後在 output/ 看到 PNG 檔（如 comfyui-test_00001_.png）。

用 REST API 直接生成（不開瀏覽器）

GUI 適合互動探索、自動化要走 REST API。完整 script 在 scripts/comfyui-test/generate.py、實際驗證指令：

1cd ~/Projects/blog
2python3 scripts/comfyui-test/generate.py --steps 15

腳本流程：

 1def build_workflow(prompt_text, neg_text, steps):
 2    return {
 3        "3": {"inputs": {"seed": 42, "steps": steps, "cfg": 7.0, "sampler_name": "euler",
 4                         "scheduler": "normal", "denoise": 1.0,
 5                         "model": ["4", 0], "positive": ["6", 0],
 6                         "negative": ["7", 0], "latent_image": ["5", 0]},
 7              "class_type": "KSampler"},
 8        "4": {"inputs": {"ckpt_name": "sd_xl_base_1.0.safetensors"},
 9              "class_type": "CheckpointLoaderSimple"},
10        "5": {"inputs": {"width": 1024, "height": 1024, "batch_size": 1},
11              "class_type": "EmptyLatentImage"},
12        "6": {"inputs": {"text": prompt_text, "clip": ["4", 1]},
13              "class_type": "CLIPTextEncode"},
14        "7": {"inputs": {"text": neg_text, "clip": ["4", 1]},
15              "class_type": "CLIPTextEncode"},
16        "8": {"inputs": {"samples": ["3", 0], "vae": ["4", 2]},
17              "class_type": "VAEDecode"},
18        "9": {"inputs": {"filename_prefix": "comfyui-test", "images": ["8", 0]},
19              "class_type": "SaveImage"},
20    }

workflow JSON 結構解釋：

• 每個 key（“3”、“4”、…）是節點 ID。任意整數字串、只要在 workflow 內唯一即可。
• class_type：節點類型（KSampler、CheckpointLoaderSimple、CLIPTextEncode 等）、ComfyUI 內建。
• inputs：節點參數。標量值（如 1024、"euler"）直接寫；連到別的節點輸出用 [node_id, output_index] 形式。
• ["4", 0] 表示「節點 4 的第 0 個 output」。CheckpointLoaderSimple 有三個 output：model（0）、clip（1）、vae（2）、所以 ["4", 0] 是 model、["4", 1] 是 clip、["4", 2] 是 vae。

每個節點做什麼：

• 4 CheckpointLoaderSimple：載 SDXL safetensors、輸出 model / clip / vae 三個東西。是整條 graph 的根。
• 5 EmptyLatentImage：建一張 1024×1024 的空白 latent tensor（不是 RGB 圖、是 4-channel latent space tensor）。SDXL 的 「畫布」。
• 6 CLIPTextEncode (positive)：把 prompt 文字用 CLIP text encoder 轉成 conditioning vector。
• 7 CLIPTextEncode (negative)：同上、但是 negative prompt（要 avoid 的特徵）。
• 3 KSampler：核心 denoising loop。15-30 個 step、把 latent 從噪聲變成跟 conditioning 對齊的 latent。
• 8 VAEDecode：把 latent 用 VAE 解碼成 RGB 圖（1024×1024×3）。
• 9 SaveImage：寫 PNG 到 output/ 目錄、檔名 prefix comfyui-test。

為什麼 graph 結構這樣：

• 為什麼 model / clip / vae 從同一個 checkpoint 拿：SDXL 設計上三個元件互相 train、必須同源。從不同 checkpoint 拿會造成生成品質崩。
• 為什麼 EmptyLatentImage 不直接接 KSampler、要設 batch_size：保留 batch 維度、未來要 batch generation（一次生 4 張）改 batch_size: 4 就好、其他節點不用改。
• 為什麼 sampler 用 euler、scheduler 用 normal：最簡單的組合、SDXL base 上品質可預測。其他選項（dpmpp_2m、karras scheduler 等）品質可能更好但效果各模型不同。
• 為什麼 cfg=7.0：classifier-free guidance scale。SDXL 的標準預設、太低（< 3）模型忽略 prompt、太高（> 12）過 saturated。
• 為什麼 seed=42：固定 seed 讓結果可重現。每次跑同 prompt 同 seed 同 model 結果完全一樣——是調 prompt / 比較 model 的必要條件。

 1def main():
 2    workflow = build_workflow(args.prompt, args.neg, args.steps)
 3    client_id = str(uuid.uuid4())
 4    resp = http_post_json("/prompt", {"prompt": workflow, "client_id": client_id})
 5    prompt_id = resp["prompt_id"]
 6
 7    while True:
 8        time.sleep(2)
 9        history = http_get_json(f"/history/{prompt_id}")
10        if prompt_id in history:
11            outputs = history[prompt_id].get("outputs", {})
12            break
13
14    img = outputs["9"]["images"][0]
15    qs = urllib.parse.urlencode({"filename": img["filename"], "type": "output"})
16    blob = http_get_bytes(f"/view?{qs}")
17    Path(args.out).write_bytes(blob)

每段做什麼：

1. client_id = str(uuid.uuid4())：每個 client 識別碼。ComfyUI 用 client_id 把 progress events 路由給正確 WebSocket subscriber。本 demo 用 polling、client_id 隨意產生即可。
2. POST /prompt：送 workflow + client_id、server 回 prompt_id（這次 job 的 UUID）。Server 把 workflow 丟進 internal queue、立刻 return、不會等 generation。
3. while True: time.sleep(2); GET /history/{prompt_id}：polling 等 job 完成。完成的 job 才會出現在 /history 裡（執行中 / queued 都不算）。
4. if prompt_id in history：完成判讀——history 內出現該 prompt_id 表示 generation 結束。
5. outputs["9"]["images"][0]：節點 9 (SaveImage) 的輸出、含 filename、subfolder、type 等資訊。
6. /view?filename=...&type=output：拿生成的 PNG bytes。type=output 是 ComfyUI 的內部 dir 標記（區分 output / input / temp）。

為什麼這樣設計：

• 為什麼 polling 而不是 WebSocket：WebSocket 要 subscribe events、處理 connection lifecycle、邏輯複雜。Polling 兩行解決、對教學 demo 夠用。Production 自動化系統建議用 WebSocket、知道每個 progress event。
• 為什麼 time.sleep(2)：太短（< 1s）對 server 造成不必要 polling；太長（> 5s）感知延遲明顯。2 秒是 demo 友善平衡。
• 為什麼用 prompt_id 而不是 client_id 查 history：一個 client 可能送多個 job、prompt_id 唯一識別 job。client_id 主要用 WebSocket 訂閱、不是 history query 主鍵。
• 為什麼 Path(args.out).write_bytes(blob)：PNG 是 binary、用 write_bytes 直接寫；改用 open(...).write() 的 text mode 會在編碼轉換時破壞檔案內容。

實測：M4 Pro 32GB、prompt 「a photograph of an orange cat sitting on a wooden chair, soft natural lighting, detailed fur」、15 steps、cfg=7、euler+normal sampler、seed=42 → 106 秒生成 1024×1024 PNG、1.65 MB。

ComfyUI 的 REST API 形狀（無 OpenAI 相容層）

ComfyUI 沒提供 OpenAI 相容 API、它的 API 是自己的 REST + WebSocket：

• POST /prompt：丟一個 workflow JSON、回傳 job id。
• GET /history/{prompt_id}：查看生成結果。
• GET /view?filename=X：拿生成的圖。
• WebSocket：訂閱 job progress events。

API 形狀跟 Diffusion 任務匹配、跟 LLM 的 /chat/completions 完全不同——這正是 4.1 RAG 章節 提到「Diffusion 跟 Transformer 工具鏈互不通用」的具體展現。Ollama / LM Studio 對接 Continue.dev 的 OpenAI 相容路徑、跟 ComfyUI 接 SDXL 是完全平行的兩條路。

常用 Custom Nodes

ComfyUI 的核心功能來自 custom nodes、社群維護。最常用：

安裝方式（透過 ComfyUI-Manager）：

1cd ~/Projects/ComfyUI/custom_nodes
2git clone https://github.com/ltdrdata/ComfyUI-Manager.git
3# 重啟 ComfyUI、UI 多一個 Manager 按鈕、之後用 Manager 裝其他 node

常見坑

Python 版本太新、torch 沒 wheel

PyTorch 對最新 Python（3.13、3.14）的 wheel 發布有 lag、可能 pip install -r requirements.txt 跑 build from source 慢 + 失敗。退到 Python 3.11 / 3.12：

1brew install python@3.11
2python3.11 -m venv venv
3source venv/bin/activate
4pip install -r requirements.txt

mps: False、跑在 CPU 上

確認 PyTorch 是 Apple Silicon 版本（不是 x86_64 emulation）：

1python -c "import platform; print(platform.machine())"
2# arm64 ← 正確；x86_64 ← 走 Rosetta、要重裝

如果是 x86_64、表示 venv 用了 Intel Python。重建 venv：

1deactivate
2rm -rf venv
3arch -arm64 python3 -m venv venv

記憶體不夠、推論時 crash

SDXL 在 16 GB Mac 上吃緊、可能 swap 或 crash。緩解：

1# 降解析度
2python main.py --normalvram   # 預設、~12 GB
3python main.py --lowvram      # 較省、~8 GB、慢
4python main.py --novram       # 極省、~4 GB、極慢、實用上界

或換 SD 1.5（4 GB checkpoint）、記憶體需求 < SDXL 的一半。

Workflow JSON 載入失敗

ComfyUI workflow 是 JSON 描述節點 + 連線。如果是別人分享的 workflow、可能用了你沒裝的 custom node。錯誤訊息會列出缺哪些 node、用 ComfyUI-Manager 補裝。

Port 8188 被佔

1lsof -i :8188
2python main.py --port 8189  # 改 port

跟 LLM stack 並存

ComfyUI 用 port 8188、跟 Ollama (11434) / LM Studio (1234) 完全不撞、可同時跑。實務配置：

各服務獨立、不干擾、可以一台 Mac 跑全部（看記憶體預算）。

何時這篇會過時

• ComfyUI 主分支 API 短期內穩定（大量社群依賴）。
• SDXL base 1.0 不會消失、但會被新版本（SDXL 1.1、Flux 等）取代——「下載 .safetensors 放 models/checkpoints/」流程不變。
• MPS backend 持續優化、效能會提升、但介面不變。
• Python 版本相容性會持續演化、pip install -r requirements.txt 偶爾要降版 Python。

讀的時候若 pip install 失敗、看 ComfyUI GitHub issues 跟 PyTorch release notes 對應的 Python 版本。

跟其他 hands-on 章節的關係：完整 hands-on 系列見 Hands-on 章節索引、跨服務的 lifecycle / 記憶體管理見 Resource management、ComfyUI 跟 Ollama 同台跑的記憶體預算規劃見 0.5 Apple Silicon 記憶體預算。

實測日期：2026-07-01 環境：macOS Apple Silicon、Ollama 0.7.x、nomic-embed-text（768 維） Corpus：content/ 全量 2,738 個 markdown 檔、24,216 chunks 前置 demo：rag-demo（pickle、463 chunks）

讀法建議

本案例用 Go 重寫了 RAG storage 層，Go 實作細節佔不少篇幅。依你的背景選讀法：

• Python 開發者、想選自己專案的 storage 方案：先跳到「通用可複製流程」（語言無關的五步驟）→「四方案 benchmark」→「二次選型評估」（結論/理由/前提三層框架），這三段跨語言可遷移。Go 實作段（架構、效能優化）可 skim。
• Go 開發者、想做類似工具：從頭讀，每段都跟你相關。
• 只想看選型框架、不管實作：直接跳「二次選型評估」。

從 demo 到 production 的重寫動機

rag-demo 用 Python pickle 跑通了 RAG 概念驗證：71 篇 → 463 chunks → pickle 儲存 → cosine retrieval → Ollama 生成。概念層完全正確（4.1 的 retrieval + augmentation 骨架），但作為這個 blog 的日常工具有三個專案特有的限制：

1. 工具鏈語言不同：blog 的核心工具是 Go（lint / fmt / cards），加 Python dependency 讓其他維護者 clone 後多一步環境設定。Python 專案不會有這個問題 — pickle 綁 Python 對 Python 專案是優點而非缺點。
2. 只索引部分 corpus：rag-demo 只跑 content/llm/（71 篇），blog 全量有 2,738 篇、24 個 section。
3. Demo 定位：ingest.py / query.py 是教學程式碼，不是維護工具（沒有 status、沒有 section filter）。

這是一次完整重寫、不是漸進升級 — rag-demo 的 Python 程式碼不會被修改或遷移，而是用 Go 重新實作相同的 RAG pipeline（chunk → embed → store → search）、保留相同的概念架構。rag-demo 作為教學 demo 繼續存在。

升級目標：一個跟 mdtools 同級的 Go CLI 工具，能對全量 content 做語意搜尋，其他維護者 clone 後 go build 即可用。完整原始碼在 scripts/blogsearch/。

選型過程（對應 4.22 演化階梯 + 工程約束）

第一軸：規模判讀

全量 content 產生 24,216 chunks（原本估計 ~1,500）。按 4.22 判讀樹，24K 落在「10K-100K → HNSW 或 brute-force」區間。預估 vs 實際的 16 倍落差揭露一個教訓：估計 chunk 數不能用篇數乘以常數，要看每篇的實際長度跟 chunking 策略。

第二軸：工程約束（本專案特有）

以下四個 constraint 反映這個 blog 專案的偏好、不是通用判準。換一組 constraint 會篩出完全不同的方案 — Python 專案不會有「Go 單 binary」constraint、已有 Docker 的團隊不會排斥外部 server。讀者套用時應先列出自己專案的 constraint、不是照搬這張表。

剩餘選項：Go + flat file + brute-force。

第三軸：延遲容忍

CLI 工具、每天用幾次、不是 API server。< 500ms 可接受。

結論：選階段二（flat file），brute-force cosine。

實作架構

 1scripts/blogsearch/
 2├── main.go                     # CLI: ingest / query / status
 3├── cmd/
 4│   ├── ingest.go               # walk content/ → chunk → embed → store
 5│   ├── query.go                # load → embed query → cosine top-K → lazy load text
 6│   └── status.go               # index stats
 7└── internal/
 8    ├── chunk/chunk.go           # paragraph-aware markdown chunking
 9    ├── embed/embed.go           # Ollama HTTP API wrapper
10    ├── search/search.go         # brute-force cosine similarity
11    └── store/store.go           # 三檔案 binary store

日常使用

1# 語意搜尋
2./bin/blogsearch query "retry 策略"
3
4# 只搜特定 section
5./bin/blogsearch query -section backend "connection pool 設定"
6
7# 查 index 狀態
8./bin/blogsearch status

Storage 格式（三檔案分離）

1.blogsearch/
2├── vectors.bin    # float32 binary（70.9 MB）— bulk read + unsafe.Slice 零拷貝
3├── meta.json      # compact metadata 不含 text（7.3 MB）
4└── texts.bin      # length-prefixed chunk text（19.2 MB）— top-K 才 lazy load

分離 text 的設計理由：query 時只需要 vectors + metadata 做 cosine search（78 MB），top-K 結果才從 texts.bin 按 offset 讀取 5 筆 text。省掉 19 MB 的 JSON 解析。

效能優化歷程

初版：9.5 秒

初版用逐 4-byte Read 載入 vectors.bin（17.5M 次 f.Read(buf)），加上 27MB 的 index.json（含所有 chunk text）一次 JSON 解析。

優化版：0.34 秒（28x）

三項改動：

瓶頸分析：0.34 秒裡、embedding API call（Ollama）約 77ms、file I/O + JSON parse 約 200ms、cosine 計算約 50ms。cosine 計算只佔 15%。

通用可複製流程（抽掉 Go/blog）

本案例的 Go 實作細節（unsafe.Slice、os.ReadFile）是語言特定的、但背後的流程步驟跨語言通用：

1. Walk corpus：遞迴掃描目標目錄的所有文件（markdown / code / 任意文字）
2. Chunk：段落感知分割、soft token cap、保留語意邊界（原理見 4.1 Chunking）
3. Embed：對每個 chunk 呼叫 embedding API（本地 Ollama 或 cloud API），得到固定維度向量
4. Store：向量 + metadata + text 分離存檔（binary vectors / compact JSON / lazy-load text）
5. Search：embed query → brute-force cosine → top-K → lazy load text for display

Python 實作同流程只是把第 4 步的 binary 檔換成 pickle / FAISS index / SQLite DB、第 5 步的 cosine 換成 numpy / FAISS / sqlite-vec query。Node.js / Rust 同理。

關鍵優化原則也跨語言：「分離向量與文字、query 時只載入向量、top-K 才載入文字」讓 I/O 量從 ~98MB 降到 ~78MB、JSON parse 從 27MB 降到 7MB。這個原則用什麼語言實作都有效。

四方案同 corpus Benchmark

用同一個 corpus（24,216 chunks、768 維、nomic-embed-text）比較四種 storage 方案。Benchmark 腳本在 scripts/blogsearch-bench/bench.py。

前置依賴

Benchmark 腳本讀 Go 工具產生的 index（.blogsearch/ 下的 vectors.bin + meta.json）。完整指令鏈：

1cd scripts/blogsearch && go build -o ../../bin/blogsearch .   # build Go 工具
2ollama serve &                                                  # 啟動 Ollama
3ollama pull nomic-embed-text                                    # pull embedding model
4./bin/blogsearch ingest -content content -out .blogsearch       # 建 index（~4 分鐘）
5uv run --with sqlite-vec --with faiss-cpu --with numpy \
6  scripts/blogsearch-bench/bench.py --index .blogsearch         # 跑 benchmark

若無 Go 環境，可用自己的 Python embedding 腳本產生相同格式的 vectors.bin（little-endian float32、n × dim 連續排列）+ meta.json（{"dim": 768, "count": n, "metas": [...]}），benchmark 腳本只讀這兩個檔案、不依賴 Go binary 本身。Corpus 格式無硬性要求，任何目錄下的 .md 檔案都可索引。

方法論

• Embedding：四方案共用同一組 embedding（從 Go index 載入），排除 embedding model 差異
• Query：同一句 query（“RAG storage 選型”），跑 5 次取 median
• Ingest 時間：只計 storage 操作（不含 embedding），Go 方案含 embedding 不可分離故標 —
• 環境：macOS Apple Silicon、Python 3.12、Go 1.25

結果

三個關鍵發現

延遲瓶頸在 I/O 和實作、不在演算法。Go flat file 的 151ms 裡、cosine 計算約 50ms、file I/O 約 100ms。FAISS flat 用 numpy BLAS 做同樣的 brute-force cosine、純計算 1.8ms — 計算層差約 28 倍（Go pure loop vs BLAS 向量化指令），加上 I/O 後端到端差 84 倍。

HNSW 的 query 加速在此規模 ROI 低。FAISS HNSW query 0.5ms vs flat 1.8ms、每次省 1.3ms。但 HNSW build 要 23.3s。每天查 100 次、要 179 天才回本 build 成本（23.3s ÷ 0.13s/天）。4.22 的判讀結論（「此規模 brute-force 夠用」）被數據驗證。

sqlite-vec 的 19ms 是「DB overhead 換功能」。比 FAISS flat 慢 10 倍、但多了 SQL metadata filter、transaction 保護、disk persistence。對「需要 filter 但不想維運 server」的場景有意義。

讀數據的注意事項

• Go 151ms 含 file I/O（每次 query 重載 78MB）；如果做 daemon mode（常駐、載入一次），query 會降到 ~50ms（純 cosine + overhead）
• FAISS 數字是 in-memory baseline（index 已載入），不含 index 檔案的載入時間
• sqlite-vec 數字含 disk I/O（每次 query 從 SQLite 讀取），是 persistent storage 的真實代價
• 四方案都不含 Ollama embedding call 時間（~77ms），實際端到端延遲要加上

二次選型評估：同結論、理由鏈翻轉

Benchmark 數據出來後，80 倍效能差距讓原始選型（Go + flat file）受到質疑：「是否該換 Python + FAISS 或 sqlite-vec？」重新用 WRAP 框架評估，結論相同（維持 Go），但理由鏈完全不同。

第一次選型的理由（事前）

「Go 工具鏈統一（mdtools 是 Go）+ 單 binary 分發（clone 後 go build 即可）。」

實測推翻的前提

第一次的理由鏈幾乎全數被推翻。如果只看理由，應該換方案。

第二次選型的理由（事後）

重新評估時加入三個第一次沒有的變數：

端到端延遲 vs in-memory benchmark。84 倍是端到端的數字（Go 151ms 含 I/O vs FAISS 1.8ms in-memory）。但 FAISS 從 disk 載入 index 也要 ~100-200ms，端到端差距縮小到 2 倍。sqlite-vec 是唯一不需要全量載入的方案（disk-based HNSW、端到端 19ms），差距從「84 倍」變成「8 倍」。

使用頻率決定 ROI。CLI 工具、每天 ~10 次手動 query。每次省 130ms（151 vs 19），一天省 1.3 秒。重寫投入 2-3 小時，回本時間 ≈ 19 年。注意這個計算對頻率極敏感：每天 100 次（如被整合進 MCP server 當 agent 工具）回本縮短到 1.9 年、每天 1000 次則 69 天。上方 HNSW ROI 也用每天 100 次計算 — 兩處頻率假設不同是因為比較對象不同（HNSW build 成本 vs 語言重寫成本），但讀者套到自己場景時應先確定自己的查詢頻率。

Ingest 瓶頸在 Ollama API、跟語言無關。~4 分鐘的 ingest 裡、embedding API call 佔 95% 以上。換 Python 不會改善 ingest 速度。

維持的理由是「痛點不存在」

維持 Go 的理由是改善的絕對收益太小、投入回不了本 — 151ms 對 CLI 使用模式不構成痛點，與「Go 好」或「工具鏈統一」無關。

這個翻轉的教學意義

正確的結論配錯誤的理由是脆弱的。第一次 WRAP 的結論（選 Go）在當時是對的，但理由鏈（工具鏈統一、< 10ms）被實測推翻後，如果不重新建立正確的理由鏈，下次環境變動（比如 blogsearch 從 CLI 變成 API server）就會用已失效的理由做出錯誤判斷。

判讀工具選型時，要區分三層：

1. 結論：選什麼方案
2. 理由：為什麼選（可能被推翻）
3. 前提：理由依賴的假設（規模、使用模式、效能數字）

前提變了、理由就要重建，即使結論沒變。寫進決策紀錄時，三層都要記 — 只記結論的話，下次重新評估時沒有判讀基礎。

區分「正當理由重建」跟「動機性推理」（先有結論再找理由）的判準：新理由是否在看到數據之前也能成立？本例的「130ms 對 CLI 不痛」在實測前也成立（CLI 使用模式本來就低頻），所以是正當重建。如果新理由只能在看到特定數字之後才講得通（如「151ms 剛好在 200ms 閾值內」——但閾值是事後設的），就是 post-hoc rationalization。

觸發換方案的訊號

Embedding model 選型（對應 4.12 constraint 優先序）

選 nomic-embed-text 的理由鏈：

1. Ollama 原生支援：ollama pull 一行、不需要額外 Python library 或 API key
2. 體積小：274 MB、跟 chat model 共用記憶體不打架
3. 已有驗證基線：rag-demo 用同一個模型跑過 463 chunks、retrieval 命中率確認可用
4. 768 維 sweet spot：24K chunks × 768 dim × 4 bytes = 70.9 MB，brute-force 可行

未來如果 CJK retrieval 品質不夠（目前可用但未做系統性評估），multilingual-e5-large 或 bge-m3 是備選。換模型只需改 embed.go 的 Model 變數 + 重新 blogsearch ingest（4.22 的「四層可替換」設計）。

CJK 混合 Chunking 觀察

Blog 內容是繁體中文 + 英文術語混合。Chunking 策略沿用 rag-demo 的 paragraph-aware split（空白行切段、soft token cap 400）。

Token 估算用 len(s) / 2 的 heuristic（CJK 字元多算一次）。不精確但 chunking 只需要粗略估算。跟 tokenizer 精確計算的差異在 ±20%、對 chunking 品質影響小於 chunk 邊界選擇的影響。

實際觀察：24,216 chunks 的 retrieval 品質在語意搜尋場景（「哪些文章跟 retry 有關」「RAG storage 選型」）表現良好。keyword 精確搜尋場景（「找 RFC 7807」）表現較弱 — 這是 embedding-only retrieval 的已知限制（見 4.1 的語意 vs 字面相似度對比），未來可加 BM25 做 hybrid search。

跟其他章節的對應

• 純 C++ 實作、Metal backend 直接吃 Apple Silicon GPU。
• Homebrew bottle、brew install 一行裝完、不需要 Python 環境跟 torch wheel。
• Binary 名稱是 whisper-cli、CLI-first、整合到 shell pipeline 容易。

驗證日期：2026-05-12 whisper-cpp 版本：1.8.4 示範模型：ggml-tiny.en.bin（78 MB、英文專用、最小可用） 實測：7 秒音訊 484ms 轉錄、用 Metal GPU 加速

前置設定

ffmpeg 是必要的——whisper-cli 接受多種音訊格式、但實際內部會先轉成 16kHz mono WAV、ffmpeg 是這個轉換的依賴。

安裝 whisper-cpp

1brew install whisper-cpp

Homebrew 會裝：

• whisper-cli binary 到 /opt/homebrew/bin/
• ggml 共用 lib 到 /opt/homebrew/Cellar/ggml/
• BLAS / Metal backend 自動配對 Apple Silicon

驗證 binary 可用：

1which whisper-cli
2# /opt/homebrew/bin/whisper-cli
3
4whisper-cli --help 2>&1 | head -5

第一次跑會看到 Metal 初始化訊息：

1ggml_metal_library_init: using embedded metal library
2ggml_metal_library_init: loaded in 6.883 sec

第一次 Metal lib 載入慢（~7 秒）、後續會 cache、變很快。

下載 Model

whisper-cpp 跟 OpenAI 原版分離管理 model file、要自己下載 GGML 格式：

1mkdir -p ~/.whisper-models
2cd ~/.whisper-models
3curl -L -o ggml-tiny.en.bin \
4  "https://huggingface.co/ggerganov/whisper.cpp/resolve/main/ggml-tiny.en.bin"

可用 model 比較（大小越大、品質越好、速度越慢）：

選 tiny.en 是因為只驗證安裝路徑、實際日常用要 small.en 起跳。

驗證下載：

1ls -lh ~/.whisper-models/
2# 應該看到 78 MB 的 ggml-tiny.en.bin

跑第一次轉錄

需要一段測試音訊。可以用 macOS 內建 say 生成、再用 ffmpeg 轉成 whisper.cpp 需要的格式（16kHz mono WAV）：

1cd /tmp
2say -o sample.aiff -v Samantha "Hello world. This is a test of the whisper transcription system. It should produce accurate text from this short audio clip."
3ffmpeg -loglevel error -y -i sample.aiff -ar 16000 -ac 1 sample.wav

-ar 16000 -ac 1 是 whisper.cpp 的標準輸入規格（16 kHz、單聲道、16-bit PCM）。Whisper 模型訓練時用這個 sample rate、輸入不符會降低準確度。

轉錄：

1whisper-cli -m ~/.whisper-models/ggml-tiny.en.bin -f /tmp/sample.wav

預期輸出（含時間軸）：

1[00:00:00.000 --> 00:00:03.980]   Hello World, this is a test of the whisper transcription system.
2[00:00:03.980 --> 00:00:06.980]   It should produce accurate text from this short audio clip.
3
4whisper_print_timings:     load time =    39.88 ms
5whisper_print_timings:   encode time =   220.01 ms
6whisper_print_timings:    total time =   484.08 ms

關鍵觀察：

• 484ms 處理 7 秒音訊、約 14x 即時速度。
• 轉錄結果跟原文一致（除了 world 大寫變 World）。
• 含時間軸（time stamps）、可以做 subtitle / 字幕對齊。

要拿不含時間軸的純文字：

1whisper-cli -m ~/.whisper-models/ggml-tiny.en.bin -f /tmp/sample.wav -nt
2# -nt 是 --no-timestamps

常用選項

實務常用組合：

 1# 字幕生成
 2whisper-cli -m ~/.whisper-models/ggml-small.en.bin \
 3  -f input.wav \
 4  -osrt \
 5  -of output_subtitle
 6
 7# 中文轉錄
 8whisper-cli -m ~/.whisper-models/ggml-small.bin \
 9  -f speech.wav \
10  -l zh

跟其他工具串接

Whisper-cli 的 stdout 是純文字、容易串 pipeline：

 1# 轉錄結果直接餵給 LLM 摘要
 2whisper-cli -m ~/.whisper-models/ggml-small.en.bin -f meeting.wav -nt \
 3  | curl -s http://localhost:11434/v1/chat/completions \
 4    -H "Content-Type: application/json" \
 5    -d @- <<EOF
 6{
 7  "model": "gemma3:1b",
 8  "messages": [
 9    {"role": "system", "content": "Summarize the meeting transcript in 5 bullet points."},
10    {"role": "user", "content": "$(cat)"}
11  ]
12}
13EOF

這個 pipeline 串接到 Ollama 完成「語音 → 文字 → 摘要」流程、整條本地、無雲端 API。

常見坑

「audio file not found / format error」

確認 ffmpeg 已轉成 16kHz mono：

1ffprobe input.wav 2>&1 | grep -E "Stream|Audio"
2# 應該看到：Audio: pcm_s16le, 16000 Hz, mono

不是這個規格就用 ffmpeg 轉：

1ffmpeg -i input.mp3 -ar 16000 -ac 1 -c:a pcm_s16le output.wav

Model 載入慢

第一次 Metal lib 初始化要 ~7 秒、是 macOS Metal compiler 在 cache shader。後續快很多。

如果每次都慢、看是否 Metal cache 路徑（~/Library/Caches/...）有權限問題。

中文 / 多語言準確度差

確認 model 不是 .en 後綴：.en model 只訓練英文、餵中文會 hallucinate。中文要用 ggml-small.bin、ggml-medium.bin、ggml-large-v3.bin（沒 .en）。

Output 拼錯字

Whisper tiny / base model 對非母音清晰、噪音多、口音重的音訊準確度差。換 small 或 medium 通常解決。

完整 round-trip 驗證

驗證 Whisper + Piper TTS 完整迴圈：

1# Piper 生成 WAV
2echo "Hello world test." | piper -m ~/.piper-voices/en_US-lessac-low.onnx -f /tmp/out.wav
3
4# Whisper 轉回文字
5whisper-cli -m ~/.whisper-models/ggml-tiny.en.bin -f /tmp/out.wav -nt
6# 應該回：Hello world test.

兩個都跑得起來表示整條 STT / TTS pipeline 工作。沒裝 Piper 的場景：用任何 16kHz 單聲道 WAV 都能驗證（macOS 內建 say -o sample.aiff + ffmpeg 轉檔、或從 Hugging Face 拉個 sample 音訊）、不一定要用 Piper。

跟其他章節的關係：完整 hands-on 系列見 Hands-on 章節索引、本地 LLM 加 speech 在隱私 / 資料流上的位置見 0.7 隱私資料流原理、排錯走三層方法論見 1.7 排錯方法論。

何時這篇會過時

• brew install whisper-cpp 安裝方式短期內不會變。
• GGML model 路徑（Hugging Face ggerganov/whisper.cpp）穩定、是 maintainer 官方 repo。
• 模型版本會更新（large-v3 → large-v4 等）、但「下載 GGML、用 whisper-cli 餵 WAV」流程不變。
• Metal backend 自動啟用、不需配置——Apple Silicon GPU 演化會持續增進效能但不影響介面。

讀的時候若 brew 跑失敗、查 whisper.cpp GitHub release notes；模型新版本看 Hugging Face ggerganov/whisper.cpp repo 列表。

• 完全本地、隱私邊界乾淨。
• ONNX runtime、Apple Silicon 跑得動、不依賴 GPU。
• 模型小（low quality ~17-65 MB、medium ~50 MB、high ~125 MB）、適合 minimal 驗證。
• CLI-first、stdin 餵文字、stdout 或檔案輸出 WAV、容易串 pipeline。

驗證日期：2026-05-12 Piper 版本：透過 pip 安裝 示範 voice：en_US-lessac-low.onnx（63 MB、英文女聲、low quality） 實測：4 秒文字合成 < 1 秒、品質夠日常用

前置設定

Piper 跟 Whisper 一樣分離 binary 跟 model：先裝 runtime、再下載 voice。

安裝 Piper

piper-tts 沒有 Homebrew formula、用 pip 裝：

1pip3 install piper-tts --break-system-packages

PEP 668 是 macOS / Homebrew Python 的 external-management 機制、保護系統 Python 不被 pip 安裝污染；--break-system-packages 是 bypass flag、跳過該檢查直接裝。比較乾淨的做法是用 venv：

1python3 -m venv ~/.piper-venv
2source ~/.piper-venv/bin/activate
3pip install piper-tts

但裝完 PATH 要指到 venv 的 piper、稍麻煩。本 demo 用 --break-system-packages 簡化。實際生產建議用 venv 或 pipx。

驗證 binary 在 PATH：

1which piper
2# /opt/homebrew/bin/piper（若 pip3 來自 Homebrew Python）
3# 或 ~/Library/Python/3.x/bin/piper（若 pip3 來自系統 Python）
4
5piper --help | head -10

which piper 找不到時、檢查兩個 bin 目錄哪邊有檔案、把該目錄加進 PATH。

下載 Voice Model

Piper 用 ONNX 格式的 voice model、每個 voice 是一對 .onnx（model 權重）+ .onnx.json（metadata、含採樣率、phoneme map）。

從 Hugging Face rhasspy/piper-voices repo 拉：

1mkdir -p ~/.piper-voices
2cd ~/.piper-voices
3
4# 英文女聲、low quality（小、快）
5curl -L -o en_US-lessac-low.onnx \
6  "https://huggingface.co/rhasspy/piper-voices/resolve/v1.0.0/en/en_US/lessac/low/en_US-lessac-low.onnx"
7curl -L -o en_US-lessac-low.onnx.json \
8  "https://huggingface.co/rhasspy/piper-voices/resolve/v1.0.0/en/en_US/lessac/low/en_US-lessac-low.onnx.json"

可用 voice quality 等級：

語言 / 地區覆蓋（部分）：

完整清單在 rhasspy/piper-voices 的 VOICES.md。

驗證下載：

1ls -lh ~/.piper-voices/
2# en_US-lessac-low.onnx       63M
3# en_US-lessac-low.onnx.json  4.9K

跑第一次合成

1echo "Hello from Piper TTS, this is a synthesized voice test." \
2  | piper -m ~/.piper-voices/en_US-lessac-low.onnx -f /tmp/piper-out.wav

說明：

• 文字從 stdin 進、是 Piper 的標準輸入方式。
• -m：voice model .onnx path。Piper 自動找同目錄的 .onnx.json。
• -f：output WAV path。不指定的話直接寫 stdout（可以 pipe 到 aplay / afplay 即時播放）。

預期輸出：

1ls -lh /tmp/piper-out.wav
2# 128 KB

驗證 WAV 規格：

1file /tmp/piper-out.wav
2# RIFF (little-endian) data, WAVE audio, Microsoft PCM, 16 bit, mono 16000 Hz
3
4ffprobe -loglevel error -show_format /tmp/piper-out.wav | grep duration
5# duration=3.984000

16-bit PCM、16 kHz mono——跟 Whisper 期望的輸入規格一致、可以直接 round-trip。

播放確認：

1afplay /tmp/piper-out.wav

常用選項

典型應用：

 1# 從文字檔合成
 2piper -m ~/.piper-voices/en_US-lessac-low.onnx \
 3  -i article.txt \
 4  -f narration.wav
 5
 6# 多句子分檔
 7piper -m ~/.piper-voices/en_US-lessac-medium.onnx \
 8  -i script.txt \
 9  -d ~/audio-output/ \
10  --output-dir-naming text
11
12# 慢速朗讀（學習用）
13piper -m ~/.piper-voices/en_US-lessac-low.onnx \
14  --length-scale 1.4 \
15  -f slow.wav <<< "Slowly read this sentence."

Round-Trip 驗證

確認 TTS + STT 整條串得起來：

1# 1. Piper TTS：文字 → WAV
2echo "The quick brown fox jumps over the lazy dog." \
3  | piper -m ~/.piper-voices/en_US-lessac-low.onnx -f /tmp/test.wav
4
5# 2. Whisper STT：WAV → 文字
6whisper-cli -m ~/.whisper-models/ggml-tiny.en.bin -f /tmp/test.wav -nt

預期 Whisper 回應接近原文字（可能大小寫 / 標點稍變）。Round-trip 成功表示：

• Piper 輸出格式（16kHz mono WAV）符合 Whisper 輸入需求。
• 兩個模型對英文的訓練分佈相容。

跟 LLM 串接：「LLM 說話」的 minimal pipeline

 1# 1. LLM 生成回答
 2ANSWER=$(curl -s http://localhost:11434/v1/chat/completions \
 3  -H "Content-Type: application/json" \
 4  -d '{
 5    "model": "gemma3:1b",
 6    "messages": [{"role":"user","content":"Tell me a one-sentence joke."}],
 7    "stream": false
 8  }' | python3 -c "import json,sys; print(json.load(sys.stdin)['choices'][0]['message']['content'])")
 9
10# 2. Piper 把回答念出來
11echo "$ANSWER" | piper -m ~/.piper-voices/en_US-lessac-low.onnx -f /tmp/llm-says.wav
12
13# 3. 播放
14afplay /tmp/llm-says.wav

三行 shell 完成「Local LLM 講笑話」整條 pipeline、無雲端、無 GPU。

常見坑

中文 / 多語言

en_US-lessac-low 是英文 voice、餵中文會發音怪。中文要下載 zh_CN-huayan-*：

1curl -L -o ~/.piper-voices/zh_CN-huayan-medium.onnx \
2  "https://huggingface.co/rhasspy/piper-voices/resolve/v1.0.0/zh/zh_CN/huayan/medium/zh_CN-huayan-medium.onnx"
3curl -L -o ~/.piper-voices/zh_CN-huayan-medium.onnx.json \
4  "https://huggingface.co/rhasspy/piper-voices/resolve/v1.0.0/zh/zh_CN/huayan/medium/zh_CN-huayan-medium.onnx.json"
5
6echo "你好，這是 Piper TTS 的中文測試。" \
7  | piper -m ~/.piper-voices/zh_CN-huayan-medium.onnx -f /tmp/zh-out.wav

zh_CN 預設是北京話腔調。

--break-system-packages 警告

macOS 系統 Python 3.13+ 預設禁止 pip 直接裝。安全做法用 venv 或 pipx；不想搞 venv 就用 --break-system-packages flag（會跳警告但能裝）。長期建議遷到 venv、避免污染系統 Python。

Voice quality 不夠

low quality 的 voice 適合驗證 / prototype、實際用 medium 或 high。低品質 voice 在長段文字會聽起來機械、自然度差。

Sample rate mismatch

Voice metadata（.onnx.json 內 sample_rate）決定輸出 sample rate、不同 voice 可能不同（多數 22050 或 16000）。Whisper 期望 16000、若 Piper 輸出 22050、可能需要 ffmpeg 降採樣：

1ffmpeg -i piper-out.wav -ar 16000 piper-out-16k.wav

en_US-lessac-low 本來就是 16k、沒這問題。

何時這篇會過時

• pip install piper-tts 安裝方式可能演化（轉純 binary release？）、但 ONNX model + CLI invocation 形式應該穩定。
• Voice model 格式（ONNX）是 web 通用標準、未來增加 quality / locale、現有 voice 不會被 deprecate。
• Hugging Face rhasspy/piper-voices repo 是 maintainer 官方、不會消失。

讀的時候若 pip install 失敗、查 piper GitHub 最新 install 路徑；voice 列表看 piper-voices repo。

跟其他 hands-on 章節的關係：完整 hands-on 系列見 Hands-on 章節索引、語音 round-trip 對接見 Whisper STT、跨服務 lifecycle 與記憶體管理見 Resource management。

驗證日期：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。

驗證日期：2026-05-12 環境：Python 3.11+、stdlib only（json / subprocess / urllib） 依賴：RAG demo 的 index.pkl（見 RAG demo） 協議版本：MCP 2025-03-26

MCP 是什麼層的東西

回顧 4.6 應用層協議 的層級劃分：

• Function calling：模型訓練建立的能力（模型層）。
• Structured output：sampling 階段約束（推論層）。
• MCP：LLM application ↔ 外部 tool server 的協議（架構層）。

MCP 不管「模型怎麼呼叫工具」、它管「工具怎麼被暴露給 application」。本 demo 寫的是 server 端：server 不知道是哪個 LLM 在用它、不假設客戶端用 function calling 還是 structured output、它只專注「把 tool 透過 JSON-RPC 暴露出去」。

這跟 OpenAI 相容 API 的設計哲學一致：定義最小可用標準、讓生態繞著標準長。

前置設定

不需要安裝 MCP SDK——本 demo 手寫 JSON-RPC 處理、為了 inspection 透明度。Production server 建議改用 官方 SDK（Python / TypeScript 都有）、處理 framing、capability negotiation、transport edge cases。

MCP 協議的最小子集

MCP server 要 handle 的核心 method：

四個 method 之外、還可以暴露 resources / prompts / sampling、本 demo 只做 tools。

Server 實作

完整檔案：scripts/mcp-demo/blog_mcp_server.py、約 150 行。

主迴圈：讀 stdin、分派 method、寫 stdout

 1def main():
 2    log(f"[blog-mcp-demo] starting, index={INDEX_PATH}, tools={list(TOOLS.keys())}")
 3    for line in sys.stdin:
 4        line = line.strip()
 5        if not line:
 6            continue
 7        try:
 8            msg = json.loads(line)
 9        except json.JSONDecodeError as e:
10            log(f"  parse error: {e}")
11            continue
12        method = msg.get("method")
13        rid = msg.get("id")
14        params = msg.get("params", {})
15        log(f"  → {method} (id={rid})")
16        if method not in HANDLERS:
17            respond(rid, error={"code": -32601, "message": f"Method not found: {method}"})
18            continue
19        handler = HANDLERS[method]
20        if handler is None:
21            continue  # notification, no response expected
22        try:
23            result = handler(params)
24            respond(rid, result=result)
25        except Exception as e:
26            log(f"  ✗ handler error: {e}")
27            respond(rid, error={"code": -32000, "message": str(e)})

每段做什麼：

1. log(...) 開機訊息：印到 stderr（不是 stdout）、讓人類能看到 server 啟動了、什麼 tools 可用。stdout 完全保留給 JSON-RPC 用。
2. for line in sys.stdin：MCP 的 stdio transport 是 line-delimited JSON—— 每個 message 一行、\n 結束。Python 的 file iteration 自動按行切。
3. line.strip() + if not line：空行 skip（不是 protocol error、只是 idle）。
4. json.loads(line) with try / except：parse 失敗（malformed input）不 crash、log error 繼續下一行。Protocol 訊息該是合法 JSON、parse error 表示 client 出錯。
5. msg.get("method") / msg.get("id") / msg.get("params", {})：JSON-RPC 2.0 標準三個欄位。get 而不是 []、避免 KeyError；params 預設空 dict、後面 handler 可以安全 .get("xxx")。
6. if method not in HANDLERS: respond(rid, error={"code": -32601, ...})：未知 method 回標準 JSON-RPC error -32601（Method not found）。Client 知道這個 method 不能用、但 server 不死。
7. if handler is None: continue：notification（如 notifications/initialized）對應的 handler 是 None、不該回 response。
8. try: result = handler(params); respond(rid, result=result)：呼叫 handler、把結果回給 client。
9. except Exception as e: ... respond(rid, error={"code": -32000, ...})：handler 內部錯誤回 -32000（generic server error）。確保 server 任何時候都不 crash、即使工具 bug 也讓 client 拿到 error response。

為什麼這樣設計：

• 為什麼用 line-delimited JSON、不是 length-prefixed：MCP spec 規定 stdio transport 是 newline-delimited。length-prefixed 是 LSP 的做法、解析複雜（要先讀 Content-Length header 再讀 N bytes）；newline-delimited 用 for line in sys.stdin 一行解決。
• 為什麼 stderr 不能寫 stdout：stdio transport 的 invariant——stdout 是 protocol channel、只能寫 JSON-RPC message。任何 stray print() / debug output 進 stdout、會被 client parse JSON 時炸（「multiple JSON values on one line」或 invalid JSON）。所有 log / debug / progress message 必須走 stderr。寫錯這條 server 看起來不工作、debug 很久才找到。
• 為什麼 dispatch 用 dict-of-handlers 而不是 if/elif chain：擴充性。加新 method 只要往 HANDLERS dict 加一項、不用改 main loop。也讓 dispatch logic 跟 method 實作分離、容易測試。
• 為什麼每個 handler 都用 try/except 包：「single point of failure」設計——任何 handler 例外不影響其他 method。Server 應該是 long-running daemon、不能因為一個 tool bug 死掉。
• 為什麼 errors 用 JSON-RPC error code 而不是 HTTP-style status：JSON-RPC 2.0 標準。-32700 parse error、-32600 invalid request、-32601 method not found、-32602 invalid params、-32603 internal error、-32000 to -32099 留給應用層自訂。

工具：search_blog

 1def tool_search_blog(query: str, top_k: int = 5) -> dict:
 2    records = load_index()
 3    q_vec = embed(query)
 4    scored = sorted(
 5        ((cosine(q_vec, r["embedding"]), r) for r in records),
 6        key=lambda x: x[0],
 7        reverse=True,
 8    )[:top_k]
 9    results = [
10        {
11            "source": r["source"],
12            "chunk_index": r["chunk_index"],
13            "score": round(score, 4),
14            "preview": r["text"][:160] + ("..." if len(r["text"]) > 160 else ""),
15        }
16        for score, r in scored
17    ]
18    return {"content": [{"type": "text", "text": json.dumps(results, ensure_ascii=False, indent=2)}]}

每段做什麼：

1. records = load_index()：lazy load index.pkl、第一次 call 載入記憶體、後續直接用 cached。Server 啟動時 lazy load 而不是 import 時 load、讓 server 即使在 Ollama 還沒起 / index 不存在時也能 boot（之後 call 才會報 error）。
2. q_vec = embed(query)：把 query 轉成 768 維向量、呼叫 Ollama embedding API、跟 RAG demo 的 embed 是同一個 function。
3. sorted((...) for r in records, key=lambda x: x[0], reverse=True)[:top_k]：generator expression + sorted 一次完成「算分 → 排序 → 取 top-K」。
4. results = [{...} for score, r in scored]：把 top-K 整理成 client 友善的 dict 結構、含 source、chunk_index、score、preview（前 160 字 + 省略號）。
5. {"content": [{"type": "text", "text": json.dumps(...)}]}：MCP tools/call 標準 response 格式——content 是 array、每個元素 type + payload。type: "text" 是文字 content、text 是實際內容（這裡是 JSON 字串、讓 LLM 可以 parse）。

為什麼這樣設計：

• 為什麼 generator expression 而非 list comprehension：(... for r in records) 是 generator、sorted 直接消費、不會在記憶體中建中間 list。對 463 records 影響不大、但展現 memory-efficient pattern。
• 為什麼 preview 切到 160 字：兩件事的平衡——讓 LLM 看到的 search result 短（不淹沒 LLM 的 context）、但夠判讀（160 中文字約 80 token、能看出 chunk 是不是相關）。如果 LLM 要完整內容、再 call read_chunk。
• 為什麼回傳 JSON 字串、不是 nested object：MCP content 規定每個 element 是 {type, payload}、type: "text" 的 text 必須是 string、不能直接放 nested object。要傳結構化資料、就把它 json.dumps 成字串。LLM 看到後可以自己 parse。
• 為什麼 ensure_ascii=False：預設 json.dumps 把非 ASCII 字元（如中文）轉成 \uXXXX、難讀。ensure_ascii=False 直接輸出 UTF-8、LLM 也能直接讀懂、節省 token 數（一個中文字 1 token vs 6 token 的 中）。
• 為什麼 round(score, 4)：score 是 float、原始可能是 0.7497284598827362、長且無意義。round(score, 4) 保留 4 位小數、0.7497、夠精確、wire size 短。

工具：read_chunk

1def tool_read_chunk(source: str, chunk_index: int) -> dict:
2    records = load_index()
3    for r in records:
4        if r["source"] == source and r["chunk_index"] == chunk_index:
5            return {"content": [{"type": "text", "text": r["text"]}]}
6    return {
7        "content": [{"type": "text", "text": f"Not found: {source}#chunk{chunk_index}"}],
8        "isError": True,
9    }

每段做什麼：

1. for r in records: if r["source"] == source and r["chunk_index"] == chunk_index: return ...：linear scan 找匹配的 record、找到回完整 text。
2. 找不到時 return {... "isError": True}：MCP 標準的「tool 內部失敗」訊號。isError: True 告訴 client「這個 tool call 失敗了」、content 內是 human-readable error message。

為什麼這樣設計：

• 為什麼 linear scan 而不是 dict lookup：可以改用 {(source, chunk_index): record} dict 變 O(1)。但 463 records 的 linear scan 是 < 1ms、optimize 不值得。Production 跟 vector DB 整合時、retrieval 系統自帶 indexing。
• 為什麼 isError: True 而不是 JSON-RPC error：分兩種錯誤：
  • Protocol error：method 不存在、params 不合法、JSON parse 失敗——回 JSON-RPC error 物件。
  • Tool semantic error：method OK、params OK、但 tool 邏輯上不能 complete（找不到資料、外部 service down）——回 normal response 加 isError: True。 MCP 設計這層分離、讓 client / LLM 區分「我做錯了」（協議層）跟「資料不存在」（語意層）。Production 設計工具時要仔細區分。

Tool 描述用 JSON Schema

 1TOOLS = {
 2    "search_blog": {
 3        "description": "Semantic search over blog content. Returns top-K relevant chunks with source paths.",
 4        "inputSchema": {
 5            "type": "object",
 6            "properties": {
 7                "query": {"type": "string", "description": "Natural language query"},
 8                "top_k": {"type": "integer", "default": 5, "minimum": 1, "maximum": 20},
 9            },
10            "required": ["query"],
11        },
12        "fn": lambda args: tool_search_blog(args["query"], args.get("top_k", 5)),
13    },
14    "read_chunk": {
15        "description": "Read the full text of a specific chunk by source path and chunk index.",
16        "inputSchema": {
17            "type": "object",
18            "properties": {
19                "source": {"type": "string", "description": "Markdown file path relative to content/"},
20                "chunk_index": {"type": "integer", "minimum": 0},
21            },
22            "required": ["source", "chunk_index"],
23        },
24        "fn": lambda args: tool_read_chunk(args["source"], args["chunk_index"]),
25    },
26}

每個 field 角色：

1. description：給 LLM 看的、解釋這個 tool 解什麼問題。LLM 看 description 決定何時 call。這是模型 follow tool 的最主要訊號——寫得清晰具體、模型用得對。
2. inputSchema：JSON Schema、描述 tool 接受的參數結構。LLM application 用這個 schema 約束 LLM 生成「合法的呼叫」。
3. properties：每個參數的型別 + 約束。
4. required：必填參數清單。LLM 漏掉時、client 端可以 reject、不會浪費 round-trip。
5. default：可選參數的預設值。傳的時候不給、tool 就用 default。
6. minimum / maximum：數值約束。top_k 設 1-20 是因為 < 1 沒意義、> 20 浪費 retrieval。
7. fn：實際 dispatch 用的 callable。本 demo 用 lambda 把 args dict 轉成 positional / keyword call。

為什麼這樣設計：

• 為什麼 description 要具體：LLM 看 description 決定 call 時機。「search the blog」對 LLM 來說太模糊（搜什麼？找什麼？）、改成「Semantic search over blog content. Returns top-K relevant chunks with source paths.」明確描述輸入跟輸出形狀、LLM 能判讀「使用者問技術問題時該 call 這個」。
• 為什麼 schema 用 JSON Schema、不是自訂格式：JSON Schema 是 web 標準、所有 LLM application 都認識、跨 framework 可移植。也是 function calling 跟 Tool use 原理 的 schema 描述語言。
• 為什麼 required 跟 default 兩個機制：對 LLM 看的 prompt 越清楚越好。required 告訴 LLM「不傳這個會錯」、default 告訴 LLM「可不傳、預設值是 X」。沒分清的話、LLM 可能總是傳所有參數、雜訊多。
• 為什麼 fn 用 lambda 包：實際 tool function 是 positional args、但 client 送的是 dict。lambda 把 dict 拆成 function call 的 args。也方便將來如果 tool function signature 變、只要改 lambda 不用改 dispatcher。

Client 實作（測試用）

完整檔案：scripts/mcp-demo/test_client.py。實際 production 用 Claude Desktop / Cursor 等 MCP-capable application。本 demo 寫一個 stdio client、模擬 application 行為：

 1proc = subprocess.Popen(
 2    [sys.executable, str(SERVER)],
 3    stdin=subprocess.PIPE,
 4    stdout=subprocess.PIPE,
 5    stderr=subprocess.PIPE,
 6    text=True,
 7    bufsize=1,
 8)
 9
10def send(method, params=None, rid=None):
11    msg = {"jsonrpc": "2.0", "method": method}
12    if params is not None:
13        msg["params"] = params
14    if rid is not None:
15        msg["id"] = rid
16    proc.stdin.write(json.dumps(msg) + "\n")
17    proc.stdin.flush()
18    if rid is None:
19        return None  # notification
20    line = proc.stdout.readline()
21    return json.loads(line)

每個參數做什麼：

1. subprocess.Popen([sys.executable, str(SERVER)], ...)：spawn server 當 child process。用 sys.executable 確保用同一個 Python interpreter（避免 venv 跟系統 Python 混用）。
2. stdin=subprocess.PIPE, stdout=subprocess.PIPE, stderr=subprocess.PIPE：三條 pipe 都接到 client、讓我們能讀寫 server 的 stdio。
3. text=True：自動處理 str ↔ bytes 編碼、直接讀寫字串、不用手動 encode/decode。預設是 binary mode。
4. bufsize=1：line buffering、每寫一行就 flush。沒這個的話、Python 預設 block buffering（4KB 才 flush）、client 寫的 message server 看不到、整個卡住。
5. proc.stdin.write(json.dumps(msg) + "\n")：寫 JSON 訊息、結尾加 \n（line-delimited）。
6. proc.stdin.flush()：強制立刻送出。即使有 bufsize=1、明確 flush 是好習慣、避免任何 buffer 累積。
7. if rid is None: return None：notification 不該等 response。
8. line = proc.stdout.readline() + json.loads(line)：讀一行 response、parse。

為什麼這樣設計：

• 為什麼 stdio 而不是 socket / HTTP：MCP stdio transport 的主要場景是「application spawn server」(Claude Desktop 開 Python 進程當 MCP server)。Stdio 自然形成 1-to-1 ownership、不需要 port allocation、不需要 auth。HTTP transport 也存在、用在 multi-client 場景。
• 為什麼 bufsize=1 這麼關鍵：Python 預設 stdio buffer 4KB。如果 server / client 任一邊寫了 short message 但沒 fill 4KB、message 不會被另一邊看到、protocol 卡死。看起來是 hang、debug 困難。bufsize=1 強制 line buffering、解決這個 deadlock。
• 為什麼 text=True：JSON-RPC 都是文字、binary mode 要手動 .encode() / .decode()、增加複雜度。text=True 自動處理 UTF-8。

跑通整條流程

1cd ~/Projects/blog
2python3 scripts/mcp-demo/test_client.py

• cd ~/Projects/blog：切到 repo 根、讓 SERVER 路徑相對解析正確。
• python3 scripts/mcp-demo/test_client.py：跑 test client、它會 spawn server 跟它對話。

預期看到五個階段：

1. initialize（握手）

 1=== 1. initialize ===
 2{
 3  "jsonrpc": "2.0",
 4  "id": 1,
 5  "result": {
 6    "protocolVersion": "2025-03-26",
 7    "capabilities": {"tools": {}},
 8    "serverInfo": {"name": "blog-mcp-demo", "version": "0.1.0"}
 9  }
10}

Protocol 意義：

• protocolVersion：server 支援的 MCP 版本。Client 要 negotiate（自己 cap 較新時要 downgrade）。
• capabilities.tools: {}：server 宣告「我支援 tools 功能」、空 object 表示沒額外 sub-feature。Client 拿到後知道可以 call tools/list。
• serverInfo：server 識別資訊、給 client 顯示用（debug、logging）。
• id: 1：對應 client 送的 request id、讓 client 知道這個 response 是哪個 request 的。

2. tools/list

Server 回兩個 tool 的完整 schema：

 1{
 2  "tools": [
 3    {
 4      "name": "search_blog",
 5      "description": "Semantic search over blog content...",
 6      "inputSchema": {...JSON Schema...}
 7    },
 8    {
 9      "name": "read_chunk",
10      "description": "Read the full text of a specific chunk...",
11      "inputSchema": {...}
12    }
13  ]
14}

Protocol 意義：這個輸出就是 LLM application 會塞給 LLM 的 tool 描述。LLM application 把這份 schema 用 function calling 機制給模型看、模型決定何時呼叫、傳什麼參數。Server 跟模型之間靠這層 schema 對齊、模型不直接呼叫 server、是經 application 中介。

3. tools/call: search_blog

Client 送：

1{
2  "method": "tools/call",
3  "params": {
4    "name": "search_blog",
5    "arguments": {"query": "什麼是 KV cache？", "top_k": 3}
6  },
7  "id": 3
8}

params 包兩件事：

• name：要 call 的 tool 名（matches tools/list 內某個 tool）。
• arguments：實際傳給 tool 的 dict、結構符合該 tool 的 inputSchema。

Server 回 cosine 搜尋結果（preview）：

1[
2  {"source": "llm/00-foundations/hardware-memory-budget.md", "chunk_index": 5, "score": 0.7497, "preview": "| Context 長度 | KV cache 估算..."},
3  {"source": "llm/00-foundations/why-llm-feels-slow.md", "chunk_index": 4, "score": 0.7212, "preview": "..."},
4  {"source": "llm/03-theoretical-foundations/attention-mechanism.md", "chunk_index": 7, "score": 0.7176, "preview": "..."}
5]

實測命中合理——KV cache 相關段落都被找到。

4. tools/call: read_chunk

Client 用 search 拿到的 source + chunk_index、call read_chunk 拿完整內容：

 1{
 2  "method": "tools/call",
 3  "params": {
 4    "name": "read_chunk",
 5    "arguments": {
 6      "source": "llm/00-foundations/hardware-memory-budget.md",
 7      "chunk_index": 5
 8    }
 9  }
10}

Server 回該 chunk 的完整 markdown 文字。這實現了「search → read」的兩段流程——避免 search 一次就把所有 chunk 完整內容塞給 LLM（context 暴炸）、讓 LLM 自己看 preview 決定要 deep dive 哪個。

5. 錯誤路徑

1=== 5. unknown method (error path) ===
2{"jsonrpc": "2.0", "id": 5, "error": {"code": -32601, "message": "Method not found: does/not/exist"}}

-32601 是 JSON-RPC 標準 error code for unknown method。Server 對未知 method 回標準 error、不 crash。Client 知道這個 method 不能用、繼續其他操作。

跟 Claude Desktop / Cursor 整合

把這個 server 接到實際 MCP-capable application：

Claude Desktop

編輯 ~/Library/Application Support/Claude/claude_desktop_config.json：

1{
2  "mcpServers": {
3    "blog-search": {
4      "command": "/path/to/python3",
5      "args": ["<absolute-path-to-blog>/scripts/mcp-demo/blog_mcp_server.py"]
6    }
7  }
8}

每個 field 做什麼：

• mcpServers：MCP server 註冊表、key 是任意名稱（client 識別用）。
• command：spawn 用的 executable path。要寫絕對路徑、Claude Desktop 啟動時的 PATH 可能不含 python3。
• args：傳給 command 的 args list。第一個是 script path。

為什麼這樣設計：Claude Desktop 啟動時讀這個 config、對每個 server 用 subprocess.spawn(command, args) 起 child process、用 stdio 跟它對話。跟本 demo 的 test_client.py 做的事完全一樣、只是改成 GUI application 而已。

重啟 Claude Desktop 後、在對話框問「用 search_blog 找 KV cache 相關段落」、Claude 會自動 call tool 並用結果回答。

Cursor

.cursor/mcp.json（per-project）或全域設定類似結構。具體欄位看當下版本文件。

兩種整合的共通點：MCP server 自己不變、只要 application 端配置 path 跟 args、整合就完成。這正是 4.3 章節 N×M → N+M 的具體展現——本 server 不為任何特定 application 客製化、就能被多個 application 接到。

觀察跟原理對應

回到 4.6 應用層協議 的三層 framing：

這個分離正是 MCP 的核心收益：server 寫好之後、用什麼 LLM 跟它互動跟 server 無關。換掉 LLM、換掉 application、server code 完全不動。

何時這份 demo 會過時

• MCP protocol version：目前用 2025-03-26、未來會更新、但「server 暴露 tool 給 application」的 framing 不變。
• JSON-RPC 細節：可能 transport 形式增加（HTTP / WebSocket）、stdio 不會消失。
• Tool 描述格式：JSON Schema 是 web 通用標準、不會被換掉。

實作換代時、可以把手寫 JSON-RPC 換成官方 SDK、tool 內部邏輯（embedding / cosine / pickle）依需求換、但 protocol 骨架（initialize / tools/list / tools/call）會保留。

跑這個 demo 的指令總結

1# 前置：確認 Ollama 跑著、index.pkl 存在
2ollama list | grep nomic-embed-text
3ls scripts/rag-demo/index.pkl

• ollama list：列已下載 model、grep 過濾出 embedding model。沒看到表示要先 ollama pull nomic-embed-text。
• ls scripts/rag-demo/index.pkl：確認 RAG ingest 跑過、index 存在。沒看到要先跑 python3 scripts/rag-demo/ingest.py。

1# 自動測試 MCP server
2python3 scripts/mcp-demo/test_client.py

• 跑 test_client、spawn server、依序送 5 個 request 驗證 protocol。stdout 印 protocol 對話、stderr 印 server log。看到全部 5 階段 OK 就成功。

1# 手動跟 server 互動（看 protocol 原始 wire format）
2python3 scripts/mcp-demo/blog_mcp_server.py
3# 然後手打：{"jsonrpc":"2.0","id":1,"method":"initialize","params":{}}

• 直接 invoke server、它讀 stdin 等 request。手打 JSON-RPC 訊息、看 server 回。是學 protocol 最直接的方式——你會看到 wire format 真實長相、跟自動 client 包裝後不一樣。

完整 source 在 scripts/mcp-demo/、約 250 行 Python、stdlib only。

跟其他 hands-on 章節的關係：完整 hands-on 系列見 Hands-on 章節索引、本 demo 依賴的索引由 RAG demo ingest 產生、MCP + RAG 同跑的記憶體 / 程序預算見 RAG + MCP resource footprint、術語見 MCP。

本篇用四組對照實驗證明這個事實、再展開 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。

本篇 framing 是「真實會跑、不只跑 demo」、所以包含：硬體預算估算、catastrophic forgetting 防護、evaluation 確認真的有提升、回退方案（fine-tune 失敗時怎麼辦）。

驗證日期：2026-05-12 環境：M4 Max 64GB + Hugging Face PEFT 0.13、或 5090 24GB + bitsandbytes 目標模型：Qwen3-Coder-7B-Instruct（fine-tune 後輸出符合自己 codebase 慣例的 code）

為什麼這個議題重要

寫 code 場景的常見 fine-tune 動機：

1. 私有 codebase 慣例：自家專案有特殊 naming、特殊 design pattern、prompt engineering 拉不到、希望模型「自然知道」
2. 特殊框架 / library：用 obscure 的內部 framework、通用模型沒看過、補完品質差
3. 特定文檔風格：commit message、PR description、code comment 有 team-specific 格式
4. Reduce RAG dependence：把高頻 knowledge 編進模型權重、減少每次 query 都要 retrieve

但不該 fine-tune的情境（先排除）：

1. 新增世界知識：fine-tune 不擅長加新事實、用 RAG 即可
2. 複雜 reasoning 能力：fine-tune 一般不會讓模型變更會 reason、reasoning 來自 pre-training + RL
3. 改善通用對話品質：通用對話品質取決於 RLHF、fine-tune 多半會 catastrophic forgetting
4. 資料太少（< 500 對）：fine-tune 收益低、不如優化 prompt + RAG

整體流程

11. 硬體預算估算       → 知道能跑哪個 size 的 base model
22. 蒐集 fine-tune 資料 → 50-5000 對 (prompt, response)
33. 環境準備           → Python + bitsandbytes / PEFT / transformers
44. 跑 QLoRA 訓練      → 1-3 epochs、看 loss 趨勢
55. Evaluation         → 在 held-out set + 通用 benchmark 都跑
66. Merge LoRA → base  → 得到合併權重 .safetensors
77. Convert → GGUF     → 用 llama.cpp convert 工具
88. Deploy 到 Ollama   → ollama create my-coder -f Modelfile
99. 配 Continue.dev    → config.json 加新 provider

Step 1：硬體預算估算

QLoRA 訓練的記憶體需求（粗略估算）：

 1記憶體 ≈ N (B 參數) × 0.6 GB     ← 訓練時
 2        ≈ N (B 參數) × 0.3 GB     ← 推論（4-bit）
 3
 4Apple Silicon Mac：
 5  M4 Pro 24GB → 訓 7B 可、訓 14B 緊
 6  M4 Pro 36GB → 訓 7B 寬鬆、訓 14B 可
 7  M4 Max 64GB+ → 訓 30B 可、推論 70B 可
 8
 9PC 獨立 GPU：
10  RTX 4090 / 5090 24GB → 訓 7B 寬鬆、訓 14B / 30B with `--n-cpu-moe` 可
11  RTX A6000 48GB → 訓 30-32B 寬鬆

事實查核註：Apple Silicon 上的 QLoRA 支援度跟 bitsandbytes / MLX 工具鏈版本相關、2026/5 主流是用 MLX 自己的 LoRA 實作（mlx-lm）、CUDA 路線用 transformers + bitsandbytes + PEFT。具體支援度以對應 release 為準。

本篇假設 fine-tune Qwen3-Coder-7B、所以 24GB+ Mac 或 16GB+ GPU 都能跑。

Step 2：蒐集 fine-tune 資料

最關鍵的 step。資料品質決定 fine-tune 成敗。

資料格式（典型 SFT format）

1[
2  {
3    "instruction": "用我們 codebase 的慣例寫一個 REST endpoint 處理 user signup",
4    "input": "需求：accept email + password、回 JWT",
5    "output": "// 完整符合我們慣例的 code..."
6  },
7  ...
8]

或對話格式（ChatML）：

1[
2  {
3    "messages": [
4      {"role": "system", "content": "你是我們 codebase 的 coding assistant"},
5      {"role": "user", "content": "..."},
6      {"role": "assistant", "content": "..."}
7    ]
8  }
9]

資料來源

資料量門檻

資料 mixing（防 catastrophic forgetting）

訓練 batch 內 mix 通用資料、避免 fine-tune 把通用能力洗掉：

180% in-domain data（你的 codebase 範例）
220% 通用 instruction data（如 Alpaca、ShareGPT subset）

通用 data 可從 Hugging Face datasets 抓（如 tatsu-lab/alpaca、teknium/OpenHermes-2.5）。

Step 3：環境準備

Apple Silicon Mac（用 MLX）

1# MLX 是 Apple 的 ML framework、原生支援 Apple Silicon
2pip install mlx mlx-lm
3
4# 或用 conda（推薦）
5conda create -n llm-ft python=3.11
6conda activate llm-ft
7pip install mlx-lm

PC（CUDA + transformers + bitsandbytes）

1# 安裝 CUDA 12.x（依 GPU 驅動）
2
3# Python 套件
4pip install torch transformers peft bitsandbytes accelerate datasets trl

Step 4：跑 QLoRA 訓練

Apple Silicon（MLX）方式

 1# 把 base model 下載到本機
 2huggingface-cli download Qwen/Qwen3-Coder-7B-Instruct \
 3  --local-dir ~/models/qwen3-coder-7b
 4
 5# 把資料整理成 JSONL（一行一筆）
 6# data/train.jsonl、data/valid.jsonl
 7
 8# 跑 LoRA fine-tune（MLX 內建 4-bit）
 9mlx_lm.lora \
10  --train \
11  --model ~/models/qwen3-coder-7b \
12  --data data/ \
13  --batch-size 4 \
14  --lora-layers 16 \
15  --iters 1000 \
16  --learning-rate 1e-4 \
17  --steps-per-eval 100 \
18  --adapter-path ./adapters

PC（CUDA）方式

 1# train.py（簡化版）
 2from transformers import AutoTokenizer, AutoModelForCausalLM, TrainingArguments, BitsAndBytesConfig
 3from peft import LoraConfig, get_peft_model
 4from trl import SFTTrainer
 5from datasets import load_dataset
 6
 7# 4-bit 量化載入 base
 8bnb_config = BitsAndBytesConfig(
 9    load_in_4bit=True,
10    bnb_4bit_quant_type="nf4",
11    bnb_4bit_compute_dtype="bfloat16",
12)
13model = AutoModelForCausalLM.from_pretrained(
14    "Qwen/Qwen3-Coder-7B-Instruct",
15    quantization_config=bnb_config,
16)
17
18# LoRA 配置
19lora_config = LoraConfig(
20    r=16,
21    lora_alpha=32,
22    target_modules=["q_proj", "v_proj"],
23    lora_dropout=0.05,
24    task_type="CAUSAL_LM",
25)
26model = get_peft_model(model, lora_config)
27
28# 資料
29dataset = load_dataset("json", data_files="data/train.jsonl")
30
31# 訓練
32training_args = TrainingArguments(
33    output_dir="./checkpoints",
34    learning_rate=1e-4,
35    num_train_epochs=2,
36    per_device_train_batch_size=4,
37    gradient_accumulation_steps=4,
38    save_steps=200,
39    logging_steps=20,
40    optim="paged_adamw_8bit",
41    bf16=True,
42)
43trainer = SFTTrainer(
44    model=model,
45    args=training_args,
46    train_dataset=dataset["train"],
47    max_seq_length=2048,
48)
49trainer.train()
50trainer.save_model("./adapters")