概念位置

Sampling 約束屬於推論階段，不修改模型權重，也不等於模型真的理解規則。常見控制手段有 temperature、top-p / top-k、logit bias、grammar mask、JSON mode 與 constrained decoding；其中 grammar mask 是 structured output 最關鍵的一類。

1prompt → model forward pass → logits
2  ↓
3sampling constraint：調整候選 token / logit / 機率
4  ↓
5sample next token → append → 下一輪

可觀察訊號與例子

看到「低 temperature 讓答案更穩」「top-p 過濾長尾 token」「logit bias 禁止某個 token」「grammar mask 只允許合法 JSON token」就是 sampling 約束。例子是 enum 分類：如果合法答案只有 billing、technical、other，推論伺服器可以在輸出欄位值的位置只允許這幾組 token 的路徑。

Sampling 約束的風險是把模型逼到錯誤但合法的輸出。當 grammar 太窄、enum 缺少 unknown、schema 沒有容納例外狀態時，模型可能輸出看似可解析但語意不可信的值；這時要加 fallback、confidence 或人工覆核路由。

設計責任

Sampling 約束適合處理格式合法性與候選空間控制，不適合單獨承擔事實正確性。設計時先問三件事：合法 token 集合能否完整表示業務狀態、約束失敗時要 retry 還是回退、下游 validator 如何分辨「格式合法但語意可疑」。下一步路由是 Structured Output 與 Top-K / Top-P / Min-P Sampling。

概念位置

Structured output 位在推論與應用交界，常見實作包含 JSON mode、JSON Schema、grammar 約束、constrained decoding 與 logit mask。它跟 function calling 的差異在責任層：function calling 是模型訓練出的工具呼叫能力，structured output 是推論時讓輸出形狀穩定的約束。

1模型能力：知道是否該呼叫工具、該填什麼參數
2推論約束：輸出必須符合 JSON / schema / grammar
3應用消費：parser 解析、validator 檢查、dispatcher 執行

可觀察訊號與例子

看到「固定輸出 JSON」「把結果分類成 enum」「回傳符合 schema 的物件」「讓 parser 不再處理自由文字」就是 structured output 場景。例子是客服工單分類：模型輸出 {"category":"billing","priority":"high"}，後端可以直接依欄位路由，而不是從一段自然語言裡抽關鍵字。

Structured output 的成功訊號是合法率、schema 對位率與下游解析失敗率。JSON 合法率只代表文字可被 parser 讀，schema 對位率才代表欄位、型別、enum、required 都符合應用契約；兩者分開看，才能分辨是語法錯、schema 錯，還是模型語意判斷錯。

設計責任

Structured output 適合「下游要自動執行」的輸出：tool 參數、分類、抽取、workflow 狀態、查詢條件。它的邊界是語意品質：grammar 可以保證格式合法，但不能保證模型填的值正確。下一步路由是：需要理解 token mask 機制讀 Constrained Decoding；需要判斷它跟工具呼叫的分工讀 Function Calling；需要完整應用層組合讀 4.6 應用層協議。

概念位置

Beam search 跟其他 decoding 策略的對比：

Beam search 的算法直覺：

1beam_width = 3
2Step 1：從機率分佈挑前 3 個 token、得到 3 條 partial sequence
3Step 2：每條 partial 各自展開所有可能下個 token、組合機率排序、保留前 3
4Step 3：重複 Step 2、直到所有 beam 都遇到 EOS 或達到 max_length
5Final：選總 log-probability 最高的 beam 當輸出

Beam search 在 LLM chat / coding 場景的副作用：

1. 輸出偏 boilerplate：K 個 beam 容易收斂到同樣的高頻開頭（「Sure!」「That’s a great question」）、各 beam 平均化掉原本該有的多樣性。
2. 缺乏隨機性：給同 prompt 永遠生同輸出、缺乏寫作 / 創意任務需要的變化。
3. 計算貴：K 倍記憶體 + K 倍 forward pass。

設計責任

讀 inference framework 看到 num_beams: 1 預設值就是用 greedy/sampling、num_beams: 5 才會開 beam search。寫 code 場景的判讀：日常用 top-p sampling 為主、需要確定性測試用 greedy、需要「在多個候選中挑最好的」用 best-of-N（每個獨立 sample、再選 reward 最高）而非 beam search。Beam search 在現代 LLM chat 場景已經少用、但在 translation / structured output 等「有正確答案」場景仍見。

概念位置

跟既有 sampling 概念的層次：

1模型 forward pass → logits（每個 vocab token 一個分數）
2   ↓ apply temperature
3   ↓ apply grammar mask（constrained decoding）  ← 本卡聚焦
4       - 算出當下位置的合法 token 集合
5       - 不合法 token 的 logit 設 -∞
6   ↓ softmax → 機率分佈
7   ↓ sampling（greedy / top-p / top-k）
8   ↓ next token

主要 grammar 類型：

主流實作對比：

設計責任

讀 sampling / structured output / function calling 進階文件看到「constrained decoding」「grammar mask」「JSON schema enforcement」就是這 framing。寫 code 場景的判讀：

1. 何時值得用：需要 100% 合法 JSON / 特定格式、function calling spec 嚴格、structured output 不可有解析錯誤
2. 不該用的情況：自由 / 創意輸出（會限制模型表達）、grammar 太嚴讓模型「該說的話說不出來」（如 enum 不含「unknown」、模型強制選錯）
3. 跟 function calling 的關係：function calling 是「模型訓練 + structured output」、constrained decoding 是 sampling 層的工程實作、可獨立組合
4. 加速 vs 拖慢：常見誤解是 grammar 拖慢 — 實測 XGrammar 等 pre-compiled 實作反而加速生成（跳過 boilerplate token 直接生關鍵 token、節省 forward pass）
5. 跟 3.10 constrained decoding 章節 的關係：本卡是定義、章節是內部機制（token mask 計算、CFG 編譯、性能取捨）

概念位置

Logit 在 LLM 輸出 pipeline 的位置：

1最後一層 Transformer 輸出 hidden state
2   ↓ output projection（linear layer）
3logits（shape: vocab_size、實數、可正可負）
4   ↓ logit warping / masking（可選、用於控制輸出）
5   ↓ /temperature
6   ↓ softmax
7probability distribution
8   ↓ sampling（greedy / top-k / top-p）
9next token

操作 logit 的常見技巧：

設計責任

理解 logit 後可以判讀 sampling 階段的控制粒度：所有「不重訓模型、影響輸出」的技巧（temperature、structured output、constrained generation、logit bias）本質上都是「在 softmax 前後動 logit」、不是動模型權重。這也是為什麼同一個模型用不同 sampling 設定能產生差很多的輸出。

概念位置

LLM 中 softmax 出現的兩個位置：

1位置 1：Attention 內部
2  Q · K^T → 一堆 score
3  softmax(scores) → attention weight（總和 1）
4  weight · V → output
5
6位置 2：每次 token 生成的最後一步
7  最後一層 hidden → logit（每個 vocab token 一個實數分數）
8  softmax(logits / temperature) → 機率分佈
9  從這個分佈 sample 出下一個 token

兩個位置的關鍵差異：

Temperature 在 sampling 端跟 softmax 結合：softmax(logits / T)、T 越小分佈越尖（接近 greedy）、T 越大分佈越平（接近隨機）。

設計責任

理解 softmax 後可以判讀幾件事：temperature 為什麼影響輸出多樣性（改的是 softmax 前的縮放）、為什麼 logit bias / logit warping 等技巧能控制輸出（直接動 softmax 的輸入）、為什麼 structured output 的 grammar-constrained sampling 是「把不合法 token 的機率歸零」（在 softmax 後或前做 masking）。

概念位置

三種策略的篩選方式：

範例（vocab 前 10 個 token 的機率）：

1token:     A     B     C     D     E     F     G     H     I     J
2prob:    0.45  0.30  0.12  0.05  0.03  0.02  0.01  0.01  0.005 0.005
3
4Top-K=3：保留 A、B、C（前 3 個）
5Top-P=0.9：累積機率達 0.9、保留 A、B、C、D（0.45+0.30+0.12+0.05 = 0.92）
6Min-P=0.1：max=0.45、閾值=0.045、保留 A、B、C、D（≥ 0.045）

三者實務上常組合使用（如 top_k=40, top_p=0.9, temperature=0.7）、各自處理不同形狀的分佈。

設計責任

讀 inference config / Continue.dev 設定看到 top_k、top_p、min_p、temperature 就是這組參數。寫 code 場景的判讀：嚴謹任務（code generation、structured output）用低 temperature + 緊 Top-P 取「最可能對的少數 token」；創意 / 對話用高 temperature + 寬 Top-P 取多樣性。Min-P 是 2023 後流行的新策略、實務上比 Top-P 更穩、避免「分佈很尖時 Top-P 仍納入長尾低品質 token」的問題。

動態取樣

流量超過閾值時自動降低取樣率。平時 100% 收集、超載時降到 10% — 仍有資料可分析，只是精度下降。

觸發條件

取樣的公平性

動態取樣不應該只丟新事件保留舊事件（FIFO 丟棄）— 這會讓取樣偏向「burst 初期的事件」。更好的策略是隨機取樣（每個事件有 sampling_rate 的機率被保留），讓取樣後的資料仍然能代表整體分佈。

取樣後的事件帶 _sampling_rate 欄位，分析時用 1 / sampling_rate 做加權還原。

事件優先級

不同事件類型的 debug 價值不同。超載時先丟價值低的，保留價值高的。

優先級的判斷原則：「這個事件丟了、要花多少時間從其他來源補回相同資訊」。Error 的 stack trace 丟了幾乎不可能從其他來源補回；event 的 click 計數可以從後續資料的趨勢推測。

功能降級

非核心功能暫時關閉或降低更新頻率，把資源留給核心功能。

降級的觸發和恢復應該自動化 — 用 collector 的內部 metric（goroutine pool 使用率、寫入延遲）作為訊號。

聚合前移

讓 SDK 端做預聚合，減少送到 collector 的事件數量。

平時：每次 click 送一筆 button.clicked 事件 → 100 次 click = 100 筆事件。 聚合前移：SDK 累積 10 秒內的 click → 送一筆 button.clicked 帶 count: 17 → 100 次 click = ~10 筆事件。

聚合前移犧牲的是事件粒度（失去每次 click 的精確時間戳），換取的是 10x 的事件量減少。適用於高頻但單筆資訊量低的事件（click、scroll、mousemove）。

聚合前移的觸發也可以是動態的 — collector 回 429 時 SDK 自動啟用聚合前移，流量恢復後關閉。

下一步路由

• 突發流量的分類 → 突發流量的分類
• Queue 做更大規模的緩衝 → Queue 緩衝
• 不同規模的應對方案 → 規模分級應對表
• 背壓和 rate limit 的基礎 → 模組三 流量管控

本章拆開主流 sampling 策略的機制、各自適合的場景、以及 temperature、top_p 這些常見參數在這條鏈上的位置。

本章目標

讀完本章後、你應該能：

1. 解釋 temperature=0 跟 temperature=0.8 的具體差別。
2. 區分 top-k、top-p、min-p 三者的機制。
3. 看到 repetition_penalty=1.1 設定時、知道它解什麼問題。
4. 解釋為什麼確定性測試要設 temperature=0 + seed。

從 logits 到下個 token

複習一下 LLM 輸出端的鏈：

1final hidden states → output projection → logits → temperature → softmax → 機率分佈
2→ sampling 策略 → 下個 token

各環節在 sampling 中的位置：

實際參數順序視推論伺服器實作而異、但概念上是這條鏈。

Greedy Decoding：永遠選機率最大

Greedy decoding 的核心定義是「每步選 softmax 後機率最大的 token」：

1next_token = argmax(probabilities)

特性：

• 確定性：同 prompt 永遠生同樣輸出。
• 快：不用 sampling、不用算 cumulative probabilities。
• 缺點：傾向選最常見 pattern、輸出單調；常陷入 repetition loop。

實務用途：

• Reproducible 評估：跑 benchmark、自動測試。
• 單元測試：確保模型輸出可預測。
• 某些 reasoning chain：選最有信心的下一步。

效果上等同 temperature=0、許多推論伺服器把兩者當同義詞。

Beam Search：保留 top-K 條候選序列

Beam search 的核心想法是「每步保留累積機率最大的 K 條序列、每條繼續展開、最後選整體機率最高的」。K 叫 beam size。

特性：

• 全局較優：不只看當步、考慮整段序列。
• 適合「有正確答案」的任務：翻譯、摘要、code 生成。
• 缺點：對 open-ended 生成（聊天、創意寫作）會 collapse 到平庸、缺乏多樣性。

具體失效症狀：K=5 在 chat 場景常產生「Sure!」「Thank you」「That’s a great question」這種高頻 boilerplate、各 beam 探索的方向都收斂到相似的平庸開頭、明明 logit 分佈本來該保留的多樣性被 beam 平均化掉。

Chat / 對話場景多半不用 beam search、用 sampling 策略保留多樣性。

Temperature：調分佈尖銳度

Temperature 的機制在 模組二 2.1 已經詳細展開。簡單回顧：

1adjusted_logits = logits / temperature
2probabilities = softmax(adjusted_logits)

實務經驗：

• 寫 code 場景設 0.2 ~ 0.4 較穩。
• 創意任務（寫故事、brainstorming）設 0.8 ~ 1.0。
• Reproducible 測試設 0 + 固定 seed。
• T > 1.5 失效症狀：產出開始出現拼字錯誤、語法破洞、UTF-8 byte 混亂、甚至跨語言突然切換；極端 T 等同近 uniform 分佈、模型結構被當作 dice。

Temperature 在 sampling 鏈上的位置（行 26 的流程鏈）跟其他過濾步驟有疊加順序、值得展開：

1. Temperature 先動分佈尖銳度：高 T 把分佈拉平、低 T 拉尖。
2. 再過 top-p / top-k / min-p：在拉平 / 拉尖後的分佈上做候選過濾。
3. 兩者相乘的常見坑：高 T（如 1.5）+ 低 top-p（如 0.5）= 「分佈被拉平、然後只挑前幾名」、實際出現的多樣性反而被壓縮、容易出現語義跳動。穩健做法：固定其中一個（多半是 top-p=0.9）、調另一個。
4. Reasoning model 的特殊性：o1、DeepSeek-R1 等內建 chain-of-thought 的模型、官方建議 T=0 或 1.0、調 T 會破壞 reasoning trace 連貫性。

Top-K Sampling

Top-K sampling 的核心定義是「只考慮機率最大的 K 個 token、其他設 0、重新正規化後取樣」：

11. 對機率排序、取最大的 K 個。
22. 其他設 0。
33. 重新正規化（讓總和為 1）。
44. 從正規化分佈取樣。

K 控制候選範圍：

缺點：K 是固定值、無法適應分佈尖銳度。當分佈尖銳時（一個 token 機率 90%）、K=40 包括很多近 0 機率的雜訊；當分佈平坦時（每個 token 機率 1%）、K=40 過於限制。具體失效症狀：在 code 生成情境、模型對「下一個 token 是 )」極度確定（95%+ 機率）時、K=40 把後面 39 個近零雜訊也納入候選、偶爾 sample 出語法錯的字元；改用 top-p 或 min-p 可避開。

Top-P / Nucleus Sampling

Top-P sampling（也叫 nucleus sampling、Holtzman et al., 2019）的核心想法是「動態決定候選集大小」：

11. 對機率從大到小排序。
22. 從大到小累加、直到累積機率 ≥ P（如 0.9）。
33. 只保留這些 token、其他設 0。
44. 重新正規化、取樣。

例：

• 分佈尖銳（一個 token 機率 95%）：P=0.9 可能只選 1 ~ 2 個 token。
• 分佈平坦（top 10 各 5%）：P=0.9 可能選 15 ~ 20 個 token。

P 的常用值：

在 chat / coding 場景下 top-p 是主流選擇、比 top-K 彈性；reproducible 評估則回到 greedy（T=0）、不用 sampling。多數推論伺服器預設 top_p=0.9。

Min-P：自適應閾值 sampling

Min-P sampling（2024 ~）的核心想法是「設一個機率閾值、最大機率 token × P_min 以下的全部去掉」：

11. 找出最大機率 p_max。
22. 閾值 = p_max × P_min（如 0.1）。
33. 機率 < 閾值的 token 全部設 0、重新正規化。

特性：

• 自動適應分佈尖銳度（用比例而非絕對值）。
• 比 top-P 更穩定、近一兩年在開源社群興起。
• LM Studio、llama.cpp 等支援。

P_min 常用值：

Repetition Penalty

Repetition penalty 的核心想法是「對已出現的 token 降低機率、避免無限重複」：

1adjusted_logit(token) = logit(token) / repetition_penalty   if token 已出現
2                      = logit(token)                          if token 沒出現

P 大於 1 時、已出現 token 的 logit 被降低、後續 sampling 較難選到。

代價：寫 code 場景下、if、for、return 等關鍵字常出現、太高的 repetition penalty 會壞掉 code。寫 code 場景 penalty 設低（1.0 ~ 1.05）或關閉；creative writing 場景則設 1.1 ~ 1.2、避免段落 / 句子層級的重複。

Seed：固定 sampling 的隨機性

Sampling 用 random number generator 取樣。設定 seed 讓 RNG 確定性、相同 prompt + 相同 seed 給相同輸出：

1{
2  "temperature": 0.7,
3  "top_p": 0.9,
4  "seed": 42
5}

實務用途：

• Reproducible 評估：跑 benchmark 要可重複。
• A/B 測試：對比不同 prompt 在同 seed 下的差異。
• Debug：重現一個錯誤輸出。

注意：seed 不是所有伺服器都支援、OpenAI API 是 best-effort（同 seed 不保證完全一致）、本地伺服器多半支援嚴格 seed 控制。

Logit Bias：強制 / 排除特定 token

Logit bias 的機制是「對特定 token 的 logit 加減一個固定值」：

1adjusted_logit(token) = logit(token) + bias(token)

用途：

• 強制特定 token：bias = +100、softmax 後機率近 1。
• 完全禁止：bias = -100、softmax 後機率近 0。
• 微調傾向：bias = ±5、輕微傾斜。

實務用例：

• 強制輸出 JSON 格式：對 { 加 bias 在開頭。
• 避免特定詞：對敏感詞加負 bias。
• 約束輸出：限制只能用特定 vocabulary。

OpenAI、Ollama 等多數推論伺服器支援 logit_bias 參數。

Structured Output / Constrained Decoding

Structured output 的核心想法是「sampling 時加 grammar 約束、強制輸出符合特定結構（JSON、SQL、regex 等）」。實作方法：

• JSON mode：每步只允許「能讓 JSON 仍合法」的 token。
• Grammar-based：用 BNF / lark / etc. 定義語法、sampling 時 reject 違反語法的 token。
• Token mask：依當前狀態決定哪些 token 合法、不合法的 logit 設 -∞。

實務工具：

• llama.cpp 的 grammar 參數。
• Outlines、LMQL 等 framework。
• OpenAI 的 response_format: { type: "json_schema" }。

寫 code 場景中、structured output 對「要可解析的輸出」（如 commit message 格式、structured API call）很有用。

Decoding 策略對體感的影響

下表是寫 code 場景下、不同 decoding 配置的體感：

實務建議：寫 code 場景下 temperature=0.2 ~ 0.4、top_p=0.9 ~ 0.95、其他保留預設就好。Continue.dev 等 IDE 整合多半自動調整。

下一章

下一章：3.6 tokenization 算法、補完 input / output 端的細節。

點擊/觸碰感測器

點擊感測器偵測使用者和 UI 元素的互動 — 按鈕點擊、連結觸碰、選單選擇。每次互動產生一個 event 類型的事件。

哪些元素值得追蹤

追蹤粒度的判斷依據是「這個互動是否對應一個有意義的使用者意圖」。

有意義的互動（值得追蹤）：提交表單、點擊導航按鈕、觸發功能操作（連線、配對、匯出）。這些互動對應使用者的明確意圖，是 funnel 分析 的步驟候選。

低價值的互動（通常不追蹤）：滾動、hover、重複的相同操作（每秒多次的按鈕連按）。這些互動要麼太頻繁（滾動每秒觸發數十次），要麼不代表新的使用者意圖。

實作方式

Web（JS/TS）：在 document 層級用 event delegation 攔截 click 事件，過濾出帶 data-track attribute 的元素。開發者在需要追蹤的元素上加 data-track="connect-button"，感測器自動收集。不追蹤所有 click — 只追蹤被標記的。

Flutter：用 NavigatorObserver 或 custom GestureDetector wrapper。GestureDetector 包裝在需要追蹤的 widget 外層，onTap 觸發時送出事件。

效能影響

Event delegation 在 document 層級只有一個 listener，效能影響接近零。瓶頸在事件產生頻率 — 如果追蹤了高頻操作（每秒多次的滑動），事件進入 buffer 的速度可能超過 flush 的速度。用取樣控制（見本章末段）。

導航/路由感測器

導航感測器偵測使用者在不同畫面之間的切換 — page view、screen view、route change。每次切換產生一個 lifecycle 類型的事件。

平台差異

Web SPA：SPA 的 route 變換不觸發頁面載入，需要主動偵測 URL 變化。兩種偵測方式：

• History API 攔截：覆寫 pushState / replaceState，攔截 popstate 事件
• 框架層級 Hook：React Router 的 useLocation、Vue Router 的 afterEach guard

History API 攔截是 SDK 層的通用做法（不依賴框架）；框架 Hook 更精確但需要使用者整合（見 JS/TS 平台 的 SPA 路由段）。

Flutter：用 NavigatorObserver 的 didPush / didPop / didReplace 回呼。每次路由變化自動觸發，不需要使用者在每個頁面手動埋點。

Python CLI/Hook：沒有「畫面切換」的概念。對應的 lifecycle 事件是 hook.start / hook.complete — 每個 Hook 執行視為一個「畫面」。

事件 schema

1{
2  "type": "lifecycle",
3  "name": "screen.view",
4  "data": {
5    "screen_name": "TerminalScreen",
6    "previous_screen": "HomeScreen",
7    "navigation_method": "push"
8  }
9}

navigation_method（push / pop / replace / go）記錄導航方式，和 go vs push 的 UX 語意 對應。

錯誤邊界感測器

錯誤邊界感測器攔截元件級的 error — 和 auto-intercept 的全域 error 攔截互補。

和 auto-intercept 的職責分工

全域攔截捕獲「逃逸到頂層的 error」，錯誤邊界捕獲「在元件層級就被攔住的 error」。如果一個 error 被元件的 ErrorBoundary 捕獲，它不會觸發 window.onerror — auto-intercept 看不到它。錯誤邊界感測器填補這個缺口。

實作方式

React：ErrorBoundary 元件的 componentDidCatch 回呼中呼叫 monitor.error()。

Flutter：在 Widget 層用 ErrorWidget.builder 或自訂的 error handling widget。

額外 context

錯誤邊界感測器比全域攔截多一個 context — 知道 error 發生在哪個元件（component name / widget name）。這個資訊在 error 的 data schema 中記錄為 component 欄位。

效能標記感測器

效能標記感測器量測操作的延遲和系統的渲染表現。產生 metric 類型的事件。

Web Core Vitals

Web 平台用 PerformanceObserver API 自動收集三個核心指標：

• LCP（Largest Contentful Paint）：最大內容元素的載入時間
• FID（First Input Delay）：首次互動的延遲
• CLS（Cumulative Layout Shift）：累計佈局位移分數

1new PerformanceObserver((list) => {
2  for (const entry of list.getEntries()) {
3    monitor.metric(`web.vitals.${entry.entryType}`, {
4      value: entry.startTime || entry.value,
5      url: location.pathname
6    });
7  }
8}).observe({ type: 'largest-contentful-paint', buffered: true });

實務上依 entryType 分別取值（LCP 用 startTime、CLS 用 value、FID 用 processingStart - startTime），上述範例簡化示意。

Flutter frame timing

Flutter 用 SchedulerBinding.addTimingsCallback 偵測掉幀：

 1SchedulerBinding.instance.addTimingsCallback((timings) {
 2  for (final t in timings) {
 3    if (t.totalSpan > const Duration(milliseconds: 16)) {
 4      monitor.metric('render.frame_drop', {
 5        'build_ms': t.buildDuration.inMilliseconds,
 6        'raster_ms': t.rasterDuration.inMilliseconds,
 7      });
 8    }
 9  }
10});

16ms 是 60fps 的單幀預算。超過代表掉幀。

自訂 duration 量測

業務操作的延遲用手動標記量測：

1final stopwatch = Stopwatch()..start();
2await connectToTerminal();
3stopwatch.stop();
4monitor.metric('terminal.connect.duration', {
5  'duration_ms': stopwatch.elapsedMilliseconds,
6});

輸入敏感度感測器

輸入敏感度感測器偵測使用者正在輸入敏感資料 — 密碼欄位、API key 輸入、信用卡號碼。這個感測器的責任是觸發 redaction，而非記錄輸入內容。

偵測邏輯

Web：偵測 <input type="password">、帶有 autocomplete="cc-number" 或 data-sensitive attribute 的欄位。當使用者 focus 這些欄位時，標記當前 session 進入「敏感輸入模式」— 後續的事件自動加嚴 redaction 規則（例如暫停記錄按鍵事件）。

Flutter：偵測 TextField 的 obscureText: true 或 enableIMEPersonalizedLearning: false（見 安全敏感輸入框的 IME 控制）。

不記錄的原則

輸入敏感度感測器偵測「使用者正在輸入敏感內容」這個事實，但不記錄輸入的內容本身。送出的事件只包含：

1{
2  "type": "lifecycle",
3  "name": "input.sensitive_mode.entered",
4  "data": { "field_type": "password" }
5}

取樣策略設計

感測器產生的事件量可能很大（效能標記每 30 秒一筆 × 活躍使用者數）。取樣控制事件量、避免 SDK 和 collector 的資源壓力。

三種取樣模式

全收：每筆事件都送出。適合事件量低且每筆都有價值的類型 — error（每筆都可能是新 bug）、lifecycle 狀態轉換（量低）、認證失敗（安全敏感）。

百分比取樣：隨機丟棄一定比例的事件。適合高頻的效能和行為事件。取樣率由 SDK config 控制：

1sensors:
2  metric:
3    render.frame_drop: { sampling: 0.1 }    # 只收 10%
4    resource.memory: { sampling: 0.5 }       # 收 50%
5  event:
6    feature.*.used: { sampling: 1.0 }        # 全收
7    click.*: { sampling: 0.1 }               # 只收 10%

百分比取樣的代價是低機率事件可能被漏掉（取樣 10% 時、發生 5 次的事件可能一次都沒收到）。

條件取樣：正常情況下取樣、特定條件下全收。適合「平時不需要全量但問題發生時需要完整資料」的場景。例：正常 session 取樣 10%、但 session 內發生 error 後、該 session 剩餘事件全收（error session 的完整 context 比正常 session 更有價值）。

取樣率的管理

取樣率可以從三個層級設定：

三個層級由上到下優先順序遞增 — feature flag 覆蓋 collector config、collector config 覆蓋本地 config。

下一步路由

• 動機驅動的事件設計（哪些動機需要哪些感測器） → 動機驅動的事件設計
• 感測器的啟停控制和生命週期 → 感測器生命週期管理
• 被動攔截機制（和感測器互補） → 自動攔截機制
• 安全敏感輸入的完整 checklist → 安全敏感輸入框的 IME 控制

兩種取樣

靜態取樣：SDK config 中設定固定比例（例如 metric 類 0.1 = 每 10 筆只收 1 筆），在 SDK 整個生命週期保持不變。適合已知高頻但單筆 debug 價值低的事件（render.frame_time、scroll.position）。

動態取樣：SDK 在收到 collector 的 HTTP 429 後自動降低取樣率，collector 恢復正常後逐步回升。動態取樣在正常情況下不生效（取樣率 = 1.0），只在 collector 過載時啟用。和靜態取樣互補 — 靜態控制基線負載，動態應對突發。

取樣校正

分析時用取樣率還原原始量級。取樣率 0.1 時收到 100 筆事件，推估原始量為 100 / 0.1 = 1000 筆。SDK 端的 sdk.sampling.rate 指標記錄當前取樣率，讓下游分析知道如何校正。取樣校正對 funnel 和 cohort 分析有效（趨勢和比例不變），對個別事件追蹤無效（被丟棄的事件無法回復）。

設計責任

取樣承擔的設計責任是「在可觀測性覆蓋率和系統負載之間找到平衡」。Error 類事件不做取樣（每筆都可能是需要修的 bug），metric 類事件適合高比例取樣（丟幾筆不影響趨勢），event 類和 lifecycle 類取決於分析需求。

完整章節

靜態取樣率的設定 → 感測器生命週期管理。動態取樣在四層防線中的位置 → Ingestion Scaling。取樣造成的損失量化和控制 → 端到端資料完整性。

五個階段

早期開發

開發期的首要需求是 debug — 程式碼寫完跑起來、出問題時能定位。

開發期的取樣率全部設 1.0（全收）— 事件量極低（開發者自己操作），不需要取樣。

功能測試

針對被測功能開啟完整感測器，驗證功能的行為事件和效能指標是否正確觸發。

被測功能的 event 和 metric 全開。其他功能維持開發期設定。測試期間的感測器設定通常由測試 config 檔覆寫 SDK 預設值。

Production 上線

上線後的感測器組合平衡覆蓋率和成本：

A/B 測試

實驗感測器只對 treatment group 啟用。Control group 不觸發實驗事件，避免污染對照組資料。

實驗專用事件（experiment.pricing_test.assigned、experiment.pricing_test.converted）由 feature flag 控制 — flag 開啟時 SDK 才送這些事件。實驗結束後 flag 關閉，感測器自動停止。

實驗事件的保留期和實驗週期綁定，實驗結束 + 分析完成後可以 purge。

功能下線

功能移除時，對應的感測器 config 一起移除。Collector 端 purge 該功能的歷史事件（或降級到聚合摘要）。

移除 checklist：SDK config 移除事件名稱 → SDK 版本部署 → 確認 collector 不再收到該事件 → purge 歷史資料（可選）。

控制機制

三層控制機制各自適合不同的變更頻率：

SDK init config（靜態）

隨 app 版本部署的本地設定檔。變更需要發新版本。適合穩定的感測器組合。

 1sensors:
 2  error: { enabled: true, sampling: 1.0 }
 3  lifecycle: { enabled: true, sampling: 1.0 }
 4  event:
 5    funnel.*: { enabled: true, sampling: 1.0 }
 6    click.*: { enabled: true, sampling: 0.1 }
 7  metric:
 8    duration: { enabled: true, sampling: 0.5 }
 9  experiment:
10    pricing_test: { enabled: false }

Collector 端下發（動態）

SDK 啟動時從 collector 的 /config endpoint 拉取當前的感測器設定。Collector 端修改設定後，下一次 SDK 重啟或定期 refresh（每 5 分鐘）時生效。適合需要動態調整但不值得接 feature flag 服務的場景。

MVP 階段跳過 collector 下發，只用 SDK 本地 config。下發 API 的定義和實作標為第二階段 — 感測器的開關在 SDK 本地 config 已經能完全控制。

Feature flag 服務整合

SDK 在送出事件前查詢 feature flag 判斷感測器是否啟用。適合 A/B 測試 — flag 可以按使用者 / 百分比 / 條件分群啟用。

優先順序

三層控制的覆蓋優先順序：

1Feature flag > Collector 下發 > SDK 本地 config

SDK 本地 config 是 baseline。Collector 下發覆蓋 baseline 的特定欄位。Feature flag 覆蓋一切 — 即使本地 config 和 collector 都說啟用，flag 說關閉就關閉。

取樣率設計

取樣率決定「多少比例的事件會被實際送出」。取樣在 SDK 端執行 — 不送的事件不佔頻寬和儲存。

全收（sampling: 1.0）

每筆事件都送。適用於：

• error：每個 production error 都有 debug 價值，漏掉的 error 可能是最嚴重的那個
• 安全事件：auth 失敗、權限越界的取樣可能讓攻擊嘗試隱形
• 漏斗關鍵步驟：funnel 分析的轉換率計算需要精確的步驟計數

百分比取樣（0.01-0.5）

只送一定比例的事件。適用於高頻且個別事件價值低的場景：

• scroll / mousemove / hover：每秒觸發數十次，全收會產生大量事件。取樣 1-10% 足以分析使用者行為模式
• frame rate 量測：每幀一筆 metric 太多，每秒或每 30 秒取一筆足夠

取樣的實作用 SDK 端的隨機數 — if random() < sampling_rate then send(event) — 不需要 server 端參與。

條件取樣（retrospective full capture）

正常情況取樣，但發生 error 時回溯收集該 session 的全部事件。實作方式是 SDK 在記憶體中保留最近 N 筆事件的環形 buffer，觸發 error 時把 buffer 中的事件一併送出。

條件取樣讓「error session 的上下文完整」和「正常 session 不過度收集」兩個目標共存。

感測器開關的可觀察性

感測器本身的狀態變化需要被觀察 — 如果感測器靜默失效（config 錯誤導致某類事件停送），開發者可能很久後才發現「怎麼最近沒有 funnel 資料」。

啟動時 log 感測器清單

SDK 初始化完成時 log 當前啟用的感測器清單和取樣率。開發者在 debug console 就能看到「哪些感測器在跑」。

Config 變更事件

感測器 config 變更時（collector 下發新 config、或 feature flag 變化），SDK 送一個 lifecycle 事件：

1{
2  "type": "lifecycle",
3  "name": "sensor.config.changed",
4  "data": {
5    "source": "collector_push",
6    "changed": {"click.*": {"sampling": "0.1 → 0.05"}},
7    "active_sensors": 12
8  }
9}

這筆事件讓開發者在查詢時能看到「某個時間點感測器 config 改變了」，和事件量的變化做交叉比對。

下一步路由

• 感測器偵測哪些行為 → 前端感測器設計
• SDK 的公開 API → SDK 公開 API 設計
• 四類事件的定義 → 四類事件的完整定義
• 事件枚舉方法 → 事件枚舉與補齊檢查

本章目標

讀完本章後、你應該能：

1. 解釋「grammar 強制」是在 sampling 階段哪一步做的。
2. 區分 JSON schema / regex / CFG 三種 grammar 的適用場景。
3. 看 XGrammar / outlines / llama.cpp grammar 等實作、能對應到本章 framing。
4. 判讀「constrained decoding 加速還是拖慢」的具體場景。

Sampling 階段的位置

回顧 LLM 輸出流程（見 3.5）：

1[forward pass] → logits（vocab_size 維、每個 token 一個實數）
2       ↓ apply temperature（logits / T）
3       ↓ apply constrained decoding（本章聚焦）  ← grammar mask
4       ↓ softmax → probability distribution
5       ↓ top-p / top-k / sampling
6       ↓ next token

Constrained decoding 在 softmax 之前插入 grammar mask：

1For each position：
2  1. Grammar 算當前位置的「合法 token 集合」（vocab 子集）
3  2. 對不在合法集的 token、logit 設 -∞
4  3. Softmax 後、不合法 token 機率為 0
5  4. Sampling 只可能選到合法 token

關鍵理解：grammar 不改變模型本身、不改變 logits 數值（除了 mask 部分）、只是限制 sampling 空間。

三種主流 grammar

JSON Schema

1{
2  "type": "object",
3  "properties": {
4    "name": {"type": "string"},
5    "age": {"type": "integer", "minimum": 0}
6  },
7  "required": ["name"]
8}

LLM 輸出必須是合法 JSON 且符合 schema。實作：

1當前已生：'{"name": "alice", '
2  ↓ 算下一個合法 token：
3  - 必須繼續產合法 JSON
4  - schema 還沒填 age（optional）但 name 已填、所以 } 合法、"age" 也合法
5  - 不合法：'{' / ']' / 任意其他 key
6  ↓ Token mask 套用
7  → 模型只能選 } 或 "age"

Regex

1\d{3}-\d{4}-\d{4}  # 台灣 phone number 格式

LLM 輸出必須符合 regex。實作：

1當前已生：'09'
2  ↓ 算下一個合法 token：
3  - regex 期望 \d 接下來
4  - 合法 token：'0'-'9' 開頭的 token
5  - 不合法：字母、符號
6  ↓ Token mask

CFG（Context-Free Grammar）

用 BNF / EBNF 描述合法語法：

1expr   ::= term ("+" term)*
2term   ::= number | "(" expr ")"
3number ::= [0-9]+

LLM 輸出必須符合此 grammar。實作：

1當前已生：'(1+2'
2  ↓ CFG 算當下合法 next token：
3  - 已 match 部分 term + "+" + term
4  - 合法：")" 或 "+" 開始新 term
5  - 不合法：字母、其他符號
6  ↓ Token mask

CFG 是最強表達力、但實作最複雜。SQL / 程式碼 generation 多用 CFG-based grammar。

XGrammar 的 pre-compile 機制

XGrammar（Dong et al., 2024）是 2024-2025 主流的高效實作。核心優化：

 1Naive 實作（如 outlines 早期版）：
 2  每次 sampling 都重算 grammar state
 3  每個 token 都跑一次 grammar parse
 4  → 開銷大、可能拖慢 generation
 5
 6XGrammar 優化：
 7  1. Pre-compile grammar → 確定性 DFA / push-down automaton
 8  2. Cache 每個 grammar state 的「合法 token mask bitmap」
 9  3. Sampling 時 O(1) 查表得到 mask
10  4. Mask 用 bitwise op 套用到 logits

效果：grammar 套用 overhead 趨近 0、甚至因為跳過 boilerplate token 反而加速：

1無 grammar 生 JSON：
2  {     " n a m e "     : " a l i c e " ...
3  ←     每個 token 都跑 forward pass    →
4
5有 grammar 生 JSON：
6  跳過固定 token（{ " : 等）、直接生關鍵字串
7  forward pass 次數減少
8  → 實測加速 1.5-3×

主流推論伺服器（vLLM、SGLang、TensorRT-LLM）2025 後預設用 XGrammar。

性能取捨：加速還是拖慢

常見誤解：「constrained decoding 拖慢生成」。實際看實作：

判讀：用主流推論伺服器（vLLM / SGLang）+ XGrammar 路線、constrained decoding 通常加速；自己寫 naive 實作可能拖慢。

跟 function calling 的關係

兩個概念可獨立、也可疊用：

主流商業 API（Anthropic / OpenAI / Gemini）的 function calling 通常內部已用 constrained decoding、開發者無感。本地推論用 vLLM / SGLang + XGrammar 也是預設組合。

失敗模式

1. Grammar 太嚴讓模型「該說的話說不出來」

1Schema 強制 type 是 enum ["A", "B", "C"]
2但真實答案是「none of the above」
3→ 模型強制選 A/B/C、輸出語義錯誤

緩解：enum 加 fallback option（“unknown” / “none”）、schema 別過度約束

2. CFG 太複雜、編譯失敗 / 慢

1復雜 CFG（如完整 SQL grammar）pre-compile 數秒
2production cold start 多花這數秒

緩解：cache compiled grammar、用較簡單 grammar 版本（如「INSERT only」而非完整 SQL）

3. Grammar 跟 model 訓練分佈不符

1Schema 要求很罕見的 JSON 結構
2模型訓練沒見過這結構
3即使 grammar 強制合法、語義可能空洞

緩解：grammar 用模型訓練過的形態（function call spec、common JSON）、自定義 schema 加 few-shot example

4. Streaming 跟 grammar 衝突

1Streaming 邊生邊輸出
2Grammar 中段 token 可能要 backtrack 修正
3streaming UX 跳字

緩解：用 incremental-parsing grammar（XGrammar 支援）、避免 backtrack 場景

5. Constrained decoding 蓋過 function calling 訓練

1模型訓練用 OpenAI function spec、應用強制套 Anthropic tools 的 grammar
2模型輸出「合法但語意空洞」（schema 對、欄位胡亂填）

緩解：grammar spec 跟模型訓練 spec 一致、別人工維護兩份不同 schema

何時不該用 constrained decoding

1. 自由 / 創意輸出：寫作、brainstorming、grammar 限制模型表達
2. 可靠的 model + simple format：模型本身能穩定輸出 JSON、grammar overhead 不必要
3. Grammar 太嚴有語義錯：見失敗模式 1
4. Streaming + 複雜 grammar：streaming UX 受影響

主流實作詳細

何時過時 / 何時不過時

不會過時的部分：

• Constrained decoding 在 sampling 哪一步插入（softmax 之前）的 framing
• 三種 grammar 類型（JSON schema / regex / CFG）的分類
• Token mask 機制（不合法 token logit 設 -∞）
• 「正確實作下加速、不是拖慢」的反直覺結論
• 5 大失敗模式分類

會變的部分：

• XGrammar / outlines 等實作的具體效能跟功能
• 主流推論伺服器的預設 grammar engine
• JSON schema spec 標準化（新版會出）
• Function calling + constrained decoding 是否會被 native multimodal 取代

下一章

下一章：3.11 想學更深、整個模組三理論基礎走完。