用作走查的任務：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 索引。

本章把 RAG 拆成不會隨工具世代消失的部分：retrieval 的本質、chunking 的取捨、失敗模式的分類、跟 fine-tuning / long context 三種路線的比較。LangChain、LlamaIndex、Vector database 選型等具體實作不在本章範圍——這些半年一個版本、教程價值低於壽命。本章寫的是「為什麼 retrieval 會這樣設計、什麼時候會失敗、什麼時候改用其他方案」。

本章目標

讀完本章後你能：

1. 解釋為什麼 LLM 需要外掛知識、純靠模型參數記憶解不了什麼問題。
2. 區分「語意相似」與「字面相似」對 retrieval 的影響、看到 retrieval 結果不理想時、判斷是哪一類失配。
3. 看到 chunking 參數時、知道背後的 resolution vs context 取捨。
4. 在「RAG / fine-tuning / long context」三者之間、依任務做合理選擇。

為什麼模型需要外掛知識

LLM 的參數記憶是「壓縮過的訓練資料」：權重把預訓練看過的所有文字壓進一個固定大小的數值結構、推論時用這份壓縮表示生成下一個 token。這個結構有三個天然限制：

1. 訓練 cutoff：模型只認識訓練資料截止前的世界、cutoff 之後發生的事完全看不見。Claude 4 cutoff 是 2026/1、2026/5 的新聞模型不知道。
2. 私有資料缺席：訓練資料是公開來源、私有 codebase、內部文件、個人筆記都不在裡面。再強的模型也不會「知道你 repo 的內部慣例」。
3. 長尾事實壓縮損失：訓練資料中出現很多次的常識（如 Python 語法）模型記得清楚、出現一兩次的長尾事實（如某個 obscure library 的某個 function）會被壓縮損失。

RAG 把這三個限制都繞開：retrieval 階段從動態外部 retrieval source（可即時更新、可放私有資料、可保留長尾完整內容）拉出相關片段、augmentation 階段把這些片段塞進 prompt 當 context。模型不需要「知道」這份知識、只需要「讀懂」當下 prompt 裡的這份知識。

這個結構的根本價值是「把知識從模型權重解耦」。模型負責「語言理解 + 推理」、知識負責「事實儲存 + 動態更新」、兩者各自演化：模型升級不需重建知識庫、知識更新不需重訓模型。具體 retrieval 機制依賴 embedding model 把文字轉成向量、用相似度衡量「相關性」。

Retrieval 的核心問題：語意相似 vs 字面相似

Retrieval 解的是「給一個 query、找出相關的 document」這個問題、但「相關」有兩種定義：

• 字面相似（lexical similarity）：query 跟 document 共用多少 keyword。傳統 search engine 用這套（如 Elasticsearch / OpenSearch 的 BM25 算法、以 keyword 出現頻率加權的傳統檢索演算法、不考慮語意）。
• 語意相似（semantic similarity）：query 跟 document 表達的意思接近、即使共用 keyword 少。Embedding-based retrieval 用這套。

兩種模式的失敗模式恰好互補：

實務上現代 RAG 多半用「hybrid retrieval」：BM25 + embedding 分數加權合併、補單一模式的失敗模式。但理解兩者本質的差異、能解釋為什麼 retrieval 結果有時很準、有時莫名其妙。

語意 retrieval 還帶來一個容易忽略的限制：embedding 模型本身有訓練分佈。它在 Wikipedia / Common Crawl 風格的文字上表現好、在你的內部 codebase 風格上表現未必好。Domain shift 是 retrieval 失敗的常見根本原因、不是「embedding 不夠強」、是「embedding 沒見過這類資料」。

Chunking 的本質取捨

RAG 若把整份文件當 retrieval 單位、document 太長、retrieval 拿到的太粗、實務上要先切成 chunk。Chunk 大小的選擇是 retrieval 設計最關鍵也最容易誤判的決定。

Chunk 太小（如每段 100 token）的失敗模式：

• 每塊資訊不完整、retrieval 拿到的 fragment 無法獨立理解（如「他在第三章提到這個概念」、但「他」「這個概念」需要前文才解得開）。
• 跨 chunk 的語意關聯被切斷、retrieval 拿到一個 chunk 但相關的補充資訊在下個 chunk。
• 同一個概念可能切到多個 chunk、retrieval 拿其中一個是不完整論述。

Chunk 太大（如每段 2000 token）的失敗模式：

• Retrieval 精確度低、一個 chunk 包含多個主題、相似度計算被無關內容稀釋。
• 塞進 prompt 浪費 token、context 利用率差。
• 重要訊號可能埋在 chunk 中間、被前後 noise 蓋過。

「resolution vs context loss」是無法兩全的設計問題：細粒度精確但缺脈絡、粗粒度有脈絡但精度差。不同任務有不同最適點：

• 問答任務（答案是短句）：偏細粒度、500 token 左右常見。
• 摘要任務（答案需要長段脈絡）：偏粗粒度、1500-2000 token 常見。
• Code retrieval：以邏輯單位切（function、class）、不是按 token 數切。
• 規格 / 法律文件：按章節結構切、保留 hierarchy。

Chunking 還有兩個常被忽略的設計維度：

• Overlap：相鄰 chunk 之間留 10-20% overlap、避免「重要訊號剛好被切斷」。
• 語意邊界 vs 字數邊界：純按字數切會穿過句子或段落中間；按段落 / heading / 邏輯單位切保留語意完整、但實作複雜。

寫 code 場景的 retrieval（如 Continue.dev 的 @codebase、即 IDE 內把整個 codebase 當 retrieval 來源的指令）多半按邏輯單位切 code（function、class、import block）、配合 AST 解析、比純文字 chunking 收益高很多。

Retrieval 失敗的根本原因

Retrieval 結果不理想時、根本原因通常落在這幾類：

語意 gap

Query 跟 document 描述的是同一個東西、但用詞、立場、抽象層級都差很多，這是 query-document gap。例：query 是「怎麼讓 API 跑快」、document 是「latency optimization techniques」。Embedding 模型訓練得好的話可以對齊、訓練不好或 domain 不熟就 miss。緩解：query rewriting（讓 LLM 把 query 改成更接近 document 的 phrasing）、HyDE（hypothetical document embeddings、用 LLM 生成「假設的答案」、用這個假答案的 embedding 去 retrieval）。

超出訓練分佈

Embedding 模型對某個 domain 表現崩（如金融術語、醫療 jargon、特殊 codebase 慣例）。判讀訊號：retrieval 結果看起來「隨機」、語意相關性低。緩解：換 domain-specific embedding 模型、或退回 BM25。

Chunk 邊界穿過語意單位

正確答案被切到兩個 chunk、retrieval 拿到的只是其中半邊。判讀訊號：模型回答不完整或「我看到 X 但不知道 Y」、檢查發現 Y 在相鄰 chunk。緩解：加 overlap、改用語意邊界 chunking。

Query 過短缺乏 disambiguation context

Query 太短、模型不知道使用者真正想要什麼（如 query 「python」可以指語言、shell binary、套件、文件章節）。Retrieval 拿到的可能語意完全錯。緩解：在 retrieval 前讓 LLM expand query、加上對話歷史當 context。

Embedding 跟下游 LLM 訓練分佈不一致

Embedding 模型擅長把「相關」拉近、但「相關」的定義可能跟下游 LLM 「能用」的定義不同。例：embedding 把同義詞拉近、但下游 LLM 需要的是「能完整回答 query 的 document」、不是「跟 query 同義」。判讀訊號：retrieval 看起來合理但回答品質差。緩解：retrieval + re-ranker（用較強模型對 retrieval candidates 再排序）。

這五類失敗各有自己的訊號、根本原因不同、緩解策略也不同。Retrieval 出問題時、先用症狀分類、再對應到根因、比「換更大 embedding 模型」這種反射式修法有效得多。

Production retrieval pipeline：hybrid + reranker

實務 production RAG 多不只用單一 embedding-based retrieval、而是「hybrid search + reranker」兩段式：

 1User query
 2   ↓
 3[Stage 1: Hybrid retrieve top-50]
 4   ├── BM25（字面）retrieve top-25      ← 抓精確 keyword、識別碼、罕見 entity
 5   └── Embedding（語意）retrieve top-25  ← 抓同義詞、jargon、語意相似
 6   ↓ Reciprocal Rank Fusion 合併
 7   top-50 candidates
 8   ↓
 9[Stage 2: Reranker rerank to top-5]
10   Cross-encoder 對每對 (query, doc) 算 fine-grained relevance
11   ↓
12   top-5 給 LLM

為什麼兩段式：

何時不需要 reranker：

• 小語料（< 1000 docs）、embedding 已準
• 純 keyword 任務、BM25 已準
• 極低 latency 要求（reranker 加幾百 ms）

主流 reranker：Cohere Rerank 3（SaaS）、Jina Reranker v2（OSS）、BGE Reranker（OSS、中文友善）、Voyage rerank-2。詳細選型見 reranker 卡。

Chunking 策略對比

chunking 卡 講概念、實務有五種主流策略：

判讀流程：

 1內容類型？
 2├── 純文字 / 文章       → Recursive 或 Semantic
 3├── Markdown 文檔       → Markdown header（fallback recursive）
 4├── 程式碼              → Code-aware（tree-sitter）
 5├── 混合（文章 + code） → Markdown header 主、code block 用 tree-sitter
 6└── PDF                 → 先轉 Markdown 再用 Markdown header
 7
 8Chunk 大小？
 9├── 一般 RAG            → 512-1024 token、overlap 50-100 token
10├── 短回答 / 精確匹配  → 256-512 token、更精確
11└── 整段理解 / 長 narrative → 1024-2048 token、配合 long context model

實務常見錯誤：

1. 拿 raw PDF 直接 chunking：PDF 結構亂、應該先轉 markdown
2. 過大 chunk 套小 context embedding：bge-large context limit 512、塞 2048 chunk 直接截斷
3. 不加 overlap：句子被切斷、retrieval 漏前後文
4. 混合語料用同樣 chunking：technical doc + casual blog + code 一視同仁、品質都差

RAG vs Fine-tuning vs Long Context

「讓模型知道新東西」有三條路、解的問題層級不同：

三者不互斥、實際應用常組合使用：fine-tune 模型懂 domain jargon、RAG 拉動態知識、long context 在單一任務塞完整脈絡。

判讀「該用哪一條」的核心問題：

• 知識會不會變？常變 → RAG。穩定 → fine-tune 或 long context。
• 知識量多大？小（< 100K tokens、塞得進 context window）→ long context。大 → RAG。
• 需要 traceable（知道答案來源）？是 → RAG（每個 chunk 有 source）。否 → fine-tune 也可。
• 是行為 / 風格還是事實？行為 → fine-tune（教模型「該怎麼回應」）。事實 → RAG（教模型「該知道什麼」）。

寫 code 場景：codebase 變得快、量大、需要 traceable（要知道參考的是哪個 file）——RAG 是預設選擇。Fine-tune 在「想讓模型懂特定 codebase 風格 / 慣例」時補上、但在 codebase 變動頻繁的多數場景成本壓過收益；少數穩定大型 codebase 且風格規範強的情境（如金融 / 醫療 SDK）才值得評估 fine-tune。

何時不適合 RAG

RAG 適用面有邊界、下列情境改用其他方案更划算：

• 需要 holistic 理解整份文件：如改寫整篇文章的風格、跨段邏輯重組。Retrieval 拿到的是片段、看不到整體。改用 long context 把整份塞進 prompt、或先讓 LLM summarize 再對 summary 操作。
• 知識是高度結構化資料：如使用者資料庫、產品目錄。直接用 SQL query 比 embedding retrieval 精確得多。RAG 變成繞遠路。
• 知識量小、每次都會用到：如系統 prompt 的角色設定、不變的規則。直接寫進 system prompt 比每次 retrieval 簡單。
• Retrieval cost 高於 long context：知識量壓過 context 但壓力不大（如 50K tokens）、retrieval pipeline 維護成本可能高於直接塞長 context。值不值得做 RAG 看 query 頻率：偶爾用就 long context、高頻用才值得建 retrieval。
• Latency 敏感場景：RAG 加一輪 retrieval、TTFT 變長。即時補完場景可能受不了。

判讀「該不該做 RAG」的反射：先問「不做 RAG 會怎樣」、再評估 RAG 的維護成本。RAG 不是免費的——需要 ingestion pipeline、embedding 服務、vector database、retrieval logic、re-ranker、評估系統。判讀 overengineering 的訊號：查詢量 < 100/day、文件 < 1000 份、變動頻率 < 月一次、這類規模通常 long context + 簡單檔案讀取已足夠；超過這個量級才值得建完整 RAG stack。

何時過時 / 何時不過時

不會過時的部分：

• Retrieval + augmentation 的二段式結構：retrieve 找相關內容、augment 塞進 prompt。這個 framing 跟具體實作無關。
• 語意 vs 字面相似的差異跟互補性。
• Chunking 的 resolution vs context loss 取捨。
• 五類 retrieval 失敗模式的分類。
• RAG / fine-tuning / long context 三條路線的判讀框架。

會變的部分：

• 具體 embedding 模型（nomic-embed、bge、mxbai 等會持續更新）。
• Vector database 選型（Pinecone / Weaviate / Chroma / pgvector 等市場格局會變）。Storage layer 的工程判讀（規模驅動升級、dependency 約束、index 生命週期）見 4.22 RAG storage 工程。
• Framework API（LangChain / LlamaIndex 的具體呼叫方式半年一變）。
• 最佳 chunk size 數字（隨 embedding 模型跟 LLM context 能力演化）。
• Hybrid retrieval / re-ranker 的具體實作（會持續優化）。

當這篇文章「過時」的時候、過時的是參考數字跟工具選型；retrieval 本質、失敗模式、跟其他路線的取捨判讀仍會成立。看到新 RAG 工具時、回到本章的 framing：它解的是哪類問題、它的 chunking 策略是什麼、它如何處理五類失敗模式——能很快判斷它解的問題跟你的場景是否對齊。

下一章

本章預設「有 backend」、沒 backend 的場景（個人 blog、docs site 加 RAG）的 deployment 取捨見 4.16 靜態 / serverless RAG deployment。

下一章：4.2 RAG 檢索增強、看 vanilla RAG 不夠用時的下一層工具箱（query rewriting / HyDE / multi-step / context packing）。把 LLM 從讀資料延伸到對外部世界做事見 4.3 Tool use 原理。Retrieval 把外部內容引入 prompt 本身就是攻擊面（同個機制讓 codebase 內容、外部文件、剪貼簿都能間接影響模型輸出）、IDE 場景的 prompt injection 判讀見 6.3 IDE 場景的 prompt injection。

實務上 vanilla RAG 不夠用的場景比想像多：query-document gap 大、單次 retrieve 拿到的片段不足以回答完整問題、retrieve 結果太多塞爆 context、不該 retrieve 的問題被強制 retrieve。每個場景對應不同的增強技術。本章把這些技術寫成可挑選的工具箱、不是「全部都套」的最佳實踐。

本章目標

讀完本章後你能：

1. 區分 retrieval pipeline 的四個增強層（query 端 / retrieval 端 / context 組裝端 / 控制流端）。
2. 對 query-document gap 選對工具（query rewriting / expansion / HyDE）。
3. 判斷任務需要 multi-step retrieval 還是 single-step 夠用。
4. 設計 retrieve 後的 context packing（dedup、ordering、summarization）。
5. 設計 adaptive retrieval：什麼時候該 retrieve、什麼時候直接答。

Retrieval Pipeline 的四個增強層

Vanilla RAG 是「query → retrieve → prompt」三步。增強分四層、每層解不同問題：

 1┌─────────────────────────────────────────────────┐
 2│ User query                                      │
 3└─────────┬───────────────────────────────────────┘
 4          ↓
 5   [1. Query 端增強]
 6   query rewriting / expansion / HyDE / query decomposition
 7          ↓
 8   [2. Retrieval 端增強]
 9   hybrid search + reranker（見 4.1）
10   multi-step / iterative retrieval
11          ↓
12   [3. Context 組裝端]
13   dedup / ordering / summarization / compression
14          ↓
15   [4. 控制流端]
16   adaptive retrieval（要不要 retrieve）/ self-RAG
17          ↓
18   LLM final answer

判讀 vanilla 不夠時、先定位失敗在哪一層、再選對應工具。盲目把四層全套上、retrieval cost 跟 latency 翻倍、accuracy 不一定有對應收益。

Query 端增強

Vanilla RAG 直接用 user query 做 embedding、但 user query 往往不是「最適合 retrieve 的形狀」。Query 端增強就是在 retrieve 前重塑 query。

Query rewriting

用 LLM 把 user query 改寫成「更接近 document phrasing」的形式。

• 適用：query 口語、document 正式（如 user：「怎麼讓 API 跑快」、document：「latency optimization techniques」）。
• 實作：LLM call、prompt 是「把以下 query 改寫成適合 search 的查詢句、保留語意、改用技術詞彙」。
• 失效：rewriting 把意圖改偏（user 問「為什麼慢」、改成「optimization」、答非所問）。緩解：rewriting 提示要求 preserve intent、retrieve 結果回來後讓 LLM 對照原 query 判斷。
• Cost：每 query 多一個 LLM call、latency 加 200–500ms，屬於 retrieval cost。

Query expansion

不改 query、而是生成多個 query 變體、一起 retrieve、合併結果。

• 適用：query 短、有多種可能解讀（「python」可指語言 / shell / 套件）、單一 query 漏 coverage。
• 實作：LLM 生成 3–5 個變體（同義改寫、不同角度、不同抽象層級）、每個變體獨立 retrieve、結果用 Reciprocal Rank Fusion 合併（RRF 是 RAG 文獻常見的多 retrieval source 合併演算法、不在本指南範圍展開）。
• 失效：變體太發散、混入無關 doc、稀釋了 top-k 的精確度。緩解：限制變體數量（3–5）、合併時對重複出現的 doc 加權。
• Cost：N 倍 retrieval cost、但每次 retrieve 是平行、latency 不是 N 倍。

HyDE（Hypothetical Document Embeddings）

HyDE（4.1 RAG 原理 提過、這裡展開）。核心觀察：query 跟 document 在 embedding 空間的距離、往往比 document 跟 document 之間更遠——這是 query-document gap 的典型表現。

機制：

1. 用 LLM 對 user query 生成「一份假設的答案文件」（hallucinated document）。
2. 對這份假文件做 embedding、不是對原 query。
3. 用假文件 embedding 去 retrieve 真實 document。

為什麼比直接 embed query 好：假文件的 phrasing、長度、結構都更接近 document 分佈、embedding 距離更可靠。重點是 retrieval、不是回答——假文件的事實正確性不重要（hallucinate 出錯誤細節 OK）、但語意 / 領域要落在對的範圍、才能拉回對的 document。

• 適用：query-document gap 顯著的場景（問句 vs 陳述、口語 vs 正式、抽象 vs 技術詞彙）。HyDE 原論文跨多個領域 benchmark 都有提升、不限技術 / 學術。
• 失效：假文件偏離主題（LLM hallucinate 到別的領域）、retrieve 拿到完全不相關的東西。緩解：生成多個假文件取平均 embedding、或用 query + 假文件兩個 embedding 合併 retrieve。
• Cost：每 query 多一個 LLM call（生假文件）、latency 加 500ms–1s。

Query decomposition

把複雜 query 拆成幾個子 query、各自 retrieve、再合併。

• 適用：複合問題（「比較 A 跟 B 在 X 跟 Y 的差異」）、單次 retrieve 拿到的 chunk 不完整。
• 跟 multi-step retrieval 的差異：decomposition 是「一次拆成 N 個 query 平行 retrieve」、multi-step 是「retrieve → 看結果 → decide 下一個 query」。前者快、後者貼近資料。
• 失效：子 query 之間有依賴（後面的 query 要看前面的結果）、平行做不出來、要走 multi-step。

何時用哪個

實務上 query rewriting 跟 HyDE 是首選——cost 低、改 prompt 即可、收益穩。Expansion 跟 decomposition 在特定 query 形態才有顯著收益、預設不開。

Multi-step / Iterative Retrieval

Single-step retrieve 假設「一次 retrieve 拿到所有需要的 chunk」、但多 hop 問題（要從 doc A 找到 entity X、再從 doc B 找 X 的屬性）這個假設不成立。Multi-step retrieval 是 retrieve → LLM 判斷夠不夠 → 不夠就再 retrieve、靠 LLM 的判斷決定 retrieve 路徑。

機制：

 1Initial query
 2   ↓
 3Retrieve round 1 → top-k chunks
 4   ↓
 5LLM：「這些 chunks 夠回答嗎？若不夠、下一個該 retrieve 什麼？」
 6   ↓ (不夠)
 7Generate sub-query 2
 8   ↓
 9Retrieve round 2 → top-k chunks
10   ↓
11LLM 判斷
12   ↓ (夠)
13Final answer

跟 vanilla single-step 的差異：

• 靈活：retrieve 路徑是 query-dependent、不是固定。
• 昂貴：每 round 加一個 LLM call + retrieve、latency 跟 cost 線性疊加。
• 失敗模式：LLM 判斷「不夠」的能力差、無限 retrieve；或判斷「夠了」太樂觀、缺資訊還是答。

對應 4.4 agent 架構 的失敗模式分類：multi-step retrieval 是 agent loop 的特例、context drift / goal drift 一樣會發生。

Multi-hop 推理的核心模式

Multi-hop 問題的典型 pattern：「A 跟 B 有什麼共同點」、需要先 retrieve A 的屬性、再 retrieve B 的屬性、再 compare。Single-step retrieve 不會自動把這兩組 chunk 都抓回來。

Multi-step retrieval 在這類問題上的 accuracy 提升明顯、但 trade-off 是 latency 翻倍以上、cost 翻倍以上。

Multi-step 划算的三條件

三條件全滿足才走 multi-step、任一不滿足就停在 single-step：

• 問題確實 multi-hop：需要 retrieve A → 推 X → retrieve B 的形態。Single-hop 問題硬套 multi-step 純增加 cost。
• Latency budget 允許：每 round 加 1-2 秒、即時 chatbot 場景通常不容許、batch 場景才行。
• 有客觀停止訊號：可用 deterministic check 判斷「夠了」、不是純靠 LLM 自評。沒有停止訊號容易無限 loop。

Context packing：retrieve 拿到後怎麼塞進 prompt

Retrieve 拿到 top-k chunks 後、怎麼塞進 prompt 不是「直接 concat」這麼簡單。Context 組裝端的決策影響最終 accuracy 跟 cost。

Dedup

不同 chunk 可能涵蓋同樣內容（同段文字被多個版本切到、或不同 doc 引用同一個事實）。直接 concat 浪費 context budget。

• 實作：semantic dedup（embedding 距離小於 threshold 視為重複）、或字面 dedup（hash 比對）。
• 失敗：dedup 太激進、誤殺有用 chunk；dedup 不夠、context 塞重複內容。

Ordering

塞進 prompt 的 chunk 順序影響 LLM 注意力。LLM 對 context 開頭跟結尾的注意力比中間強（lost-in-the-middle 現象、深度討論見 4.11 long context engineering）。

• 策略一：relevance ordering：最相關的 chunk 放最前 / 最後、不重要的放中間。Trade-off：依賴 retrieval 的 ranking 準。
• 策略二：document order：按原文順序排（同一 doc 的 chunk 連起來）。Trade-off：保留邏輯流、但相關性散落。
• 策略三：mixed：top-3 放最前、top-4 到 top-K 按 document order 放後面。

Summarization / compression

Retrieve 拿到的 chunk 太多、塞不進 context。兩條路：

• Summarization：用 LLM 把 chunks 摘要成更短的版本、再餵主 LLM。
• Compression：用較小模型抽出 chunks 中跟 query 相關的句子、丟掉無關部分。

Trade-off：

Source attribution

Retrieve 拿到的 chunk 進 prompt 時、要不要標來源，是 retrieval source 的追溯責任問題。

• 標：LLM 可以引用、提升可信度、user 可以 verify。Cost：每 chunk 加幾十 token。
• 不標：context 短、但 LLM 沒法引用、user 沒法追溯。

實務多半標、特別是法律 / 醫療 / 學術場景。

控制流端：要不要 retrieve

Vanilla RAG 對每個 query 都 retrieve、不問該不該。實務上有些 query 不需要外部資料（「現在幾點」「2+2 等於多少」「翻譯這段文字」）、強制 retrieve 反而塞無關 chunk 干擾，也會浪費 retrieval cost。

Adaptive retrieval

讓 LLM 自己決定 retrieve 與否。

• 路線一：predict-then-retrieve：先用小模型 / 規則判斷 query 類型（factual / reasoning / chitchat）、factual 才 retrieve。
• 路線二：self-RAG：LLM 在生成過程中、輸出特殊 token 「我需要 retrieve」、觸發 retrieve、整合結果繼續生成。需要訓練過或 prompt engineered 的模型支援。

判讀 adaptive retrieval 是否有用：

• Query 分佈：若 80% query 都需要 retrieve、adaptive 收益小、固定 retrieve 就好。
• Query 分佈：若 query 一半 chitchat 一半 factual、adaptive 減半 retrieval cost、收益大。

Confidence-based retrieval

LLM 先嘗試直接答、若 confidence 低（self-report 或 logits 機率）、再 retrieve。

• 適用：模型對部分 query 有把握、部分沒、想省 retrieval cost。
• 失敗：模型過度自信、low-confidence 訊號不準、該 retrieve 沒 retrieve。

失敗模式：增強堆疊出反效果

不同層的增強可以堆、但堆過頭會反效果：

• Query rewriting + HyDE + expansion 全開：query 端 noise 過多、retrieve 結果稀釋、accuracy 反降。
• Multi-step + reranker + summarization 全開：每 round latency 累積到使用者不能忍受。
• Adaptive + multi-step 混亂：adaptive 說「不 retrieve」、但 multi-step 又觸發 retrieve、控制流互打。

設計反射動作：先確認 vanilla RAG（hybrid + reranker）的失敗在哪一層、針對性加一個增強、看是否有收益、有再加下一個。不要四層全套。

跟相鄰章節的邊界

• vs 4.1 RAG 原理：4.1 寫 vanilla 骨架跟 production 兩段式（hybrid + reranker），這章寫進一步增強。
• vs 4.11 long context engineering：long context 是「context 大到能塞」、RAG 是「context 不夠要 retrieve」、兩者是不同 regime 的策略。本章 context packing 段的 lost-in-the-middle 是兩個 regime 的共通議題。
• vs 4.7 workflow patterns：multi-step retrieval 是 workflow pattern 在 RAG 場景的特例。

何時過時 / 何時不過時

不會過時的部分：

• 四層增強分類（query / retrieval / context 組裝 / 控制流）的座標。
• 各 query 端技術解的核心問題（用詞落差 / 歧義 / 形態落差 / 複合問題）。
• Multi-step retrieval 跟 single-step 的 trade-off 結構。
• Context 組裝的三個議題（dedup / ordering / compression）。
• 「先 vanilla、再針對失敗加增強」的設計反射。

會變的部分：

• HyDE 等特定方法的最佳實作（隨 embedding 模型演化、效果會變）。
• Self-RAG 等需要訓練的方法（隨 base model alignment 訓練成熟、可能變預設能力）。
• 各家 reranker 跟 embedding 模型的選型（半年一個世代）。

下一章

下一章：4.3 Tool use 原理、從「LLM 讀外部資料」延伸到「LLM 對外部世界做事」。Vanilla RAG 的骨架見 4.1、long context 跟 RAG 的取捨見 4.11、multi-step 跟 reflection 的失敗模式比對見 4.7。

本章寫的是「為什麼需要 tool use」「structured output 怎麼運作」「設計工具時該如何思考副作用」這類跟具體 framework 無關的原理。OpenAI function calling spec、Anthropic tools API、JSON Schema constrained sampling 等具體格式半年一變、不在本章焦點；本章寫的是「換 spec 之後仍然成立」的設計取捨。

本章目標

讀完本章後你能：

1. 解釋為什麼 LLM 需要呼叫工具、純生成解不了什麼問題。
2. 看到 structured output / JSON mode 設定時、知道它在限制 sampling 的哪一層。
3. 判讀「這個模型 tool use 為什麼表現崩」的常見根因。
4. 設計工具時用「副作用範圍 + 信任邊界」思考、不只看「功能對不對」。

為什麼 LLM 需要呼叫工具

LLM 的能力邊界決定了什麼任務「光靠生成解不了」：

• 即時資料：模型訓練後不知道現在發生的事。「查今天天氣」「現在股價」必須拉外部資料。
• 精確計算：模型對大數運算、長乘法、開根號等表現不穩、calculator 一行解決。
• 副作用：把檔案寫到磁碟、發 email、call API——這些是「動作」、文字本身不會觸發磁碟 / 網路 / 外部系統的狀態變更（這也是為何要設計 sandbox 來限制副作用範圍）。
• 持久化狀態：模型本身無狀態、需要外部資料庫 / vector store / file system 儲存跨對話的資料。
• 規模化操作：搜尋一千個 file、處理 batch、跑 SQL——這些是 deterministic、用程式跑比讓模型「逐字模擬」快幾個量級。

Tool use 解的不只是「能力延伸」、更是「把 LLM 跟確定性系統接起來」。沒有 tool use、LLM 只能在自己的文字宇宙裡跑；有了 tool use、它變成可以呼叫資料庫、寫檔、發網路請求的「會說話的 agent」。

這個跨界本身帶來新的問題：模型輸出必須能被工程系統消費。自然語言對人類友善、對程式不友善——下一節要解的就是這個橋。

Structured Output 是 LLM 跨入工程系統的橋

自然語言對下游 parser 不友善：同一個意思有無限種表達、模型可能加 prefix、加 disclaimer、加 markdown 格式、漏關鍵欄位。如果直接 regex 解析、會 case by case 補例外、最終 parser 比 LLM 還複雜。

Structured output 解這個問題：把 LLM 的輸出約束到預定義的結構（JSON、YAML、XML、特定 schema）。實作機制有幾種：

• Prompt-level：在 prompt 裡明確要求「請輸出 JSON、schema 是 X」。靠模型 follow instruction 的能力、不保證 100% 合法。
• JSON mode / response_format：推論伺服器在 sampling 階段（從機率分佈挑下一個 token 的步驟）對每個 token 都套合法 JSON 約束、把不合法的選項機率歸零。
• Grammar-constrained sampling：用 grammar（描述合法語法的形式化規則、實作上常用 BNF 或類似格式）描述合法輸出形狀、推論時逐 token 過濾。可以約束到任意嚴格的結構。
• Function calling 訓練：模型訓練階段就教「該怎麼呼叫工具」、輸出格式內建在模型行為裡。

四種機制的層級不同：prompt-level 是「請模型自律」、JSON mode 跟 grammar 是「sampling 階段強制」、function calling 是「訓練讓模型自然」。越靠近 sampling / 訓練端的機制越穩、但實作越複雜。

理解這個 stack 的價值是：看到「模型輸出 JSON 不穩」時、知道該往哪一層下手。Prompt 寫得清楚不夠的話、要動 sampling 約束；sampling 約束打開了還不穩、要看模型本身的 tool use 訓練覆蓋度。

Function Calling 跟 Free-form Generation 的取捨

「讓 LLM 呼叫工具」有兩條路：

Function calling（模型訓練支撐）：

• 模型訓練時看過大量「使用者問題 → 工具呼叫格式」的範例、知道該怎麼決定要不要呼叫、傳什麼參數。
• 優點：呼叫格式穩、模型「自然」知道何時該呼叫；不需要 prompt 工程寫很長。
• 缺點：受訓練資料分佈影響大、跨模型行為不一致；只支援模型訓練過的協議格式。
• 適合：主流 / 大型模型、想用最少 prompt 工程拿穩定行為。

Free-form + structured output（推論時約束）：

• 寫 prompt 描述工具、用 grammar / JSON mode 約束輸出。
• 優點：跨模型可移植、不依賴模型 fine-tune；支援任意自訂協議格式。
• 缺點：模型可能不知道「何時該呼叫」、需要 prompt 工程描述觸發條件；嚴格約束下品質可能受影響。
• 適合：跨多家 LLM 都要用同一套程式、或用較弱的模型不能依賴 function calling 訓練。

實際應用常混用：主流模型走 function calling、fallback 模型走 free-form。但混用增加維護成本、小型應用挑一條走通常更簡單。

判讀「該用哪一條」的訊號：

• 目標模型主流 + 規模大（>30B）→ function calling、函式呼叫格式通常穩、prompt 工程量最低（注意：Llama 3 70B 等大模型也有 function calling 訓練不均的 case、實際採用前最小驗證）。
• 目標模型小或非主流 → free-form + structured output、跨模型較穩。
• 想跨 LLM 供應商可移植 → free-form + 標準化 schema、不綁特定 provider 的 function spec。

為什麼本地小模型 Tool use 失敗率高

寫 code 場景的本地小模型（7B、14B 級）跑 tool use 經常失敗、表現訊號清楚：

• 呼叫格式錯（JSON 不合法、欄位拼錯）。
• 參數胡亂填（type 不對、value 超出 schema 範圍）。
• 不該呼叫時呼叫（簡單問題硬要叫 calculator）。
• 該呼叫時不呼叫（複雜計算自己算錯）。
• 連續呼叫 loop（一直叫同一個工具不收斂）。

根因有兩層、訓練端跟推論端各佔一半：

訓練端：

• Tool use 範例在預訓練資料中比例低（網路文字主要是「人類對話」、不是「人類 + 工具 trace」）。
• SFT 階段才大量加 tool use 資料、但 SFT 規模相對小、小模型容量有限、學不全。
• 大模型（70B+）SFT 學得進、能 generalize；小模型 SFT 容量不夠、tool use 只在訓練過的 narrow 場景表現好。

推論端（同一個模型在不同推論配置下失敗率不同）：

• Temperature 過高：分佈被拉平、原本合法 JSON 的 token 機率被攤稀、不合法 token 反而被 sample 到。Tool use 場景建議 T ≤ 0.3。
• Context 接近上限：tool schema + 歷史對話 + retrieval result 把 context 用滿、模型在末段對 schema 的記憶衰減、輸出開始飄。
• 多 tool / 巢狀 schema：可選工具超過 5 個、或單個 tool 參數有 3 層巢狀時、小模型 capacity 不足以同時 hold 所有結構約束。

緩解策略：

• 限制 tool 數量：把可用 tool 控制在 3-5 個內、小模型較能 handle。
• 詳細 prompt 描述每個 tool：補模型訓練的不足。
• 強 structured output 約束：用 grammar 強制輸出合法、把不合法輸出的機率在 sampling 階段壓到零。
• 重試 + fallback：第一次失敗的話、加 error feedback 重試；多次失敗 fallback 到「不用 tool」的 free-form。
• 接受能力限制：複雜 multi-step tool use 本地小模型現階段做不好、切到雲端。

判讀「該不該本地跑 tool use」的反射：先看任務的 tool 複雜度，單 tool / 簡單呼叫本地堪用，multi-step / 跨多 tool 通常需要 30B+ 模型，否則失敗率高到不實用。

工具的「副作用範圍」設計

設計給 LLM 用的工具時、除了「功能對不對」、把「副作用範圍 + 可逆性」一起納入設計。

可逆性 spectrum、由低風險到高風險：

每升一級、人類審查的需求越高、agent 的自主度越低。設計工具時、把同樣功能切到不同等級可以大幅降風險：

• 「edit file」分成「propose diff」（等級 2）+「apply diff」（等級 3）、前者自動、後者要確認。
• 「query DB」分成「SELECT」（等級 1）+「INSERT / UPDATE」（等級 4）、前者自動、後者強制確認。
• 「run shell command」是 spectrum 上分佈最廣的工具——讓 LLM 自由跑 shell 等於開放等級 1-5 全部、是常見的 over-permissioned 設計。

這個 framing 跟 OS 的權限模型同概念：least privilege 套用到 LLM tool use。每個工具設計時、先問「最差情況是什麼」、再決定該不該全自動。個人 dev 場景跑本地 LLM 的 tool use / MCP server 權限判讀（檔案系統 / shell / 網路存取邊界、第三方 MCP 信任）見 6.2 tool use 與 MCP server 的權限模型。

結構化輸出的失敗模式

Structured output 用得好的時候、parser 不用寫 error handling；用得不好的時候、會撞到幾種典型失敗：

• Schema 太嚴：模型「失敗」次數多、流程卡住。例如要求 enum 只能是 5 個值、但實際 query 有第 6 種情境、模型只能硬選一個錯的。
• Schema 太寬：模型輸出歧義、下游解析失敗。例如欄位定義成 string、模型可能輸出空字串、null、"N/A"、"none"、各種變體。
• Free-form 跟 structured 混合：要求 JSON 但同時要求「reasoning 寫在 markdown」、模型容易把 markdown 寫進 JSON string 亂掉 escape。
• 巢狀太深：超過 3 層的 JSON 巢狀、模型容易在中間漏 } 或 ,。Grammar-constrained sampling 可解、純 prompt 控制就脆弱。

緩解模式：

• Schema 寬度配合 retry：先用較寬 schema、解析失敗時 retry + 把錯誤訊息餵回模型修正。
• 拆步驟：把複雜 structured output 拆成多個小步驟、每步驟一個簡單 schema、累積成完整結果。
• Few-shot 範例：在 prompt 裡放 3-5 個正確輸出範例、比文字描述 schema 更穩。

何時不需要 Tool use

Tool use 的適用面有邊界、下列情境純生成已足夠、加 tool use 反而增加成本與失敗點：

• 純文字產出任務：寫文章、改寫、翻譯、摘要——輸出本身是文字、不需要副作用、tool use 沒戲。
• 單一回應對話：使用者問問題、模型答問題、不需要去 fetch 外部資料時。模型參數記憶覆蓋的範圍直接回答即可。
• 靠 prompt + 模型內知識能解的任務：簡單 reasoning、code generation 不需要 file I/O、解釋程式碼——這些 tool use 加進去 overhead 大於收益。
• 小型 in-process 應用、tool 數量極少（1-2 個）：可能直接 if-else 比 function calling 更簡單。

判讀反射：先問「不用 tool use 能不能做到」、能做就保留純生成路徑。Tool use 是 LLM 能力延伸、把「加 tool use」當「應用變高級」的標誌會踩到過度設計、single-call 能解的問題包進 tool 是常見浪費。

何時過時 / 何時不過時

不會過時的部分：

• 「LLM 輸出需要被工程系統消費」這個 framing。
• Structured output 是 LLM 跟工程接軌的底層機制。
• Function calling vs free-form 的取捨判讀。
• 訓練資料分佈如何影響 tool use 能力（小模型崩的根因）。
• 副作用範圍 / 可逆性 spectrum 的設計框架。

會變的部分：

• 具體 schema spec（OpenAI function spec → Anthropic tools API → 未來的標準化）。
• 各 framework 的 tool 註冊 API。
• 哪些模型 function calling 訓練得好（會隨新模型更新）。
• Grammar-constrained sampling 的具體實作（llama.cpp / vLLM / Outlines 等會持續演化）。

看到新 tool use 介面或新 framework 時、回到本章的 framing 評估：它支援哪一層的 structured output、訓練過哪些 protocol、對副作用範圍有沒有設計——這些問題的答案決定它在你的場景能不能用。

下一章

下一章：4.4 Agent 架構原理、看 LLM 自主決策的設計取捨。副作用等級跟 HITL 時機怎麼配（pre-act / mid-stream / post-hoc）見 4.5 人機協作拓樸。本地 dev 場景把 tool use 落地到「實際給 wrapper 寫權限」的 hands-on、見 Ollama 改檔案 / 寫程式碼的權限邊界；個人 dev 視角的 tool use / MCP 權限判讀見 6.2。

狀態：大綱階段、部分章節待完成內容。

本模組整理 LLM 應用層的核心原理：模型裝起來、能對話之後、要怎麼跟外部世界互動、怎麼組成可用的工作流、怎麼測它跑得對不對。模組零到模組三建立的是「模型本身」的心智模型；本模組建立的是「模型作為系統元件」的心智模型。

寫這個模組的核心約束是「只寫不會過時的部分」。LangChain、LlamaIndex、aider、Cline 等工具半年一個世代、寫具體 API 半年後就過時；但「retrieval 在做什麼」「為什麼 LLM 需要 tool use」「agent loop 為什麼會失敗」「eval 軸怎麼選」這些原理跨工具世代都成立。本模組刻意避開具體實作教學、把焦點放在跨世代的設計取捨。

章節列表

為什麼這個順序

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

1. 先 4.0 Prompt 技術光譜：within-call 增強是後續所有設計的基底、先建立「prompt 層能做什麼、邊界在哪」的座標。
2. 接 4.1 RAG 原理 + 4.2 RAG 檢索增強：應用層最常見的模式、把「LLM + 外部知識」這個基本組合走過一遍、概念對映到每個讀者都用過的 @codebase 等實務經驗。
3. 再 4.3 Tool use：RAG 是「LLM 讀外部資料」、Tool use 是「LLM 對外部世界做事」、兩條延伸方向自然接續。
4. 再 4.4 Agent 架構 + 4.5 人機協作：把 Tool use 從「單次呼叫」延伸到「自主多步」、自然進入 agent；agent 自主後立刻面對人類介入時機問題。
5. 再 4.6 應用層協議：前面章節涉及 function calling、structured output、MCP 等術語、本章把這三個概念放回正確的層級、避免混為一談。
6. 再 4.7 Workflow + 4.8 Multi-agent：上層整合、把多 LLM call 跟多 agent 組合的設計模式整理成跨 framework 不變的概念地圖。
7. 4.9 起進入 production / 細節：部署資源、衍生產物管理、long context、embedding 內部、eval / benchmarking、tracing、judge——每個都是 production 場景遇到的具體議題。
8. 最後 hands-on：把上述所有原理串成具體案例、看「實際做的時候、原理怎麼落」。

每章可以單獨讀、但若你是第一次接觸 LLM 應用層、照順序讀最不容易迷路。

跟其他模組的分工

適合的讀者

不在本模組內的主題

1. 具體 framework 教學：LangChain、LlamaIndex 等的 API 用法、隨版本變、交給官方文件。
2. 具體 prompt 寫法：跨模型跨任務不可遷移、本模組 4.0 寫的是 prompt 技術 landscape 的結構、不是具體寫法。
3. 具體 agent 工具配置：aider、Cline 等的安裝設定、隨工具版本變、見 1.6 延伸方向 的入口資訊。
4. 訓練 / fine-tuning：屬於改變模型本身、見 3.4 訓練流程。

這個轉變看似只是「加個 loop」、實際上帶來新的設計問題：失敗模式從「答錯」變成「跑偏」、終止條件變成設計重點、人類審查角色從「事後讀」變成「決定何時介入」。本章把 agent 的這些核心問題拆開、寫成跨 framework 都成立的原理。aider、Cline、LangGraph、各家 Agent SDK 等具體工具不在本章焦點——這些半年一個版本、原理層級更穩。

本章目標

讀完本章後你能：

1. 區分「LLM agent」跟「對話 LLM」的本質差異。
2. 畫出 agent loop 的核心結構、看到新 agent 工具能對應到這個骨架。
3. 看到 agent 失敗時、能診斷是哪一類失敗（context drift / 目標漂移 / tool 誤判）。
4. 判斷一個任務該用 agent 還是 single-call。

Agent 跟「對話 LLM」的差異

這個轉變對 LLM 提出新的能力要求：

• 規劃能力（把目標拆成可執行的子步驟）。
• 自我評估能力（判斷子步驟做對了沒）。
• 工具選擇能力（多個工具中挑對的）。
• 上下文管理能力（哪些 context 該帶下去、哪些可以丟）。

這幾項能力是雲端旗艦模型的明顯強項、也是本地小模型的明顯弱項。理解這個能力差距、能解釋為什麼「本地寫 code 用 Continue.dev 還行、本地跑 agent 經常失敗」、不是工具問題、是模型能力 baseline 問題——背後牽涉 function calling 訓練深度、long context prefill 痛點、規劃能力差距。

Agent Loop 的核心結構

所有 agent framework 不管實作怎麼包裝、骨架都是同一個 loop：

11. 感知（Perceive）：讀當前 context、環境狀態、上一步結果
2   ↓
32. 推理（Reason）：思考下一步該做什麼、選工具、決定參數
4   ↓
53. 行動（Act）：呼叫工具、修改環境
6   ↓
74. 觀察（Observe）：解讀工具回應、更新 context
8   ↓
95. 判斷終止：done 還是回 1

這個 loop 跟控制系統的 sense-plan-act 同骨架、本質是「在環境中執行目標導向行為」。Agent framework 的差異主要在每一步的具體實作：

• 感知怎麼編成 prompt？要保留多少歷史？怎麼壓縮 long context？
• 推理用什麼模型？用 chain-of-thought 還是直接決定？要不要再拆成 plan + act？
• 行動支援什麼 tool？怎麼防止破壞性操作？
• 觀察怎麼把工具回應翻成 context？大 output 怎麼摘要？
• 終止怎麼判斷？模型自己說、外部 critic 判斷、step 上限、cost 上限？

理解這個骨架的價值是：看到新 agent framework 時、按這 5 步問就能拆解它的設計取捨；agent 跑出問題時、定位是哪一步壞掉、不是「整個 agent 壞了」。

為什麼 Agent 容易失敗

Agent 跑長時間任務時、失敗率比 single-call 高很多、根因多半落在這三類：

Context drift（上下文漂移）

每輪累積的 context 偏離原始目標、後期 LLM 「忘記」要做什麼。典型表現：開始任務是「修這個 bug」、跑了 10 步後變成「重構這個 module」、再 10 步後變成「rewrite 整個 file」。每一步看起來都合理、累積起來偏離原目標。

根因：

• 模型對 long context 後段的 attention 偏弱（middle-loss 現象、attention 在序列中段表現最弱、見 3.2 attention 機制）。
• 子步驟產出的中間結果會被當成「新目標」、模型沿著中間結果繼續推、原始目標被擠掉。
• 沒有定期重新引用原始目標的機制。

緩解：每隔 N 步把原始目標重新塞回 context、或用外部 critic 比對「現在這步跟原目標的距離」。緩解失敗的下一步：N 步重塞仍漂移、改換較大 model（context 處理能力跟模型大小強相關）；換 model 仍漂移、escalate human 或退回 single-call 拆解任務。

Goal drift（目標漂移）

模型把子目標當主目標、執行完子目標就停下來、原始任務沒完成。例：原任務「實作 + 測試 + commit」、模型實作完就回「我寫完了」、忘了還要測 + commit。

根因：

• 訓練資料中「完成單一任務」的範例多、「完成複雜 multi-step 任務」的範例相對少。
• 子任務做完的「完成感」訊號比「整個任務還沒完」訊號強。

緩解：終止條件用外部驗證（test 跑通、PR 開、commit 進）、不靠模型自己說「完成了」。緩解失敗的下一步：外部驗證仍漏步、加 explicit checklist 在 system prompt、每步要求模型回報 checklist 完成狀態。

Tool result misread（工具結果誤判）

Tool 回 error 或意外結果、模型 hallucinate「成功了」繼續推進、累積錯誤越來越深。例：git push 失敗、模型沒讀 error message、下一步開始寫 PR description、最終提交一個沒推上去的 branch。

根因：

• 模型對「無聲失敗」（tool 回的格式正常但內容是 error）解讀差。
• 部分 framework 對 tool error 處理弱、模型看不到完整 error message。

緩解：tool 設計時 error 用結構化、模型容易識別；agent loop 加 explicit error handling step、看到 error signal 強制 retry 或 escalate。緩解失敗的下一步：retry 仍失敗、強制呼叫 tool 重新讀狀態（如 git status / git log）確認、避免依賴模型對 tool 結果的記憶。

什麼任務適合 Agent vs Single-call

Agent 適用面有邊界、判讀 framework：

適合 agent：

• 目標可分解成明確子步驟。
• 子步驟有客觀驗證訊號（test 跑通、file 寫入、API 200）。
• 單一 call 上下文不足、需要跨多次 tool 互動。
• 失敗可以 recover（agent 跑錯一步可以糾正）。

不適合 agent、改用 single-call：

• 目標模糊探索性（沒有客觀驗證）。
• 緊湊推理任務（拆步驟反而失去全局視角）。
• 簡單可預測的任務（agent overhead 大於收益）。
• 失敗代價極高（agent 跑錯一步很難 recover）。

例子對照：

「先 single-call 試、不夠再 agent」是合理的預設姿勢。Agent 是「特定問題的解法」、客觀驗證訊號 + 可承擔失敗 + 多步必要、三者俱備時用；用錯地方反而增加 cost 跟失敗率。

灰色帶反例：判讀容易誤判的情境

實務上常見的「該用但失敗了」「不該用但成功了」灰色帶、列幾個典型情境跟判讀路徑：

• 目標可分解但子步驟驗證不夠客觀：如「優化這段 code 的可讀性」、可以分成「重構函式 / 加註解 / rename 變數」、但「好不好」沒客觀驗證。Agent 跑完可能改成「自己覺得好」的版本、跟使用者期待差很多。判讀：改用 single-call + 人類審查、或加明確的 lint / formatter 當客觀驗證。
• 失敗代價不對稱：如 production database migration、子步驟清楚（dump → migrate → verify）、但中間失敗可能毀資料。判讀：用 agent 但強制每步要 human-in-the-loop confirm、或拆成 agent 生 migration script + 人類執行兩階段。
• 子步驟之間有強依賴：如「研究某 topic → 寫摘要 → 翻譯」、agent 容易在中間步驟漂掉、累積誤差傳到最後。判讀：強依賴 chain 走 single-call sequential pipeline、不走 agent loop。
• 任務在訓練分佈邊緣：如 niche domain（特定 framework、罕見語言）的 multi-step 任務、模型對該 domain 沒看過 multi-step 範例、容易在 step transition 漏 context。判讀：先 small-scale 驗證 agent 在這個 domain 表現、再決定要不要 scale up。

Termination 條件：怎麼讓 Agent 知道停下來

Agent 的失敗模式很多落在 termination：該停沒停（無限 loop）、不該停就停（漏做子步驟）。Termination 策略選擇是 agent 設計的核心。

主流 termination 機制：

• 明確 done signal：tool 回 special token、模型輸出特定 phrase。最直接、但靠模型自律、不夠 robust。
• Step 上限：跑 N 步強制停。防止無限 loop、但 N 設不對會中途砍掉。
• Cost 上限：累計 token / dollar 超過 cap 強制停。實務防錢被燒掉。
• 目標達成評估：另一個 LLM 或 deterministic check 判斷「任務完成了沒」。最 robust 但 cost 高。
• 外部訊號：test 跑通、檔案被寫入、人類介入。客觀、用在有明確完成判準的任務。
• 人類介入：把 termination 決定交給人類。最保守、適合不可逆任務。

實務上多重 termination 並用：step 上限當 safety net、cost 上限當預算守門、外部訊號當主要判準、人類介入當最終 fallback。

判讀 termination 設計的訊號：

• 沒有 step / cost cap → 失控風險高。
• 完全靠模型自己說「完成」→ 漂移風險高。
• 沒有客觀驗證 → 「成功」訊號可能是 hallucination。

Agent 跟人類審查的協作模型

Agent 的自主程度跟人類審查粒度是 spectrum、不是 binary：

選擇依據主要是「副作用範圍」（見 4.3 工具的副作用範圍設計）：等級 1-2 工具可以 full auto、等級 3 適合 checkpoint、等級 4-5 強制 step-by-step。不同自主度對應的 HITL 時機選擇（pre-act / mid-stream / post-hoc）跟確認流程設計（避免橡皮圖章化）見 4.5 人機協作拓樸。

設計 agent 時、先設想最差情況：「agent 跑偏到底會發生什麼」、再決定該用哪一級協作模型。完全自動跑 production migration 通常是 over-trust、step-by-step 跑 search 通常是 under-trust。個人 dev 把這個協作模型從本機 wrapper 演化到團隊 / production 服務時的 routing 判讀見 6.5 跨進 production 的 routing 中樞。

本地 LLM 跑 Agent 的特殊挑戰

本地 LLM 跑 agent 現階段（2026/5）失敗率明顯高於雲端、根因不只一條：

• Tool use 訓練不足（見 4.3）：小模型 tool use 本來就崩、agent 需要多次穩定 tool use、失敗率複合放大。
• Long context prefill 痛點（見 0.1 為什麼 LLM 生字慢）：Agent 每步都重新 prefill 累積 context、TTFT 越跑越長。
• 規劃能力弱：雲端旗艦在 multi-step planning 上的優勢是公認的；本地 model SFT 規模有限、規劃能力跟雲端有明顯差距。
• 失敗 recovery 弱：模型發現走錯路時、本地模型較容易繼續錯下去、雲端模型較會自我修正。

實務啟示：本地 agent 在 2026/5 屬於「值得試、但不一定留下」的階段。對寫 code 場景的多數使用者、agent loop 的複雜任務交給雲端旗艦更划算；本地保留給 single-call 跟簡單 tool use 場景。在以下條件成立前、雲端仍占優、可作為 tripwire 重新評估：

• 30B+ 本地模型 SWE-bench tool-use 子集達雲端旗艦的 80% 以上、且推論成本可接受
• 本地推論伺服器（Ollama / LM Studio / oMLX）穩定支援 function calling spec、跨框架行為一致
• Apple Silicon Mac 記憶體預算夠跑「主 model + drafter + KV cache」整套 agent loop 不 swap

任一條件達標時、本地 agent 的成本效益就可能翻轉、值得重新評估。

何時過時 / 何時不過時

不會過時的部分：

• Agent vs 對話 LLM 的控制流差異 framing。
• Agent loop 五步骨架（感知 / 推理 / 行動 / 觀察 / 終止）。
• 三類失敗模式（context drift / 目標漂移 / tool 誤判）的分類。
• 「適合 agent vs single-call」的判讀框架。
• Termination 策略的 trade-off。
• 人類審查協作 spectrum。

會變的部分：

• 具體 agent framework（aider / Cline / LangGraph / OpenAI Assistants 等會持續演化）。
• 模型 agent 能力（本地模型會逐步追上雲端、平衡點會移動）。
• Tool ecosystem 跟 MCP server 普及度（見 4.6 應用層協議）。
• 各家 agent 的最佳 prompt / system prompt（屬於 prompt engineering、本指南不展開）。

看到新 agent framework 時、回到本章的 5 步骨架、3 類失敗模式、5 種人類審查協作模型——這些 dimension 不變、看新工具能很快理解它的定位跟限制。

下一章

下一章：4.5 人機協作拓樸、把上文的人類審查 spectrum 落到「人類什麼時候介入、怎麼介入」的三時機設計。應用層協議（function calling / structured output / MCP）的層級差異見 4.6。Agent 對本機資源副作用的個人 dev 權限判讀見 6.2、個人工作流跨進 production 服務時的 routing 中樞見 6.5。

本章寫人機協作的拓樸設計：兩種工作模式（centaur / cyborg）、能力邊界的不規則性（jagged frontier）、三種 HITL 觸發時機、跟 4.4 agent 自主度分層 的對應。這層問題是跨產品 / 跨領域通用、跟具體 framework 無關。

本章目標

讀完本章後你能：

1. 區分 centaur 跟 cyborg 兩種工作模式、判斷哪種適合哪種任務。
2. 描述 jagged frontier、解釋為什麼「全自動」是錯題。
3. 在 pre-act / mid-stream / post-hoc 三個時機點選對 HITL 設計。
4. 設計確認流程、避免人類變橡皮圖章。
5. 把這層設計對應回 4.4 agent 架構 的自主度分層。

兩種工作模式：Centaur 跟 Cyborg

Centaur 跟 cyborg 是兩種人類跟 LLM 共事的姿態。概念起源於 Kasparov 2010 提的 advanced chess（人類 + AI 配合下棋）、HBS / UPenn / Wharton 對 BCG 顧問使用 AI 的研究把這對 framing 套到 knowledge work、觀察到兩種使用模式都存在且各有適用。

Centaur 模式

人類把整段任務委派給 LLM、等結果回來再審。

• 比喻：人馬獸——上半身人、下半身馬、清楚的職責分工。
• 典型場景：「寫一份這個主題的 PPT 大綱、含三個案例、按以下風格、做完給我」、LLM 跑幾分鐘、人類審結果。
• 適合：任務邊界清楚、人類能事先描述完整需求、結果可離線審。
• 失敗模式：任務描述漏細節、LLM 跑偏到沒注意、結果不能用。緩解：先給小範圍試跑、確認方向再放手。

Cyborg 模式

人類跟 LLM 緊密協作、快速來回、人類隨時調整方向。

• 比喻：半機械人——人類跟 LLM 融合、邊做邊改。
• 典型場景：寫 code 時 IDE 內 inline completion、寫文章時邊輸入邊看 LLM 建議、debug 時來回問。
• 適合：任務探索性、需求邊做邊浮現、無法事先完整描述。
• 失敗模式：頻繁打斷思路、context switch 成本高、最後產出反而比 centaur 慢。緩解：對熟悉的任務 cyborg、不熟的任務 centaur。

該用哪種

學生 / 個人開發更常 cyborg 工作、企業自動化更常 centaur 工作。看到一個產品設計時、問「它鼓勵 user 走 centaur 還是 cyborg」、就能判讀它的設計取向。

Jagged Frontier：AI 能力的不規則邊界

Jagged frontier 是觀察 AI 能力分佈的 framing。直覺上「AI 能做的任務」應該是一個 smooth 的連續區、簡單的能做、難的不能。實際上不是——AI 能做的任務分佈是鋸齒狀（jagged）：某些看起來難的任務 AI 做得很好、某些看起來簡單的任務 AI 反而做不好。

這張表是 2024-2025 的觀察、frontier 會隨模型升級漂移——reasoning model + tool use 普及後、算術跟計數已經部分往「能做」那邊移、URL 也可以靠 web search tool 補救。表的價值在於 framing「能力分佈不規則」、不是把具體 4 個 case 當定論。

每個例子背後的失敗機制各不相同：

• 精確算術：靠符號操作、訓練資料中算術佔比小、tokenizer 把數字切成多 token 也加難度。Tool use（呼叫 calculator）能補救。
• 計數：要對 input 做精確 traversal、跟 LLM 的並行 attention 機制不對盤、容易少算多算。對 needle in long context 的失敗模式類比見 needle in haystack 卡。
• 嚴格遵守冷僻格式：format 沒在訓練分佈中見過、模型回退到「我熟悉的格式」。Constrained decoding（見 3.10）能補救。
• 引用真實 URL：模型沒辦法區分「真實存在」跟「看起來合理」、hallucinate 出格式對但內容假的 URL。靠 tool（web search、URL validator）才能驗證。

整體看：能力分佈跟訓練資料分佈、tokenizer 行為、推論機制相關、跟人類直覺的「難易」沒對齊。這給三個實務啟示：

• 不要用「人類直覺難易」推測 AI 能力。試跑、看結果、不要預判。
• 「全自動」是 over-trust 假設：frontier 鋸齒、總有些子任務落在 frontier 外、需要人介入或 tool 補。設計時要假設「有部分子任務 AI 會失敗」、而不是「都會成功」。
• 失敗在 frontier 外的任務、再加 prompt iteration 通常無效：那是模型能力邊界問題、不是 prompt 問題。對應 4.0 prompt 技術光譜 的 systematic vs random error 診斷。

Falling asleep at the wheel：frontier 外的隱性風險

研究發現一個跟 jagged frontier 互動的人類行為模式：人類傾向不分辨任務是否在 frontier 內、對 AI 結果一律低度審查。結果 frontier 內的任務 AI 做得好、人類審不審差別不大；frontier 外的任務 AI 做得差、但人類也沒審出來、產出帶錯送出。

緩解：

• 明確標 frontier：對團隊 / 產品 user 標出「AI 在這類任務可靠 / 不可靠」、不要假設 user 會自己分辨。
• frontier 外的任務強制人類審查：把「該審 vs 不該審」做成 deterministic 規則、不交給 user 自由心證。
• 抽樣審查：即使 frontier 內任務、隨機抽樣審查、偵測 frontier 漂移（模型升級或 prompt 變動後 frontier 可能移動）。

HITL 三種觸發時機

人類介入的時機決定 HITL 的型態。三個時機點各有適用場景：

Pre-act：動作執行前確認

LLM 決定要做某個 action、但 action 真的執行前停下來、給人類審 + approve。

1LLM decides: 「我要刪除 user_id=123 的 record」
2   ↓
3[HUMAN APPROVE?]
4   ↓ (approved)
5Execute deletion

• 適用：不可逆 / 高代價的 action。對應 4.4 agent 的「step-by-step approval」協作模型。
• 失敗模式：approval 流程太頻繁、人類疲勞、最後變橡皮圖章。緩解見後面「避免橡皮圖章化」段。

Mid-stream：執行過程中介入

Agent loop 跑到一半、發現自己不確定、主動停下來問人類。

1Agent: 「我有兩個方案、不確定哪個、請選 A 還是 B？」
2   ↓
3[HUMAN PICKS]
4   ↓
5Agent continues with chosen path

• 適用：任務有多個合理路徑、選擇影響後續策略、不該由 agent 自決。
• 跟 pre-act 的差異：pre-act 是「我準備做 X、你 approve 嗎」（agent 已決定方向）、mid-stream 是「我不確定該做什麼、你決定」（決策權交給人類）。
• 失敗模式：agent 不知道自己該不知道（unknown unknowns）、該問沒問、自己亂走。緩解：在 prompt 內 enumerate 常見的「該問人類」情境、降低 agent 自決的範圍。

Post-hoc：事後申訴 / 校正

Agent 已執行、結果交付、user 看完後可以申訴 / 校正。

1Agent produces result → User sees result
2                              ↓
3                       [USER APPEALS?]
4                              ↓ (yes)
5                       Human reviews + adjusts
6                              ↓
7                       Feedback loop → 改 prompt / fine-tune

• 適用：行為層次的細節調整、評分類任務（如自動打分後 user 申訴）、預先審不可行的場景。
• 跟 pre/mid 的差異：post-hoc 不擋執行流、執行完才介入；前兩者擋在執行前 / 執行中。
• 典型例子：自動評分系統的 appeal 流程——LLM 打分完、user 對分數有異議時、走人類審查、結果不只改這次分數、還回饋進系統改善後續評分。
• 失敗模式：appeal rate 過高（系統信任度差）、或 appeal rate 過低（user 不知道可以申訴 / 申訴成本高）、回饋訊號失真。

三個時機的選擇

實務多重組合：pre-act 擋高代價、mid-stream 處理 agent 的不確定性、post-hoc 收 user 回饋改善系統。三者各自處理不同 risk class、不互斥。

有效 HITL 的四個設計條件

HITL 要真的擋住失敗、不退化成 rubber-stamp approval、設計上要滿足四個條件。每個條件對應一個常見退化模式、可以同時當 checklist 用。

條件一：分級、不同 risk 走不同 gate

高 risk 動作（push、deploy、production change）強制 step-by-step approval；中等 risk（檔案寫入、本機 commit）每 N 步 checkpoint；低 risk（read-only、本機 sandbox）full auto。對應 4.3 tool use 副作用範圍 的等級分類。

對應反例：每個 tool call 都要 approve、不分高低代價、user 每天按 100 次 approve、按到下意識、根本沒看內容。

條件二：approval UI 強制 show diff

審查的具體內容（準備寫的檔案內容、準備執行的 SQL、準備發的 email 草稿）必須在 approval UI 上呈現、user 看得到才能做出有意義的判斷。

對應反例：「approve this action?」按鈕、但 user 看不到 action 的具體內容、只能盲簽。沒有 diff 就沒有審查、不要假裝有審查。

條件三：reject 有明確 fallback 路徑

User reject 後 agent 該怎麼處理（換方案、停下來、escalate）要在設計時確定、不能讓「reject 等同流程斷」。

對應反例：只能 approve、reject 的話 agent 不知道怎麼辦、user 怕 reject 後續流程斷、就一律按 approve、HITL 失去意義。

條件四：approval 訊號要回饋進系統

User 的 approve / reject pattern 進 trace、定期 analyze、把「總是 approve 的動作」自動降級、「總是 reject 的動作」進 prompt 改變 agent 預設行為。

對應反例：User 一直 approve / reject、但訊號沒回饋、agent 下次還是問一樣的問題、user 疲勞累積。

跟 Agent 自主度分層的對應

4.4 agent 架構 列了五種人類審查協作模型：full auto、checkpoint、step-by-step approval、plan first then auto、human-in-the-loop。本章三種 HITL 時機跟這五種協作模型的對應：

選哪一層、看 4.3 工具副作用範圍 等級：等級 1-2 用 full auto + post-hoc、等級 3 用 checkpoint、等級 4-5 強制 step-by-step。

跟 Fuzzy Engineering 典範的關係

0.8 Deterministic vs Fuzzy Engineering 講 fuzzy 邊界要包 deterministic guardrail。HITL 是 guardrail 的一個 case——把人類判斷當成 deterministic check 來包 fuzzy LLM 行為。

判讀 HITL 該存在的訊號：

• 任務的 fuzzy 行為輸出進入不可逆 deterministic 系統（DB write、API call、實體 action）。
• LLM 在這類 boundary 上的失敗代價遠高於 HITL 的人類 cost。
• 沒有可靠的自動 validator（用 LLM judge 風險也太高）。

三者俱備時、HITL 是必要的 guardrail。任一不滿足、可能用 schema validation / output validator / distribution monitoring 替代、不需要人類在 loop 內。

何時過時 / 何時不過時

不會過時的部分：

• Centaur vs cyborg 兩種工作模式的分類。
• Jagged frontier 概念、「全自動」是錯題的論證。
• 三種 HITL 觸發時機（pre-act / mid-stream / post-hoc）的分類。
• 橡皮圖章化的四個反模式跟緩解。
• 跟 agent 自主度分層、fuzzy engineering 典範的對應結構。

會變的部分：

• Jagged frontier 的具體位置（哪些任務在 frontier 內、隨模型能力進步會移動）。
• HITL 的 UI / UX 工具（隨產品 framework 演化）。
• Approval 自動化的程度（更強的 distribution monitoring 可能讓部分 HITL 變得不必要）。

下一章

下一章：4.6 應用層協議、把 function calling / structured output / MCP 三個概念放回正確層級、銜接 agent 跟外部系統的協議設計。Agent 自主度分層完整討論見 4.4、工具副作用範圍見 4.3、HITL 在 fuzzy engineering 中的定位見 0.8。

本章把三者的層級差異拆開、解釋為什麼會出現 MCP、跟它們在實際應用中怎麼組合。具體 spec 細節（OpenAI function calling JSON 格式、Anthropic tools API、MCP server 實作）不在本章——這些半年一變、本章寫的是「換 spec 之後仍成立」的概念結構。

本章目標

讀完本章後你能：

1. 用一句話分別說清楚三者解什麼問題。
2. 看到「啟用 function calling」「設定 structured output」「裝 MCP server」這些句子時、知道在說哪一層。
3. 判斷一個 LLM 應用該用哪幾個組合、什麼情境只需要一部分。
4. 解釋為什麼 MCP 會出現、它複用了哪個成功模式。

三個概念的層級差異

三者正交、可獨立或組合：

• 用 function calling 但不用 structured output：訓練過 tool use 的模型直接呼叫工具、靠模型自律輸出合法 JSON。
• 用 structured output 但不用 function calling：模型沒訓練過 tool use、用 prompt + grammar 強制輸出合法格式。
• 用 MCP 但不用 function calling：MCP 標準化 tool 的暴露方式、模型用什麼機制呼叫不重要。
• 三者都用：function calling 讓模型穩、structured output 約束格式、MCP 提供 tool ecosystem。

把這張表記熟、再看 LLM 應用相關討論、會發現「這個工具支援 function calling」「我的應用要 MCP」這類句子實際在說不同層級。

Function Calling 是模型能力

Function calling 是模型在訓練階段建立的能力：SFT 階段大量「使用者 query + 該呼叫什麼工具 + 傳什麼參數」的範例、讓模型學會「看到 query 知道何時呼叫、怎麼呼叫」。

判讀模型 function calling 強弱的訊號：

• 該呼叫時呼叫、不該呼叫時不呼叫的準確度。
• 呼叫格式合法率（不亂寫 JSON）。
• 參數準確度（type 正確、value 合理）。
• 多工具情況下選對工具的準確度。

這四個訊號跨模型差異大、根因是訓練資料分佈：

• OpenAI / Anthropic 旗艦模型 SFT 階段 function calling 範例大量、表現穩定。
• Llama 3 / Gemma 4 / Qwen3 開源旗艦模型 SFT 階段也加 function calling、但範例量不一、表現有落差。
• 小型開源模型（< 14B）function calling 訓練嚴重不足；tool schema 複雜、多工具選擇、巢狀參數時失敗率高、單一工具 + 平坦 schema 仍可用。

理解這點的價值：看到「這個模型支援 function calling」的宣稱、要追問「訓練範例 coverage 多廣」、不是 binary 的支援 / 不支援、是 spectrum 的訓練深度。

Structured Output 是 Sampling 約束

Structured output 是推論階段的技巧、跟模型訓練無關：在 sampling（從機率分佈挑下一個 token 的步驟）時對每個 token 做 grammar / schema 約束、不合法 token 的機率（logit、token 機率的對數）被歸零、把不合法輸出的可能性壓到不會被 sample。

主要實作機制（適用 / 限制條件附在每項下）：

• JSON mode：每步 sampling 過濾、只允許「保持 JSON 仍合法」的 token。適用：絕大多數 OpenAI 相容 API 都有支援；限制：只保 JSON 合法、不保 schema 對位。
• Grammar-constrained sampling：用 grammar（描述合法語法的形式化規則、實作上常用 BNF 或 Lark grammar）描述完整輸出形狀、推論時逐 token 過濾。適用：需要嚴格自訂格式（DSL、特定 query language）；限制：要伺服器層支援（llama.cpp、vLLM 有、有些雲端 API 沒）。
• Schema-guided：依 JSON Schema 動態決定每步允許哪些 token、強制 enum / type / required 等約束。適用：複雜結構化資料；限制：實作複雜度高、跨伺服器一致性差。
• Logit bias：對特定 token 加 bias、間接引導 sampling、最弱但最靈活的方式。適用：簡單的 token 黑名單 / 白名單；限制：無法保證結構合法。

優勢相對 function calling：

• 跨模型可移植：不依賴模型訓練、任何能跑 sampling 的模型都能上。
• 可任意自訂格式：不限於 OpenAI 或某 provider 的 function spec、想定義什麼 schema 都行。
• 保證 100% 合法輸出：grammar 約束下不可能輸出 invalid JSON。

代價：

• 約束太嚴可能跟模型「自然」輸出衝突：模型本來想說 A、grammar 強制只能說 B、品質會降。
• 實作成本：grammar 解析跟動態 logit mask 在推論伺服器要支援、不是所有 server 都成熟。
• 跟模型訓練脫鉤：模型「不知道」自己被約束、可能還是用沒用 function calling 訓練的「猜測」方式生成。

實務上 structured output 跟 function calling 經常組合：function calling 訓練讓模型「自然」傾向合法輸出、structured output 約束兜底保證「真的合法」。

MCP 是 Server 協議

MCP（Model Context Protocol、2024 年由 Anthropic 提出）是「LLM application ↔ 外部 tool server 之間的標準化協議」。它不在模型能力層、不在 sampling 層、是更高層的架構規範。

要理解 MCP 的定位、回顧 LLM 生態的歷史問題：

每個 LLM application（Cursor、Continue.dev、Claude Desktop、aider 等）要接每個 tool（檔案系統、資料庫、search、自訂 API），都得寫 adapter。N 個 application × M 個 tool 的整合成本是 N×M、生態擴張時成本爆炸。

MCP 把這個成本拆成兩段：

• LLM application 端：實作 MCP client（一次）、之後支援任意 MCP server。
• Tool 端：實作 MCP server（一次）、之後被任意 MCP client 接到。

整合成本從 N×M 降到 N+M。同樣的 ecosystem effect 跟模組零的 OpenAI 相容 API 一樣——標準化中介把生態整合複雜度從乘法降到加法。

MCP 涵蓋的「server 該提供什麼」包括：

• Tool 註冊（這個 server 提供哪些 tool）。
• Tool schema（每個 tool 的參數定義）。
• Tool 呼叫協議（呼叫方式 + 回應格式）。
• Resource 暴露（檔案、文件等讀取資源）。
• Prompt template 共享（reusable system prompt）。

這些都在 protocol 層、模型怎麼用 tool（function calling 還是 structured output）不在 MCP 規範範圍——MCP 不管你模型強不強、它只管「tool 怎麼被暴露」。

為什麼會出現 MCP

MCP 是 LLM application 生態擴張到一定程度後的必然產物。觀察生態演化：

• 2023 早期：每個 LLM app 各自寫工具整合、Cursor 接 file system、Continue.dev 接 codebase、aider 接 git——各自的 adapter 邏輯互不通用。
• 2024 中期：function calling spec 標準化（OpenAI 跟 Anthropic 各自定義）、解決「模型怎麼呼叫工具」、但「工具怎麼暴露給 application」還是各家自己處理。
• 2024 底：Anthropic 提 MCP、把「工具暴露」也標準化、補完 ecosystem 拼圖。

複用 OpenAI 相容 API 的成功模式：

• OpenAI 相容 API：標準化「介面層 ↔ 推論伺服器」、所有 IDE plugin 都接這個。
• MCP：標準化「LLM application ↔ tool server」、所有 application 都接這個。

兩者都採用同個策略：定義最小可用標準、讓生態繞著標準長、所有 player 受益。

MCP 成熟度判讀訊號（不固化在某一個時間點、用這幾個 signal 重新評估）：

• Application 採納範圍：主要 LLM application（Claude Desktop、Cursor、Continue.dev、其他主流 IDE / chat 介面）是否原生支援。
• Tool server catalog 規模：社群維護的 MCP server 數量跟覆蓋範圍（檔案系統、git、Slack、雲端 API 等是否都有現成 server）。
• 本地推論生態接入度：Ollama、LM Studio 等本地伺服器是否原生支援 MCP（或仍以 OpenAI 相容 API 為主）。
• 跨平台一致性：Windows / macOS / Linux 上的 MCP server 行為是否一致、SDK 是否穩定。

四個訊號全部成熟前、MCP 仍處於「主要 application 支援、本地生態剛開始接」的擴張期；訊號逐步達標後、預期會像 OpenAI 相容 API 一樣成為應用層的默認標準。

它跟 function calling 的關係：MCP 提供 tool 的暴露機制、模型怎麼呼叫這些 tool 仍走 function calling（如果模型支援）或 structured output（如果用約束）。三者疊加而非互斥。

三者組合的實際工作流

一個完整 LLM application 的典型 stack：

 1使用者 prompt
 2  ↓
 3LLM application（Claude Desktop / Cursor / 自家應用）
 4  ↓ (MCP client、列出所有可用 tool)
 5MCP server pool（檔案系統 server、git server、自家 API server...）
 6  ↑
 7LLM application 把 tool 描述塞進 prompt
 8  ↓
 9推論伺服器（OpenAI API / Ollama / Anthropic API）
10  ↓ (function calling 訓練 + structured output 約束)
11模型輸出：「我要呼叫 tool X、參數是 Y」
12  ↓
13LLM application 用 MCP 把呼叫送到對應 server
14  ↓
15Server 執行、回應
16  ↓
17LLM application 把結果塞進 context、回到推論伺服器繼續

三者各司其職：

• Function calling 讓模型穩定輸出工具呼叫（訓練支撐）。
• Structured output 兜底保證呼叫格式合法（sampling 約束）。
• MCP 提供 tool ecosystem、application 不用為每個 tool 寫專屬 adapter（架構標準）。

少了任一個都還能跑、但效率跟生態擴展性降一級：

• 沒 function calling、靠 prompt + structured output、跨模型品質不穩。判讀訊號：同 prompt 在不同模型上 tool 呼叫格式錯誤率差 30% 以上。
• 沒 structured output、靠模型自律、偶有失敗。判讀訊號：< 30B 模型在複雜 schema 下 JSON 合法率 < 90%。
• 沒 MCP、每個 application 自己寫所有 tool 整合、ecosystem 不可規模化。判讀訊號：團隊維護 > 5 個 tool adapter、每換 LLM provider 重寫一輪。

常見的組合誤用

三者組合在以下情境會失敗、是判讀「我的應用為何不穩」的常見候選：

• Structured output 蓋過 function calling 訓練：模型訓練時用 Anthropic tools 格式、應用強制套 OpenAI function spec 的 grammar、模型輸出「合法但語意空洞」的 JSON（schema 對、欄位填湊數）。修法：用模型訓練過的 spec、避免在 grammar 層強制改寫。
• MCP server 在 prompt context 撐爆 tool 描述：MCP server 暴露幾十個 tool、每個都有 schema 跟 description、全塞進 system prompt 把 context budget 耗光。修法：dynamic tool selection（先讓 LLM 看「tool 摘要」選相關的、再把選中 tool 的詳細 schema 塞進 context）。
• Function calling + structured output 兩邊 schema 不一致：模型訓練的 function spec 跟 application 套的 JSON schema 欄位不對、模型輸出符合訓練 spec 但不符合 application schema、parser 失敗。修法：grammar 直接從 function spec 生、避免人工維護兩份。
• MCP server 沒做 input validation、prompt injection 通過 tool 結果污染 context：tool 回的內容沒檢查、惡意內容（如 PR 留言中的「請執行 rm -rf」）被模型當指令執行。修法：tool 輸出做 sanitization、可疑內容用 sandbox 標籤包起來、模型 prompt 明確區分「使用者指令」vs「tool 結果」。個人 dev 在自己機器上跑 MCP server 的權限模型（檔案系統 / shell / 網路存取邊界、第三方 MCP 信任）見 6.2；IDE 場景中 codebase / 外部文件 / 剪貼簿等 prompt injection 攻擊面見 6.3。

何時可以只用一部分

三者組合的需求視場景而定：

• 單純 structured 輸出（不呼叫工具）：只需 structured output、不需 function calling / MCP。例：把使用者輸入分類成 enum、輸出固定 schema 的 JSON。
• In-process tool（直接 Python function）：function calling + 簡單 dispatcher、不需 MCP。應用規模小時最直接。
• 跨 application 共用 tool：才需要 MCP。如果你只寫自己用的 app、in-process 比 MCP 簡單。
• 用較弱模型：可能只用 structured output、跳過 function calling。

三者的「最小可用組合」視應用複雜度而定。早期應用通常從 function calling 開始、規模化後加 MCP、品質要求高時加 structured output 兜底——演化路徑不必一步到位。

何時過時 / 何時不過時

不會過時的部分：

• 三個層級的分界（模型能力 / sampling 約束 / server 協議）。
• N×M → N+M 的標準化收益、跟 OpenAI 相容 API 的對應。
• 三者疊加而非互斥的設計取捨。
• 「最小可用組合」的判讀框架。

會變的部分：

• MCP 是 2024-2025 才標準化的協議、未來 5 年可能演化或被新協議補充（協議層更新慢、但會更新）。
• 各家 function calling spec 的具體格式（OpenAI / Anthropic / 開放標準會持續細化）。
• Structured output 的具體實作（grammar engines / JSON mode 會持續優化）。
• 哪些工具有 MCP server 可用（生態 catalog 會擴展）。

看到新協議或新 spec 時、回到本章三層 framing 問：它解的是哪一層？能不能跟既有的另兩層組合？這個問題的答案能很快定位新東西在 stack 中的位置。

下一章

下一章：4.7 Workflow 編排模式、把多 LLM call 組合的設計模式整理出來。

本章寫的是這四種模式的本質、它們的失敗模式、彼此組合的方式、何時退化成 single call 更好。具體 framework 的 DAG syntax / workflow API 不在本章——這些跨 framework 差異大、半年一變、原理層級更穩。

本章目標

讀完本章後你能：

1. 區分四種基本 workflow 模式。
2. 看到一個 LLM application 時、能畫出它的 workflow 結構圖。
3. 判斷一個 workflow 是否該退化成 single call。
4. 識別 workflow 設計常見的反模式。

LLM 應用的本質是多 Call 組合

單一 LLM call 解的問題有上限：

• Context 限制：再大的 context window 也有上限、長文件得切。
• 推理深度：複雜推理拆步驟通常比一次推完更穩。
• Tool 範圍：multi-step tool use 需要多次 call 串起來。
• 多面向評估：同時要管邏輯、風格、合規時、單次 call 容易偏其中一面。

Multi-call 組合擴展能力範圍、代價是每多一個 call 多一份成本：

• Latency：N 個 call sequential 跑是 N 倍 latency；parallel 跑也至少要 max(call latency)。
• Cost：每個 call 的 token 成本累加、N 個 call 是 N 倍 cost。
• 失敗點：每個 call 都可能失敗、N 個 call 串起來成功率是個別成功率連乘。
• 複雜度：error handling、retry、partial success 處理複雜度爆炸。

「設計 workflow」的核心問題不是「能不能拆成多 call」、是「拆成多 call 的收益值不值得這份成本」。Workflow 設計常見的失敗是過早優化（software engineering idiom：「premature optimization is the root of all evil」、在沒有 profiling 證據前就拆結構、複雜度爆炸但無實質改進）、把簡單問題切成複雜 DAG（directed acyclic graph、有向無環圖、描述步驟依賴關係的資料結構）、最終比 single call 慢、貴、難維護、品質卻沒提升。Single call 在「context 塞得下 + 任務不需要外部 tool + 失敗代價低」的情境下仍是最高 ROI 選項。

四種基本模式各自解不同的「為什麼需要多 call」、下面逐個展開。

Pipeline：線性串接

結構：call_1 → call_2 → call_3 → ...、後一個 call 用前一個的 output 當 input。

適合場景：

• 任務有清楚的線性子步驟（萃取 → 摘要 → 翻譯、或 plan → execute → review）。
• 每個子步驟用同個模型最划算（一個 call 撐不下、拆成幾個 call 接力）。
• 子步驟輸出需要中間驗證 / 處理（前一步先過 schema 解析、再餵下一步）。

典型例子：

• Code review pipeline：先 LLM 找問題列表 → 再 LLM 對每個問題寫修改建議 → 最後 LLM 合成 summary。
• 文件處理：原文 → 萃取結構化資訊 → 套用 template → 輸出最終格式。

失敗模式：

• 中間步驟誤差累積：第一步小錯、第二步基於錯誤輸出、第三步累積到完全跑偏。整體錯誤率是個別錯誤率連乘的補集（任一步錯整個 pipeline 錯）。
• 無法檢測前段錯誤：後段沒辦法回頭修正前段、即使發現結果不對。
• 過度拆解：本來 single call 能處理的事拆成 3 步、latency 跟 cost 都暴增。

緩解策略：

• 中間步驟加 validation（schema 解析、簡單 sanity check）、catch 早期錯誤。
• 關鍵 pipeline 加 logging、出問題時能定位是哪一步壞。
• 定期重新評估「這個 pipeline 真的需要拆嗎」、不需要就合併回 single call。

Router：依輸入分流

結構：input → classifier → path A / B / C → output、依分類結果走不同處理路徑。

適合場景：

• 輸入類型多樣、不同類型需要不同處理（簡單 query 用小模型、複雜 query 用大模型）。
• Cost 優化（多數簡單請求走便宜 path、少數複雜請求走貴 path）。
• 功能分流（query 是 search、summarization、還是 code edit）。

典型例子：

• 客服分流：先判斷使用者意圖（查訂單 / 退貨 / 一般諮詢）、再分到對應 specialized agent。
• 模型分流：先 1B classifier 判斷複雜度、簡單問題給本地 14B、複雜問題給雲端旗艦。

失敗模式：

• Classifier 錯判：分流錯了、整個 query 跑進最差 path、結果完全不對。
• Classifier 比下游還複雜：本來 router 是 cost saver、結果 classifier 本身就要強模型、變成多花錢的繞路。
• Path 設計不完整：有些 query 不符合任何 path、router 強塞到某個 path、結果差。

Classifier 設計常用 structured output 強制輸出 enum、避免 free-form 解析；複雜應用可能把 classifier 本身做成 tool use 的特例。

緩解策略：

• Classifier 用較弱模型但加 confidence 判讀、低 confidence 走 fallback path。
• 簡化 path 數量（3-5 個內、保留必要切分即可）。
• 設計「unknown / catch-all」path、不假設所有 input 都能歸類。

Parallel：多 Call 並行、結果合併

結構：input → [call A, call B, call C 並行跑] → 合併 → output、多次 LLM call 同時跑、結果合起來。

適合場景：

• 任務有獨立面向（評估一份 PR 的程式碼品質 / 安全性 / 可讀性、各自一個 call）。
• Ensemble（同個任務跑多次、用 majority vote 提高可靠度）。
• Multi-source retrieval（從不同來源平行拉資料、合起來餵下游）。

典型例子：

• 多面向審查：同份 code 同時跑「邏輯」「風格」「安全」三個 review、合併成總評。
• Ensemble decoding：同個 prompt 用不同 seed / temperature 跑 5 次、majority vote 拿最穩答案。

失敗模式：

• 合併邏輯難設計：parallel 容易、合併難。三個 reviewer 意見不一致時怎麼裁判？多數決還是加權？
• Cost 是 sequential 數倍：parallel 跑 N call 的 cost 是 sequential single 的 N 倍、latency 才有節省。
• 不需要並行：本來 sequential single call 能解的事、parallel 變浪費。
• 不獨立的「平行」：兩個 call 其實依賴彼此、強制 parallel 反而漏訊號。

緩解策略：

• Parallel 前先問：這些 call 真的獨立嗎？依賴的應該 sequential。
• 合併邏輯先設計、再開始 parallel；想清楚怎麼合再進 parallel。
• Cost 監控：parallel 是 cost amplifier、生產環境注意。

Reflection：產出 → 評估 → 修正

結構：產出 → critic 評估 → 依評估修正 → 再評估 → ...、self-improvement loop。

適合場景：

• 任務有客觀評估訊號（test 跑通、規範符合、structured output 合法）。
• 一次產出品質不夠、可以迭代改善。
• 創意任務的「初稿 → 修稿」流程。

典型例子：

• Code 生成 + test 驅動：產出 code → 跑 test → 失敗的話讀 error 修正 → 再跑 test → 直到通過。
• 文章寫作：生成草稿 → critic 模型評論 → 依評論修改 → 再評論 → 直到滿意。

失敗模式：

• Critic 跟 generator 共用 blind spot：兩個都同個模型、有同樣的盲點、reflection 收斂到同樣錯誤位置（如兩個都不認識某個 framework 的 API、再 reflect 也不對）。
• 無限循環：沒有客觀停止訊號、reflection 一直跑、cost 爆掉。
• 過度修正：每次 reflection 都改一點、累積結果變糟（過度 fitting critic 意見）。
• Critic 失職：critic 太寬鬆、什麼都說 OK；或太嚴格、什麼都挑、永遠停不下來。

Systematic vs random error 的關鍵分層：reflection 對 random error 有效（同 prompt 重跑因 sampling 抖動產生的錯誤、多輪重 sample 會收斂）、但對 systematic error 無效（generator 跟 critic 共用 base model、訓練分佈中的盲點不會因重跑消失、loop 收斂到同樣錯誤）。判讀訊號：若 critic 每次給的修正建議都很像、或修完還是同一類錯、就是 systematic error、加 reflection steps 無收益。修法：換不同 base model 當 critic、或加外部驗證（test、lint、schema check）取代 LLM critic。Agent loop 是 reflection 的特例、進階失敗模式分析見 4.4 Agent 架構 的三類失敗段。

緩解策略：

• Critic 用不同模型、或不同 prompt 角度、減少 blind spot。
• Reflection 設 step 上限、即使沒達標也強制停。
• 客觀驗證訊號（test pass、schema 合法、外部 metric）優先於 LLM critic 主觀評估。
• Reflection 對有客觀訊號的任務 ROI 高、對純主觀偏好任務收益有限（critic 的「主觀好壞」跟 generator 同 base 時是同樣 distribution、無法 calibrate）。

四種模式的組合

實際應用通常混用、不是純單一模式：

• Pipeline of routers：第一步先 router 分類、每個 path 內部又是 pipeline。
• Parallel of pipelines：多個 pipeline 平行跑、最後合併。
• Reflection inside pipeline：pipeline 中某幾步用 reflection loop 改進、其他步驟 single call。
• Router into reflection：依輸入複雜度分流、簡單走 single call、複雜走 reflection loop。

複雜應用通常是這四種模式的多層組合。看 LLM application 結構時、能識別出基本模式組合、就能判斷它的複雜度合不合理。

組合的判讀訊號：

• 三層以上嵌套通常 over-engineered、考慮簡化。
• 同個模式重複用很多次（如 5 個 pipeline 串）可能拆得太細。
• 看不出基本模式的 ad-hoc 流程、通常維護困難。

何時退化成 Single Call 更好

判讀「該不該設計 workflow」的反射：先問「single call 能不能解」、不行再考慮拆。

Single call 更適合的訊號：

• 上下文短（< 8K token、塞得進現代 LLM）。
• 推理單純、不需要 multi-step。
• 不需要 tool 或只需一兩個簡單 tool。
• 沒有客觀驗證訊號可用、reflection 沒意義。
• Latency 敏感、不能接受多次 round trip。

「我先寫個 pipeline」常是過早優化：

• 簡單問題切成 5 步、累積誤差大過拆分收益。
• 為了「靈活性」抽象太多、最終比 single prompt 還難改。
• 寫 workflow framework 的成本超過用 raw API 的成本。

實務做法：先 single call baseline、跑半週看品質、不夠用再分解；workflow 設計留到 baseline 不足之後。

Workflow 設計常見的反模式

幾種特別容易踩的反模式：

過度切碎 pipeline

把任務切成 10 步、每步一個 LLM call、累積誤差大、latency 拖長、cost 爆。問題通常是「我以為拆細了品質會好」、實際相反。

訊號：pipeline 步驟超過 5 個、每步輸入輸出量級接近、看不出為什麼需要分。

緩解：能合併的合併、保留必要切點（中間有外部 tool 介入、或需要驗證的步驟）。

Parallel 跑根本不需要並行的事

兩個 call 其實依賴彼此、或本質是同個任務、硬要 parallel。Cost 是 sequential 的 N 倍、品質沒提升。

訊號：parallel 出來的結果合併邏輯複雜、或合併結果跟「直接 sequential 跑」差不多。

緩解：parallel 前問「這幾個 call 真的獨立、結果真的可合併嗎」、不獨立就 sequential。

Reflection 沒有客觀停止條件

Reflection loop 純靠模型自己判斷「夠好了沒」、容易過度修正或無限循環。

訊號：reflection loop 沒有 step cap、沒有外部 metric、純依模型自評。

緩解：每個 reflection loop 都設 step 上限 + 客觀停止訊號（test pass、external check）。

Router classifier 過於複雜

Classifier 本身就需要強模型、變成 router「省 cost」反而花更多。

訊號：classifier 用的模型跟下游 path 同等級或更強。

緩解：classifier 用最便宜的小模型；最便宜小模型若 confidence 不夠、改成「沒有 router、全部走主 path」。

看不出基本模式的 ad-hoc 流程

完全自訂的 control flow、不能對應到任何標準模式、維護困難。

訊號：流程圖畫不出來、新人接手要花一週搞懂、改一個 bug 影響不知道擴散到哪。

緩解：重新設計、強制套用基本模式組合。不能套用通常代表設計過度複雜。

何時過時 / 何時不過時

不會過時的部分：

• 四種基本模式（pipeline / router / parallel / reflection）的結構跟失敗模式分類。
• Multi-call 成本（latency / cost / 失敗點累乘）的本質。
• 「先 single call baseline、不夠再分解」的設計順序。
• 五個常見反模式的識別。

會變的部分：

• 具體 workflow framework（LangGraph、LlamaIndex Workflow、各家 DAG runner）的 API。
• 「最佳化」的具體技巧（caching、batching、streaming 整合）。
• 哪些 framework 對哪種模式支援好（會持續演化）。

看到新 workflow framework 時、回到本章四模式 framing、看它支援哪些模式、有沒有解決常見反模式、能不能跟你的應用場景對齊。Framework 換代不影響這四個模式的本質結構。

下一章

下一章：4.8 Multi-Agent 拓樸、當 single-thread 多 call 不夠用、需要平行專業化角色 / 跨產品 agent 重用時、進入 multi-agent 系統的拓樸設計。

設計完 workflow 後、進 production 還要評估資源、latency / throughput 取捨、observability 三層、降級設計、見 4.9 Production 資源規劃。

本章寫的是 multi-agent 系統的拓樸結構：何時值得從多 call 走到多 agent、flat 跟 hierarchical 兩種拓樸的差異、agent-as-tool 的 MCP 視角、specialization 跟 orchestration overhead 的核心 trade-off。具體 framework（CrewAI、AutoGen、LangGraph 多 agent 等）半年一個世代、本章不寫具體 API。

本章目標

讀完本章後你能：

1. 判斷一個系統該停在 multi-call workflow 還是進入 multi-agent。
2. 區分 flat / hierarchical / agent-as-tool 三種拓樸、各自的適用場景。
3. 估算 specialization gain vs orchestration overhead 的 trade-off。
4. 識別 multi-agent 特有的失敗模式（循環依賴、責任歸屬模糊、context 重複傳遞）。
5. 把 agent-as-tool 對應回 MCP / function calling 的協議設計。

從 Multi-Call 走到 Multi-Agent 的判讀

Multi-agent 跟 multi-call 不是「agent 數量多寡」的差別、是控制流跟責任邊界的差別。

判讀「該走 multi-agent」的四條件（任一不滿足、就留在 multi-call）：

• 角色差異顯著：不同 step 要不同 prompt / model / tool / memory。任一條件同質就退回 multi-call、硬拆成多 agent 只是換個名字、orchestration overhead 純增。
• 跨產品重用：同一個 agent 要被多團隊 / 多場景使用。單一 user / 單一場景的話、寫成函數比 agent 簡單。
• 真正平行 / 動態協作：多個 agent 各做自己的事最後合併、或哪些 agent 參與是 query-dependent。控制流可寫死、step 順序固定時、multi-call pipeline 已足夠。
• 團隊熟悉度足：multi-agent 失敗模式比 multi-call 多、debug 比較難。團隊還在學階段、debug 容易性 > 靈活性、先 stick to multi-call。

「先 multi-call、不夠再 multi-agent」是合理預設姿勢。Multi-agent 是「特定問題的解法」、不是「更高級的設計」。對應 4.4 agent 架構 的「先 single-call、不夠再 agent」反射、層級往上類似。

三種拓樸

Multi-agent 的拓樸結構決定 agent 之間怎麼通訊、誰決定誰做什麼。三種主流拓樸各有適用場景。

Flat 拓樸：all-to-all

所有 agent 同層級、可以互相呼叫、沒有固定 orchestrator。

1       Agent A ─────── Agent B
2         │  ╲          ╱  │
3         │   ╲        ╱   │
4         │    ╲      ╱    │
5       Agent C ─────── Agent D

• 適用：agent 之間平等、任務需要動態協商（agent A 想知道 X、問 B 跟 D、再決定）。
• 典型場景：研究型多 agent debate、模擬多個利害關係人協商。
• 失敗模式：
  • N² 通訊複雜度：agent 多了之後、通訊路徑潛在 N²、實務常較稀疏但難預測、cost / latency 上限不可控。
  • 無權威仲裁：兩個 agent 意見衝突、沒有第三方決定、容易死鎖。
  • 責任歸屬模糊：最終結果是誰決定的不清楚、debug 困難。
• 規模限制：實務上 flat 拓樸超過 5–6 個 agent 就難維護、不推薦大規模。

Hierarchical 拓樸：orchestrator + specialists

一個 orchestrator agent 對外、底下若干 specialist agent、orchestrator 決定 dispatch 給誰、合併結果回 user。

 1              User
 2                │
 3          ┌─────────────┐
 4          │ Orchestrator │
 5          └──┬──┬──┬──┬─┘
 6             │  │  │  │
 7        ┌────┘  │  │  └────┐
 8   Specialist  │  │   Specialist
 9       A    Spec  Spec      D
10             B    C

• 適用：對 user 要單一介面、底下 agent 專業化、orchestrator 知道每個 specialist 的 capability。
• 典型場景：智慧家庭中央控制（user 對 orchestrator 說話、orchestrator 派給 climate / security / energy agent）、複雜客服系統（orchestrator 派給 product / refund / billing 不同 specialist）。
• 失敗模式：
  • Orchestrator 變單點瓶頸：所有請求過 orchestrator、它的 prompt / model 限制整個系統能力。
  • Specialist 之間訊息傳遞要過 orchestrator：增加 latency、容易丟細節。
  • Orchestrator 不知道何時該派誰：需要動態描述 specialist capability、複雜 query 容易 dispatch 錯。
• 變體：multi-level hierarchy（orchestrator 下面還有 sub-orchestrator），實務上 2 層夠用、3 層以上 overhead 大於 specialization gain。

Agent-as-Tool：agent 互通就是 tool call

把每個 agent 包成「另一個 agent 的 tool」、agent A 呼叫 agent B 跟呼叫 weather API 在介面上一樣——都是 tool call。

1Agent A
2  ├── tool: weather_api
3  ├── tool: database_query
4  └── tool: agent_B  ←── 內部其實是另一個 agent loop
5                            └── 它也有自己的 tools
6                                ├── tool: code_executor
7                                └── tool: agent_C

• 適用：agent 之間有清楚的「誰呼叫誰」、不是平等協商；想透過標準協議（function calling / MCP）讓 agent 跨系統重用。
• 典型場景：MCP 的 tool primitive 視角下、agent-as-tool 可以包成 MCP server 暴露、client agent 把它當 tool 用。跨組織 agent 互通常走這個模式。注意 MCP 還有 resources / prompts 另外兩類 primitive、不是所有 MCP server 都是 agent-as-tool。
• 跟 hierarchical 的關係：agent-as-tool 是 hierarchical 的一個實作策略——orchestrator 把 specialist agent 當 tool。差異在於：hierarchical 可能是同進程內的緊耦合、agent-as-tool 走標準協議、跨進程 / 跨組織 / 可替換。
• 失敗模式：
  • 協議的 schema 太薄：agent 跟 agent 之間的 input/output 用 string 傳、丟結構資訊、下游難解析。
  • Cascading failure：下游 agent 失敗、上游 agent 不知道為什麼失敗、誤判繼續。
  • 重複 context 傳遞：每次呼叫都要重新 brief 一次下游 agent、token cost 爆。緩解：下游 agent 自帶 session memory（見 4.19 agent memory architecture）。

三種拓樸的選擇

教材建議的組合：對外是 hierarchical（單一 orchestrator）、orchestrator 內部跟 specialist 通訊走 agent-as-tool 協議（如 MCP tool primitive）、specialist 之間用 flat 模式平等溝通。實務上組合方式因團隊跟產品差異很大、這只是一個合理起點。

Specialization Gain vs Orchestration Overhead

Multi-agent 的核心 trade-off 是專業化收益跟協調成本的拉鋸。

Specialization gain：把 agent 拆細的好處

• 單一責任：每個 agent prompt 短、focus 清楚、debugging 容易。
• 獨立優化：每個 agent 可以用不同 model（具體 routing 思路屬於 4.7 workflow patterns router 模式）、不同 prompt、獨立 eval。
• 重用：同一個 specialist 跨多個系統用、攤平訓練 / 設計成本。
• 平行：獨立 agent 可平行跑、latency 降。

Orchestration overhead：拆細的成本

• Context 傳遞成本：每個 agent 要被 brief、context 重複傳、token 累積。
• Latency 累積：每跳一個 agent 加一個 LLM call 的 latency、跨 agent chain 跟 reflection / multi-step retrieval 一樣會累積。
• 失敗模式多：每個 agent 自己會 drift、agent 之間也會誤判、debug 比 single agent 難。
• 責任歸屬：bug 出現時、定位是哪個 agent 跑偏要看完整 trace。

何時 specialization 划算

兩個容易低估的條件展開：

• 「sub-task 無法獨立評估」為何讓 debugging 困難：當 specialist agent 出問題、若沒有 component-level eval、要從 final output 倒推到「哪個 agent 跑偏」要看完整 trace + 人工讀。Single agent 失敗只需查一個 agent 的 trace、multi-agent 失敗要查 N 個、且 cascading failure 讓 root cause 模糊。要配 sub-task 客觀 eval（如 retrieval recall、抽取 accuracy）才能秒抓問題層、不然 specialization 換來的是更貴的 debug。
• 「orchestration latency 殺死 UX」的量級：每跳一個 agent 加一個 LLM call（雲端旗艦 ~1-3s）。Hierarchical 三層、user query 到回應走 3+ 次 LLM、累積 3-10s。即時 chatbot 的 latency budget 通常 < 3s、multi-agent 容易超標。Workaround：specialist 換小 model、或某些 step 改 deterministic、或退回 single agent + multi-step prompt。

「先粗、再細」的演化路徑

實務多採演化路徑、不是一開始就設計多 agent：

1. Single agent 開始：把整個任務塞一個 agent、看跑得起來嗎。
2. 發現某子任務 systematic 失敗：那個子任務拆出來、變成 specialist agent。
3. 更多子任務需要拆：演化成 hierarchical。
4. 要跨產品重用：把某個 specialist 包成 agent-as-tool（透過 MCP）。

這條路徑的好處是每一步都有具體痛點驅動拆分、不是「為了 multi-agent 而 multi-agent」。

Multi-Agent 特有的失敗模式

除了單 agent 共通的失敗（context drift / goal drift / tool misread、見 4.4）、multi-agent 系統有自己特有的失敗模式：

循環依賴

循環依賴是 agent 呼叫圖在執行期才形成 cycle、靜態 declaration 抓不出來、結果無限執行。例：Agent A 呼叫 B、B 呼叫 C、C 又呼叫 A、形成 cycle。

緩解：

• Call stack 監測、深度超過 N 強制中止。
• Agent 設計時明確 declare 它會呼叫哪些下游 agent、靜態 check 不出 cycle。
• Cycle 的合法用例（如 negotiation）要明確設停止條件。

責任歸屬模糊

責任歸屬模糊是 multi-agent 的 cascading 結構讓 final output 的「哪個 agent 出錯」可能跨多個 agent 累積、debug 時不知道從哪查。

緩解：

• 強制 trace 全部 agent call（見 4.20 LLM tracing）。
• 每個 agent 明確 declare 它對 final output 的貢獻範圍。
• Error 用結構化、明確標出 raised by 哪個 agent。

Context 重複傳遞

Context 重複傳遞是 agent-as-tool 介面下、上游每次呼叫下游都要重新 brief 一遍、缺乏跨 call 的狀態保留、累積成 token cost 跟 latency 雙重浪費。

緩解：

• Specialist agent 自帶 session memory、不用每次 brief（見 4.19 agent memory architecture）。
• 共享 context（global state、reference passing）取代複製。
• Agent-as-tool 協議設計時、輸入 schema 包含「已 brief 過、跳過 intro」flag。

Orchestrator 成為單點認知瓶頸

Orchestrator 是 hierarchical 拓樸的核心、要理解所有 specialist 跟分派邏輯、它的 prompt / capability 限制整個系統上限。換 specialist 容易（介面標準）、換 orchestrator 牽動所有 routing 邏輯（耦合深）。

緩解：

• Orchestrator 的 dispatch 邏輯外部化（不寫在 prompt 內、寫在 deterministic routing rule）。
• Specialist 自己 declare capability（用 OpenAPI / MCP schema）、orchestrator 動態讀、不寫死。

Agent 之間互相 hallucinate

Agent 之間互相 hallucinate 是 agent 介面信任假設失效——上游 agent 給的 input 被視為「可信」、下游沒驗證就執行、hallucinated 內容沿著 agent chain 層層放大。

緩解：

• Agent 之間互通也要走 schema validation（見 0.8 fuzzy engineering guardrail 段）。
• Critical path 加 deterministic check、不只靠 LLM 自評。

跟 MCP / Function Calling 的協議對應

4.6 應用層協議 寫 function calling / structured output / MCP 的層級差異。Multi-agent 拓樸的 agent-as-tool 模式直接對應 MCP：

1Agent-as-tool 在 MCP 視角下的展開：
2
3Client Agent
4  ├── MCP client
5  │     ↓ stdio / SSE / HTTP
6  │   MCP server #1 ← 包了一個 specialist agent
7  │   MCP server #2 ← 包了另一個 specialist agent
8  │   MCP server #3 ← 包了一個外部 service
9  └── 對 client agent 來說、三者介面一致、都是 tool

這個 framing 的價值：目前 agent 跨組織重用的主要工程問題是 agent-as-tool 協議普及度——MCP 是當前的主流選項。當業界對協議 schema 達成共識（無論是 MCP 還是後續演化的標準）、agent-as-tool 拓樸的工程成本會大幅下降。

判讀訊號：自家 agent 想暴露給其他團隊用、預設選 MCP server 包裝、不要設計 proprietary protocol。

何時過時 / 何時不過時

不會過時的部分：

• Multi-call vs multi-agent 的判讀框架（控制流 / 角色 / context / 重用 / 失敗歸屬五維度）。
• Flat / hierarchical / agent-as-tool 三種拓樸的結構分類。
• Specialization gain vs orchestration overhead 的 trade-off。
• 「先粗、再細」的演化路徑反射。
• Multi-agent 特有的五類失敗模式跟緩解。
• Agent-as-tool 對應 MCP 的 framing。

會變的部分：

• 具體 multi-agent framework（CrewAI / AutoGen / LangGraph multi-agent 等會持續演化）。
• MCP server 生態的成熟度（普及度會大幅影響 agent-as-tool 的工程成本）。
• 各家 framework 對 multi-agent 失敗模式的 handling 工具（debugging / tracing tooling）。

下一章

下一章：4.9 Production 部署資源評估、把多 LLM call / 多 agent 系統的 cost / latency / capacity 落到具體 production 評估。Multi-agent 跟 multi-call 的對比基礎見 4.7 workflow patterns、agent 自身的失敗模式見 4.4 agent 架構、MCP 協議層討論見 4.6 應用層協議。

本章寫的是「從本地實驗 → production 該想清楚的維度」、focus 在跨工具世代不變的原理。具體 framework（vLLM、TGI、Triton、SGLang）跟雲端服務（OpenAI / Anthropic / Bedrock）的選型不展開——這些半年一個世代、寫了會過時。本章建立的是「無論用哪套工具、都該回答」的設計取捨清單。

跟 4.1 RAG / 4.3 Tool use / 4.4 Agent 對應「應用怎麼設計」、本章對應「應用怎麼跑」。

本章目標

讀完本章後你能：

1. 列出 production LLM 部署該評估的 6 個 dimension。
2. 解釋 single-user benchmark 為什麼不能直接 extrapolate 到 multi-user 場景。
3. 區分 latency-sensitive 跟 throughput-sensitive 應用的設計差別。
4. 對成本模型（$/request、$/token、$/month）做合理估算。

從本地到 production 的 phase transition

本地 LLM 跑 RAG / MCP 的 baseline（hands-on 章節）：

Production 場景每個維度都跳一個量級：

每個維度跳一個量級的 implication 不是「資源 × 10」、是「全新的失敗模式 + 新的設計取捨」。

維度 1：Concurrent users / Throughput

為什麼這個維度最關鍵

本地 single-user 的 baseline 數字（hands-on 紀錄的 RAM / latency）在 multi-user 場景下幾乎無法 extrapolate、根因是資源爭用會放大原本看不到的成本：

• 100 個 user 同時送 request → 不是「同樣 latency × 100」、是「queueing + memory contention + GPU 排隊」、單個 user 的 latency 可能漲 10×
• 同樣 model 服務 N 個 user → KV cache 占用要乘以 N、單卡 GPU 在容量限制下可能裝不下
• Single-user 「200 ms latency」可能 production 變「p99 5 秒」

Key concept：batching

Batching 跟 KV cache 設計讓 GPU 能多 user 的 request 一次 forward pass、是 production inference server 的核心優化。但 batching 也帶取捨：

• 靜態 batching：等湊滿 N 個 request 才跑、提高 throughput、犧牲首字延遲
• 連續 batching（continuous batching）：vLLM / TGI 等用、新 request 動態加入正在跑的 batch、平衡 throughput + latency
• No batching：每 request 獨立跑、latency 低、GPU 利用率差

選 batching 策略主要取決於 latency 跟 throughput 哪個重要：

評估 concurrent throughput

要做的測試（不在本章 hands-on、是 framework）：

1. Single-user baseline：measure single request 在 idle server 上的 latency
2. N-user load test：用 k6 / vegeta / 自寫 async client 跑 1、10、100 個並發 request
3. 觀察 p50 / p95 / p99 latency 隨並發數變化：通常 < N=batch_size 時平、超過 batch_size 後 latency 線性漲
4. GPU memory 飽和點：tokens-in-flight 超過某個量、新 request 開始排隊

實務評估公式：

1Max concurrent users (steady state)
2    = (GPU memory available - model weights) / (per-user KV cache size)

例：H100 80 GB - 31B model 60 GB = 20 GB 可用 / 每 user 平均 200 MB KV cache = 100 個並發 user。

公式的失效條件（用這幾個 signal 判讀公式何時不可信）：

• 變長 context：per-user KV cache 隨 context 長度線性增長、長 context 用戶（10K+ tokens）的 KV cache 是短 context 用戶的 5-10 倍、用平均值會嚴重低估。修法：依 P95 context 長度估、不用 average。
• Prefix cache 啟用：vLLM、TGI 等用 prefix sharing 大幅省 KV cache、實際容量比公式高 2-3 倍。修法：跑實測量 prefix cache hit rate。
• Speculative decoding：drafter 跟 target 的 KV cache 都要算進去、每 user 佔用會比 dense baseline 高 10-20%。修法：用 drafter+target 合計算。
• 不同 batching 策略：static batching 上限是「batch_size × 等待時間」、continuous batching 是「平均 in-flight tokens」、不同策略下公式的「per-user」定義不同。

但這是上限、實際還要考慮 latency target。

維度 2：Latency budget

Latency-sensitive vs throughput-sensitive

兩類應用的設計取捨完全不同：

混合應用（如 chat with RAG）有兩段：retrieval（throughput-friendly、可 batch）+ generation（latency-sensitive、要 stream）。兩段獨立優化。

Latency 預算分配

一個 RAG 應用的 p99 latency 是各段加總：

1Total p99 = client → API gateway → retrieval → LLM prefill → LLM decode → response stream
2         ≈ 50 ms      20 ms        50 ms        500 ms       1500 ms      100 ms
3         ≈ 2.2 seconds

如果 p99 budget 是 2 秒、要先確認最大消耗段是哪個：

• 通常 LLM generation 是最大、是優化重心
• Retrieval 在大 corpus 場景可能超過 100 ms、要 index 優化（HNSW、近似 nearest neighbor）
• API gateway 通常可忽略、超過 50 ms 就有 SRE 議題

各段監控分開、把監控拆到各段才找得到 root cause；只看 total latency 會錯失定位線索。

維度 3：Cost model

三種計費單位

雲端 API（OpenAI / Anthropic）幾乎都 $/token、給定 model 不同 price tier。自家跑（vLLM on Lambda Labs / RunPod）是 $/server-hour。

成本估算 worked example

假設應用：

• 1000 active users / day
• 每 user 平均 10 requests / day
• 每 request 平均 1000 input tokens + 500 output tokens
• 用 Claude Sonnet 4.6（假設 $3 input / $15 output per million tokens）

每日 cost：

1total_requests = 1000 × 10 = 10000 / day
2input_tokens = 10000 × 1000 = 10M
3output_tokens = 10000 × 500 = 5M
4daily_cost = 10M × $3/M + 5M × $15/M = $30 + $75 = $105 / day
5monthly_cost ≈ $3150

跑自家 GPU 比較：

1H100 instance: ~$2/hour（以 2026 年 spot price 為例、實際隨雲廠商與當期報價變動）
2H100 monthly = $2 × 24 × 30 = $1440
3若 utilization > 50% 且團隊有 SRE 能力維運、自架較划算
4若 utilization < 30%、或團隊無 GPU 維運經驗、API 較划算

Breakeven 點通常在「持續高 utilization + 團隊有維運能力」——尖峰流量短的應用、或團隊無 GPU 維運經驗、API 更划算（不用養閒置 capacity 跟 SRE 人力）。實際判讀還要加合規 / 資料主權 / vendor lock-in 等非價格因素。

Hidden cost

容易漏算的：

• Egress bandwidth：cloud GPU instance 出流量、AWS / GCP 都 $/GB
• Storage：vector DB / log retention / metric retention
• 失敗 retry：5xx error 自動 retry、token 重算
• Cold start：scale-to-zero 設定、cold start 浪費 5-30 秒 GPU time / 次

維度 4：Storage / Vector DB

本地 RAG demo 用 pickle、production 不行——pickle 不支援並發 read、不支援 update、不支援 partition、必須換 vector database。

Vector DB 的設計取捨

具體選型半年一變、本章不展開。設計時要回答的問題：

1. Corpus 多大？1M 以下 in-memory 就好、1M 以上要 disk-based
2. Update 頻率？每天一次 vs 即時、影響 architecture
3. Latency target？< 50 ms 要 in-memory / HNSW、< 200 ms 用 disk-based
4. 並發 query 量？每秒 100 query 跟每秒 10000 query 設計完全不同

Index 大小成長

從 hands-on 章節 extrapolate：

10M docs 以上、單機（256GB RAM、商用 SSD）放不進 in-memory index、要 sharding + 分散式 index。

維度 5：Observability

Single-user tail log 不夠 production 用。要看的 metric：

Latency metrics

• TTFT (Time to First Token)：user-perceived「響應時間」、streaming 場景關鍵
• TPS (Tokens per second)：generation 速度
• End-to-end latency：含 retrieval + LLM + post-processing
• Per-percentile breakdown：p50 / p90 / p95 / p99——p99 反映最差 user 體驗

Throughput metrics

• Requests per second：API 端 RPS
• Tokens per second（aggregate）：GPU 整體 throughput
• Queue depth：等待 batch 的 request 數量、暴漲表示 overload

Cost metrics

• $ per active user per day：產品經濟學基本盤
• Cost per session：互動式應用單位成本
• Cache hit rate：prompt cache / embedding cache 命中率、直接影響 cost

Quality metrics

• Refusal rate：模型 refuse 回應的比例
• Hallucination rate：（要 reviewer 標）
• User feedback score：thumb up / down

工具：metrics / traces / logs 三層

1Metrics（Prometheus / Datadog / CloudWatch）
2    → time-series、aggregate、適合 alerting
3Traces（OpenTelemetry / Datadog APM）
4    → per-request、可追蹤跨服務 latency
5Logs（structured JSON、推 ELK / Loki）
6    → 詳細 context、debug 用

三層各司其職、各層保留專屬職責：metric 看到 p99 漲、用 trace 找哪個 request 哪段慢、用 log 看那 request 的具體 prompt / response。

維度 6：Reliability / SLA

可預期的失敗模式

Graceful degradation

設計 production LLM 應用、要回答「失敗時降級到什麼」：

在 SLA 承諾下、每個 fallback 路徑都要事前設計、避免出事時臨時決策（早期 prototype / 內部工具可接受 reactive 處理、production 階段不行）。

Capacity planning

簡單公式：

1Required capacity = peak_concurrent_users × per_user_RAM
2                  × overhead_factor (1.3-1.5)
3                  × redundancy_factor (2x for HA)

例：peak 100 並發、每 user ~500 MB KV cache、overhead 1.3、HA 2x → 130 GB GPU memory。一張 H100 不夠、要兩張 A100 80GB 或 H100 + sharding。

跟本地 hands-on 的對照

本地數字是「能跑」的證明、production 數字是「能用」的驗證。本地驗證完 architecture 後、production deployment 該重做 load test、不能 assume 線性 scale。

跨 framework 不變的設計問題

不管你用 vLLM / TGI / Triton / SGLang / OpenAI API、production 設計都要回答：

1. Latency vs throughput：哪個是主要 metric？
2. Batch strategy：static / continuous / per-request？
3. Cost ceiling：$/day budget 多少？超過怎麼處理？
4. Storage：vector DB 規模？update 頻率？
5. Observability：哪些 metric 是 alert worthy？
6. Reliability：failure mode + graceful degradation 設計
7. Capacity：peak + redundancy 需要多少 GPU memory

這 7 個問題回答一致時、framework 選擇通常不是 production 失敗的根因——資源評估跟設計取捨已對齊、framework 多半是配套選項。

何時這篇會過時

不會過時的部分：

• 6 個維度（concurrency / latency / cost / storage / observability / reliability）
• Latency-sensitive vs throughput-sensitive 應用的設計差異
• 三類計費單位的取捨
• Metrics / traces / logs 三層觀測
• Graceful degradation 設計

會變的部分：

• 具體 inference framework（vLLM / TGI / SGLang 等）的 ranking
• 雲端 API price tier
• 哪些 vector DB 主流

新 framework 出來時、回到 6 維度 framework 問：它在哪個維度有突破？對既有設計問題的答案有沒有改變？通常會發現核心問題沒變、只是工具更熟。

跟其他章節的關係

• hands-on RAG/MCP 資源：本地 baseline 數字、本章的 production extrapolation 起點
• 4.1 RAG / 4.3 Tool use / 4.4 Agent：應用層設計、本章是「應用如何跑」的補完
• 0.5 硬體記憶體預算：本地單機 perspective、本章對應 multi-machine production
• 1.7 排錯方法論：本地 trouble-shooting、本章是 production observability 的對照

本章寫的是「source / derived / external 三類產物的判讀框架」、跟「production deployment 怎麼處理 share + reproducibility 取捨」。對應到 hands-on 系列實際遇到的問題——為什麼 RAG demo 的 index.pkl 進 .gitignore、Hugging Face model weights 為什麼不能塞進 repo、prompt template 該怎麼版本管理。

跟 4.9 Production resource planning 對應「production 怎麼跑」、本章對應「production 怎麼版本控制 + 部署」。

本章目標

讀完本章後你能：

1. 用「source / derived / external」三分類判讀任何產物該不該進 git。
2. 看到 .gitignore 設計、能解釋每條規則的邏輯。
3. 在 reproducibility 跟 repo 大小之間做合理取捨。
4. 知道 derived / external 產物該用什麼機制 share（registry、build script、artifact storage）。

三類產物 framework

判讀問題：「刪掉重來、用什麼能 reconstruct 一模一樣？」

• 用人手寫 → source、必須 commit
• 用 build script + source → derived、commit manifest（如 lockfile）不 commit output
• 用 download script + URL → external、commit URL 不 commit content

這個 framework 跨任何技術 stack 都成立（不只 LLM）、但 LLM 應用尤其放大 derived / external 比例。

LLM 應用具體對應

Source（進 git）

Derived（不進 git、但 build path 進 git）

External（不進 git、用 manifest / registry）

External 跟 derived 的差別：external 來自 git 外的 source、derived 來自 git 內的 source。機制上都用同套路徑——manifest 進 git、實際 bytes 存 registry、避免大檔直接進 commit history。

為什麼 derived / external 不該進 git

每條限制有具體技術理由：

Size

Git 設計給 source code（小、純文字、頻繁 diff）。Derived / external 通常大、binary、不適合：

• Git 對 large binary 沒有有效 delta 演算法、每次小改 → 完整 copy 進 history
• Repo size 線性漲、clone 變慢、CI cache 爆炸
• GitHub 等服務有 file size 上限（GitHub 100 MB / file）

實例：scripts/rag-demo/index.pkl 3.7 MB、每次 corpus 改 → 重 ingest → 整檔變。Commit 100 次 = git history 多 370 MB。Clone 痛。

Reproducibility（反直覺）

直覺：「commit derived 保證每個 clone 都拿到一樣的 output」——錯。

實際：

• Derived 跟 build env 綁（Python 3.13 build 的 pickle 在 3.14 不一定能 load）
• Embedding index 跟 model version 綁（pull 不同 model 結果不同）
• 用舊 commit 的 derived 跑在新 env 反而比 rebuild 更脆弱

正確 reproducibility 機制：commit build instruction + lockfile、別人 rebuild 時用同樣輸入產同樣 output。

Update frequency mismatch

Source 改慢、derived 改快。content/ 加一句話、index.pkl 整個重建。如果都進 git：

• 90% 的 commit 是「rebuild artifact」、語意上不是真正的「source change」
• git log 看不出真正 source 改動
• diff review 被 derived noise 淹沒

Cost / Performance

CI / CD pipeline 通常自動 rebuild derived。不 commit 反而：

• Source-only PR 較易 review（沒 generated diff）
• CI build cache 重用、不需從 git 拉 derived
• Deploy artifact registry 跟 git 分離、各自 scale

LLM 應用 .gitignore 設計模式

LLM 應用典型 .gitignore 結構：

# === Source-side build output (derived) ===
# Compiled binaries
bin/
dist/
build/
*.pyc
__pycache__/

# Hugo / static site generators
public/
.hugo_build.lock
resources/

# RAG / vector indexes (regenerable)
scripts/rag-demo/index.pkl
*.pkl
*.index

# Embedding caches
.embedding_cache/
.vector_cache/

# === External-bound (don't commit, use manifest) ===
# Python deps (commit requirements.txt instead)
.venv/
venv/
env/

# Node deps
node_modules/

# Model weights / large files
*.safetensors
*.gguf
*.onnx
*.bin

# Datasets
data/raw/
data/processed/

# === Runtime / Local ===
# Logs
*.log
logs/

# OS / IDE
.DS_Store
.vscode/
.idea/

# Local secrets / API keys
.env
.env.local
*.key

# Temp / cache
*.tmp
.cache/

邊界 case 思考

幾個容易誤判的：

判讀 heuristic：

1這個檔案、半年後 production deploy 時要不要存在？
2├─ 要：source 或 manifest 進 git
3└─ 不要：runtime / 開發環境 only、用 .gitignore

三分類的退化情境

三分類是 default framework、實務上有幾類「該不該 commit 的判讀走兩條岔路」的情境、需要特別判讀：

• Generated client SDK in monorepo：protobuf / OpenAPI spec 產出的 client code 屬於 derived（從 .proto / .yaml 生）、但 monorepo 場景常 commit 進去、目的是「跨語言版本對齊 + CI 不用每次重生」。判讀：若 .proto / spec 改動頻率低 + 跨語言一致性比 build 速度重要、commit；變動頻繁就回到 derived 路徑。
• Jupyter notebook 的 output cell：技術上是 derived（執行 notebook 產出）、但語意上常被視為 source 的一部分（教學、demo、結果展示）。判讀：教學 / 展示 / 帶 figures 的 notebook 通常 commit 含 output；機械化的 batch run / CI notebook 走 derived、用 nbstripout 清掉 output 再 commit。
• Git LFS / git-annex 介於 commit 跟 manifest 之間：把大檔案 commit 進 git 但實際 bytes 存 LFS server、worktree 看起來像直接 commit、metadata 卻是 manifest pointer。判讀：適合「需要在 git history 中追蹤大檔案版本、但不想讓 repo 體積爆炸」的場景（如 game asset、訓練資料集 snapshot）。介於 commit 跟 dvc / S3 manifest 之間的折衷選項。
• Lockfile vs build artifact 的灰色帶：yarn-error.log 算 log（不 commit）還是 derived 但對 debug 重要（commit）？實務上多數選 .gitignore、但若團隊在 CI 失敗時要 reproduce 環境、保留少量 build log 也合理。

判讀原則：三分類給 default、灰色帶用「reproducibility + 變動頻率 + 團隊協作需求」三軸決定具體路徑。

Source / Derived / External 的 share 機制

不 commit 不代表不 share、只是用對的 channel。

Source share = git

直接 clone 即可。

Derived share 三種模式

1. Build script in repo：別人 clone 後跑 script 重建（本 blog 用這條：ingest.py 重建 index）
   • 優點：無外部依賴、self-contained
   • 缺點：每個 clone 都要重跑、累積 compute time
2. Release artifact：把 build output 上傳 GitHub Releases / S3、clone 後下載
   • 優點：clone 快、不用各自 rebuild
   • 缺點：要 maintain release pipeline、artifact 版本管理另立
3. Artifact registry：用 OCI registry、Docker registry、artifact storage（如 GitHub Packages / JFrog Artifactory）
   • 優點：production-grade、跨 team / 跨 org share
   • 缺點：複雜、配 auth、cost

選擇：小專案用 script、中型用 release、大型 / 多人 collaboration 用 registry。

External share = manifest

把「從哪下載 + checksum」commit 進 git、實際 content 不進。常見 manifest format：

Manifest 自己是 source（人寫、進 git）、它指向的 external content 不進 git（用 download script 取回）。

Prompt 跟 config 的版本控制

LLM 應用特有的問題：prompt template 是 source、但 prompt 改變影響行為跟 derived 改變不同。

Prompt + model 是一對組合、行為相依、改一個都要重 test。建議在 commit message / PR description 描述「這個 prompt 改動的 expected behavior change」、用規格層級的 review 對待、勿視為 trivial 小改。

Prompt 跟 evaluation 一起管理

進階做法：每個 prompt 配 evaluation set、commit 在同 PR：

1prompts/
2├── code_review.md           ← prompt template
3├── code_review_eval.json    ← input + expected output pair
4└── code_review_history.md   ← 改動記錄 + 對應 eval score

每次改 prompt、跑 eval、比較 score、進 commit message。這比「改完 push 看看效果」可控很多、是 prompt engineering 的基本姿勢。

Production deployment 的對接

本地 hands-on 跟 production 對應：

成熟的 LLM 應用部署 pipeline：

1Source change → git push
2              → CI triggered
3              → Build derived artifacts (index, container image)
4              → Run evaluation suite (prompt + model behavior tests)
5              → Push artifacts to registry
6              → Deploy with manifest pointing to specific artifact version
7              → Smoke test against production data
8              → Auto-rollback if metrics regress

每一步都要 commit-able 的 manifest。在可審計 / 多人協作 / 有 SLA 承諾的場景、「手動 build 完 ssh 進 prod scp」這種 ad-hoc 流程會破壞 reproducibility、出問題時無法 revert 到具體 build；早期 prototype / 單人專案 / 一次性 demo 可接受 ad-hoc 流程、進入 production 前再改成 manifest-based。Manifest 是 reproducibility 跟 audit 的基礎。

何時這篇會過時

不會過時的部分：

• Source / derived / external 三分類 framework
• 「commit manifest、不 commit content」核心原則
• .gitignore 通用模式
• Reproducibility 來自 build instruction、不來自 commit derived

會變的部分：

• 具體 manifest format（半年一個新 lockfile 格式）
• Artifact registry 主流（OCI / Conda / npm 等都會演化）
• LLM model registry（Hugging Face / Ollama 都會演化）

新 lock 格式 / registry 出來時、回到三分類問：它解的是哪類產物？我能用它 commit manifest 不 commit content 嗎？通常答案 yes。

跟其他章節的關係

• scripts/README.md：本章原理的實作 reference
• Hands-on quickstart：跑通 demo 步驟、為什麼要 rebuild index.pkl
• 4.9 Production resource planning：production runtime 視角、本章是 deployment 視角
• 0.7 隱私資料流原理：什麼可以離開機器、本章是「什麼可以進 git」的 sibling
• 4.22 RAG storage 工程：本章把 embedding index 判為 derived（不進 git、ingest.py 重建）、該章接手 vector index 存進 backend 之後的生命週期管理

本章目標

讀完本章後、你應該能：

1. 區分模型「聲稱 context」、「NIH context」、「實用 effective context」三個層級。
2. 看到 lost-in-the-middle 症狀時、知道怎麼緩解。
3. 對自己工作流的任務、判斷該用 long context 還是 RAG。
4. 設計 prompt 時、把關鍵資訊放對位置。
5. 評估「升級到更長 context 模型」的實際邊際收益。

三層 context 概念：claimed / NIH / effective

讀 model card 看到「128K context」「1M context」時、需要區分：

落差來自：

1. RoPE scaling 是延伸、不是「免費擴展」：訓練多在 8K-32K range、用 RoPE scaling 推到 128K+、實用上會 degrade
2. 訓練資料偏短：trillion-token pretrain corpus 中、極長文件相對稀少、模型對 long context 中段不熟悉
3. Attention 衰減：attention 機制對長距離 token 的注意能力隨距離下降、雖未真正 attention to 0、但「有效訊號」減弱

實務啟示：聲稱 1M context 不代表「能塞 1M 進 prompt 解任務」、實用 effective context 多半是聲稱的 1/4-1/8。

Lost-in-the-middle：long context 的主要失敗模式

Lost-in-the-middle（Liu et al., 2023）的核心發現：模型對 long context 中段內容的 recall 顯著低於開頭與結尾。實測：

1Recall accuracy vs 答案位置（10K context）：
2  位置 0%（開頭）  ：85%+
3  位置 25%        ：70%
4  位置 50%（中段）：40-55%
5  位置 75%        ：65%
6  位置 100%（結尾）：80%+

成因細節見 lost-in-the-middle 卡片。本章聚焦緩解：

1. 關鍵資訊放開頭 / 結尾：system prompt、最新指示放在 prompt 開頭 / 最末段、剛好是 attention 最強的兩處
2. 重要內容重複出現：在 prompt 開頭跟結尾各放一次摘要、提高 recall
3. 避免在中段藏 deeply nested constraint：「請遵守附件中第 47 條規則」這類引用、長 context 中段容易被忽略
4. 拆 prompt 成多輪：把 long context 拆成「load context」+「query」兩輪、第二輪 query 在前一輪結尾、recall 較強

Long context vs RAG：什麼時候該選哪個

兩者解的問題重疊但不完全替代：

判讀流程：

1知識總量 < 你模型的 effective context（見後文表格、典型 7B-14B 約 8-16K、30B+ 約 16-32K）？
2  ├─ 是 → 直接 long context
3  └─ 否 → 知識結構化、retrieval key 明確？
4            ├─ 是 → RAG
5            └─ 否 → 嘗試 hybrid：RAG 把相關段 retrieve 出來 + 放進 long context

注意「effective context」是你模型實際能 reliable 處理的範圍、不是 model card 上聲稱的 128K — 拿 7B 模型塞 16K 知識仍可能踩 lost-in-the-middle。

混用情境：

1. Codebase 理解：codebase 整體用 RAG retrieve、單檔 deep dive 用 long context（讀整個檔案）
2. 文件問答：文件用 RAG retrieve 相關段、塞進 32K context、模型可看到「retrieve 結果 + 自己的對話歷史」
3. 長對話：對話歷史進 long context、新指令在最末段（避免 lost-in-the-middle）

Context 設計策略

具體 prompt 結構建議（適用 long context 場景）：

 1[1. System prompt 開頭]         ← attention 強、放核心指令
 2  你的角色 / 主要任務 / 不變的約束
 3
 4[2. Few-shot examples（若需）]   ← attention 仍強、放示範
 5
 6[3. 大段 context]                ← 中段、可能 lost-in-the-middle
 7  - 把最重要的內容也放這段開頭跟結尾、別只放中間
 8  - 若有多段 context、各段都帶明確 heading
 9
10[4. 當前查詢]                    ← attention 強、放使用者問題
11
12[5. 重述關鍵約束（若需）]         ← 末段、attention 強、再次強調 critical rule

典型反例（容易踩 lost-in-the-middle）：

1[1. 重要約束「使用者付費等級 = premium、回應應該詳細」]
2[2. 100K 文件全文]
3[3. 「請回答上述文件相關問題」]

→ 改成：

1[1. 重要約束（同上）]
2[2. 文件摘要 + 「以下是完整文件、若需細節請參考」]
3[3. 100K 文件全文]
4[4. 重述「使用者付費等級 = premium、提供詳細答案」]
5[5. 「使用者問題：X」]

第二版有兩處可靠出現核心指令、長 context 中段含有完整文件、但模型 recall instruction 時兩處任選一處都行、品質提升。

Reasoning model + long context 的特殊互動

Reasoning models 的 reasoning trace 跟 long context 有兩個衝突點：

1. Reasoning trace 擠 context budget：1000-10000 token reasoning trace 直接吃進 context、本來 effective 32K 的模型可能只剩 22K 給輸入
2. Long thinking traces 自己也踩 lost-in-the-middle：reasoning trace 變長時、reasoning 過程中段也會「忘記前面想到的」

緩解：

1. Reasoning model 配長 context 模型：DeepSeek-R1 distill 64K context 是合理 baseline
2. Reasoning 階段引導模型「定期重述目標」：prompt 加「請每隔幾步重新確認任務目標」
3. 複雜任務拆步：別把整個任務丟給 reasoning model 一輪解、拆成多個 sub-task

量測自己模型的 effective context

不要相信 model card 上的數字、自己跑：

 1# 1. 跑 needle-in-haystack（lower bound、寬鬆指標）
 2# 用 ggerganov/llama.cpp 或 RULER 工具
 3# 看模型在 8K / 16K / 32K / 64K / 128K 各自的 NIH accuracy
 4
 5# 2. 自己工作流的 real-task 評估
 6# 拿實際的長 prompt（如完整 codebase + 任務）
 7# 對不同 context 長度比較輸出品質、找到 degradation 點
 8
 9# 3. lost-in-the-middle 測試
10# 同個 prompt 把關鍵指令分別放在開頭、中段、結尾
11# 對比模型回答準確度

實務上、寫 code 場景的 effective context 通常落在：

升級到更長 context 模型的判讀

讀 model card 看到「context 從 128K 提升到 1M」、判斷對自己的價值：

1. 看 RULER benchmark、不只看 NIH：RULER 有 multi-needle、aggregation、reasoning 等任務、更貼近實用
2. 看 effective context（如 LongBench 數字）：聲稱 1M 但 effective 64K vs 聲稱 200K 但 effective 100K — 後者更有用
3. 看自己任務真實長度：如果你的任務 prompt 多在 8K 內、聲稱 128K → 1M 對你無收益
4. 看推論成本：long context 的 KV cache 跟 prefill 時間都隨長度增加、effective 64K 模型實用上比聲稱 1M 模型更快

何時過時 / 何時不過時

不會過時的部分：

• Claimed / NIH / Effective context 三層概念
• Lost-in-the-middle 的存在跟基本緩解策略
• Long context vs RAG 的判讀框架
• 「關鍵資訊放開頭結尾」的 prompt 設計原則

會變的部分：

• 各模型的聲稱 / effective context 數字（每代會推進）
• Long context 訓練技術（RoPE scaling 變體、long-context fine-tuning 方法會演化）
• Lost-in-the-middle 的減緩進展（可能透過新訓練方法部分解決）
• Benchmark 工具（NIH → RULER → 未來新 benchmark）

下一章

下一章：4.12 Embedding model 內部、看 RAG retrieval 階段背後的 embedding 是怎麼運作。

本章目標

讀完本章後、你應該能：

1. 解釋 embedding model 跟 base LLM 的訓練差異。
2. 看到 MTEB / BEIR 分數時、知道對自己場景的意義。
3. 對自己 domain 選對 embedding model（通用 vs code vs multilingual）。
4. 判斷「需要 fine-tune 自己的 embedding model」的時機跟方法。

Embedding model vs LLM 的訓練差異

兩者底層架構可能類似（都用 Transformer）、但訓練 objective 完全不同：

關鍵理解：不能拿任意 LLM 的最後 hidden state 當 embedding — LLM hidden state 是為「預測下一個 token」優化、不為「相似度比較」優化。要再經過 contrastive learning fine-tune 才能當 embedding model 用。

Embedding model 的典型訓練 pipeline：

 1Stage 1: 從 base model 開始（如 BERT、RoBERTa、Mistral、Llama）
 2   ↓
 3Stage 2: Contrastive pre-training
 4   用大量 weak supervised pair（如 Reddit title-body、StackExchange QA）
 5   InfoNCE loss、batch size 大、hard negative mining
 6   ↓
 7Stage 3: Supervised fine-tune
 8   用標註好的 (query, relevant_doc) pair
 9   來源如 MSMARCO、Natural Questions
10   ↓
11Stage 4（可選）: Task-specific instruction tuning
12   讓模型懂「task description」、可針對不同 retrieval 任務切換
13   代表：bge-large、e5-mistral-7b-instruct

Stage 4 的「instruction-tuned embedding」是 2024 後流行的設計：query 前加「Represent this sentence for retrieving relevant passages:」這類前綴、embedding model 學會依任務調整向量。

選型維度

主流 embedding model 的選型維度：

1. Domain 相符

2. 大小（模型大小 / 向量維度）

3. Context window 上限

不同 embedding model 對單次 embed 的 token 上限不同：

事實查核註：本節所列具體型號（bge-large-en-v1.5、jina-embeddings-v3、nomic-embed-text-v1.5、voyage-3 等）、向量維度、context limit、訓練資料 domain、MTEB / BEIR 排名 — 都是 2026/5 主流版本的估計、各模型升級節奏快、引用前以 MTEB Leaderboard 跟對應 model card 當前狀態為準。

選擇影響 chunking 策略（見 4.1 RAG 的 chunking 段）：短 context embedding 要切細、長 context embedding 可保留更完整段落、但內部 attention 對長段中段仍可能 lost-in-the-middle。

4. Cosine similarity 設計

部分 embedding model 訓練時就 L2-normalized、用 cosine = dot product；部分沒 normalize、要自己處理：

詳細見 vector-norm 跟 dot-product 卡片。

評估：MTEB 跟自己 domain 的對齊

MTEB 是現在挑選 embedding model 最常用的 leaderboard、但要正確讀：

1. 看 Retrieval 子分數、不是 Overall：MTEB 含 8 大類、跟 RAG 最直接相關的是 Retrieval 跟 Reranking
2. 跟自己 domain 對齊：MTEB 通用 corpus、自己 domain 可能跟 MTEB 落差大
3. In-domain benchmark 才是 final test：用自己工作流的真實 query 跟 expected doc、自建小型評估集（如 100-200 對）、看候選 embedding model 的 hit rate / nDCG

In-domain 評估的最小可行流程：

1# 偽代碼
21. 蒐集 50-100 個 query + expected_doc（已知答案的對）
32. 對 candidate embedding models 各跑：
4   - embed 所有 doc（含 expected 跟 distractor、~1000 個 distractor）
5   - embed 每個 query
6   - 算 query-doc similarity、看 expected 是否在 top-5 / top-10
73. 比較 candidate 的 hit_rate@5 / hit_rate@10

跑完這個再決定用哪個 embedding model、比看 MTEB leaderboard 可靠很多。

實務選型的 constraint 優先序

上面四個維度（domain / 大小 / context / cosine 設計）跟 MTEB 評估是「品質軸」— 哪個 embedding model 最能解你的 retrieval 問題。但實際選型時，品質軸之前通常有一組工程 constraint 先砍掉大量選項，剩下的候選才進品質比較。

常見的工程 constraint 依砍選項力度排序：

1. Runtime 可用性：推論伺服器支援哪些模型？Ollama 目前原生支援 nomic-embed-text、mxbai-embed-large、snowflake-arctic-embed 等，但不支援所有 Hugging Face 模型。用 cloud API（OpenAI / Cohere / Voyage）則受 vendor 綁定跟成本約束。這一條通常砍掉最多選項。
2. 體積 / 記憶體預算：個人機器常駐 embedding model 跟 chat model 共用記憶體。137M 的 nomic-embed-text 跟 7B 的 e5-mistral 在記憶體佔用上差一個數量級。
3. 已有驗證基線：團隊或前期 demo 已用某個模型跑過、retrieval 品質已確認可用。換模型要重建 index + 重新驗證，成本不只是 MTEB 分數比較。
4. 向量維度的 storage 成本：維度影響 index 大小（n × d × 4 bytes）跟 brute-force search 延遲。768 維 vs 1024 維在小規模無感，但 100K+ chunks 時差異開始有意義。詳見 4.22 RAG storage 工程。

實務流程是：先用 constraint 1-3 收窄到 2-3 個候選，再跑 in-domain benchmark（上段的 hit rate 流程）做最終決定。直接從 MTEB leaderboard 挑最高分的模型、到實際場景才發現 runtime 不支援或體積太大，是常見的繞路。

何時該 fine-tune 自己的 embedding model

通常不該 fine-tune embedding model — 用現成的 bge-large、jina-v3 已經很好。但下列情境值得評估：

1. Domain 跟通用 corpus 差距大：

   • 醫療 / 法律 / 金融的專業術語、通用 embedding model 對「同義詞」「同概念不同表述」recall 差
   • In-domain term frequency 跟通用 corpus 差距大（如「IRA」在金融 vs 政治語境）

2. In-domain benchmark hit rate 顯著低於通用 benchmark：

   • 用 MTEB 高分模型、in-domain hit rate@5 仍 < 60%
   • 換多個候選 embedding model、所有都類似低分

3. 有足夠 in-domain (query, doc) 對：

   • Fine-tune 需要至少數千對、最好 1-10 萬對
   • 對少於 1000 對的場景、fine-tune 收益通常低於數據增強 / 提升 retrieval pipeline

Fine-tune 流程（詳細）：

Step 1：蒐集 in-domain training data

三種主流形態：

實務多從 positive pair 開始（InfoNCE loss 在 batch 內自動取其他樣本當 negative）、品質提升再進 triplet（hard negative mining）。

Step 2：選 base model

選擇看資料量跟硬體：

選擇原則：base model 在 generic benchmark 越強、fine-tune 後上限越高、但訓練成本越高。

Step 3：Loss 選擇

實務 default：MultipleNegativesRankingLoss + batch size 64-128（越大 negatives 越多、品質越高）。

Step 4：Hard negative mining

純隨機 negative（batch 內其他樣本）容易、但 hard negative（看似相關但實際無關）才能 push 模型品質：

11. 用初版 fine-tuned model 對每個 query 跑 retrieve top-50
22. 對每個 query 的 top-50：
3   - 真正 relevant doc（known positive）→ skip
4   - 其他 → 候選 hard negative
53. 篩 hard negatives（LLM-as-judge 或人工確認真的「看似相關但不對」）
64. 用 (query, positive, hard_negative) 重訓
75. Iterate 2-3 輪

Hard negative 是 embedding fine-tune 品質的關鍵差距 — 沒做的 fine-tune 通常 plateau 早、做了的可超越通用 model。

Step 5：LoRA fine-tune 而非 full fine-tune

跟 LLM fine-tune 一樣、embedding model fine-tune 也用 LoRA：

主流 framework：sentence-transformers + PEFT、Hugging Face Transformers + LoRA library。

Step 6：Evaluate

不只看 training loss、要實測：

11. Build in-domain test set（held-out、跟 training 完全分開）
22. 算 [hit_rate@K](/llm/knowledge-cards/retrieval-recall/)（query 的 expected doc 是否在 top-K retrieval result）
33. 跟「base model 未 fine-tune」對比：
4   - Fine-tune 後 hit_rate@5 提升 ≥ 10 percentage point → 成功
5   - 提升 < 5pp → fine-tune 沒效益、不如優化 retrieval pipeline
64. 確認沒崩通用能力：在 MTEB 跑、看主流 retrieval 任務沒大降

失敗模式

跟 LLM 的整合：retrieval pipeline

完整 RAG pipeline 裡 embedding model 的位置：

 1[Ingestion 階段（離線）]
 2  Documents
 3    ↓ chunking
 4  Chunks
 5    ↓ embedding model
 6  Chunk vectors → 存進 vector DB
 7
 8[Query 階段（線上）]
 9  User query
10    ↓ embedding model
11  Query vector
12    ↓ vector DB ANN search
13  Top-K chunks
14    ↓ (optional) reranking
15  Top-N chunks
16    ↓ augment LLM prompt
17  LLM response

關鍵設計決策：

1. Embedding model 一致性：ingestion 跟 query 必須用同個 model（換 model = 整批 re-embed）；chunk vectors 存進 vector DB 之後的 index 結構、維度成本與生命週期見 4.22 RAG storage 工程
2. Chunking 策略對齊 embedding context：見 4.1 RAG chunking
3. Reranking model 通常用 cross-encoder：embedding model 是 bi-encoder（query 跟 doc 分開 embed）、reranker 是 cross-encoder（query + doc 一起算）、品質更高但慢、適合在 top-50 → top-5 之間做 reranking
4. Hybrid retrieval：BM25（字面）+ embedding（語意）混用、用 RRF（Reciprocal Rank Fusion）合併、是 production 常見配置

本地 vs 雲端 embedding

寫 code 場景的判讀：

• codebase 內部 RAG（NDA / 機密 code）：本地 embedding 必選
• 個人開源專案 RAG：本地 embedding 是合理 default、簡單、free
• 公司內部 RAG（需高品質、量大）：評估 voyage-3 / OpenAI v3 vs 本地 bge-large
• 產品級 production RAG：通常雲端 API + 自己 fine-tune 的 embedding（最佳品質）

何時過時 / 何時不過時

不會過時的部分：

• Contrastive learning 是 embedding model 的核心訓練 paradigm
• MTEB 作為通用 embedding 評估的角色
• 「跟自己 domain 對齊」的 in-domain benchmark 必要性
• Bi-encoder vs cross-encoder 的分工（retrieval vs reranking）
• Hybrid retrieval（BM25 + embedding）的設計

會變的部分：

• 具體 embedding model（bge → bge-v2 → …、jina-v3 → v4 → …）
• MTEB leaderboard 排名（每月變）
• Instruction-tuned embedding 的 prompt format（標準化中）
• Embedding model 的 context window 上限（推升中）
• Long-context embedding 的研究（如 ColBERT-style late interaction）

下一章

沒 backend 的靜態場景（個人 blog / docs site）做 embedding 搜尋的 deployment 選擇見 4.16 靜態 / serverless RAG deployment。

下一章：4.13 Eval 設計座標系、看 eval 三軸八象限 meta 框架（先選軸再選工具）、再進 4.14 Benchmarking 與評估方法論 看具體 benchmark 設計。

本章寫 eval 設計的座標系：三個 binary 軸、八個象限、每個象限對應什麼工具、軸選錯的訊號怎麼識別。這層 framing 是 meta、不是具體 eval 方法——具體方法在 4.14 benchmarking 跟 4.21 LLM-as-Judge。

本章目標

讀完本章後你能：

1. 把任何 eval 需求放到三軸座標、定位象限。
2. 對每個象限選對應的 eval 工具。
3. 識別軸誤選的訊號、避免「工具對、軸錯」的常見坑。
4. 規劃 eval 路線：初期該做哪幾個象限、規模化後再補哪些。
5. 把 eval 設計跟 4.14 benchmarking / 4.20 tracing / 4.21 LLM-as-Judge 串成完整 pipeline。

三軸

Eval 設計的三個正交軸：

軸 1：Objective ↔ Subjective

• Objective：有明確 ground truth、檢驗可以寫成 deterministic check（金額對不對、SQL 跑得通不通、JSON schema 合不合法）。
• Subjective：沒有單一正確答案、需要評分或比較（語氣好不好、解釋清楚不清楚、推薦的 trip 合不合用戶）。

判讀訊號：「能不能用 Python 函數判定對錯」、能 → objective、不能 → subjective。

軸 2：Component ↔ End-to-End

• Component：測單一元件、孤立評估（retrieval 拿對 chunk 沒、tool call 參數對沒、prompt 抽出正確 entity 沒）。
• End-to-End：測完整流程、user 視角結果（user 問題有沒有被解決、訂單有沒有完成、conversation 滿意度）。

判讀訊號：「失敗時你想知道是哪一段壞掉」→ component；「你只在乎最終體驗」→ end-to-end。

軸 3：Quantitative ↔ Qualitative

• Quantitative：產出數字（accuracy / latency / cost / pass rate）、可以追蹤、可以比較、可以 alert。
• Qualitative：產出觀察（error pattern、user 抱怨、reviewer 註記）、無法直接 aggregate、但能引導 hypothesis。

判讀訊號：「結果能算平均嗎」→ quantitative；「結果是讀完才知道」→ qualitative。

三軸的正交性

這三軸是正交的、不是同義詞：

• 「Objective + component + quantitative」典型是 unit test（function 返回對不對）。
• 「Subjective + end-to-end + qualitative」典型是 user 訪談（user 整體滿意度）。
• 中間象限存在多種混合、各有對應工具。

八象限

3 個 binary 軸 = 8 象限。每個象限的常見對應工具：

不是「八個都要做」、是「先看你的問題在哪個象限、用對應工具」。

兩個最容易誤判的象限展開：

Subjective + Component + Quantitative（這個 step 輸出評分）：對應工具列「LLM-as-judge pairwise / rubric、human rating」、但 pairwise 是首選、不是 rubric——pairwise 比較讓 judge 的偏差更可控（兩個答案放在一起比、誰好誰差比較好判）、rubric 容易受 verbosity / position bias 影響。Rubric 留給「需要絕對分數而非相對排序」的場景（如要追蹤絕對品質漂移）。詳見 4.21 LLM-as-Judge 的 bias 緩解段。

Objective + Component + Quantitative（元件對嗎）：這象限最容易做、cost 也最低——deterministic check 配 component test、CI 跑、production trace 隨抽即驗。Production AI 系統若這象限沒覆蓋、bug 永遠靠 user 抱怨才發現、debug 跟 incident review 成本高。對應反例：把這象限的測試交給 LLM judge（見軸誤選一）。

軸誤選的訊號

軸選錯時、工具會給出「看起來合理但其實沒用」的訊號。三個常見軸誤選：

誤選一：用 subjective 工具測 objective 行為

例：訂單金額計算對不對、找 LLM judge 來看「這個金額合理嗎」。

• 問題：金額計算有 ground truth、應該 deterministic check（assert order.total == expected）。LLM judge 對「合理」的判斷有偏差、會放過明顯錯誤、會挑剔正確但不直觀的答案。
• 訊號：你發現自己在寫「judge prompt」描述「什麼樣的金額是合理的」、但其實該行為有客觀標準。
• 修正：把 judge prompt 翻成 deterministic check。

誤選二：用 end-to-end 工具測 component bug

例：整套系統 success rate 從 90% 掉到 80%、追了一週、結果是 retrieval 漏 chunk。

• 問題：E2E metric 告訴你「有問題」、不告訴你「在哪」。Component eval 缺失時、debug 從 trace 倒推、耗時。
• 訊號：incident 後 root cause analysis 經常超過一天、查到的東西其實 component eval 該秒抓。
• 修正：對 critical component（retrieval、tool 調用、parse 階段）加 component eval、production 持續跑。

誤選三：用 quantitative 工具找 qualitative 訊號

例：user 滿意度從 4.2 掉到 4.0、團隊看數字盯一週、不知道發生什麼。

• 問題：Quantitative metric 只告訴你「有變化」、不告訴你「為什麼」。Qualitative 訊號（user 抱怨內容、抽樣 conversation）才能浮現 hypothesis。
• 訊號：團隊看 dashboard 看了很久、卻沒人去讀 actual user feedback。
• 修正：quantitative trigger（指標漂移）、qualitative 跟進（讀樣本、找 pattern）。

Eval 演化路徑

不同階段的 LLM 應用、該優先補哪些象限不同。

階段 0：MVP（沒任何 eval）

問題：「能不能 demo 一下就好」、行為對不對全靠手測。

• 第一個該補的：Objective + End-to-end + Quantitative。最少跑 10 個 representative case、能看「跑得起來率」就好。
• 不該太早做：subjective eval、需要 judge / human rating 的東西。MVP 階段先讓系統穩定運行。

階段 1：有 user 在用

問題：production 偶爾有 bug、user 偶爾抱怨、不知道哪些是 systematic、哪些是 random。

• 第二個該補的：Objective + End-to-end + Qualitative。讀 incident、讀抽樣 trace、找 pattern。
• 第三個該補的：Objective + Component + Quantitative。對 critical component（retrieval / tool call / parse）加 component-level eval、production 跑。
• 不該做：完整 subjective rubric。先把 objective 失敗修了再說。

階段 2：要持續優化品質

問題：objective 部分已經穩、user 抱怨主要在 subjective 層（語氣、helpful 程度、推薦合不合用）。

• 第四個該補的：Subjective + Component + Quantitative。用 LLM-as-judge 給每個 step 評分、做 A/B test 比較 prompt 變動。
• 第五個該補的：Subjective + End-to-end + Quantitative。CSAT、thumbs up/down、appeal rate。
• 要做的：Subjective eval 跟 qualitative review 必須配合進行——quantitative 給出方向、qualitative 給出修法 hypothesis。

階段 3：規模化、跨團隊

問題：多個產品 / 團隊用同一套 LLM infra、eval 要 cross-cutting。

• 要做的：標準化 eval pipeline、把象限 1-7 都 cover、qualitative review 進入 ritual（每週 incident review、每月抽樣 trace 讀）。
• 重點不是「全部都有」、而是「每個象限的 owner 清楚」。

Eval 跟 Trace 的閉環

Eval 不是孤立的——它跟 4.20 LLM tracing 形成閉環：

 1[Production traffic]
 2       ↓
 3   [LLM trace]  ← 每次 call / agent step / tool 都記錄
 4       ↓
 5   ├── 即時 monitoring（latency / cost / error rate）
 6   ├── 抽樣進 eval set（人工標 + LLM judge）
 7   └── failed case 進 regression set（防止改 prompt 又壞同樣 case）
 8       ↓
 9   [Eval pipeline]
10       ↓
11   ├── Component eval（單元件 accuracy）
12   ├── E2E eval（整套 success rate）
13   └── Subjective eval（judge / human rating）
14       ↓
15   [Insights]
16       ↓
17   ├── Quantitative：metric 漂移 alert
18   └── Qualitative：error pattern → hypothesis → 修 prompt / tool / RAG
19       ↓
20   [改動進 production]
21       ↓
22   [回到 production traffic、看 metric 收斂]

Production trace 不只是 debug 工具、是 eval set 的活泉。Trace + eval 閉環的設計細節見 4.20。

跟其他 Eval 章節的分工

讀法建議：先讀本章建立座標系、再依當前痛點往對應章節展開。Subjective eval 痛點 → 4.21；自家 benchmark 設計 → 4.14；production observability → 4.20。

有效 eval 系統的四個設計條件

Eval 系統要持續產生有用訊號、必須滿足四個條件。每個條件對應一個常見退化模式、可同時當 checklist 用。

條件一：Judge 只用在 subjective 軸

LLM-as-judge 留給沒 ground truth 的 subjective 行為（語氣、helpful 程度、解釋清楚）、objective 行為（金額、JSON schema、API 參數）用 deterministic check。Judge 的 cost 比 deterministic check 高 1-2 個數量級、精度反而不如、明顯不划算。

對應反例：「全部 eval 都做成 LLM judge」——judge 被誤用在 objective 行為、cost 翻倍、精度反降。

條件二：每個 metric 有 owner、threshold、action

每個 production metric 都要明確：誰負責看（owner）、什麼數字觸發 alert（threshold）、alert 後做什麼（action）。沒這三項的 metric 是 noise。

對應反例：dashboard 上 50 個 metric 圖、沒人定期看、bug 還是靠 user 抱怨才知道。

條件三：Eval set 跟 production traffic 同步

Production trace 持續抽樣補進 eval set、每季 review eval set 跟 traffic 分佈是否一致。

對應反例：eval set 是兩年前定的、production traffic 已經漂得很遠、eval 通過不代表 user 滿意。

條件四：保留 frozen baseline

Frozen baseline 是把某個特定 prompt + 特定 model 跑 production 一段時間後 freeze 起來、每次新版本跟它比、定期 refresh 並標明時點。漂移看得見才能管理。

對應反例：每次 A/B 都跟「最新版本」比、長期累積漂移完全不可見、「整體變好了沒」無從回答。

何時過時 / 何時不過時

不會過時的部分：

• 三軸座標（objective / component / quantitative 三個 binary 軸）。
• 八象限對應工具的結構分類。
• 三類軸誤選的識別訊號跟修正。
• Eval 演化路徑（MVP → user → 優化 → 規模化）。
• Eval / trace 閉環的設計。
• 有效 eval 系統的四個設計條件。

會變的部分：

• 具體 eval framework（OpenAI Evals、Promptfoo、Braintrust、Langfuse 等會持續演化）。
• LLM-as-judge 的具體 prompt 模板跟 bias 緩解技巧。
• 各 benchmark 的權威性（半年一換）。

下一章

下一章：4.14 Benchmarking 與評估方法論、把座標系落到具體 benchmark 設計。Subjective eval 的工具見 4.21 LLM-as-Judge、production trace 怎麼接 eval 見 4.20 LLM tracing、跟 fuzzy engineering 典範的關係見 0.8（fuzzy 行為的測試本質就是 distribution metric）。

本章是 eval 設計的具體實作層——meta 層的 eval 軸選擇（先看軸再看工具的三軸座標）見 4.13 Eval 設計座標系、subjective eval 的核心工具見 4.21 LLM-as-Judge。三章合起來才是 production AI app 的完整 eval pipeline。

本章目標

讀完本章後、你應該能：

1. 看 model card benchmark 數字、判讀對自己場景的相關性。
2. 區分 capability benchmark（MMLU 等）跟 performance benchmark（tok/s 等）。
3. 跑 llama-bench 量測自己硬體 + 模型的真實速度。
4. 設計 in-house benchmark 評估自己工作流的真實品質。
5. 看到 benchmark 異常數字時、知道可能的陷阱。

Capability benchmarks：衡量模型「會什麼」

LLM benchmarks 卡片列了主流 benchmark 的覆蓋面。本節展開對寫 code 場景最相關的幾個：

Coding benchmarks 的演化

判讀建議：

1. 看 SWE-bench、別只看 HumanEval：HumanEval 早飽和、無法區分前沿模型；SWE-bench 仍有大差距、可信度高
2. HumanEval 90% vs 95% 差異不大：飽和區間的 noise 大、判斷 coding 能力靠 SWE-bench / 真實任務測
3. LiveCodeBench 避免污染：定期出新題、模型訓練 cutoff 後的題目不在 pretrain corpus、更能反映真實能力

事實查核註：本章所列 benchmark 飽和狀態（HumanEval 90%+、MMLU 85%+、GSM8K 90%+）、SOTA 數字（SWE-bench < 60%）、各模型在各 benchmark 的相對排名 — 都是 2026/5 估計、隨新模型推出快速變動、引用前以 Papers with Code 跟 HuggingFace Open LLM Leaderboard 當前狀態為準。

Reasoning benchmarks

判讀：

1. Reasoning model 在 AIME / GPQA 顯著領先 instruct model：這正是 reasoning model 的優勢區
2. MMLU 飽和：85%+ 後差別意義不大、改看 MMLU-Pro
3. GSM8K 接近飽和：90%+、改看 MATH / AIME

Long context benchmarks

判讀：聲稱「128K context」要配 RULER / LongBench 分數才知道實用、見 4.11 Long context engineering。

Performance benchmarks：衡量「跑多快」

跟 capability 並列的另一條軸 — 推論速度：

llama-bench：標準工具

llama.cpp 內建 benchmark 工具：

 1# 基本測試：純 generation 速度
 2llama-bench -m model.gguf -p 512 -n 128
 3# -p 512：prompt 512 token（測 prefill）
 4# -n 128：generate 128 token（測 decode）
 5
 6# 不同 context 長度的影響
 7llama-bench -m model.gguf -p 512,2048,8192 -n 128
 8
 9# 開 flash attention
10llama-bench -m model.gguf -p 512 -n 128 -fa 1
11
12# Speculative decoding 對比
13llama-bench -m target.gguf --draft-model drafter.gguf \
14            -p 512 -n 128 --speculative-draft 5

輸出範例：

1| model                |       size |     params | backend    | ngl |   test |              t/s |
2| -------------------- | ---------: | ---------: | ---------- | --: | -----: | ---------------: |
3| gemma3 31B Q4_K - M  |  18.45 GiB |    31.21 B | Metal      |  99 |  pp512 |    324.21 ± 1.27 |
4| gemma3 31B Q4_K - M  |  18.45 GiB |    31.21 B | Metal      |  99 |  tg128 |     28.43 ± 0.31 |

讀法：

• pp512：prefill 512 token 的 throughput（tok/s）
• tg128：generate 128 token 的 throughput（tok/s、即 tok/s）
• ± 0.31：多次跑的 std deviation、< 5% 是穩定基線

推論成本 vs 品質的 trade-off 矩陣

對自己機器跑 llama-bench 後、可以建一個矩陣：

1                     tok/s 高           tok/s 中           tok/s 低
2品質（HumanEval）
3     高              [Q4 7B coder]      [Q4 14B coder]    [Q4 30B reasoning]
4     中              [Q4 14B instruct]  [Q4 30B instruct]
5     低              [Q4 30B base]      [unused]          [unused]

對應到實際選型：

• 自動補完（高頻、低品質需求）：左上 tok/s 高的小模型
• 對話（中頻、中品質需求）：中段
• 複雜 reasoning（低頻、高品質需求）：右下大 reasoning model

In-house benchmark：自己工作流的真實評估

最重要的 benchmark 是「自己真實任務上的表現」、公開 benchmark 是粗略 filter。

建立 in-house benchmark 的步驟

 11. 蒐集真實案例
 2   - 從過往工作流挑 30-100 個有代表性的任務
 3   - 含「容易任務」「中等任務」「困難任務」三類
 4   - 每個任務記錄 (input prompt, expected output 或評分標準)
 5
 62. 定義評分機制
 7   - Objective（最理想）：unit test、exact match、能機械驗證
 8   - Semi-objective：rubric 評分、人工或 LLM-as-judge
 9   - Subjective（最後手段）：人工 A/B 偏好
10
113. 跑 candidate models
12   - 對每個模型、每個任務都跑、記錄輸出
13   - 注意推論參數一致（temperature、top-p、max_tokens 一樣）
14   - 注意 prompt 一致（chat template、system prompt）
15
164. 評分
17   - Objective：跑 test、算 pass rate
18   - Semi-objective：建 rubric、評分
19   - Subjective：人工 / LLM 評
20
215. 看分佈、不只看平均
22   - 平均 80% 可能來自「20 題滿分 + 80 題 70%」或「100 題 80%」
23   - 看 std、看哪些任務崩、針對性 debug

LLM-as-judge 的注意點

用 LLM（如 GPT-4、Claude）評其他 LLM 是省人力的方法、但有 bias：

1. Verbosity bias：judge 傾向給「答得長」的高分、即使內容沒提升
2. Position bias：A/B 比較時、judge 對 A、B 位置敏感、要做 swap 平均
3. Self-preference bias：judge 模型偏好自己風格的答案
4. Judge 能力上限：judge 模型本身不夠強、評不出兩個強模型的差距

緩解：

1. 用結構化 rubric：給 judge 明確評分標準、不只「哪個好」
2. 多 judge 取共識：用 2-3 個不同 judge model 各評、取一致 / 平均
3. Critical task 仍要人工 review：高 stake 任務不能全靠 LLM-as-judge

常見陷阱跟反例

陷阱 1：訓練資料污染

模型在 benchmark 題目上「看似強」、實際是 memorization：

判讀訊號：

• benchmark cutoff date 之前的 dataset、新模型分數異常高
• 同模型在「同 dataset 變體（rephrase）」上分數顯著低

緩解：用較新出題的 benchmark（如 LiveCodeBench 定期更新）。

陷阱 2：Single benchmark 過擬合

模型廠商針對特定 benchmark fine-tune、benchmark 高但通用能力沒提升：

判讀訊號：

• 在 benchmark A 顯著領先、在 benchmark B（測類似能力）沒差
• 同模型實際使用後評價跟 benchmark 不符

緩解：看多個 benchmark + in-house benchmark。

陷阱 3：Prompt sensitivity

同 benchmark 用不同 prompt 格式、score 差幾個百分點：

判讀訊號：

• model card 報的數字跟自己跑差很多
• 同模型不同 prompt template 結果差距大

緩解：自己跑、用一致的 prompt template；report 時明確標 prompt 版本。

陷阱 4：Sampling 設定不一致

不同模型用不同 temperature / top-p、結果不可比：

判讀訊號：

• 兩篇 paper 用同 benchmark 報不同數字、推論參數不同

緩解：對 reproduction 用 temperature=0 + greedy decoding 確保一致。

Benchmark 之間的關係跟導讀路徑

各 benchmark 在不同階段的角色：

 1研究模型能力（paper 階段）：
 2  HELM / MT-Bench / Chatbot Arena → 通用能力 baseline
 3  MMLU / GSM8K / AIME            → reasoning 能力
 4  HumanEval / SWE-bench           → coding 能力
 5  RULER / LongBench               → long context
 6
 7挑選模型（user 階段）：
 8  Open LLM Leaderboard            → 快速 filter
 9  MTEB（若 RAG）                  → embedding model
10  In-house benchmark              → final 確認
11
12監控模型（production 階段）：
13  自己工作流 KPI                  → 真實品質
14  A/B test                       → 部署前的決策
15  User feedback                  → 持續迭代

何時過時 / 何時不過時

不會過時的部分：

• Benchmark 跟自己任務對齊的必要性
• 訓練污染 / 飽和 / single-task overfit 的陷阱
• LLM-as-judge bias 的存在
• In-house benchmark 是最後 final test
• llama-bench 是量測本地推論的標準工具

會變的部分：

• 各 benchmark 的飽和狀態跟前沿 score
• 主流 benchmark 的選擇（HumanEval → MBPP → SWE-bench → …）
• LLM-as-judge model 的偏好（隨 judge model 更新而變）
• 新 benchmark 出現（特別是 reasoning / long-context 領域）

下一章

下一章：4.15 Vision in coding workflow、把 vision 維度加進 coding 工作流的設計取捨。讀完 4.10、模組四覆蓋了 LLM 作為系統元件的設計取捨（RAG、tool use、agent、應用層協議、workflow、resource planning、long context、embedding、benchmarking、vision）、寫 code 場景需要的應用層概念完整、之後可進入 模組五 PC 獨立 GPU 或 模組六 安全。

本章 framing 重點：教材整體聲明過「不放多模態」、但 VLM 在 coding 工作流的 trigger 已經響（雲端 IDE 普遍整合、本地推論伺服器陸續支援）、重新評估後加入本章。本章聚焦「跨工具世代不變的原理 + 寫 code 場景特有的判讀」、避開「具體 IDE plugin API」這類易過時內容。

本章目標

讀完本章後、你應該能：

1. 解釋 VLM 跟純文字 LLM 在 coding 場景的能力差異。
2. 看到截圖 / mockup / 設計稿時、判斷該用 VLM 還是純文字描述。
3. 對自己硬體預算選擇本地 VLM（Qwen2.5-VL / Llama 3.2 Vision / Gemma 3 Vision）。
4. 估算 VLM 推論的 context budget（image token + text token）。
5. 知道 IDE 整合 VLM 的現狀跟 trigger 訊號（什麼時候該升級到 vision-native workflow）。

Coding 場景的 vision use cases

寫 code 工作流中、有 vision 跟沒 vision 的差距：

判讀反射：任務需要看「整體 visual context」（如 layout 對齊、設計稿 → code）→ VLM 顯著贏；純 OCR（只認字）→ 專門 OCR 工具（Tesseract / PaddleOCR）可能更穩。

VLM 在 coding 場景的失敗模式

VLM 不是萬能、寫 code 場景的常見失敗：

1. 看不清細節：低解析度模式下、截圖中的小字 / 細邊框 / 1px 對齊看不出來；要開高解析度模式 + 高 image token budget
2. OCR 出錯：手寫字 / 模糊截圖 / 特殊字型上錯字、特別是中文 / 程式碼 special character
3. 空間關係推理弱：「左上角的按鈕」「flexbox 第二行第三個」這類描述、VLM 推理仍不穩
4. DPI 跟縮放問題：Retina 截圖、放大縮小、subpixel 等情況、不同 VLM 結果差異大
5. 多張圖比較：比兩張截圖差異、VLM 容易遺漏細節；最好給明確指令「請對比 A、B 兩張圖的 X 元素」

緩解：

• 截圖前裁切到「跟問題相關的區域」、別整個螢幕丟
• 高細節任務開高解析度模式（API 的 detail: high 或本地 VLM 的 min_pixels 設高）
• OCR-only 任務改用專門工具、不靠 VLM

本地 VLM 選型（2026/5）

本地可跑的主流 VLM：

事實查核註：本地 VLM 的推論伺服器支援度（llama.cpp、Ollama、MLX）依模型 / 推論伺服器版本變動很快、引用前以對應 release notes 為準。2026/5 主流是 llama.cpp 對 Qwen2-VL / Llama 3.2 Vision / Gemma 3 Vision 支援度較好、其他模型可能要等。

硬體 vs 模型對照

跟純文字 LLM 對照的記憶體成本

本地 VLM vs 雲端 VLM 的分工

跟模組六的 跨雲端 / 本地資料邊界 同邏輯、按任務分流：

混用配置（同 4.11 long-context 跟 6.4 cross-cloud 推薦模式）：

1Continue.dev config：
2  Local VLM（default for vision）：Qwen2.5-VL-32B
3    日常 vision 工作、敏感內容
4  Cloud VLM（manual switch）：Claude 4 vision
5    複雜 Figma → code、高品質要求
6
7Local text model：Qwen3-Coder-30B-Instruct
8  純文字 coding 任務

Image token 跟 context budget

VLM 推論時、image token 跟 text token 共用同一個 context window。預算估算：

 1一張 1024×1024 截圖：
 2  低細節（low detail）：~85-256 image tokens
 3  中等：~500-1000 image tokens
 4  高細節（high detail）：~1500-3000 image tokens
 5
 6VLM 對話的典型 context 構成：
 7  System prompt：~500 token
 8  之前對話歷史：~2000-5000 token
 9  3 張截圖：~3000-6000 token
10  使用者當前 prompt：~200 token
11  → 合計 ~6K-12K input
12  → 加上 generated answer 跟 reasoning trace（若 VLM 也支援 reasoning）
13  → 16K context 模型開始吃緊

實務建議：

1. VLM 工作流配 long context 模型：至少 32K context、64K 更好
2. 多輪對話控制歷史長度：每幾輪 trim 舊截圖、避免 context 爆
3. 裁切截圖、只貼相關區域：別把整個 4K 螢幕貼進來、跟問題相關的窗口就行
4. 看清楚 API 文件的 detail 模式：不需要看小字的任務用 low detail、省 token

IDE 整合的現狀（2026/5）

事實查核註：IDE 跟推論伺服器對 VLM 的支援度 2026/5 仍在快速演化、引用前以各工具當前 release notes 為準。雲端 IDE（Cursor / Claude Code）的 vision 支援多半成熟、本地 IDE plugin + 本地 VLM 的組合仍在追趕。

Trigger 訊號

判斷「該升級到 vision-native coding workflow」的訊號：

1. Continue.dev / Ollama release notes 出現「first-class vision support」「image input now stable」
2. 本地 VLM 在自己工作流的 use case（如 debug UI）品質追上 2024 年的 Claude 3 vision
3. 同事 / 社群開始日常用截圖 + IDE 互動
4. 自己工作流出現「人類花時間文字描述視覺問題給 LLM」的 friction

任一觸發 → 開始 explore 本地 vision plugin、設配置。

Multimodal RAG 跟 VLM 的關係

RAG 章節覆蓋了 text-based retrieval。Multimodal RAG 加上 vision 維度：

1傳統 RAG：
2  text query → text embedding → 檢索 text docs
3
4Multimodal RAG：
5  text or image query → multimodal embedding → 檢索 text + image
6  例：「跟這張 UI 截圖相似的設計」、「跟這個 error 一樣的 issue ticket」

Multimodal RAG 的 embedding 通常用 CLIP-style 模型（跟 4.12 embedding model internals 介紹的 text-only embedding model 訓練 paradigm 同源、都用 contrastive learning、但同時 embed 圖跟文字到共享空間）。

寫 code 場景的潛在應用：

• 設計系統 RAG：把過去設計稿、UI screenshots 都 embed 起來、給新 task 截圖時 retrieve 相似 case
• Bug screenshot 知識庫：歷史 bug 截圖 + 解法 embed、給新 bug 截圖時找相似 case
• Architecture 圖譜：架構圖 retrieve、給新需求找對應的舊架構

目前實用度比 text RAG 低、需要的 infrastructure（multimodal embedding service、image-friendly vector DB）尚不普及。

Tripwire（什麼時候值得評估 multimodal RAG）：

1. 推論伺服器（Ollama / llama.cpp）的 release notes 出現 first-class CLIP-style embedding 支援
2. Vector DB（Qdrant / Milvus / Weaviate）的 image embedding 索引從 experimental 變 stable
3. 自己工作流累積 1000+ 截圖（設計稿 / UI bug / 架構圖）、且 text 描述 retrieval 已撞天花板
4. Team 開始把「跟 X 類似的舊 case」當常規查詢、不只是「找特定關鍵字」

任一觸發 → 評估 multimodal RAG；都沒觸發 → 仍用 text RAG。

不在本章內的主題

1. 影片理解 / video LLM：寫 code 場景用得到的相對少（screen recording 倒是會用、但實作上多半切 keyframe 變多張圖）、見專門 video LLM 教材
2. Vision-only model（不含語言）：OCR、object detection、image classification 等專門 vision 任務、用 specialised 工具更好
3. 生圖（Diffusion 等）：跟 VLM 完全不同 paradigm、見 Diffusion 卡片 跟 ComfyUI 教材
4. 3D / point cloud：CAD / 3D 模型理解、目前 VLM 支援少、屬研究階段
5. 具體 IDE plugin 設定：Continue.dev 的 image upload UI、Ollama 的 vision API 細節等、隨版本變、見各工具當前文件

何時過時 / 何時不過時

不會過時的部分：

• Coding 場景 vision 的 use case 分類（UI debug、mockup → code、OCR 等）
• 本地 vs 雲端的分流邏輯（沿用 cross-cloud-local-data-boundary 框架）
• Image token 跟 context budget 的關係
• VLM 的失敗模式分類（細節、OCR、空間推理、DPI）
• Multimodal RAG 的概念框架

會變的部分：

• 具體本地 VLM 模型（Qwen2.5-VL → 2.6 → …、Llama 3.2 → 4 → …）
• 推論伺服器對 VLM 的支援度（llama.cpp、Ollama、LM Studio 都在追）
• IDE plugin 的 vision integration（Continue.dev、Cursor、Aider 都在演化）
• Vision encoder 設計（CLIP → SigLIP → DFN → …）
• 雲端跟本地的品質差距（會持續縮小）

跟其他章節的關係

本章是 4.1 RAG / 4.3 Tool use / 4.12 embedding model 在 vision 延伸的補完；隱私 / 跨雲端分流邏輯沿用 6.4；本地 VLM 配 IDE 的 hands-on 屬於 模組一 hands-on 範圍、視推論伺服器支援度成熟度補。

本章目標

讀完本章後、你應該能：

1. 區分四種 RAG deployment 方案（純前端 / edge serverless / RAG SaaS / 純文字 search）。
2. 對自己場景判斷該選哪個方案、看資料量 / 隱私 / 預算。
3. 認識靜態場景特有的資安議題：API key 暴露、CORS、abuse、第三方 SaaS 供應鏈、client-side 模型完整性。
4. 知道哪些資安議題在 模組六 已覆蓋、哪些是本章獨有。

為什麼這個議題重要

傳統 RAG 教材預設架構：

1User → backend server → embedding API → vector DB → LLM API → response

需要 backend 可執行 server-side code、藏 API key、控制 rate limit。但個人開發者場景常見的 deployment：

這些場景跟「個人 dev 跑本地 LLM」並列、是教材的合理覆蓋面。

四種 deployment 方案總覽

1                          embedding   vector       LLM call
2                          搜尋          DB
3方案 1 純前端            browser       browser     browser（WebLLM）或 user-key 直 call
4方案 2 edge serverless   edge fn       edge DB     edge fn → LLM API
5方案 3 RAG SaaS          SaaS          SaaS        SaaS（或自 call）
6方案 4 純文字 search     N/A           static idx  N/A（不是 RAG）

四方案快速對比：

方案 1：純前端 RAG（browser-side everything）

整個 RAG pipeline 都跑在使用者瀏覽器：

 1Build time（Hugo build / CI pipeline）：
 2  content/*.md
 3    ↓ 抽段、chunk
 4    ↓ embedding model（Node.js 版 sentence-transformers）
 5  embeddings.json（每個 chunk 一個 vector）
 6    ↓ 跟 HTML 一起 deploy
 7
 8Runtime（user browser）：
 9  User query
10    ↓ load @xenova/transformers + embeddings.json（首訪載 ~50MB）
11    ↓ embed query in browser
12    ↓ cosine similarity vs embeddings.json
13  top-K chunks
14    ↓ LLM call（兩條子路線、見下）
15  Response in browser

LLM 的兩條子路線：

實作概要：

1# Build time（Node.js script）
2npx @xenova/transformers-cli embed content/*.md > static/embeddings.json
3
4# Frontend（簡化版）
5import { pipeline } from '@xenova/transformers';
6const embedder = await pipeline('feature-extraction', 'nomic-embed-text-v1.5');
7const queryVec = await embedder(userQuery, { pooling: 'mean' });
8const ranked = embeddings.map(c => ({ ...c, score: cosineSim(c.vec, queryVec.data) }))
9                          .sort((a,b) => b.score - a.score).slice(0, 5);

規模上限：

• < 1000 chunks：embeddings.json ~ 4MB（1024-dim float32）、輕鬆
• 1K-10K：~40MB、首訪載入慢但可接受
• 10K+：純前端開始勉強、考慮方案 2

適合場景：個人 blog、docs site、demo、隱私敏感、規模 < 10K chunks。

方案 2：靜態 + edge serverless

「靜態主站 + edge function 處理動態請求」：

 1靜態前端（HTML / JS、Hugo / Astro）
 2   ↓ fetch /api/rag
 3Edge function（Cloudflare Workers / Vercel Edge / Netlify Functions）
 4   ↓
 5Embedding API（OpenAI / Voyage）
 6   ↓
 7Vector DB（Cloudflare Vectorize / Pinecone / Turso vector / Upstash Vector）
 8   ↓
 9LLM API（OpenAI / Anthropic / Cloudflare AI Gateway）
10   ↓ response
11靜態前端

對使用者體感跟「有 backend」一樣、但你不用維護 server / 不用 sysadmin。

主流元件搭配：

關鍵特性：

1. API key 不暴露在 browser：edge function 內讀環境變數、安全
2. 可加 rate limit：edge function 內判斷 client IP / user agent、避免 abuse
3. Build-time index 仍重要：embedding ingestion 通常在 build 階段、不在 runtime
4. Edge cold start：第一次 query latency 略高（~100ms 額外）、後續 hot 路徑快

適合場景：規模 1K-100K chunks、想保留近 backend 體驗、可接受少量 cost。這條路線一旦升級到有 backend 的 vector DB、storage 選型（index 結構、維度、成本）就回到 4.22 RAG storage 工程 的判讀。

方案 3：靜態 + RAG SaaS

把整個 RAG stack 外包：

API key 設計：

• search-only key：只能查詢、無寫入權限、可安全暴露在 browser（這是設計支援的）
• admin key：build time CI 用、有寫入權限、必須藏 server-side

前端範例（Algolia）：

1const client = algoliasearch('APP_ID', 'SEARCH_ONLY_KEY');  // 可公開
2const index = client.initIndex('my-blog');
3const { hits } = await index.search(userQuery, { hitsPerPage: 5 });

適合場景：想最快上線、不在乎 vendor lock-in、規模中小、retrieval-only（不需要 LLM 對話）。

方案 4：靜態 + 純文字 search（不是真 RAG）

Pagefind、Stork、lunr.js、FlexSearch — build time 產靜態 search index、純前端查詢。

這不是 RAG：

1. 無 embedding similarity：keyword / fuzzy match、不是語意相似
2. 無 LLM augmentation：只列文章連結、不生成回答
3. 算 retrieval 的「字面」變體：見 4.1 RAG 的「語意 vs 字面」段

適合場景：blog 內搜尋只需要找文章、不需要對話、極致 zero-cost。

規模門檻：什麼時候該升級方案

1< 1K chunks                    → 方案 1 純前端、最簡單
21K - 10K chunks                → 方案 1 或 方案 4
310K - 100K chunks              → 方案 2 edge serverless
4100K+ chunks                   → 完整 backend RAG（不再是「靜態」場景）
5非 RAG、只要找文章             → 方案 4（Pagefind 等）

靜態場景特有的資安議題

本章節最重要的部分。靜態 / serverless RAG 有些議題模組六沒覆蓋、要在本章補。

1. API key 暴露 — 靜態場景的根本問題

核心衝突：靜態網站沒 server-side runtime、藏不了 secret。任何寫在前端 JS / 編進 HTML 的東西、使用者按 F12 都看得到。

對應到 RAG：

如果要 LLM 對話功能、三條合法路線：

1. 使用者自帶 API key（如 Anthropic / OpenAI）、存 localStorage、前端直接 call API — 適合 power user、需要使用者授信
2. WebLLM / wllama 跑前端 LLM — 模型在 browser、不需 server-side key
3. 方案 2 edge serverless — key 藏在 edge function、就不是純靜態了

寫死 API key 在前端 JS 等於把 key 公開、會被 scraper 撿走燒爆 quota — 這是 anti-pattern、跟 6.4 跨雲端 / 本地資料邊界 提到「API key 寫死 config」的延伸版（前端更嚴重、所有訪客都看得到）。

2. User query 隱私

靜態場景的 query 走向：

對應 framing 跟 0.7 隱私資料流 同源 — 但靜態場景的特殊性是「前端直接出去」、不像 backend 場景可以加一層中介控制。

特別注意：

1. 方案 3 SaaS 的 query 隱私：Algolia / Pinecone 都會 log query、依政策可能用於改進服務；對隱私敏感場景不適合
2. Edge provider 的 region：Cloudflare Workers 的 edge node 可能在跟使用者不同 region 處理、跨境資料法規（GDPR 等）要考慮
3. Browser extension 偷 query：使用者裝的 plugin 可能 access 整個頁面、包含 RAG 介面內的 query

3. CORS / 同源策略 — Browser 特有的安全模型

靜態前端 call 任意 API 會撞 CORS（Cross-Origin Resource Sharing）：

1靜態網站：https://my-blog.com
2要 call：https://api.openai.com/v1/...
3   ↓
4Browser 檢查 OpenAI 是否在 Access-Control-Allow-Origin 含 my-blog.com
5   ↓
6OpenAI 預設允許所有 origin（為了讓前端 SDK 能用）→ 通過
7某些 API（Anthropic 早期版本）不允許 browser 直 call → 失敗、必須走 edge

判讀：

• 能在 browser 直 call 的 API：OpenAI、Voyage、Algolia（search-only）等明確設計 browser-friendly 的服務
• 不能 browser 直 call、要 edge proxy：許多企業 LLM API、私有 vector DB、需要 server-only credentials 的服務

CORS 不是「資安漏洞」、是 browser 對「JS 從一個網站 call 另一個網站」的設計約束、用來保護使用者。要繞 CORS 要嗎服務商配合（設 ACAO）、要嗎用 edge function proxy。

4. 第三方 SaaS 信任 — 跟 6.0 同源、對象換

6.0 模型供應鏈與信任邊界 處理的是「模型權重的信任」。靜態 RAG SaaS（Algolia / Pinecone / Weaviate Cloud）引入另一條供應鏈：

 1模型供應鏈（6.0 覆蓋）：
 2  原作者 → quantizer → registry → 你機器
 3
 4RAG SaaS 供應鏈（本章新增）：
 5  你的 content → SaaS embedding service → SaaS vector DB → SaaS retrieval
 6    └──────── 全程在 SaaS 內、你信任 SaaS 沒做以下事 ────────┘
 7              - 把你 index 用於訓練他們自己的模型
 8              - 把你 query log 賣給第三方
 9              - 沒做適當 isolation（你跟其他客戶的資料）
10              - 沒處理好 supply chain（他們用的 base embedding model）

判讀類似 0.7 物理 vs 合約保證：本地方案是物理保證（資料不離 browser）、SaaS 方案是合約保證（信 SaaS 的 ToS）。

5. Rate limit / abuse — 前端被 scrape 後濫用

靜態 RAG 的特殊 abuse 路徑：

1攻擊者掃到你的 demo blog
2   ↓ 找到前端載入的 embedding endpoint / LLM endpoint
3   ↓ 直接從攻擊者 server 重複 call（不經 browser）
4   ↓ 你的 LLM API quota 燒爆 / SaaS 配額耗光

緩解：

1. 方案 2 edge + 加 rate limit by IP / token bucket：edge function 內 reject 過量請求
2. 方案 1 純前端 + WebLLM：根本沒 server-side endpoint 可被 abuse、最安全
3. 方案 3 SaaS + 用 search-only key 並設 query 上限：SaaS 通常內建 quota
4. CAPTCHA / Turnstile：邊緣防護

絕對不該做：把 OpenAI / Anthropic API key 寫在前端 JS、想用 rate limit 阻擋 — 攻擊者拿到 key 後不會經過你的 rate limit。

6. Client-side LLM 的模型完整性

Client-side LLM 把幾 GB 模型權重下載到 browser、引入新的供應鏈面：

1你的網站
2   ↓ <script> 載入 WebLLM runtime（CDN）
3   ↓ runtime 從 HuggingFace CDN 抓 model weights
4   ↓ 使用者 browser 跑模型

風險：

1. CDN 被 compromise：WebLLM runtime 或 model weights 在 CDN 上被換、注入 backdoor
2. HTTPS 之外無額外驗證：不像本地 GGUF + hash 比對、browser 載模型純信 CDN + HTTPS
3. 使用者本機沒 inventory 記錄：跟 6.0 推薦的「下載後記 hash」對比、browser 沒這機制

緩解：

1. Subresource Integrity（SRI）：HTML 的 <script integrity="sha384-..."> 屬性、browser 自動驗證 hash
2. CSP（Content Security Policy）：限制可載入的 script / image source、減少 supply chain attack 面
3. 挑大廠 CDN：Cloudflare / jsdelivr / unpkg 等被 compromise 的歷史紀錄較少

跟 6.0 的關係：6.0 講「本機跑的 GGUF 模型供應鏈」、本章補「browser 跑的 client-side 模型供應鏈」— 兩種場景的 framing 一致、但具體威脅面跟工具不同。

跟模組六的 routing

本章資安段跟既有 模組六 的對應：

判讀流程

 1你的場景：
 2  ├─ 有 backend？
 3  │    └─ 是 → 用 4.0 RAG + 4.8 embedding 主章節、本章不適用
 4  │    └─ 否 → 繼續
 5  │
 6  ├─ 規模？
 7  │    ├─ < 1K chunks → 方案 1 純前端
 8  │    ├─ 1K-10K → 方案 1（embeddings.json ~ 40MB 仍可接受）
 9  │    ├─ 10K-100K → 方案 2 edge serverless
10  │    └─ 100K+ → 不再是靜態場景、回 backend
11  │
12  ├─ 需要 LLM 對話、不只 retrieval？
13  │    ├─ 是 + 隱私第一 → 方案 1 + WebLLM
14  │    ├─ 是 + 品質第一 → 方案 1 + user-key 或 方案 2
15  │    └─ 否（只要找文章） → 方案 4 純文字 search
16  │
17  └─ 預算 / vendor lock-in 容忍度？
18       ├─ 完全 zero-cost、無 vendor → 方案 1 純前端
19       ├─ 接受少量 cost、不想自己寫太多 → 方案 3 SaaS
20       └─ 接受少量 cost、想自己控 → 方案 2 edge

不在本章內的主題

1. 完整 backend RAG：see 4.1 RAG 原理 跟 4.12 embedding model
2. 具體 SaaS API 教學：Algolia / Pinecone 等 API 細節隨版本變、見各 SaaS 文件
3. WebGPU 內部細節：GPU shader、WebGPU API 設計屬 web platform 議題、不在 LLM 教材範圍
4. Production 多租戶 RAG 服務：屬 backend/07、本章 framing 是「個人 / 小團隊靜態網站」
5. 企業合規 deployment：HIPAA / GDPR / SOC 2 跟具體 SaaS / cloud provider 強相關、見 backend/07 合規卡片 跟 6.4 跨雲端

何時過時 / 何時不過時

不會過時的部分：

• 四方案分類（純前端 / edge / SaaS / 純文字 search）
• 「靜態場景藏不了 secret」這個根本特性
• API key 暴露 / CORS / abuse / 供應鏈 / 模型完整性 五大資安議題分類
• 跟 模組六 的 routing 關係

會變的部分：

• 具體 SaaS / edge provider（Cloudflare Vectorize / Pinecone / Algolia 等持續演化）
• Client-side LLM runtime（WebLLM / wllama / transformers.js）的能力上限
• WebGPU 支援度跟 browser 標準
• 哪些 LLM vendor 允許 browser 直 call（CORS 政策會變）
• 純文字 search 工具（Pagefind 等持續改進）

下一步

本章是 模組四 最後一章。讀完整個模組四、完整覆蓋 LLM 作為系統元件的設計取捨。下一步可進入 模組五 PC 獨立 GPU 或 模組六 安全 補本地 dev 視角的安全議題。

本章目標

讀完本章後、你應該能：

1. 用 scaffold vs harness 分層拆解任何 coding agent。
2. 對自己工作流計算 context budget、看到 budget 超標訊號時知道怎麼修。
3. 判斷何時值得拆 subagent、何時用 single agent。
4. 看 Claude Code / Cursor / Aider 等 coding agent 的設計差異、能對應到本章 framing。

Scaffold vs Harness 分層

Coding agent 的內部結構分兩層：

 1Scaffold（建構時靜態結構、編譯 / 載入時就決定）：
 2  - System prompt 模板（agent 角色、輸出約束、錯誤處理 policy）
 3  - Tool schema 註冊（read_file / write_file / run_bash / web_fetch 等 spec）
 4  - Subagent 拓樸（main agent + 子 agent 關係）
 5  - Skill / playbook 註冊（特定任務的 known recipe）
 6  - 安全 policy（permission boundary、要 confirm 的動作清單）
 7
 8Harness（runtime 動態運作、每個 query / loop iteration 跑）：
 9  - Tool dispatch（接 LLM tool call、call function、回 result）
10  - Context budget 管理（剪裁 history、塞新內容、避免超 budget）
11  - Safety / 中斷（confirm UI、permission check、可逆性判斷）
12  - Error recovery（tool failed → retry / fallback / escalate）
13  - Telemetry（trace / metrics / cost、見 [4.20 OTel tracing](/llm/04-applications/llm-tracing-and-observability/)）

不同 coding agent 的 scaffold / harness 比較：

關鍵理解：所有 coding agent 都遵循這個 framing、差異在「scaffold 多複雜」「harness 多強」、不是有沒有這兩層。

Context Budget 工程實務

Context budget 是 coding agent harness 的核心責任。實務拆分（以 200K context 模型為例）：

關鍵 25% 規則：Scaffold 部分（system prompt + tool schema + conversation history）合計不超過 25% context。剩 75% 給「當下任務」、避免 lost-in-the-middle 把指令吃掉。

超標訊號跟對應策略：

實作概要：

1每個 turn 開始時、harness 算：
2  available_input = context_window - reserve_margin
3  used = len(system + tool_schema + history + new_content)
4
5  if used > available_input × 0.75：
6    觸發 summarize：把舊 history 壓縮成 1 段摘要
7    或觸發 dispatch：交給 subagent 處理特定子任務、回主 agent 時只帶 summary

Subagent 設計

Subagent 把單一大 agent 拆成多個專責子 agent、各自有獨立 context。何時用：

主流 subagent 模式：

1. Search subagent

Specialty：在大 codebase 找相關片段、不污染 main agent context Tool：grep / find / semantic search Output：top-K 相關段落 + 摘要、main agent 不需要看完整 grep 結果

2. Test runner subagent

Specialty：跑測試、解讀失敗、提出 fix 建議 Tool：run_bash（pytest / jest 等）+ read failed test Output：「測試結果 + 失敗根因 + 建議 fix」、不是完整 test log

3. Docs writer subagent

Specialty：寫 docstring / README / commit message System prompt：強化「寫作風格、語言、長度」、跟 main coding agent 完全不同的 system prompt Output：寫好的 docs 文字

4. Code review subagent

Specialty：對 PR diff 做 review、檢查 style / bug / security Tool：git diff / grep Output：comments 列表

5. Long-running task subagent

Specialty：跑可能持續數分鐘的任務（如 large-scale refactor）、main agent 不阻塞 Tool：背景 process management Output：階段性進度回報 + 最終結果

主 agent 對 subagent 的 handoff 設計：

1main agent 收到任務
2   ↓ 判斷 specialty
3   ↓ 用 dispatch_subagent tool 呼叫
4   tool spec：{name, task_brief, expected_output_format}
5   ↓
6Subagent 在自己 context 內跑完
7   ↓ 回 summary（不是完整 trace）
8   ↓
9main agent 拿到 summary、繼續推進

跟既有概念的關係

跟具體 coding agent 的 mapping

讀者實際用 / 想客製某個 coding agent 時、用本章的 framing 拆解：

Claude Code

Scaffold：CLAUDE.md（system prompt 入口）、Skills registry、SubagentTypes、tool schema Harness：context budget management、Task tool（dispatch subagent）、permission system、trace 特色：完整 scaffold-harness 分層、強 subagent system、explicit context budget

Cursor

Scaffold：System prompt 較固定、tool list 較簡、Composer mode 是 scaffold variant Harness：IDE 整合度高、tool dispatch 跨 client / server、streaming response 特色：產品優化重於可客製、scaffold 半開放

Aider

Scaffold：edit-format（diff / udiff / whole）+ git integration、tool 較少（read / edit / run） Harness：repl-style loop、自動 commit、線性對話 特色：CLI-first、scaffold 簡單、harness 圍繞 git 設計

Continue.dev（搭本地 LLM）

Scaffold：Provider-agnostic、tool list 由 plugin 註冊 Harness：較輕量、tool dispatch 在 VS Code extension host 特色：適合本地 LLM、scaffold / harness 都相對開放

失敗模式跟緩解

Coding agent 常見失敗：

本地小模型跑 coding agent 的限制

本地 < 14B 模型跑完整 coding agent 通常不穩、根因（跟 3.8 reasoning-models / 4.4 agent-architecture 已述）：

1. Tool use 不穩：小模型 function calling 訓練不足、tool call 格式錯誤率高
2. Long context 退化：< 14B 模型 effective context 通常 < 16K、coding agent 場景容易撞 budget
3. Reasoning 弱：multi-step planning、failure recovery 都需要 reasoning 能力
4. Subagent handoff 失敗：小模型對「該 handoff 給誰」的判斷不穩

實務組合：

• Autocomplete + 簡單 chat：本地 7B-14B coder（Qwen3-Coder / Gemma 4 coder）可勝任
• 完整 coding agent：30B+ 本地模型或雲端旗艦
• 混用：本地小模型當 autocomplete + 雲端旗艦當 agent

何時過時 / 何時不過時

不會過時的部分：

• Scaffold vs harness 分層 framing
• Context budget 配額概念跟 25% 規則
• Subagent 設計原則跟 handoff 機制
• 失敗模式分類（context 爆、infinite loop、permission 邊界）
• 本地小模型限制

會變的部分：

• 具體 coding agent（Claude Code / Cursor / Aider 等持續演化）
• Subagent registry 標準化（目前各家不同）
• Tool schema 標準化（MCP 是其中一條路）
• 本地小模型的 agent 能力（會逐步追上）

下一章

下一章：4.18 Prompt caching 工程實務、看 scaffold 部分的 cost / latency 優化。

注意三層 cache 概念的層次差異（prompt cache 卡片 有完整對比表）：KV cache 是單次推論內、過去 token 的 K/V 暫存（autoregressive 才省重算）；prefix cache 是同一推論伺服器內跨 request 共用 KV cache；prompt cache（本章聚焦） 是雲端 LLM API 商業 feature、跨 request 跨時間、有 TTL。三者不同層、要區分。

本章目標

讀完本章後、你應該能：

1. 解釋 prompt cache 跟 KV cache / prefix cache 的層次差異。
2. 對 coding agent / RAG / long-conversation 場景設計 cache breakpoint。
3. 估算自己應用開 prompt cache 的 cost / latency 收益。
4. 看到「cache 不命中」訊號時、能定位 anti-pattern 並修。

Prompt cache 怎麼運作

LLM 推論的 prefill 階段對整個 prompt 算 KV cache、是長 prompt 的主要 latency 跟 compute 成本：

1無 cache：
2  Request 1：[10K system prompt] + [tool schema 5K] + [user query 500] = 15.5K prefill
3  Request 2：[10K system prompt] + [tool schema 5K] + [user query 700] = 15.7K prefill
4  → 兩次都付 15K prefill 成本

開 prompt cache 後：

1Request 1：[10K system + 5K tool schema] | cache_control | + [user query 500]
2  → 算出 prefix 的 KV cache、寫進服務端 cache（付 1.25× cost）
3  → 後段 prefill 500 token
4
5Request 2（5 分鐘內）：[10K system + 5K tool schema] | + [user query 700]
6  → 服務端命中 cache、跳過 prefix 的 prefill（付 0.1× cost = 90% 折扣）
7  → 只 prefill 700 token
8  → TTFT 大幅降低

關鍵運作細節：

1. Cache key = prefix 的 token sequence：完全相同的 token sequence 才命中、差一個 token 就 miss
2. TTL（time-to-live）：cache 過一段時間（多數 5 min）自動失效、要 ext 1h 通常付額外 cost
3. Write 比原價略貴、Read 大幅打折：Anthropic 模型 write 1.25×、read 0.1×；OpenAI 模型 read 0.5×
4. Minimum cacheable size：通常 1K-4K token 起跳、短 prompt 不適合
5. Cache 範圍：跨 request、跨 conversation、跨 session、但同一 model + 同一 region

Cache breakpoint 設計

Anthropic 用 cache_control 標記顯式 breakpoint、OpenAI 用自動偵測。但設計原則一致：把不變的內容放 prefix、變動的放後面。

典型 coding agent 的 prompt 結構：

1[1. System prompt]：agent 角色、規則、輸出格式             ← 不變
2[2. Tool schema]：所有 tool 的 spec                       ← 不變（除非加新 tool）
3[3. Skill registry / playbook]：known recipes              ← 半變（偶爾更新）
4[4. Codebase context]：固定載入的核心檔案                  ← 半變
5       ↓ cache_control breakpoint ↑
6[5. Conversation history]：過去回合                       ← 變動
7[6. Current user query]：當前 query                       ← 變動
8[7. Current tool result]：剛跑完的 tool output             ← 變動

Breakpoint 放在「不變 vs 變動」交界處、讓 [1-4] 永遠 cache hit。

Anthropic 最多 4 個 breakpoint、可分層：

1breakpoint 1（最早）：[system prompt] → 永久 cache
2breakpoint 2：       [+ tool schema] → 永久 cache
3breakpoint 3：       [+ skill registry] → 半永久 cache
4breakpoint 4（最晚）：[+ recent stable context] → 短期 cache
5[後段]：             variable content（不 cache）

每個 breakpoint 各自命中 / miss、layered cache 讓「加新 skill」只 invalidate breakpoint 3 之後、不影響 breakpoint 1-2。

場景 1：Coding agent

Coding agent 是 prompt cache 命中區 — system prompt + tool schema 動輒 10K-30K token、每個 user turn 都重用。

收益估算（200K context 模型、10K scaffold、5K user query、3K answer）：

 1無 cache：
 2  每 turn input cost = (10K + 5K) × $3/M = $0.045
 3  每 turn TTFT = 10K-15K prefill time（200-400ms）
 4
 5開 cache：
 6  Turn 1（write）：(10K × 1.25 + 5K) × $3/M = $0.0525
 7  Turn 2-N（read）：(10K × 0.1 + 5K) × $3/M = $0.018
 8  TTFT：read 階段省掉 10K prefill、只剩 5K
 9
1010 turns 的累計 cost：
11  無 cache：10 × $0.045 = $0.45
12  開 cache：$0.0525 + 9 × $0.018 = $0.215
13  → 節省 52%

長對話越長、cache 收益越大（cache write 是一次性成本）。

場景 2：RAG / long-context

RAG 場景把 retrieved chunks 放 prefix、user query 放後面、可以 cache retrieved chunks：

1[system prompt]
2       ↓ breakpoint 1（system 永久 cache）
3[retrieved chunks 來自 RAG]
4       ↓ breakpoint 2（同 chunks 在 5min 內 cache）
5[user query]

注意：每次 retrieval 不同 chunks 就 cache miss、所以 cache 適合「同個對話多輪、retrieval 結果穩定」、不適合「每 query 都 fresh retrieve」；後者要回到 retrieval cost 評估。

場景 3：Long document Q&A

讀者上傳 PDF / 文件、多輪問問題：

1[system prompt]
2       ↓ breakpoint 1
3[完整文件內容（可能 100K token）]
4       ↓ breakpoint 2（文件永久 cache）
5[user query]

第一次 query 付 1.25× 文件成本、後續 query 都 0.1×。100K 文件 + 10 個問題的場景下、節省極顯著（> 80% cost）。

常見 anti-pattern

1. 在 prefix 插入 timestamp / request-id

1反例：System prompt: "你是 coding assistant、當前時間 2026-05-12 16:30:42、..."
2   → 每秒不同 cache key、永遠 cache miss、付 1.25× write 不回本
3正解：把 timestamp 放後段、或省略（多數場景模型不需要精確時間）

2. 在 prefix 動態插入 user metadata

1反例：System prompt: "User: alice@example.com, plan: premium、..."
2   → 每個 user 不同 cache、命中率低
3正解：User metadata 放後段、prefix 保持 user-agnostic

3. Tool schema 順序不固定

1反例：每次 request 把 tool list 隨機 shuffle
2   → 同樣 tool 但 token sequence 不同、cache miss
3正解：Tool list 順序固定、新加 tool 都 append 到末尾

4. 太短的 prompt 也想 cache

1反例：500 token system prompt 開 cache
2   → 多數服務商 minimum 1K-4K、不到門檻不 cache、且 write cost 不回本
3正解：Cache 留給 > 1K 的 prefix、短 prompt 不必開

5. 混用 stream + cache 卻不檢查命中

1反例：開 cache 後不檢查 response 的 cache_read_input_tokens 欄位
2   → 不知道實際命中率、可能 anti-pattern 已在燒 cost 沒察覺
3正解：監控 cache_read / cache_creation token 比例、低於 80% 命中率時 debug

Cache miss 訊號跟診斷

訊號：

1. Cost 比預期高：應該命中的場景仍付 full price
2. TTFT 沒改善：cache hit 應該大幅降 TTFT、沒改善 = miss
3. Response 的 usage 顯示 cache_read = 0：直接訊號

診斷流程：

11. 印出 raw request 的 prefix（cache_control 之前）
22. 比對連續兩次 request 的 prefix token sequence
33. 找出差異位置（diff）
44. 移除 / 重構讓兩次 prefix 完全相同
55. 跑 2-3 次 request、看 cache_read_input_tokens 是否上升

常見差異：timestamp、request id、user id、tool list 順序、retrieved chunks 順序、conversation summary 變動。

跟其他 cost 優化技巧的關係

本地推論伺服器有沒有類似機制

Ollama / LM Studio / llama.cpp 自身的 prompt cache：

本地推論的 cache 主要靠 prefix cache 機制、跟雲端 API 的 prompt cache 商業 feature 同源、但定價 / TTL / 顯式 control 是雲端 API 才有的 product layer。

何時不適合用 prompt cache

1. 每 request prefix 必變：streaming 任務、每 query 都帶 fresh 上下文
2. Single-shot 對話：用完就丟、沒有重複使用、write cost 不回本
3. Prefix < 1K token：不到 minimum、cache 不生效
4. Cost 不敏感場景：個人小流量、cache 設計 overhead 大於收益
5. 本地推論為主：本地多用 prefix cache、prompt cache 是雲端 API 概念

何時過時 / 何時不過時

不會過時的部分：

• 「不變放 prefix、變動放後段」的設計原則
• Cache breakpoint 分層（system / tool schema / skill / context）
• Anti-pattern 分類（timestamp、user metadata、tool 順序）
• Cache miss 診斷流程

會變的部分：

• 各 vendor 的具體定價（write × / read × 折扣）
• TTL（5min vs 1h）的可選性跟價格
• Automatic vs explicit cache（OpenAI vs Anthropic 路線）
• Breakpoint 上限數量
• 本地推論伺服器的 cache 功能（持續演化）

下一章

下一章：4.19 Agent memory 分層、看 agent 如何在 context window 之外管理長期狀態。

本章目標

讀完本章後、你應該能：

1. 區分 agent memory 的五個層次（working / short-term / long-term episodic / semantic / procedural）。
2. 對自己 agent 場景判斷要哪幾層 memory、不要哪幾層。
3. 設計 long-term memory 的「何時寫」「何時讀」邏輯。
4. 認識 memory 的常見失敗模式（drift / PII / 污染）跟對應緩解。

五個層次的責任劃分

 1[Working memory]：當前 forward pass 的 context window
 2   - 規模：模型 context（4K-1M token）
 3   - 範圍：當下這次推論的全部輸入
 4   - 例：當下 user query + recent tool result + reasoning trace
 5
 6       ↑ 從這層讀 / 寫到這層
 7
 8[Short-term / session memory]：單一 session 的 scratchpad
 9   - 規模：一輪對話到一天
10   - 範圍：跨多個 turn、但 session 結束就丟
11   - 例：本 session 算過的中間結果、tried strategies
12
13       ↑ session 結束時可選擇 persist 到 long-term
14
15[Long-term episodic memory]：跨 session 的「事件」
16   - 規模：永久（直到主動刪除）
17   - 範圍：跨所有 session、按時間順序
18   - 例：「上週解過這個 race condition」「alice 上個月問過 X」
19
20[Long-term semantic memory]：跨 session 的「事實 / 知識」
21   - 規模：永久
22   - 範圍：跨所有 session、按主題索引
23   - 例：「user 偏好 markdown 輸出」「專案用 React 18」「team 不用 Tailwind」
24
25[Long-term procedural memory]：跨 session 的「流程 / 技能」
26   - 規模：永久
27   - 範圍：可重複使用的 known-good 程序
28   - 例：「跑測試前先 npm install」「commit 前要 lint」「deploy 前要 dry-run」