驗證日期：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 記憶體預算。

• 純 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")

關鍵超參數的判讀邏輯：

看 training loss 趨勢

訓練過程中、loss 應該：

 1Initial：~2.5（cross-entropy on next-token）
 21/4 訓練：降到 ~1.5
 31/2 訓練：降到 ~1.0
 43/4 訓練：降到 ~0.7
 5末段：穩定在 ~0.5
 6
 7警示訊號：
 8- Loss 不降（≈ 2.0+ 持平） → lr 太小、或資料品質差、或 base 跟資料分佈完全不合
 9- Loss 降到 < 0.1 → over-fit、validation loss 應該已升、stop training
10- Loss 出 NaN → lr 太大、降 lr 重來

Step 5：Evaluation

訓練完不能只看 training loss、要實測：

1. Held-out test set（你自己的 in-domain 資料）

1# 拿 valid.jsonl 跑、看模型輸出 vs expected
2# 用 BLEU / ROUGE / 或 LLM-as-judge 評分
3mlx_lm.generate \
4  --model ~/models/qwen3-coder-7b \
5  --adapter ./adapters \
6  --prompt "<test prompt from valid.jsonl>"

2. 通用 benchmark（防 catastrophic forgetting）

跑通用 HumanEval、看分數有沒有崩：

1# 用 lm-evaluation-harness
2git clone https://github.com/EleutherAI/lm-evaluation-harness
3cd lm-evaluation-harness
4pip install -e .
5
6lm_eval --model hf \
7  --model_args pretrained=~/models/qwen3-coder-7b,peft=./adapters \
8  --tasks humaneval \
9  --batch_size 8

判讀：

• HumanEval 從 75% → 75%：通用能力保留、in-domain 提升、成功
• HumanEval 從 75% → 55%：catastrophic forgetting、要重新 fine-tune（用 LoRA + 資料 mixing 加強）

3. 自己工作流測試（最重要）

實際在 Continue.dev 用幾天、看：

• In-domain 任務輸出是否確實貼近 codebase 慣例
• 通用 coding 任務（如「寫一個 helper function」）是否仍 OK
• 對話流暢度有沒有變差
• 出現怪行為的頻率

Step 6：合併 LoRA 跟 base model

訓練完得到 adapter（小檔、< 100MB）。要用於日常推論、通常 merge 進 base：

 1# MLX 方式
 2mlx_lm.fuse \
 3  --model ~/models/qwen3-coder-7b \
 4  --adapter-path ./adapters \
 5  --save-path ~/models/qwen3-coder-7b-mycodebase
 6
 7# PEFT 方式
 8python -c "
 9from peft import AutoPeftModelForCausalLM
10import torch
11
12model = AutoPeftModelForCausalLM.from_pretrained('./adapters', torch_dtype=torch.bfloat16)
13merged = model.merge_and_unload()
14merged.save_pretrained('./merged-model')
15"

Step 7：Convert 成 GGUF（給 Ollama / llama.cpp 用）

 1# 安裝 llama.cpp
 2git clone https://github.com/ggml-org/llama.cpp
 3cd llama.cpp
 4pip install -r requirements.txt
 5
 6# Convert HF → GGUF
 7python convert_hf_to_gguf.py ~/models/qwen3-coder-7b-mycodebase \
 8  --outfile ~/models/qwen3-coder-7b-mycodebase.gguf
 9
10# 量化（可選、Q4_K_M 是甜蜜點）
11./llama-quantize \
12  ~/models/qwen3-coder-7b-mycodebase.gguf \
13  ~/models/qwen3-coder-7b-mycodebase-Q4_K_M.gguf \
14  Q4_K_M

Step 8：Deploy 到 Ollama

 1# 寫 Modelfile
 2cat > ~/models/Modelfile-mycodebase <<EOF
 3FROM ~/models/qwen3-coder-7b-mycodebase-Q4_K_M.gguf
 4
 5TEMPLATE """<|im_start|>system
 6{{ .System }}<|im_end|>
 7<|im_start|>user
 8{{ .Prompt }}<|im_end|>
 9<|im_start|>assistant
10"""
11
12PARAMETER temperature 0.3
13PARAMETER top_p 0.9
14PARAMETER num_ctx 32768
15EOF
16
17# 註冊到 Ollama
18ollama create mycodebase-coder -f ~/models/Modelfile-mycodebase
19
20# 測試
21ollama run mycodebase-coder "寫一個 user signup endpoint"

Step 9：配 Continue.dev

 1// ~/.continue/config.json 加：
 2{
 3  "models": [
 4    {
 5      "title": "My Codebase Coder",
 6      "provider": "ollama",
 7      "model": "mycodebase-coder",
 8      "apiBase": "http://localhost:11434"
 9    },
10    // ... 既有 models
11  ]
12}

VS Code restart 後、Continue panel 下拉就能切換。

失敗模式跟回退

失敗 1：訓練 loss 不降

可能原因：

• 資料品質差 → 人工 review 50 對、看 instruction-response 是否真有對應
• 資料 token 太短 → 多數 < 100 token、模型學不到複雜 pattern
• lr 太小 → 試 lr 5e-4

回退：把資料品質提升、或放棄 fine-tune 用 RAG。

失敗 2：HumanEval 大幅下降（catastrophic forgetting）

緩解：

• 加入 20% 通用 data mixing、重訓
• 降低 epochs（從 3 → 1）
• 降低 LoRA rank（從 16 → 8）

失敗 3：In-domain test 進步、但日常用感覺沒變

可能原因：

• Test set 跟真實工作流分佈不符
• Prompt template 在訓練跟推論不一致

緩解：實際在 Continue.dev 跑 1-2 週、看真實效果再判斷。

失敗 4：訓練爆 OOM

緩解：

• 降 batch size（4 → 2 → 1）
• 加 gradient_accumulation_steps（保持 effective batch size）
• 用更小的 LoRA rank
• 換更小的 base model（7B → 3B）

何時不該繼續 fine-tune 路線

跑完一次 fine-tune 評估後、若：

1. In-domain 提升 < 10%：相對成本（時間 + 維護）不划算、用 RAG
2. Catastrophic forgetting > 10%：跟其他能力 trade-off 不值得
3. 資料量不夠（< 500 對）：RAG 比 fine-tune 更有效
4. 工作流變化快（codebase 慣例每月變）：fine-tune 過時得快、RAG 更靈活

跟其他模組的關係

• 原理層的 LoRA 設計見 LoRA 卡片 跟 QLoRA 卡片
• Catastrophic forgetting 跟整體 alignment 議題見 3.4 訓練流程
• Fine-tune 後的模型評估見 4.14 Benchmarking
• 隱私 / 供應鏈面：fine-tune 後 model 怎麼分享（給 team / 上 HuggingFace）見 6.0 模型供應鏈
• 跟 RAG 的取捨見 4.1 RAG 原理 的「RAG vs Fine-tuning vs Long Context」段

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

• 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、同樣輸入內容。

對比表