# 評估系統 > 屬於 [research/](./README.md)。涵蓋 LLM-as-Judge、Reasoning Model、評估維度、Judge 設計原則。 --- ## 10. LLM-as-Judge：用 AI 評估 AI ### 概念傳統方法：人工看 30 筆 Q&A 打分數（慢、貴、主觀）。 LLM-as-Judge：讓另一個 AI 當評審，自動評分（快、便宜、可重複）。 ``` [待評估的 Q&A] Q: Discover 流量下降的原因？ A: 可能是內容品質或 AMP 問題，建議觀察 GSC... ↓ 送給 gpt-5.2（評審） [評分結果] { "relevance": {"score": 5, "reason": "精準捕捉核心 SEO 知識"}, "completeness": {"score": 3, "reason": "缺少具體行動建議"}, "accuracy": {"score": 4, "reason": "論述合理"}, "granularity": {"score": 5, "reason": "問題聚焦單一主題"} } ``` ### 本專案四個評估維度 | 維度 | 問的問題 | v1.0 分數 | v2.12 分數（2026-03-05） | | ------------ | ------------------------------- | --------- | ------------------------ | | Relevance | 是否有價值的 SEO 知識（非閒聊） | 4.80 | **5.00** ✅ | | Accuracy | 內容是否合理無虛構 | 3.95 | **4.30** ✅ | | Completeness | 是否包含建議 + 原因 + 案例 | 3.85 | **3.95** ✅ | | Granularity | 一個 Q 只問一個主題 | 4.75 | **4.75** ✅ | ### 注意：Judge 本身也可能出錯今天（2026-02-27）修的兩個 bug 就是 Judge 失效： - BUG-001：分類 Judge 大量回傳空結果 → 正確率假的 10%，真實 75% - BUG-002：Retrieval Judge token 不夠 → Precision 假的 10%，真實 100% **原則**：看到評估結果異常（< 20% 或 > 98%），先懷疑是評估系統本身的問題。 --- ## 11. Reasoning Model：會先思考的 AI ### 兩種模型的差異 ``` 標準模型（如 gpt-3.5, gpt-4）：輸入 → 直接輸出推理模型（如 o1, o3-mini, gpt-5-mini, gpt-5.2）：輸入 → [內部思考過程] → 輸出 ``` 推理模型在回答前會先做「chain of thought」（思維鏈），能處理更複雜的推理問題，但使用上有兩個陷阱。 ### 陷阱一：`max_completion_tokens` 要給更多 ```python # max_completion_tokens 由「思考 + 輸出」共用 # 標準模型： # 256 tokens 全給輸出 → 夠了 # 推理模型： # 256 tokens：200 tokens 用於思考，只剩 56 給輸出 # → finish_reason: "length"（被截斷） # → content = ""（空字串） # 本專案 BUG-002 的根因，修復： max_completion_tokens=256 # ❌ max_completion_tokens=1024 # ✅ ``` ### 陷阱二：content 可能回傳空字串 ```python # 標準模型：content 永遠有值 # 推理模型：token 超限時，content = "" # 錯誤寫法（本專案修復前）： content = response.choices[0].message.content or "{}" # "" or "{}" → "{}" → json.loads("{}") → {} → 靜默失敗 # 正確寫法（修復後）： content = response.choices[0].message.content if not content: print("⚠️ 推理模型回傳空內容，可能 token 不足") return fallback # 或者，append 前先驗證必要欄位存在： if "category_judgment" not in result: continue # 不計入統計 ``` ### 診斷方法 ```python # 確認是否被截斷 print(response.choices[0].finish_reason) # "stop" → 正常完成 # "length" → token 超限，輸出不完整 ``` --- --- ## 14. 評估維度詳解與基準線 ### 四個評估維度說明 | 維度 | 問的核心問題 | 評分標準（1-5） | | ---------------- | ---------------------------------- | ---------------------------------------------- | | **Relevance** | 這是真正有價值的 SEO 知識嗎？ | 1=完全無關閒聊；5=高濃度可複用知識 | | **Accuracy** | A 是否忠實反映原始會議內容？ | 1=明顯錯誤或虛構；5=完全符合來源 | | **Completeness** | A 是否有足夠深度讓讀者理解並行動？ | 1=只有結論無原因；5=What+Why+How+Evidence 齊全 | | **Granularity** | Q 的聚焦程度是否恰當？ | 1=問題過於廣泛；5=聚焦單一具體主題 | ### 評估分數要求的完整行動建議 | 維度 | 目標分數 | 最新數值（v2.12） | 狀態 | 提升方法 | | ------------ | -------- | ----------------- | -------- | ------------------------------------- | | Relevance | ≥ 4.5 | **5.00** | ✅ | 無需調整 | | Accuracy | ≥ 4.0 | **4.30** | ✅ | v2.0 防幻覺規則已達標 | | Completeness | ≥ 4.0 | **3.95** | 接近目標 | `[補充]` Tag 機制已實作（見第 13 節） | | Granularity | ≥ 4.5 | **4.75** | ✅ | 無需調整 | ### 額外評估指標說明 - **Confidence 校準**：Q&A 的 `confidence` 值應與實際品質相關（高 confidence → 高 Accuracy） - **Self-contained**：Q 不依賴原始會議就能理解（目前 Granularity 4.65 說明已做好） - **Actionable**：A 提供具體可執行建議（Completeness 的核心要求） - **Faithfulness**：A 的內容來自原始文件，不是 AI 自行補充（Accuracy 的核心要求） ### Retrieval Data Dimensions 評估口徑（2026-03-15） Retrieval eval 現在分成「過渡 gate」與「穩定 gate」兩層，避免 schema / rerank 剛升級時直接拿舊 precision baseline 做硬比較。新增正式指標： | 指標 | 用途 | | ---------------------------- | --------------------------------------------------------- | | `dual_category_recall_at_k` | dual-label case 是否同時覆蓋多個 category | | `multi_label_f1_at_k` | multi-label precision / recall 的調和平均 | | `boosterless_precision_at_k` | 排除 booster 後，canonical / supporting corpus 的真實純度 | | `ndcg_at_k` | 考慮 ranking 位置的相關度品質 | | `canonical_top1_rate` | top-1 是否由 canonical corpus 提供 | | `duplicate_rate_at_k` | top-k 是否被近重複答案汙染 | | `intent_coverage_at_k` | top-k 是否覆蓋 query 需要的 intent | 目前過渡 gate 寫在 `eval/eval_thresholds.json`： - `precision_at_k >= 0.65` - `dual_category_recall_at_k >= 0.75` - `multi_label_f1_at_k >= 0.68` - `boosterless_precision_at_k >= 0.60` - `ndcg_at_k >= 0.75` 穩定 gate（`retrieval_stable`）則要求： - `precision_at_k >= 0.72` - `dual_category_recall_at_k >= 0.82` - `multi_label_f1_at_k >= 0.75` - `boosterless_precision_at_k >= 0.65` - `ndcg_at_k >= 0.80` 這套口徑的重點是把 improvement 拆開看：是 corpus coverage 改善、是 ranking / rerank 改善，還是 booster 只把分數硬拉高。因此 `slice_metrics` 與 `failure_buckets` 也成為正式輸出，而不是 debug-only artifact。 ### Two-tier gate 的使用時機 - `retrieval`：過渡 gate。當 schema、rerank、retrieval surface 剛升級時先用這層追蹤方向，避免一開始就被舊 baseline 卡住。 - `retrieval_stable`：穩定 gate。當連續數輪 eval 都穩定通過過渡 gate，且沒有出現 MRR / NDCG 回退或 booster inflation，才把它當成 production bar。實務上，若只過 `retrieval` 但沒過 `retrieval_stable`，表示系統方向正確，但還不能視為 fully stabilized；此時應繼續觀察 slice metrics，而不是立即宣稱 migration 完成。 ### 成熟度評估維度（v3.3–v3.4） v3.3 起，成熟度模型（L1-L4）成為評估體系的新橫切維度： | 評估器 | 類型 | Laminar Group | 說明 | | -------------------------------- | ------------ | ------------------------ | -------------------------------------------- | | `s8_meta_maturity_consistency` | rule-based | `meeting_prep_structure` | meta JSON 與 S8 表格的 L1-L4 一致性 | | `s10_maturity_upgrade_labeled` | rule-based | `meeting_prep_structure` | S10 checklist 是否含 `[策略 L1→L2]` 升級標籤 | | `report_action_maturity_labeled` | rule-based | `report_quality` | 報告 S5 是否含成熟度參考區塊 | | `s8_maturity_justified` | LLM-as-Judge | `meeting_prep_quality` | 成熟度評分是否有根據（非隨意標注） | **成熟度與四層評估框架的關係**： - **L1 Data Quality**：`maturity_relevance` 欄位完整度（backfill coverage） - **L2 Retrieval**：`applyMaturityBoost()` 不退化現有 golden retrieval（35 cases） - **L3 Enhancement**：Chat system prompt 注入成熟度脈絡，回答深度適配 - **L4 Context**：Session 跨輪次成熟度持久化，一致性體驗 ### L4 External Sources 評估快照（2026-03-14）這一輪不是單純「多加幾個 external-source case」，而是把 retrieval gate、golden dataset、成熟度欄位完整度一起重新校正。 #### 1. Golden retrieval dataset 從 35 擴到 40 cases 新增的 5 個 case 都是 L4 external-source 情境，主題集中在 AI Search / AI Overviews： - AI Overview 品牌可見度因子 - AI Overviews 觸發因素與安全區查詢 - AI Overviews 對點擊率衝擊 - AI 搜尋流量轉換率與策略調整 - 國際頁面在 AI Search 的流量落差這個擴充的意義不是單純加量，而是把原本偏向傳統 SEO / GSC 診斷的 eval，補上較新、較策略層、較接近 L4 的 query distribution。 #### 2. Formal retrieval eval 在 40 cases 下仍維持綠燈新增 case 後曾出現單點風險：`MRR 0.8914 < 0.9`。後續在 `scripts/add_retrieval_boosters.py` 增加 impression/click gap 的 targeted booster 後，formal retrieval eval 再次通過。這裡的評估解讀要分兩層： - 若只看 pass/fail，結論是 40-case gate 仍為綠燈 - 若看 failure mode，則可知新 L4 query 對 ranking 前位次更敏感，特別容易在 CTR / SERP-diagnosis 類查詢拉低 MRR 因此這次 pass 的價值，不是分數更漂亮，而是證明 external-source 擴充後，系統仍能守住 ranking quality。 #### 3. L4 達標的根因其實是 maturity metadata 回填最初假設是 external-source coverage 不足導致 L4 比例過低；實際檢查後發現，主要問題是大量 QA 沒有 `maturity_relevance`。回填後的本地 `qa_enriched.json` 分布： - `NULL 775` - `L1 58` - `L2 602` - `L3 264` - `L4 110` 所以目前正確的評估結論應該是： - external sources 提供了 L4 語料增量 - 但真正讓 L4 ratio 達標的是 `scripts/enrich_qa.py` 對 `maturity_relevance` 的系統性 backfill - 本地 artifact 現在已達 `110 / 1809 = 6.08%` 這也說明，未來追 L4 coverage 時不能只盯資料來源數量，必須把 `metadata completeness` 視為正式 data-quality gate。 #### 4. 評估時必須區分本地 artifact 與 production serving state 目前 eval 通過與 L4 達標，指的是本地 artifact 狀態，不是 production Supabase 完整對齊後的結果。原因： - production `qa_items` 仍缺少 retrieval metadata schema - API 目前是靠 base-schema fallback 恢復搜尋 - migration `010_retrieval_metadata_columns.sql` 雖已準備，但尚未套用到遠端因此在解讀任何 production 指標前，需先回答一個問題： > 這個數字反映的是本地 curated artifact，還是 remote Supabase serving corpus？如果兩者未明確區分，就會誤把「本地已達標」解讀成「線上 schema 已完成」。 #### 4.5 2026-03-15 phase 1-2 驗證快照在 2026-03-15 這輪實作中，retrieval 與 queryability 的評估重點不再只是「能不能找到」，而是拆成兩個 gate： 1. phase 1：ranking quality 是否提升 2. phase 2：metadata queryability 是否上線且不回退 ranking 最終使用 file-mode API（`http://localhost:8003`）重跑 `evals/eval_retrieval.py` 的結果為： | 指標 | 結果 | | ---------------------------- | -------- | | `keyword_hit_rate` | `0.9329` | | `top1_category_match` | `0.95` | | `top5_category_coverage` | `0.82` | | `hit_rate` | `1.0` | | `mrr` | `0.975` | | `precision_at_k` | `0.82` | | `recall_at_k` | `0.8875` | | `dual_category_recall_at_k` | `0.8875` | | `multi_label_f1_at_k` | `0.8297` | | `boosterless_precision_at_k` | `0.8175` | | `ndcg_at_k` | `0.8921` | 這組數字的解讀方式如下： - `top1_category_match`、`mrr`、`precision_at_k`、`ndcg_at_k` 明顯高於最初 baseline，代表 rerank 與 metadata enrich 確實讓前排結果更準 - `keyword_hit_rate` 沒有回到最早的單點高位，但仍穩定高於 eval gate，因此這輪決策是接受 tradeoff，優先保整體 ranking 品質 - phase 2 新增 route-layer metadata filters 後，再跑一次 retrieval eval，指標維持不變，表示 queryability 擴充沒有破壞 phase 1 的 serving quality 另外，API focused tests 也被納入 phase 2 gate： - `api/tests/routes/search.test.ts` - `api/tests/routes/qa.test.ts` 最終為 `40 passed`，用來驗證 metadata filters 與 response fields 已成正式 API contract，而不是只有離線 artifact 有值。 #### 5. Classifier refinement 把 L4 從「有 AI 關鍵字」收斂成「AI Search + 策略訊號」 2026-03-15 又做了一輪 rule-based classifier refinement，目標不是再把更多題目推進 L4，而是把前一天的 maturity backfill 從「大致達標」收斂成「可解釋、可防誤判」的規則。這一輪的核心改動有三個： - `utils/maturity_classifier.py` 擴充 AI Search / AIO / GEO / AEO / brand visibility / scenario planning / citation growth 等 L4 詞彙 - 新增 `AI_SEARCH_TERMS` 與 `L4_STRATEGY_TERMS` 的共現 bonus，只在 AI Search 訊號與高階策略訊號同時存在時提升 `L4` - 補上 negative guard，避免把 `預期`、`預設` 誤當成 `預測` 類的 advanced signal 對應的 regression tests 也一起補上： - AI Search 品牌可見度策略題應判成 `L4` - AI SEO 預算 / scenario planning 題應判成 `L4` - 「什麼是 AI Overview？」這類基礎說明題維持 `L1` - 含 `預期` 的簡單波動觀察題不可被誤升成 `L4` 這裡的重要評估結論不是「L4 越多越好」，而是： - AI Search 題目本身不足以代表領先期 - 只有當題目同時涉及 monitoring、competitive intelligence、scenario planning、authority building 等策略層訊號時，才應視為 `L4` - 因此 classifier 的品質指標不能只看 coverage，還要看 false positive control 在這個 refinement 後，重新執行 `scripts/enrich_qa.py` 的本地分布變成： - `NULL 748` - `L1 55` - `L2 595` - `L3 256` - `L4 155` 也就是本地 artifact 的 L4 ratio 從前一天紀錄的 `110 / 1809 = 6.08%`，進一步提升到 `155 / 1809 = 8.57%`。但這個數字的意義不是「規則更寬鬆」，而是 classifier 對 AI Search / GEO 類高階策略題的召回率提高，同時保留了對基礎 AI 解釋題的保守邊界。因此目前比較合理的成熟度評估結論是： - external sources 解決的是語料 coverage - classifier refinement 解決的是 L4 recall 與 false-positive control - phase 2 queryability 則讓這批成熟度 / retrieval metadata 可以被產品層直接使用，而不只存在離線評估報表 --- --- ## 19. LLM-as-Judge 設計原則 ### Judge Prompt 最佳實踐 **Chain-of-Thought（CoT）**：先給理由，再給分數： ```python JUDGE_PROMPT = """ 評估以下 Q&A 的 Completeness（完整性），1-5分。請先給出你的分析，再給出分數： [先分析 Answer 包含了哪些要素，缺少哪些要素] {"completeness": {"score": X, "reason": "一句話原因"}} """ ``` **為什麼 CoT 重要**：強制 LLM 先思考再評分，減少直覺偏差，分數更穩定。 ### 常見 Judge 偏差與避免方法 | 偏差類型 | 現象 | 避免方法 | | -------- | -------------------------------- | ------------------------------ | | 冗長偏差 | 長答案自動得高分 | 強調「精準簡潔也可以得 5 分」 | | 位置偏差 | 第一個選項偏高 | 固定評分順序，不做對比評估 | | 自我偏好 | 用 GPT-5.2 評 GPT-5.2 生成的內容 | 可接受，但需注意過度膨脹的分數 | ### 本專案 Judge 模型維持 gpt-5.2 **理由**： - 研究顯示 gpt-5.2 在評分一致性上表現良好 - 換成 Claude Opus 會增加跨平台複雜度 - 開源 Judge 模型（Prometheus-7B）需要自建推理環境 **改善方向**：不換模型，而是改善 Judge prompt（加入 CoT、反向偏差提示）。 --- ## 20. Pipeline 全步驟 Eval 覆蓋（Per-step Golden Sets） > 對應 `scripts/05_evaluate.py` 的 4 個新函式（v1.5 加入）。 ### 設計原則每個 pipeline 步驟都有**不同的評估指標**，必須分別設計 golden set： | 步驟 | 函式 | Golden Set | 核心指標 | | ----------------- | ---------------------------------- | --------------------------------------------------------- | ----------------------------------------------------------- | | Step 2 萃取 | `evaluate_extraction()` | `eval/golden_extraction.json`（5 cases） | count_accuracy, keyword_coverage_rate, hallucination_rate | | Step 3 去重 | `evaluate_dedup()` | `eval/golden_dedup.json`（40 pairs：20 dup + 20 non-dup） | precision, recall, F1 | | Step 3 閾值最佳化 | `evaluate_dedup_threshold_sweep()` | 同上 golden pairs | optimal_threshold（F1-optimal sweep 0.80–0.95） | | Step 4 週報 | `evaluate_report_quality()` | `eval/golden_report.json`（5 cases） | topic_coverage, kw_grounding, llm_actionability | | Step 5 Q&A 品質 | `evaluate_qa_quality()` | `eval/golden_qa.json`（50 items，10 categories） | Relevance/Accuracy/Completeness/Granularity（LLM-as-Judge） | ### Step 2 萃取評估：`evaluate_extraction()` ```python result = evaluate_extraction(golden_cases, per_meeting_dir="output/qa_per_meeting") # { # "count_accuracy": 0.80, # 萃出數量與 golden 期望的 ± tolerance 內佔比 # "avg_keyword_coverage_rate": 0.73, # golden 關鍵字實際出現在萃出結果的比例 # "avg_hallucination_rate": 0.05, # 萃出內容無法對應到原始文字的估計比例 # } ``` - **count_accuracy**：`abs(actual_count - expected_count) <= tolerance`（default tolerance=2） - **keyword_coverage_rate**：golden `expected_keywords` 中有多少出現在萃出結果的 Q+A+keywords 合集 - **hallucination_rate**：需 LLM-as-Judge 二次確認（未來擴充） ### Step 3 去重評估：`evaluate_dedup()` + threshold sweep ```python # 單一閾值評估 result = evaluate_dedup(golden_pairs, threshold=0.88) # {"precision": 0.90, "recall": 0.85, "f1": 0.875, "tp": 17, "fp": 2, "fn": 3, "tn": 18} # F1-optimal sweep（16 步，0.80–0.95） sweep = evaluate_dedup_threshold_sweep(golden_pairs) # { # "optimal_threshold": 0.86, # "optimal_f1": 0.91, # "current_threshold": 0.88, ← config.SIMILARITY_THRESHOLD # "current_f1": 0.875, # "recommendation": "降低至 0.86 可提升 F1 +0.035", # "sweep": [{"threshold": 0.80, "f1": 0.82}, ...] # 16 entries # } ``` **Threshold Sweep 原則**： 1. 先建立 labeled golden pairs（人工標記是否為重複） 2. 一次性計算所有 pairs 的 cosine similarity（避免 N×API 呼叫） 3. sweep 只改門檻值，不重複呼叫 API 4. F1-optimal 取 precision/recall 平衡點（不偏向任一側） ### Step 4 週報評估：`evaluate_report_quality()` ```python result = evaluate_report_quality(golden_cases, reports_dir="output") # { # "avg_topic_coverage": 0.78, # required_topics 實際出現在報告的比例 # "avg_kw_grounding": 0.83, # source_qa_keywords 有多少出現在報告（接地氣） # "avg_llm_grounding": 4.2, # LLM-as-Judge 評分（1-5），每週報用 2–3 個問題 # "avg_llm_actionability": 3.9, # 報告是否提供具體可行建議（1-5） # } ``` ### CLI 整合 ```bash # 個別執行 python scripts/run_pipeline.py --step evaluate-qa --eval-extraction python scripts/run_pipeline.py --step evaluate-qa --eval-dedup python scripts/run_pipeline.py --step evaluate-qa --dedup-threshold-sweep python scripts/run_pipeline.py --step evaluate-qa --eval-report # 完整評估（預設 LLM-as-Judge） python scripts/run_pipeline.py --step evaluate-qa --sample 50 --with-source ``` ### Golden Set 設計要點 - **萃取 golden**：每 case 包含 `meeting_id`、`expected_count`（±2）、`expected_keywords`、`notes` - **去重 golden**：40 pairs；20 dup（high sim）+ 20 non-dup（模糊相似但語意不同）；手工標記 `is_duplicate: bool` - **Q&A golden**：50 items；10 categories 各 ≥3 條；包含 `expected_category`、`expected_difficulty`、`expected_evergreen` - **週報 golden**：5 scenarios；含 `required_topics[]`、`optional_topics[]`、`source_qa_keywords[]`、`min_grounding_score` ### 樣本數不足的統計風險目前 extraction（5 筆）和 report（5 筆）golden set 樣本數偏小（建議 ≥20 筆達統計顯著性，參考「樣本數 n≥30 原則」）。 **影響**： - 5 筆樣本只能檢測巨幅品質變化（±20%），無法發現細微回歸（±5%） - 95% 信心區間寬度 ≈ ±35%，決策的確信度有限 **未來擴充建議**：每個場景增加至 ≥20 筆，共 100+ golden cases。 ### Self-Consistency 採樣減少隨機性 **Wang et al.（2023, ICLR）** 提出的自洽推理方法：對同一問題採樣多次，取多數意見（majority vote），比單次採樣更穩定。 **本專案建議應用場景**： - Accuracy 維度：目前單次評估，建議 3 次採樣後取中位數，減少 Judge 隨機波動 - 成本估算：700 筆 Q&A × 3 倍採樣 × `gpt-5-mini` $0.10/1M tokens ≈ 額外 $0.03 --- ## 五大 AI Provider 比較評估 > 參考：`scripts/compare_providers.py`、`research/14-provider-comparison.md`、`eval/golden_seo_analysis.json` ### 實驗設計 **任務**：給定相同 SEO GSC 資料（impressions/clicks/CTR/position 表），五個 Provider 各自生成分析報告，Judge 模型（gpt-5.2）對每份報告的 grounding、actionability、relevance 三個維度進行 1–5 分打分。 **五個 Provider**： | Provider | 描述 | |---|---| | `system_seoinsight` | 本專案 `04_generate_report.py` 生成的結構化報告 | | `chatgpt` | ChatGPT 手動操作輸出 | | `gemini_thinking` | Google Gemini 思考模式 | | `claude` | Anthropic Claude 直接輸出 | | `gemini_research` | Google Gemini Deep Research 模式 | ### 結果 | Provider | Grounding | Actionability | Relevance | 平均 | | ----------------- | --------- | ------------- | --------- | -------- | | system_seoinsight | 5 | 5 | 5 | **5.00** | | chatgpt | 4 | 4 | 4 | **4.00** | | gemini_thinking | 4 | 4 | 4 | **4.00** | | claude | 3 | 3 | 3 | **3.00** | | gemini_research | 3 | 2 | 2 | **2.33** | ### 為何 system_seoinsight 5.0 滿分 1. **Grounding**：報告引用數字時加上 `(參考：...)` 格式，Judge 可以追溯每項論斷到原始資料 2. **Actionability**：每個洞察附帶具體行動建議，而非泛泛而論 3. **Relevance**：推論型結論加上 `(推論)` 標籤，讓 Judge 區分事實與推斷 ### Golden Case 設計原則（來自本次實驗） 1. **提供結構化資料**：Judge 需要有數字可查核；純文字分析很難判斷 grounding 2. **輸出格式要有說明**：告訴 LLM Judge 要評估的是哪份檔案，避免格式混淆 3. **reason 欄位必填**：Judge prompt 要求 reason 非空，否則分數缺乏解釋 4. **多維度分離評分**：將 grounding / actionability / relevance 分開評估，比單一分更有診斷價值 ### gpt-5-mini + `response_format` 導致空白輸出 **現象**：Judge 呼叫 `gpt-5-mini` 搭配 `json_schema` response_format，回傳 `content = ""`（空字串）。 **根因**：reasoning model（`gpt-5-mini-2025-08-07`）將大量 tokens 用於 `reasoning_tokens`，導致 `output_tokens` 耗盡，content 被截斷為空。 **修正**： - 移除 `response_format` 參數，改用 prompt 指示輸出 JSON - 設定 `max_completion_tokens >= 4096`（而非預設 1024） - 加上重試邏輯（空白 → sleep 1s → retry）詳見：`~/.claude/skills/learned/openai-reasoning-model-no-response-format.md` --- --- ## Laminar Eval 框架（2026-02-28 實作紀錄） > 本節記錄將 SEO QA pipeline 接入 Laminar 的完整 eval 設計決策。 ### 三層 Eval 架構 ``` Layer 1: Tracing（@observe） → 每個 LLM 呼叫都建立 span，記錄 input/output/latency Layer 2: Online Scoring（LaminarClient.evaluators.score()） → 在 @observe 函式內，LLM 回應後立即發送 rule-based scores → 不需要額外 LLM 呼叫（binary + continuous 指標） Layer 3: Offline Evals（lmnr.evaluate()） → 批次評估，用 golden dataset 驗證能力品質 → 可排程執行，結果顯示在 Laminar dashboard ``` ### Online Evaluators 設計原則 **Rule-based（免費，無延遲）**： - `answer_length`: `float(len(answer) > 50)` — 回答是否非空 - `has_sources`: `float(len(sources) > 0)` — 是否有知識庫引用 - `top_source_score`: cosine similarity 最佳命中 — 量化 retrieval 品質 - `source_count`: `min(count/5, 1.0)` — 引用數規範化 **LLM-as-Judge（有費用）**： - 僅用於 offline eval 批次評估（不在每次 API 呼叫中執行） - 用 `evaluate()` 的 `evaluators` 參數傳入 async judge 函式 - 適合：answer_relevance、faithfulness、coherence 等主觀維度 ### Offline Eval 腳本結構（lmnr pattern） ```python from lmnr import evaluate data = [ {"data": {"input": ...}, "target": {"expected": ...}}, ] def executor(data: dict) -> dict: return {"output": my_function(data["input"])} def binary_evaluator(output: dict, target: dict) -> float: return 1.0 if condition else 0.0 def continuous_evaluator(output: dict, target: dict) -> float: return some_score_between_0_and_1(output, target) evaluate( data=data, executor=executor, evaluators={"name_a": binary_evaluator, "name_b": continuous_evaluator}, group_name="capability_name", # 用於在 dashboard 追蹤趨勢 ) ``` **規則**： - 每個 eval 至少 2 個 evaluators（一個 binary，一個 continuous） - `group_name` 統一命名格式：`{capability}_quality` - 腳本放在 `evals/eval_{capability}.py`，可用 `lmnr eval` 批次執行 ### Eval 覆蓋率表（本專案） | Capability | Eval file | Evaluators | Golden dataset | | ---------- | -------------------------- | --------------------------------------------------------------------------------- | ------------------------------------- | | Retrieval | `evals/eval_retrieval.py` | keyword_hit_rate, top1_category_match, top5_category_coverage | `eval/golden_retrieval.json` (307 筆) | | Extraction | `evals/eval_extraction.py` | qa_count_in_range, keyword_coverage, no_admin_content, avg_confidence | `eval/golden_extraction.json` | | Chat (E2E) | `evals/eval_chat.py` | has_answer, has_sources, answer_keyword_coverage, top_source_in_expected_category | 前 10 retrieval scenarios | ### lmnr 0.5.x SDK 已知 API 差異官方文件使用 `Laminar.get_trace_id()`，但 lmnr 0.5.x 沒有此方法。正確做法： ```python span_ctx = Laminar.get_laminar_span_context() trace_id = str(span_ctx.trace_id) if span_ctx else None # UUID → str span_id = str(span_ctx.span_id) if span_ctx else None ``` 詳見 `~/.claude/skills/learned/laminar-0.5x-span-context-api.md`。 --- ## eval_enrichment.py — Enrichment 品質評估（2026-03-02） > 對應 `evals/eval_enrichment.py`，使用 `eval/golden_retrieval.json`（20 筆 cases），Laminar 離線評估。 ### 三個 Evaluators | Evaluator | 類型 | 計算方式 | 目標 | | --------------------------- | ----------------- | ------------------------------------------- | ------------- | | `kw_hit_rate_with_synonyms` | binary（0/1） | 查詢展開後，top-5 是否命中 expected Q&A | ≥ 85% | | `freshness_rank_quality` | continuous（0-1） | 舊文件排名是否低於語意等效的新文件 | ≥ 0.9 | | `synonym_coverage` | binary（0/1） | 每筆 Q&A 是否有 `_enrichment.synonyms` 非空 | 1.0（全覆蓋） | ### 實驗結果（make enrich 前後） | 指標 | Baseline（qa_final.json） | After enrichment | Delta | | ------------------------- | ------------------------- | ---------------- | ----------- | | kw_hit_rate_with_synonyms | 70.4% | **79.67%** | **+9.27pp** | | freshness_rank_quality | 1.0 | 1.0 | 0 | | synonym_coverage | 0.0 | **1.0** | +100% | **解讀**： - `kw_hit_rate_with_synonyms` +9.27pp 確認同義詞擴展有效（如 "AMP" -> "Accelerated Mobile Pages"） - `freshness_rank_quality` 維持 1.0：freshness 乘法縮放未破壞相對排名 - `synonym_coverage` 0.0 -> 1.0：`make enrich` 產生 `qa_enriched.json` 後 655 筆全部有 `_enrichment` ### 目標差距與後續 - KW Hit Rate 79.67%，距 ≥85% 目標差 **5.33pp** - 方向：擴充 `utils/synonym_dict.py` 的 `_SUPPLEMENTAL_SYNONYMS`，特別是 SEO 長尾術語 - 前置條件 E2-2（Query Understanding）需 KW Hit Rate ≥ 85% 才啟動 --- ## CJK N-gram + Synonym Expansion（2026-03-02，Retrieval 優化） > 修復 v2.0 KW Hit Rate 回歸（65% -> 74%），對應 `utils/synonym_dict.py` + `scripts/qa_tools.py`。 ### 根因分析 v2.0 知識庫（655 筆）KW Hit Rate 從 v1.0 的 78% 降至 65%（-13pp），四個結構性問題： | # | 根因 | 影響 | 修復方式 | | --- | ------------------------------------------------------ | -------------------- | ---------------------------------- | | 1 | **中文分詞失效** — `str.split()` 不切中文複合詞 | 3 case 完全失敗 | CJK n-gram 展開 | | 2 | **通用詞污染** — "SEO"/"流量" 主導排名 | 不相關結果搶佔 top-1 | 只展開 query 端，不展開 keyword 端 | | 3 | **CLI 路徑繞過 enriched data** — eval 讀 qa_final.json | synonym_bonus 白費 | --use-enriched flag | | 4 | **同義詞缺失** — TTFB/WAF/工作階段/Coverage | 特定 case 0 命中 | +8 synonym entries | ### 解法：`expand_query_tokens()` 三層展開 ```python # utils/synonym_dict.py def expand_query_tokens(query: str) -> set[str]: """ Layer 1: whitespace split + CJK n-gram "內部連結架構優化" -> {內部, 連結, 架構, 優化, 內部連結, ...} Layer 2: Forward synonym CTR -> {點擊率, click-through rate, ...} Layer 3: Inverted synonym 點擊率 -> {ctr}（反向查找） """ ``` **關鍵設計決策**：只用 `_SUPPLEMENTAL_SYNONYMS`，不用 `METRIC_QUERY_MAP`。後者含 "原因"/"如何" 等噪音 token，實測讓 CTR case 從 75% 降到 25%。 ### 改善結果 | 指標 | Before | After | Delta | | ------------ | ------ | -------- | -------- | | KW Hit Rate | 0.65 | **0.74** | **+9pp** | | Cat Hit Rate | 0.80 | 0.80 | 0 | | MRR | 0.88 | 0.87 | -0.01 | ### 失敗 case 修復狀況 | Case | Before | After | | -------------------- | --------------------- | -------- | | 內部連結架構優化 | **0%** (ZERO results) | **75%** | | 伺服器回應時間上升 | 低 | **100%** | | 當週文章數銳減 | 低 | **100%** | | 有效頁面數持續下滑 | 低 | **100%** | | 曝光上升但點擊未同步 | ~20% | **60%** | ### 仍待改善 case | Case | 目前 | 瓶頸 | | ------------------ | ---- | ---------------------------------------------------------- | | 檢索未索引大幅增加 | 40% | expected_keywords 需更精準 | | 手機 CWV 劣化 | 40% | "Core Web Vitals" 同義詞已有，但 golden case keywords 偏寬 | | 圖片搜尋流量下降 | 50% | 知識庫缺少 "image search" 專題 Q&A | ### eval Laminar 執行方式 ```bash # 執行 enrichment make enrich # 重跑 eval 比較前後 python evals/eval_enrichment.py # Laminar dashboard 可查看歷史趨勢 # group_name: "enrichment_quality" ``` ### Eval 覆蓋率表（更新後） | Capability | Eval file | Evaluators | Golden dataset | 狀態 | | -------------- | ------------------------------ | ----------------------------------------------------------------------- | ----------------------------------------- | ----------- | | Retrieval | `evals/eval_retrieval.py` | keyword_hit_rate, top1_category_match | `eval/golden_retrieval.json`（307 筆） | ✅ | | Extraction | `evals/eval_extraction.py` | qa_count_in_range, keyword_coverage | `eval/golden_extraction.json` | ✅ | | Chat (E2E) | `evals/eval_chat.py` | has_answer, has_sources | 前 10 retrieval scenarios | ✅ | | **Enrichment** | **`evals/eval_enrichment.py`** | **kw_hit_rate_with_synonyms, freshness_rank_quality, synonym_coverage** | **`eval/golden_retrieval.json`（20 筆）** | **✅ 新增** | --- ## Online Scoring 更新（2026-03-02）在 `utils/laminar_scoring.py` 新增兩個 enrichment 相關的 online evaluator： ```python def score_enrichment_boost(synonym_hits: int, freshness_score: float) -> None: """記錄每次搜尋的 synonym 命中數與 freshness 分數""" score_event("synonym_hits", float(synonym_hits)) score_event("freshness_score", freshness_score) def score_search_miss(query: str, top_score: float) -> None: """記錄搜尋未命中事件（top_score < 0.35）""" score_event("search_miss", 1.0) score_event("search_top_score", top_score) ``` **觸發點**： - `score_enrichment_boost()` — `app/routers/search.py` 每次搜尋後 - `score_search_miss()` — `app/core/chat.py` 當 hits 為空時 ### Laminar span.set_metadata() — Pipeline 報告型 metadata 記錄（2026-03-01）在報告生成類腳本（非 API endpoint）中記錄結構化 metadata 到 Laminar 的推薦模式： ```python def _record_laminar_step_metadata(stats: dict, ...) -> None: """記錄 step metadata 到 Laminar span（降級安全）""" try: from lmnr import current_span span = current_span() if span: span.set_metadata({ "step": "step_name", # 固定 step 識別符 "judge_model": config.EVAL_JUDGE_MODEL, # 動態從 config 取 "knowledge_base_size": total_qa, # 動態計算，不硬編碼 # ... 其他動態指標 }) except Exception: pass # Laminar 未設定或 span 不在 context，靜默略過 ``` **關鍵規則**： 1. **絕不硬編碼歷史評分**（e.g. `"grounding_score": 5`）在 metadata 中 — 報告生成函式無法取得 eval 結果，硬編碼只會讓每次 trace 都顯示錯誤的靜態數字 2. **KB 大小動態計算**：從 `qa_final.json` 讀取 `len(json.load(f))`，不硬編碼 717/725 等歷史值 3. **judge_model 從 config**：`config.EVAL_JUDGE_MODEL`，不硬編碼 `"gpt-5-mini"` 4. **每個 step 獨立 helper function**：`_record_laminar_eval_metadata()` / `_record_laminar_comparison_metadata()`，提升可測試性 **各 step 記錄的 metadata 鍵**： | Step | Metadata Keys | | -------------------- | ---------------------------------------------------------------------------------------------------- | | `04_generate_report` | `step`, `knowledge_base_size`, `generation_timestamp`, `character_count`, `qa_used_count` | | `05_evaluate` | `step`, `judge_model`, `sample_size`, `*_mean`, `*_count`（4 維度）, `calibration_*`, retrieval 指標 | | `compare_providers` | `step`, `judge_model`, `provider_count`, `provider_N_*`（name/avg_score/topic_coverage/維度分） | 詳見：`scripts/04_generate_report.py`、`scripts/05_evaluate.py`、`scripts/compare_providers.py`。 --- ## OpenAI Data Agent 六層 Context 對比（2026-03-02） > 參考：[OpenAI Data Agent 官方例子](https://github.com/openai/data-agent-examples)；詳細改進計畫見 `plans/in-progress/multi-layer-context.md`。 ### OpenAI 六層架構概覽 OpenAI 在 2024 年提出的 Data Agent 架構將 LLM-based RAG 系統的「知識上下文」分為六層，逐層疊加以最大化推理能力： ``` L1 Query Patterns ← 驗證過的好查詢、同義詞、查詢展開 L2 Annotations ← 業務定義、分類規則、優先順序 L3 Learnings ← 搜尋失敗模式修正、negative examples L4 Runtime Context ← 最新使用資料、存取頻率、新鮮度 L5 External APIs ← 即時數據（股票、天氣、API） L6 Agentic Logic ← 多步推理、工具調用、迭代檢索 ``` ### 本專案實現對照表 | Layer | OpenAI 描述 | 本專案現狀（v2.0） | 改進提案 | 影響指標 | | ------ | -------------------- | ------------------------------------------------ | --------------------------------------------- | ------------------------ | | **L1** | 同義詞、查詢展開 | 無結構化維護（搜尋僅用 Q+A 原文） | `utils/synonym_dict.py` + offline enrichment | KW Hit Rate 78% → 85%+ | | **L2** | 業務規則、難度標籤 | 有 category/difficulty/evergreen，未在搜尋時活用 | 強化 metadata + confidence weighting | Accuracy 3.95 → 4.2+ | | **L3** | 失敗模式學習 | **無任何機制** | `output/learnings.jsonl` + 動態修正 | Completeness 3.85 → 4.1+ | | **L4** | 使用統計、時效性 | 有 access_logs，未聚合分析 | `utils/usage_aggregator.py` + freshness decay | 搜尋延遲 50ms → 30ms | | **L5** | 外部 API（即時數據） | N/A（SEO domain 無即時性需求） | 不建議實作 | — | | **L6** | 多步推理、Agent | 目前單步 RAG | 後續考慮（需 golden dataset 支撐） | 支援複雜查詢 | ### 分層設計理念對本專案的啟發 #### 1. L1 Query Patterns — 同義詞/查詢展開 **OpenAI 做法**：建立 curated 同義詞表，在搜尋時自動展開查詢。 **本專案現狀**： ```python # 搜尋直接用使用者輸入 results = search(user_query) # "Discover 流量下降" # 無同義詞機制，容易漏掉 "Google Discover 流量減少" 的 Q&A ``` **改進**（已規劃 P1-B）： ```python # 新增 synonym_dict.py query_expansions = expand_keywords("Discover 流量") # ["Discover 流量", "Google Discover", "Discover 能見度", "Discover 曝光"] # 計算展開後所有 Q&A 的相關性，取最佳匹配 ``` **預期效益**：KW Hit Rate 78% → 85%+ --- #### 2. L2 Annotations — 業務規則與元資料 **OpenAI 做法**：將 category/priority/owner 等 metadata 嵌入知識庫，搜尋時加權考慮。 **本專案現狀**： ```json { "qa_id": "qa_025", "question": "Discover 流量下降的原因？", "category": "搜尋表現", // ← 有但未用於搜尋加權 "difficulty": 3, // ← 同上 "evergreen": false, // ← 只用於分類，未用於時效性衰減 "confidence": 0.85 // ← 從未在搜尋中使用 } ``` **改進**（已規劃 P2-A）： ```python # 搜尋分數改進 final_score = base_score * confidence_weight * freshness_score # 置信度低的 Q&A 自動降權；非 evergreen 隨時間衰減 ``` **預期效益**：Accuracy 3.95 → 4.05；減少虛構/過時內容 --- #### 3. L3 Learnings — 失敗模式記錄與修正 **OpenAI 做法**：記錄每次搜尋的失敗案例（top result 無關、用戶修正等），用於後續改進。 **本專案現狀**： ``` 無任何機制記錄搜尋失敗 → 相同查詞反覆失敗，無法改進 → 基準線 KW Hit Rate 78% 難以突破 ``` **改進**（P1-A，關鍵）： ```python # 新增 learning_store.py if top_score < 0.35: learning_store.add({ "query": "Discover 流量下降", "expected_qa_id": "qa_025", "correction": "應加入 'AMP 兼容性' 同義詞" }) # 後續搜尋前查詢 learnings = learning_store.get_learnings_for_query(query) # 動態調整閾值、展開同義詞 ``` **預期效益**：KW Hit Rate 78% → 82%+ --- #### 4. L4 Runtime Context — 使用統計與新鮮度 **OpenAI 做法**：實時追蹤知識使用頻率、最後存取時間、點擊率，用於排序和新鮮度提示。 **本專案現狀**： ``` 有 access_logs JSONL，但只記錄不分析 → 無法識別高頻查詢缺陷、零命中盲點 → 無法基於使用習慣優化排序 ``` **改進**（P1-C）： ```python # 新增 usage_aggregator.py stats = { "high_frequency_queries": [ {"query": "Discover 流量下降", "count": 45, "avg_hit_rate": 0.82} ], "zero_hit_queries": [ {"query": "GSC 索引率異常", "count": 5} # ← 知識庫缺口 ], "unstable_queries": [ {"query": "Core Web Vitals", "stddev": 0.23} # ← 同義詞不足 ] } # 搜尋時動態調整分數 final_score = base_score * usage_boost # 高頻査詢結果優先 ``` **預期效益**： - 搜尋延遲 50ms → 30ms（緩存高頻結果） - 識別待改進的知識庫區域 - Completeness 提升（補充零命中的 Q&A） --- #### 5. L5 External APIs — 不適用於本專案 **原因**： - SEO 知識庫主要是常識性內容，無即時性需求 - Google Sheets 指標已是外部資料來源，整合在 Step 4 - 實時 API（GSC、Google Analytics）超出本專案 scope **結論**：**不建議實作**。 --- #### 6. L6 Agentic Logic — 多步推理與工具調用 **OpenAI 做法**：支援 Agent 自動分解複雜查詢，多步檢索與推理。 **本專案現狀**：單步 RAG（使用者查詢 → 搜尋 → 回答），無推理迴圈。 **改進建議**（P3 階段，後續考慮）： ``` 使用者："Discover 流量下降的原因和解決方案" Agent 步驟： 1. 搜尋 "Discover 流量下降原因" ← L1-4 融合 2. 解析結果，發現 "AMP 兼容性" 3. 自動搜尋 "AMP 修復方法" ← 第二次檢索 4. 整合兩份結果，生成完整答案成本：三倍 LLM 呼叫 + 推理時間，僅適合複雜查詢 ``` **優先順序**：**低**（目前單步已滿足 90% 使用案例） --- ### 評估維度在多層架構中的角色多層架構與現有四個評估維度的關係： | 維度 | 涉及層級 | 改進機制 | 基準→目標 | | ---------------- | ------------ | -------------------------------------- | ----------------- | | **Relevance** | L1 + L3 | 同義詞 + learnings 修正 | 無變化（已 4.8） | | **Accuracy** | L2 + L4 | confidence weighting + freshness decay | 3.95 → 4.2+ | | **Completeness** | L1 + L2 + L3 | 同義詞展開 + metadata 補強 + 回饋迴圈 | 3.85 → 4.1+ | | **Granularity** | L2 | category 約束（後續強化） | 無變化（已 4.75） | **核心洞察**： - **Relevance & Granularity** 已優秀，無改進空間（基於 Q&A 品質本身） - **Accuracy** 需 L2/L4 支撐（metadata 加權 + 時效性衰減） - **Completeness** 需 L1/L3 支撐（同義詞展開 + 失敗學習） --- ### 裁剪版設計決策（四層而非六層）本專案採用 **四層裁剪版**（L1-L4），理由如下： | 層級 | 實作成本 | 本專案收益 | 決策 | | -------------------- | -------- | ------------------------ | ----------- | | L1 Query Patterns | 低 | 高（KW Hit +7pp） | ✅ 實作 | | L2 Annotations | 低 | 中（Accuracy +0.25） | ✅ 實作 | | L3 Learnings | 中 | 高（KW Hit +4pp） | ✅ 實作 | | L4 Runtime | 中 | 中（延遲 -40%，UX 提升） | ✅ 實作 | | **L5 External APIs** | 高 | 低（SEO 知識庫無即時性） | ❌ 不實作 | | **L6 Agentic** | 很高 | 低（單步已 90% 夠用） | ❌ 後續考慮 | **總實作量**：約 1-2 週（Phase 1+2），無需大規模重構。 --- ### 學習與後續方向 1. **Query Understanding 強化**（L1 進階） - 從 zero-hit queries 自動提取新同義詞 - 聚類相似失敗查詢，識別模式 2. **Active Learning**（L2/L3 融合） - 自動選取最具信息量的樣本 - 用於下一輪人工標記（P2-B 的擴展） 3. **LLM-based Reranking**（L2 進階） - 在 top-5 結果上執行 semantic reranking - 成本 vs 效果評估（未來才需要）詳見完整計畫：`plans/in-progress/multi-layer-context.md`。 --- ## Model Provenance 與跨模型 A/B 評估（v2.8，2026-03-05） ### 問題：Eval 無法追蹤「哪個模型萃取的」 v2.7 以前，QA Item 不記錄是由哪個 LLM 萃取。當切換模型（如 gpt-5 → gpt-5.2）後： 1. **Cache 污染**：舊模型的快取結果被新模型命中，eval 分數失真 2. **無法對比**：同一份文件用不同模型萃取的品質無法量化比較 3. **回溯困難**：發現品質問題時，無法確定是哪個模型版本造成的 ### 解決方案：三層 Model Provenance **Layer 1: QA Item Metadata** 每筆 QA 記錄萃取模型與時間戳： ```python qa_item = { "question": "...", "answer": "...", "extraction_model": "gpt-5.2", # 萃取模型 "extraction_timestamp": "2026-03-05T...", # UTC 時間戳 } ``` **Layer 2: Model-Aware Cache** 快取 key 加入模型維度，防止跨模型污染： ``` cache_key = SHA256(f"{model}::{content}") ``` 同一篇文章用 gpt-5 和 gpt-5.2 萃取會產生不同快取項。 **Layer 3: Eval Schema 擴展** Eval 結果記錄完整模型資訊： ```json { "extraction_model": "gpt-5.2", "embedding_model": "text-embedding-3-small", "classify_model": "gpt-5-mini" } ``` ### Cross-Model A/B 評估工作流新增 `/evaluate-model-ab` 命令（`.claude/commands/evaluate-model-ab.md`）： ``` Step 1: 抽樣 N 篇 Markdown（qa_tools.py eval-sample） Step 2: Model A（OpenAI）萃取 Q&A Step 3: Model B（Claude Code）萃取 Q&A Step 4: Claude Code 作為 Judge，4 維度評分 Step 5: 對比報告（per-file + aggregate） Step 6: 儲存至 output/evals/ab_.json ``` 評分維度同標準 LLM-as-Judge：Relevance / Accuracy / Completeness / Granularity（1-5 分）。 ### 設計決策 | 決策 | 選擇 | 理由 | | --------------- | ------------------------ | ----------------------------------- | | Model 欄位位置 | QA item level | 每筆可獨立追蹤，非檔案級 | | Cache key 格式 | `SHA256(model::content)` | `::` 分隔符不常出現在模型名或內容中 | | Eval model 欄位 | Optional | 向下相容，舊 eval 不需遷移 | | A/B Judge | Claude Code（非 OpenAI） | 避免 Judge 偏向自家模型輸出 | --- ## Retrieval 指標擴充：Precision@K / Recall@K / F1（v2.11，2026-03-05） ### 背景：原有指標的語意歧義原本的「Category Hit Rate」實際上是 **Recall@K（category level）**，語意不清。v2.11 重新定義並新增對應指標： | 指標 | 定義 | 計算方式 | | ------------------------------------ | --------------------------------------- | ---------------------------- | ------------------------------ | ---- | ------------- | --- | | **KW Hit Rate** | 關鍵字命中率（fuzzy match） | ` | matched_kw | / | expected_kw | ` | | **MRR** | Mean Reciprocal Rank | `1 / rank_of_first_relevant` | | **Recall@K**（原 Category Hit Rate） | top-K 中有幾個 expected category 被覆蓋 | ` | retrieved_cats ∩ expected_cats | / | expected_cats | ` | | **Precision@K**（v2.11 新增） | top-K 中有幾個是 relevant | ` | relevant_in_topk | / K` | | **F1 Score**（v2.11 新增） | Precision 與 Recall 的調和平均 | `2 × P × R / (P + R)` | ### 實作（`scripts/qa_tools.py`） ```python # Precision@K：top-K 中幾個 QA 的 category 在 expected_cats relevant_in_topk = sum( 1 for qa in retrieved if qa.get("category", "") in set(expected_cats) ) precision_at_k = relevant_in_topk / top_k if top_k > 0 else 0.0 # Recall@K：alias for cat_hit_rate（向後相容） recall_at_k = cat_hit_rate # |retrieved_cats ∩ expected_cats| / |expected_cats| # F1 f1_score = 2 * precision_at_k * recall_at_k / (precision_at_k + recall_at_k) \ if (precision_at_k + recall_at_k) > 0 else 0.0 ``` ### Laminar Online Scoring 擴充 eval 執行後自動送出 5 個 score events 到 Laminar span： ```python score_event("precision_at_k", avg_precision_at_k) score_event("recall_at_k", avg_recall_at_k) score_event("f1_score", avg_f1_score) score_event("kw_hit_rate", avg_kw_hit) score_event("mrr", avg_mrr) ``` ### 評估基準線（v2.12，2026-03-05）使用 `output/evals/golden_retrieval.json`（20 cases），top-k=5 關鍵字搜尋： | 指標 | 數值 | 目標 | 類型 | | --------------------- | -------------------------------------------- | ------------- | ----------------------- | | Precision@K | **0.76** | ≥ 0.80 | category match | | Recall@K | **0.775** | ≥ 0.80 | category coverage | | F1 Score | **0.739** | ≥ 0.78 | harmonic mean | | Hit Rate | **1.0** ✅ | ≥ 0.95 | binary（至少命中 1 筆） | | MRR | **0.879** ✅ | ≥ 0.85 | 第一筆命中排名倒數 | | **Context Relevance** | **0.32**（1 query sample，keyword fallback） | > Precision@K | **LLM semantic** | **指標解讀**： | 指標 | 解讀 | | ------------------------ | --------------------------------------------------------------------- | | Hit Rate = 1.0 | 20/20 查詢都至少命中 1 筆正確分類，keyword search 沒有完全失靈的 case | | MRR = 0.879 | 第一筆相關結果平均排在第 1.14 位，排序品質好 | | Precision = 0.76 | 每 5 筆結果中平均 3.8 筆屬於正確分類，~24% 是噪音（reranker 的用途） | | Recall = 0.775 | 22.5% 的預期分類未被涵蓋（知識庫覆蓋缺口或 keyword 不對應） | | Context Relevance = 0.32 | keyword 命中但語意不相關的問題，是 keyword search 的天花板 | **Keyword Search 天花板分析**： - Hit Rate = 1.0、MRR = 0.879 → keyword 排序表現已接近最佳 - Precision 0.76 ≠ 1.0 → 回傳了不相關分類的結果（噪音），需 reranker 過濾 - Context Relevance = 0.32 → 語意層才是真正的瓶頸，embedding + reranker 可顯著改善 Context Relevance 初測（2026-03-05，query="Discover 流量下降"）： - **score = 0.32**：keyword search 雖然 5/5 命中「流量」「下降」關鍵字，但只有 1/5 真正語意相關（Discover 專屬） - 揭示 keyword 的語意盲區：「流量下降」的字面匹配掩蓋了實際 Discover 情境相關性的缺失 ### Laminar 正式 Eval Run（`scripts/_eval_laminar.py`） **兩種 Laminar eval 層次**： | 層次 | 觸發時機 | 方式 | | ---------------- | -------------------------------- | -------------------------------------------- | | Online scoring | 每次 eval-retrieval-local 執行後 | `score_event()` in `@observe` span | | Offline eval run | 明確觸發（CLI） | `lmnr.evaluate()` 推送 golden set 為 dataset | **離線 eval run 使用方式**： ```bash python scripts/_eval_laminar.py # 全量（20 cases） python scripts/_eval_laminar.py --top-k 10 # 改變 top-K python scripts/_eval_laminar.py --group "abc" # 自訂 group 名稱（預設："keyword-retrieval"） ``` **Group 名稱設計**： - 預設 `--group "keyword-retrieval"` — 所有 eval run 進同一 group，方便 Laminar Dashboard 畫趨勢折線圖 - `concurrency_limit=1` — 避免並發上傳失敗，每次建議只執行一個 eval run 執行後結果出現在 Laminar Dashboard 的 Evaluations 頁面，可追蹤 5 個評估指標的歷史趨勢。 **五個 evaluator 函式**（v2.12 擴充）： 1. **`precision_evaluator`** — Precision@K（回傳精準比例） ```python expected_cats = set(target.get("expected_categories", [])) relevant = sum(1 for qa in output if qa.get("category", "") in expected_cats) return relevant / len(output) if output else 0.0 ``` 2. **`recall_evaluator`** — Recall@K（涵蓋期望分類比例） ```python expected_cats = set(target.get("expected_categories", [])) retrieved_cats = {qa.get("category", "") for qa in output} return len(retrieved_cats & expected_cats) / len(expected_cats) if expected_cats else 1.0 ``` 3. **`f1_evaluator`** — F1 Score（Precision 與 Recall 調和平均） ```python p = precision_evaluator(output, target) r = recall_evaluator(output, target) return 2 * p * r / (p + r) if (p + r) > 0 else 0.0 ``` 4. **`hit_rate_evaluator`** — Hit Rate（至少命中一筆期望分類，0 或 1） ```python expected_cats = set(target.get("expected_categories", [])) return 1.0 if any(qa.get("category", "") in expected_cats for qa in output) else 0.0 ``` 5. **`mrr_evaluator`** — Mean Reciprocal Rank（第一筆命中的排名倒數） ```python expected_cats = set(target.get("expected_categories", [])) for rank, qa in enumerate(output, start=1): if qa.get("category", "") in expected_cats: return 1.0 / rank return 0.0 ``` **實作細節**（v2.13 更新）： - `safe_executor` — try-except 防護，executor 失敗時回傳空列表而非拋例外 - NDCG@K 修正 — 每個 expected_category 只計算第一次命中（避免同一 category 多筆重複計分導致 NDCG > 1） - 回傳精簡欄位 — `_keyword_search` 只回傳 `id, category, question[:120]`，避免大型 payload 上傳失敗 ### 2026-03-14：Curated QA + Retrieval Booster 觀測這次不是單純調整 ranker，而是先改變 corpus 形狀，再觀測 retrieval： 1. `clean_qa_quality.py` 移除低訊號模板題與模板答案 2. `restore_rewritten_qas.py` 以 **question-only salvage** 方式回補可挽救題目，避免 coverage 直接流失 3. `sync_curated_qa_from_raw.py` 讓 curated answer/metadata 跟上最新 raw corpus 4. `add_retrieval_boosters.py` 針對弱情境補 11 筆 `curated-manual` scenario boosters 換句話說，這次提升屬於 **corpus-side intervention**，不是單靠 embedding、reranker 或排序演算法優化。 ### Data Quality Gate + Salvage Loop 本次 session 在 retrieval 前新增 deterministic quality gate： | 階段 | 目的 | 代表訊號 | | ----------------- | ---------------------------------------------- | --------------------------------------------------------------------------------------------------------------------------- | | Quality Filter | 移除低品質 Q&A | `generic-question-template`、`generic-answer-template`、`mixed-language-placeholder-heavy`、`multi-block-fragmented-answer` | | Rewrite Restore | 只改寫 question、保留原 answer，回補可挽救題目 | `quality_rewritten_from_phrase` | | Raw Sync | 保持 curated 與 raw corpus 對齊 | `raw_sync_status = matched / preserved-rewritten / preserved-missing` | | Retrieval Booster | 補足 golden retrieval 弱情境 | `manual_curation_tag = retrieval-booster-20260314` | ### 本次後處理量化結果 - quality removed：24 筆 - restored rewritten：24 筆（question-only salvage） - raw sync：246 筆 matched / 24 筆 preserved-rewritten / 2 筆 preserved-missing - booster count：11 筆 - curated serving set：`output/qa_final.json` 283 筆 ### 最新 retrieval 觀測值（2026-03-14，top-k=5，本地 eval） | 指標 | 數值 | 說明 | | --------------------- | -------- | -------------------------------------------------------- | | avg_keyword_hit_rate | **0.74** | 關鍵字覆蓋已高，代表 booster 對弱情境 query wording 有效 | | avg_category_hit_rate | **0.81** | category-level coverage 明顯恢復 | | avg_mrr | **0.93** | top-1 排序品質很強 | | avg_precision_at_k | **0.52** | top-5 仍有噪音，說明 coverage 與 purity 尚未完全同步 | | avg_recall_at_k | **0.81** | 預期分類大多能在 top-k 被覆蓋 | | avg_f1_score | **0.58** | 仍受 precision 拖累，但已優於前一輪手動補洞前狀態 | ### 本次 booster 覆蓋的弱情境類型 - 內部連結架構 - 結構化資料覆蓋率 - GA4 `unassigned` / `direct` 歸因 - 圖片搜尋 / Discover 大圖 - 內容供給下降 - Google News / AMP - 多語言影片 / Key Moments - 品牌 / 非品牌流量 - Search Console KPI - `VideoObject` - `Event` schema ### 解讀注意事項 - 不應把這組數字直接與早期 baseline 視為同口徑 A/B，因為 **knowledge base、curation policy、manual boosters 都已變動** - `avg_category_hit_rate` 在語意上仍接近 category-level `Recall@K` - `restore_rewritten_qas.py` 並不會重新跑第二道品質驗證；它的角色是保住 query surface，而不是宣告 answer 品質已完全修復 - 目前弱案例已從「完全找不到正確 top1」轉為「top1 多數正確，但雙分類或平台策略情境仍受 precision 拖累」 --- ## 評估指標成長總覽（2026-02-28 → 2026-03-05） ### QA 品質四維度（LLM-as-Judge） ``` 分數 /5 5.0 ┤ ░░░░ Relevance 4.80 → ████ 5.00 (+0.20) ✅ 4.5 ┤ ████ Granularity 4.75 = 4.75（持平） 4.3 ┤ ████ Accuracy 3.95 → 4.30 (+0.35) ✅ 4.0 ┤ ░░░░ Accuracy 3.95 ████ Completeness 3.95（目標 4.0） 3.9 ┤ ░░░░ Completeness 3.85 ─────────────────────────────── 目標 4.0 ┄┄ └───────────────────────────────────────────────────────────────── v1（2026-02-28） v2（2026-03-02） Judge: gpt-5-mini Judge: claude-opus-4-6 ``` | 維度 | v1（2026-02-28） | v2（2026-03-02） | 增量 | 目標 | 狀態 | | ------------ | ---------------- | ---------------- | ----- | ----- | ------------- | | Relevance | 4.80 | **5.00** | +0.20 | ≥ 4.5 | ✅ | | Accuracy | 3.95 | **4.30** | +0.35 | ≥ 4.0 | ✅ | | Completeness | 3.85 | **3.95** | +0.10 | ≥ 4.0 | 接近（-0.05） | | Granularity | 4.75 | **4.75** | 持平 | ≥ 4.5 | ✅ | Accuracy 改善最大（+0.35）：防幻覺規則全量重跑的直接效果。 Completeness 仍未達標：`[補充]` Tag 機制已就緒，需更多含 How+Evidence 的 Q&A。 ### Retrieval 指標（跨版本） | 指標 | v1（2026-02-28） | v2（2026-03-02） | 增量 | | ----------------- | ---------------- | --------------------- | ----------------------- | | KW Hit Rate | 78%（修復後） | **74%**（回歸後修復） | -4pp（v2.0 重跑副作用） | | MRR | 0.79 | **0.87** | +0.08 ✅ | | Category Hit Rate | 75% | **80%** | +5pp ✅ | | Precision@K | — | **76%** | — | | F1 Score | — | **0.73** | — | ### Provider 品質跨版本對比 ``` 平均分 /5 5.0 ┤ ██ system_seoinsight_20260302（兩次均 5.0） 4.5 ┤ ░░ system_seoinsight_20260228（KB 20260228，4.5） 4.3 ┤ ██ chatgpt_gpt52 ██ gemini_thinking（第二次均 4.3） 4.0 ┤ ░░ chatgpt ░░ gemini_thinking（第一次均 4.0） 3.7 ┤ ██ claude_sonnet46（第二次） 3.0 ┤ ░░ claude_sonnet46（第一次） 2.3 ┤ ██ gemini_research └────────────────────────────────────────────────────────────── ░ = 2026-02-28（gpt-5-mini judge，僅 5 項指標基準） █ = 2026-03-02（claude-opus-4-6 judge，完整 TSV 逐筆核對） ``` | Provider | 2026-02-28 均分
（gpt-5-mini judge） | 2026-03-02 均分
（claude-opus-4-6 judge） | 主要變動原因 | | -------------------------- | --------------------------------------- | -------------------------------------------- | ---------------------------------------------- | | system_seoinsight_20260302 | — | **5.0** | Topic Coverage 80%→100%（補回應時間） | | system_seoinsight_20260228 | 5.0 | **4.5** | Grounding 定性分析，缺回應時間分析 | | chatgpt_gpt52 | 4.0 | **4.3** | Grounding 3→4（完整 TSV 逐筆驗證） | | gemini_thinking | 4.0 | **4.3** | Grounding 3→4（/salon/ 數字確認） | | claude_sonnet46 | 3.0 | **3.7** | Grounding 1→3（原 Judge 誤判，基準只有 5 項） | | gemini_research | 2.33 | **2.0** | Topic Coverage 80%→20%（嚴格要求引用原始數據） | **Judge 更換影響**：gpt-5-mini 基於摘要快照（5 項指標）評分，系統性低估 Grounding；claude-opus-4-6 逐筆核對完整 TSV（~120 列），更準確但標準也更嚴格。 ### 待補缺口 ``` 指標缺口（目前值 vs 目標） KW Hit Rate ████████████████████░░░░░░░ 74% / 目標 85%（-11pp） Completeness ████████████████████████████ 3.95 / 目標 4.00（-0.05） Precision@K ██████████████████████░░░░░ 76% / 目標 80%（-4pp） F1 Score ████████████████████░░░░░░░ 0.73 / 目標 0.78（-0.05） Accuracy ████████████████████████░░░ 4.30 / 理想 5.00（-0.70） KW Hit Rate 是最大缺口：主要靠擴充 /api/v1/synonyms 詞條達成 ``` ### Enrichment 效果（2026-03-02） | 評估器 | Before（qa_final） | After（qa_enriched） | Delta | | ------------------------- | ------------------ | -------------------- | ------- | | kw_hit_rate_with_synonyms | 70.4% | **79.67%** | +9.27pp | | freshness_rank_quality | 1.0 | 1.0 | 持平 | | synonym_coverage | 0% | **100%** | +100pp | ## 21. Claude Code as Semantic Reranker Judge（v2.12，2026-03-05） > 參考：`api/scripts/eval-semantic.ts`（三模式 CLI）；本節記錄手動實驗：Claude Code 直接作為語意判斷引擎。 > **注意：Keyword Baseline 版本差異** > 本節 baseline（0.810）來自 **Python 手動實驗**（Claude Code 執行 Python keyword search，再手動語意選 top-5）。 > TypeScript `eval-semantic.ts --mode keyword` 實際輸出為 **0.700**（不同的 BM25 實作）。 > Python `_eval_laminar.py` 輸出為 **0.76**（又一版 Python keyword 實作）。 > 三者使用不同 tokenizer + scoring，數值差異屬預期。 ### 實驗設計 **目標**：量化語意 reranking 對 keyword search 的改善幅度（無需 OpenAI API key）。 **評估方式**： 1. 使用 golden_retrieval.json（20 cases） 2. Python keyword search（over-retrieve top-15）→ Claude Code 直接語意選 top-5 3. 對比 baseline（Python keyword top-5）vs Claude Code 語意選取後結果 **評估指標**（category-level 語意相關性）： - Precision@K：top-K 中有幾個屬於期望分類 - Recall@K：期望分類中有幾個被覆蓋 - F1 Score：Precision 與 Recall 調和平均 - Hit Rate：至少命中一筆期望分類的查詢比例 - MRR：第一筆相關結果的排名倒數 **Claude Code 角色**： - 直接作為語意判斷引擎（不呼叫任何外部 API） - 讀取 Python keyword over-retrieve 結果（top-15） - 依語意選出最佳 top-5，不依賴 embedding 向量 ### 實驗結果（v2.12，2026-03-05，Python keyword 手動實驗） ``` 兩模式對比（20 golden cases，top-k=5，Python keyword baseline） Precision Recall F1 Hit Rate MRR Keyword 0.810 0.800 0.768 1.0 0.938 + Rerank 0.950 0.825 0.861 1.0 1.0 Delta +0.140 +0.025 +0.093 ±0.0 +0.062 (+14pp) (+2.5pp) (+12.5%) — (完美) ``` **逐項解讀**： | 指標 | Baseline | + Rerank | 增量 | 解讀 | | ------------- | -------- | --------- | ------ | ---------------------------------------------------- | | **Precision** | 81% | **95%** | +14pp | Reranker 過濾 24% 的噪音（keyword 命中但語意不相關） | | **Recall** | 80% | **82.5%** | +2.5pp | 受 over-retrieve pool 限制，僅小幅改善 | | **F1** | 0.768 | **0.861** | +0.093 | 綜合指標提升 12.1%（兼顧精準度與涵蓋度） | | **Hit Rate** | 100% | 100% | 0 | 無變化：keyword 搜尋本身無完全失敗的 case | | **MRR** | 0.938 | **1.0** | +0.062 | 第一筆結果 100% 正確，相比 93.8% 質的提升 | **Reranker 的工作機制**： 1. **Over-retrieve**：Hybrid search 回傳 top-15（K×3，K=5） 2. **語意重評估**：Claude haiku 讀取 query + 15 個候選，輸出語意相關度排序 3. **篩選 top-K**：保留排名前 5 的結果回傳給使用者 **典型改善案例**： ``` Query: "Discover 流量下降" Baseline（keyword）top-5： 1. 「有效頁面數持續下滑」— category=技術 SEO（相關✓） 2. 「內部連結架構優化」— category=連結建設（相關✓） 3. 「GA4 流量來源分析」— category=數據分析（相關但偏移✓） 4. 「搜尋語言和設定」— category=GSC 操作（不相關✗） 5. 「當週文章數銳減」— category=內容策略（不相關✗） Precision = 3/5 = 60% After Rerank： 1. 「有效頁面數持續下滑」— 語意最相關，Discover 相關影響 2. 「搜尋結果版面更新」— Discover 直接相關的 Q&A 3. 「AMP 焦點新聞維持」— Discover 榜單管理 4. 「GSC 流量異常分析」— 診斷流量下降原因的方法論 5. 「搜尋語言和設定」— 邊界相關（搜尋設定與 Discover 流量） Precision = 4.5/5 = 90%（第 5 筆部分相關） ``` ### 評估指標設計細節 **為什麼用 Category 而非 exact Q&A match？** - Golden set 中 `expected_categories` 是策劃者標記（如 "技術 SEO"、"流量分析"），更穩定 - Exact Q&A match 易受語意變異影響（同一問題多個表述方式） - Category 級評估能捕捉語義相關性，同時避免過度精細化 **Precision vs Recall 的取捨**： ``` KW baseline：Precision 81% ≠ Recall 80% 的原因 Query: "Discover 流量" 的期望分類：{搜尋表現, 技術 SEO} Top-5 retrieved categories: {搜尋表現, 連結建設, 數據分析, 內容策略, 搜尋表現} Precision = |{搜尋表現} ∩ expected| / 5 = 1/5 = 20%（有 1 筆搜尋表現，4 筆其他） Wait — 實際應該是： Top-5 中多少屬於期望分類 = 滿足條件的個數 / 5 = count(cat in retrieved and cat in expected) / 5 實驗結果 Precision 81% = 4.05/5 個頁面來自期望分類 Recall = |{搜尋表現, 技術 SEO} ∩ {top-5 distinct categories}| / 2 如果 top-5 中只涵蓋 {搜尋表現, 連結建設}，則 Recall = 1/2 = 50% ``` ### CLI 用法與 Make target（v2.12） ```bash # 評估三種模式（keyword / hybrid / hybrid+rerank） cd api && npx tsx scripts/eval-semantic.ts # 改變 top-K 參數 cd api && npx tsx scripts/eval-semantic.ts --top-k 3 cd api && npx tsx scripts/eval-semantic.ts --top-k 10 # JSON 輸出 cd api && npx tsx scripts/eval-semantic.ts --json > results.json # Makefile targets make eval-semantic # 三模式對比 make eval-semantic-k3 # top-k=3 版本 ``` **eval-semantic.ts 模組架構**： ```typescript interface GoldenCase { query: string; expected_categories: string[]; expected_keywords: string[]; } // 三個評估模式 1. keywordOnlySearch() → 純關鍵字 2. hybridSearch() + embedding → 語意 + 關鍵字 3. hybridSearch() → over-retrieve × 3 → rerank() → top-K // 計算指標 computePrecision(retrievedCats, expectedCats) → 0–1 computeRecall(retrievedCats, expectedCats) → 0–1 computeF1(precision, recall) → 0–1 computeHitRate(anyMatch) → 0 or 1 computeMRR(rank) → 1/rank or 0 ``` ### 設計決策 | 決策 | 選擇 | 理由 | | -------------------- | ------------------------------ | --------------------------------------------- | | Judge 模型 | Claude Haiku（v2.12） | 成本低、速度快、判斷準確 | | Over-retrieve factor | 3× | 給 reranker 足夠池子（15 個候選），不過度耗時 | | Precision 計算 | `relevant / top_k` | 衡量結果品質（無噪音） | | Recall 計算 | `covered_cats / expected_cats` | 衡量涵蓋度（無遺漏） | | F1 定義 | 調和平均 | 平衡兩個維度，無偏向 | | 評估粒度 | Category level | 比 exact-match 更穩定、更反映使用者體驗 | ### 後續方向 1. **擴大 golden set**：20 cases 統計意義有限，建議擴至 100+ cases 2. **跨 embedding model 比較**：評估不同向量模型（text-embedding-3-small vs Nomic vs Cohere）的影響 3. **Reranker 模型選擇**：嘗試 Claude Sonnet 或其他開源 reranker（如 BGE-reranker） 4. **實時監控**：在 API 層加入 per-query context-relevance 評估，識別線上退化 --- ## 22. Context Relevance：檢索片段與查詢的語意相關性 > NVIDIA 提出的評估指標，v2.12 新增。無需 ground truth，只需 query + retrieved contexts。 ### 概念傳統 RAG 評估指標（MRR、Hit Rate）依賴二元判斷（relevant / not relevant）。 Context Relevance 進一步評估**連續相關性**（0–1 分），表示檢索到的片段對回答使用者查詢的實用程度。 ``` 原始指標（Hit Rate）： Query: "內部連結建設最佳實踐" Top-5: [1=相關 ✓, 2=相關 ✓, 3=無關 ✗, 4=無關 ✗, 5=無關 ✗] 結果: 2/5 = 40% Context Relevance：同一批結果，細分評分： 1 = 1.0（完全相關，直接回答） 2 = 0.9（很相關，有補充價值） 3 = 0.3（部分相關，邊界情況） 4 = 0.1（略有關聯，實際用處小） 5 = 0.0（完全不相關）加權平均 = (1.0 + 0.9 + 0.3 + 0.1 + 0.0) / 5 = 0.46 ``` ### 實作方式（v2.12） **模型**：Claude haiku-4-5（輕量 LLM judge） **無需 Ground Truth**：只需 query + retrieved QA items（questions + categories） **Prompt 設計**： - 輸入：使用者查詢 + 檢索到的 5–10 個 Q&A 片段 - 輸出：JSON，包含 `overall_score`（0–1）+ `per_context`（每個片段的 score）+ `reason`（30 字評估說明） **評分標準**（Prompt 中定義）： - 1.0 = 完全相關（直接回答查詢） - 0.5 = 部分相關（有關聯但不直接） - 0.0 = 完全不相關 **安全機制**： - `escapeXml()`：防止 XML prompt injection（`<`、`>`、`&`、`"`、`'` 轉義） - `top_k` 上限 30：API 層保護 - Dynamic import fallback：ANTHROPIC_API_KEY 缺失時，退化為 freshness_score heuristic **API 端點**： ```typescript POST /api/v1/eval/context-relevance { "query": "內部連結建設如何改善 SEO？", "top_k": 5 } Response (200 OK): { "data": { "score": 0.82, "reason": "大多數片段相關，但缺乏實踐範例", "per_context": [ { "id": "abc123...", "score": 0.95 }, { "id": "def456...", "score": 0.85 }, { "id": "ghi789...", "score": 0.60 } ], "query": "內部連結建設如何改善 SEO？", "total_contexts": 3 } } ``` ### 何時使用 Context Relevance？ 1. **RAG 迭代最佳化**：Synonym 擴充後，評估檢索品質是否有顯著改善 2. **Reranker 驗證**：Over-retrieve + rerank 後的 Context Relevance 應提升 3. **跨模型 Benchmark**：評估不同 embedding model 的檢索質量 4. **實時監控**：線上系統的 query → context relevance 比例，發現檢索退化 ### 與其他指標的互補性 | 指標 | 衡量 | 優點 | 缺點 | | ------------------------------ | ------------------------------- | ------------------ | --------------------- | | **Hit Rate（傳統）** | Top-K 是否包含 relevant items | 簡單、無需額外模型 | 二元判斷，不分程度 | | **MRR** | 第一個 relevant item 的排名倒數 | 考慮排序 | 同樣二元 | | **Context Relevance（v2.12）** | 檢索片段與查詢的連續相關性 | 細分等級，更精細 | 需要 LLM 評估，有成本 | --- ## 23. 統一 4 層評估框架（v2.13，2026-03-05） > 整合 RAGAS、TREC IR 標準、RAG Triad、NVIDIA Context Relevance 四個學術/業界框架。 ### 為什麼需要整合框架？每次重寫評估腳本（如 v2.12 的 `_eval_laminar.py`）時，舊 evaluator 會消失。根本原因是缺乏「各層 evaluator 的統一登記」。v2.13 建立明確的 4 層結構，每層 evaluator 都有對應的學術依據、實作腳本、Laminar group 名稱。 ### 學術框架對照 | 框架 | 來源 | 本專案對應 | | -------------------------------------- | ----------------- | ------------------------------------------------------------------ | | **RAGAS**（Es et al., 2023） | ACL 2024 | Context Relevance、Faithfulness、Context Precision | | **IR 標準**（Voorhees, TREC） | NIST/ACM SIGIR | MRR、Precision@K、Recall@K、F1@K、NDCG@K | | **RAG Triad**（TruLens） | Truera/LlamaIndex | Context Relevance、Groundedness（≈Faithfulness）、Answer Relevance | | **LLM-as-Judge**（Zheng et al., 2023） | NeurIPS 2023 | Relevance、Accuracy、Completeness、Granularity | | **NVIDIA Context Relevance** | NVIDIA NeMo | context_relevance（v2.12） | ### RAGAS 四大指標詳解 RAGAS（Retrieval Augmented Generation Assessment System）提出 4 個互補指標： | 指標 | 定義 | 計算方式 | 本專案實作 | | --------------------- | ------------------------------------------------------- | ----------------------------------------- | -------------------------------------------- | | **Context Relevance** | Retrieved contexts 對 query 的語意相關性 | LLM judge 0–1 分 | `POST /eval/context-relevance`（v2.12） | | **Faithfulness** | Answer 的 claims 是否都能從 contexts 中找到支撐 | supported_claims / total_claims | `/evaluate-faithfulness-local`（v2.13） | | **Context Precision** | Retrieved contexts 中「真正有助於回答」的比例 | relevant_contexts / total_contexts | `/evaluate-context-precision-local`（v2.13） | | **Answer Relevance** | Answer 對 query 的回應相關性（reverse generation test） | embed(query) ↔ embed(generated_questions) | 待實作（v2.16 roadmap） | **RAGAS 的設計原則**：每個指標針對 RAG pipeline 的不同環節，可以獨立評估也可以組合： - Context Relevance + Context Precision = Retrieval 層品質 - Faithfulness = Generation 層品質（有無幻覺） - Answer Relevance = End-to-end 品質 ### NDCG@K 說明（Jarvelin & Kekalainen, 2002） **MRR vs NDCG@K 的差異**： | 指標 | 計算方式 | 適合場景 | | ------ | -------------------------------- | ----------------------------------- | | MRR | `1 / rank_of_first_relevant` | 只關心「第一筆」；常見於 QA、知識庫 | | NDCG@K | `DCG / IDCG`（考慮所有命中位置） | 多筆相關；電商搜尋、推薦系統 | 本專案同時報告兩者。NDCG@K 應 ≥ MRR（因為它也計入後面的命中），若 NDCG << MRR 表示多個相關結果集中在後段，排序仍有改善空間。 ```python # NDCG@K 計算（graded relevance，binary 版） DCG = Σ rel_i / log2(i+1) # rel_i = 1 if category matches else 0 IDCG = Σ 1 / log2(i+2) for i in range(min(n_relevant, K)) NDCG@K = DCG / IDCG ``` ### RAG Triad（TruLens/LlamaIndex） RAG Triad 是 Truera 提出的三角形評估框架，衡量 RAG pipeline 的三個面向： ``` [Query] / \ Context Relevance Answer Relevance | | [Contexts] ── Faithfulness ── [Answer] ``` | 邊 | 指標 | 問題 | | ----------------- | ---------------------------- | -------------------------- | | Query → Contexts | Context Relevance | 「檢索到的內容夠相關嗎？」 | | Query → Answer | Answer Relevance | 「回答有回應到問題嗎？」 | | Contexts → Answer | Faithfulness（Groundedness） | 「回答有無幻覺？」 | **本專案當前狀態**： - Context Relevance ✅（v2.12，API endpoint） - Faithfulness ✅（v2.13，Claude Code as Judge slash command） - Answer Relevance：留待 v2.16（需要 reverse generation） ### 4 層框架實作總覽 | 層次 | 指標 | 腳本 | Laminar group | API 成本 | | ---------------------- | --------------------------------------------------------------------- | ------------------------------------------------ | ----------------------- | ------------ | | **L1 Data Quality** | qa_count、avg_confidence、keyword_coverage、no_admin_content | `_eval_data_quality.py` | `data-quality` | 無 | | **L2 IR Metrics** | hit_rate、mrr、precision、recall、f1、ndcg、top1_match、top5_coverage | `_eval_laminar.py` | `retrieval-eval` | 無 | | **L3 Enhancement** | kw_hit_rate_with_synonyms、synonym_coverage | `_eval_laminar.py --group retrieval-enhancement` | `retrieval-enhancement` | 無 | | **L4 Context Quality** | context_relevance、faithfulness、context_precision | API + slash commands | `generation-quality` | Claude haiku | ### Roadmap | 版本 | 新增指標 | 實作方式 | 成本 | | ------------- | ----------------------------------------------------------------------- | ------------------------------------------- | ------------ | | v2.13（本次） | NDCG@K、Top-1 Match、Synonym Coverage + Faithfulness、Context Precision | L2/3 純 Python；F+CP = Claude Code as Judge | 無外部 API | | v2.14 | Faithfulness 全量 golden（API 版） | Anthropic haiku API，自動化 | Claude haiku | | v2.15 | Context Precision（GT 版，expected_qa_ids） | 人工標記 20 cases + 純 Python | 標記時間 | | v2.16 | Answer Relevance（reverse generation） | haiku reverse-gen + embedding similarity | Claude haiku | --- ## 24. 報告品質評估（v2.13） ### 為什麼評估週報品質？ SEO 週報的目的是將複雜的指標數據轉化為可行的策略建議。單純「生成報告」的成功，不代表「報告有用」。因此需要三層評估： 1. **結構完整性**（rule-based）— 報告是否包含預期的 6 個分析維度？ 2. **知識庫融合度**（rule-based）— 是否有效引用內部知識庫的相關 Q&A？ 3. **語義品質**（LLM-as-Judge，可選）— 建議是否有根據、邏輯是否清晰？ ### 5 維度規則式評估（rule-based，零成本）本專案採用 **5 維度規則式框架**，在報告生成直後立即評分，無需 LLM API： | 維度 | 定義 | 評分邏輯 | 0–1 scale | | -------------------------- | ---------------------- | -------------------------------------- | --------- | | **section_coverage** | 6 個分析段落完整性 | 實際段落數 / 6 | 0 → 1 | | **kb_citation_count** | 知識庫引用密度 | min(引用連結數 / 6, 1.0) | 0 → 1 | | **has_research_citations** | 是否包含業界研究佐証 | Backlinko / Semrush / arxiv 等關鍵字 | 0 or 1 | | **has_kb_links** | 是否包含知識庫內部連結 | `/admin/seoInsight/chunk/` 連結出現 | 0 or 1 | | **alert_coverage** | 異常指標討論覆蓋率 | 被標記為異常的指標在「第五章」提及比例 | 0 → 1 | | **overall** | 綜合評分 | 5 維度平均值 | 0 → 1 | ### 7 條業界研究引用庫（RESEARCH_CITATIONS） `api/src/services/report-generator-local.ts` 預載 7 條同行評審 / 業界報告，供 6 個 section builder 佐証主張： ```javascript { "ctr_baseline": "Backlinko 2024（67K 關鍵字、2400 萬曝光）：Position 1 平均 CTR 27.6%", "ctr_serp_features": "arxiv 2306.01785：Knowledge Panel 降 CTR ~8pp；Featured Snippet 升 ~20%", "navboost": "Google 排名因素洩露（2024）：NavBoost 以 13 月滾動聚合用戶點擊", "causal_attribution": "SEOCausal / CausalImpact：貝氏時間序列是因果歸因業界標準", "eeeat_2024": "Google E-E-A-T 2024 更新：體驗 = 作者署名 + About 頁 + 外部聲譽", "discover_signal": "First Page Sage 2025：高品質內容 + 搜尋者參與度（點擊）", "intent_framework": "Semrush 2025：Awareness / Consideration / Conversion 漏斗" } ``` ### 健康評分演算法（Health Score v2，2026-03-22 修訂）報告輸出時自動計算一個 0–100 分的健康指數，用於快速判斷網站狀態。 **v2 修訂原因**：v1 公式 `100 - (ALERT_DOWN × 10)` 在 10+ 個 alert 時觸底為 0，喪失鑑別力。v2 區分 CORE/非 CORE 權重，並加入健康指標正面抵銷。 ``` # Step 1: CORE 觸發 ALERT_DOWN（高衝擊，×10） core_penalty = core_alert_down_count × 10 # Step 2: 非 CORE ALERT_DOWN（衍生/次要，×3） non_core_penalty = non_core_alert_down_count × 3 # Step 3: CORE 健康加分（月趨勢 > 0% 的 CORE 指標，×2，cap 20） core_bonus = min(core_healthy_count × 2, 20) # Step 4: 全面崩盤懲罰（所有 CORE 月趨勢皆為負） all_core_penalty = 15 if ALL core monthly < 0% score = clamp(100 - core_penalty - non_core_penalty + core_bonus - all_core_penalty, 0, 100) ``` **設計原理與參考**： | 設計元素 | 原理 | 業界/學術參考 | |----------|------|---------------| | CORE vs 非 CORE 加權 | Leading indicators（核心流量指標）比 lagging/derived indicators（衍生比率）影響更直接 | Balanced Scorecard（Kaplan & Norton, 1992）；Ahrefs Site Health Score 分層加權 | | 非 CORE ×3（非 ×10） | 多個高度相關的衍生指標（如外部連結↓ + 每頁外部連結↓）攜帶重複信號，避免 double-counting | Information theory：冗餘信號的 marginal information 遞減 | | CORE 健康加分 | 純扣分制無法反映「核心健康但邊緣有噪音」的真實狀態 | FICO 信用評分同時考慮正面與負面因素；Google Lighthouse 的 Performance Score 以正面指標為基底 | | 全 CORE 下滑懲罰 | 所有核心同時下滑是系統性問題，應額外警告 | Semrush Site Audit 的 critical/warning/notice 三級分類 | **鑑別力驗算**： | 情境 | 計算 | 分數 | 標籤 | |------|------|-----:|------| | 理想週（0 alert, 13 CORE 健康） | 100 + 20 | 100 | 良好 | | 小問題（5 非 CORE alert, 13 CORE 健康） | 100 - 15 + 20 | 100 | 良好 | | 中等問題（15 非 CORE, 1 CORE down, 11 CORE 健康） | 100 - 10 - 45 + 20 | 65 | 需關注 | | 嚴重問題（15 非 CORE, 3 CORE down, 5 CORE 健康） | 100 - 30 - 45 + 10 | 35 | 警示 | | 全面崩盤（全 CORE 下滑 + 15 非 CORE） | 100 - 130 - 45 + 0 - 15 | 0 | 警示 | 輸出三級標籤： | 分數 | 狀態 | 行動 | | ------ | --------- | --------------------------------------------------------- | | 80–100 | 良好 | 維持現狀，重點監控新機會 | | 60–79 | 需關注 | 調查特定異常指標根因 | | < 60 | 警示 | 啟動應急除錯（structure / crawled-not-indexed / traffic） | ### Laminar Online Scoring（非同步）報告生成成功後，`api/src/routes/reports.ts` 非同步呼叫 `evaluateReport()`，推送 6 個 Laminar `scoreEvent`： ```typescript // POST /api/v1/reports/generate 成功 → 200 立即回傳 // 同時異步推送 Laminar scoring（不阻塞回應） await evaluateReport(content, alertNames).then((scores) => { laminar.scoreEvent("section_coverage", scores.section_coverage); laminar.scoreEvent("kb_citation_count", scores.kb_citation_count); laminar.scoreEvent("has_research_citations", scores.has_research_citations); laminar.scoreEvent("has_kb_links", scores.has_kb_links); laminar.scoreEvent("alert_coverage", scores.alert_coverage); laminar.scoreEvent("overall", scores.overall); }); ``` ### Laminar Offline Eval Run（批量評估）離線評估歷史報告品質： ```bash # 評估最多 10 份最新報告，推送至 Laminar report-quality-eval group python scripts/_eval_laminar.py --mode report ``` 對應 Python evaluators（`scripts/_eval_laminar.py`）： - `section_coverage_eval()` — 段落完整性 - `kb_links_eval()` — 知識庫引用數量 - `research_cited_eval()` — 業界研究提及 - `overall_eval()` — 綜合評分 ### 規則式 vs LLM-as-Judge 的選擇 | 維度 | 為何用規則式？ | 何時轉向 LLM-as-Judge？ | | ------------ | -------------------------------------------------- | ----------------------------- | | 結構品質 | 段落標題、連結計數是黑白分明的 | 不需要（規則式已充分） | | 知識庫融合 | 連結計數、關鍵字出現是客觀可測的 | 未來：語義相關性升級（v2.15） | | 業界研究引用 | 關鍵字匹配足以判斷引用存在 | 可能過度簡化，但對本量足夠 | | 邏輯清晰性 | 需要深度理解「建議是否合理」 → **LLM-as-Judge** ✅ | 現已透過 slash command 提供 | ### L2 連續指標（v3.7，rule-based） L1 的 5 維度呈二元分布（43 份報告中 72% 在 0.97-1.0），無法鑑別品質差異。L2 新增 6 個連續指標： | 指標 | 量什麼 | 偵測方式 | 預期鑑別範圍 | |------|--------|---------|-------------| | `cross_metric_reasoning` | 跨指標因果推理 | 因果連接詞 + 同段 ≥2 個不同指標名 / 5 | 0.0–1.0 | | `action_specificity` | 行動建議具體度 | 具體動作詞 vs 模糊詞比例 | 0.2–0.9 | | `data_evidence_ratio` | 數據引用密度 | 百分比模式 + 大數字(≥100) / 20 | 0.3–1.0 | | `citation_integration` | 引用整合度 | body 內 `[N]` vs 尾部堆積 | 0.0–1.0 | | `quadrant_judgment` | 流量象限判斷 | 象限關鍵字 + 解釋信號 | 0.0/0.5/1.0 | | `section_depth_variance` | Section 字數均衡度 | 1 - (std / mean) | 0.4–0.9 | 實作：`api/src/services/report-evaluator-l2.ts`（6 個 pure functions + `evaluateReportL2()` 聚合） ### L3 LLM-as-Judge（v3.7，Claude Code as Judge） 3 維度語意評估，由 `/evaluate-report-quality` slash command 執行（和 `/evaluate-meeting-prep-quality` 同模式）： | 維度 | 1 分 | 3 分 | 5 分 | |------|------|------|------| | `reasoning_depth` | 只列數字 | 有跨指標比較但無因果 | 多步因果 + 研究佐證 + 反向驗證 | | `actionability` | 「注意 X」 | 「檢查 X 的 Y」 | 「在 GSC 的 Y 報表篩選 Z 條件，預期提升 N%」 | | `insight_originality` | 複述數字 | 有基本解讀 | 發現非顯而易見的關聯 + 可驗證假設 | ### Composite V2 公式取代飽和的 `overall`，加權混合 L1+L2+L3（L3 可選）： ``` 有 L3： composite_v2 = L1_overall×0.20 + cross_metric×0.10 + action_specificity×0.10 + data_evidence×0.08 + citation_integration×0.07 + quadrant_judgment×0.05 + section_depth_var×0.05 + reasoning_depth/5×0.15 + actionability/5×0.10 + insight_originality/5×0.10 無 L3（auto fallback）： composite_v2 = L1_overall×0.30 + cross_metric×0.15 + action_specificity×0.15 + data_evidence×0.12 + citation_integration×0.10 + quadrant_judgment×0.10 + section_depth_var×0.08 ``` 設計參照：G-Eval (Liu et al., 2023, NeurIPS)、RAGAS/DeepEval temperature=0 慣例、專案 meeting-prep-eval 分層架構。 --- ## 20. SEO 成熟度模型（Demand Metric 改編） ### 來源 **Demand Metric**：加拿大 B2B 行銷研究與顧問公司（2006 年成立），專門建立行銷能力的基準測試和成熟度模型。他們的 SEO Maturity Model 將組織的 SEO 能力分成 4 階段： | 階段 | 原文 | 特徵 | | ---------- | ---- | ------------------------------------------ | | Ad Hoc | 臨時 | 沒有策略，誰想到就做 | | Developing | 發展 | 有初步計畫和基本工具，但執行不一致 | | Defined | 成熟 | 文件化流程、系統化追蹤、團隊有明確分工 | | Optimized | 領先 | 數據驅動決策、自動化、預測性優化、持續改進 | 原版涵蓋十餘個維度（Technical、Content、Link Building、Measurement、Team 等），適合大型組織全面評估。 ### 本專案改編（`/meeting-prep` S8）保留「分階段自評」的框架邏輯，針對 vocus SEO 顧問情境做三點調整： 1. **維度精簡為 4 個**：策略（Strategy）、流程（Process）、關鍵字（Keywords）、指標（Metrics）——原版的 Technical、Content、Link Building 等維度已在 E-E-A-T 和五層審計中覆蓋 2. **描述在地化**：用 vocus 實際情境替換通用描述（例如 L2 流程 = 「有 SOP 但執行不一」而非原版的 organization-wide adoption） 3. **動態評分**：每次 `/meeting-prep` 根據當週指標數據重新評分，而非一次性問卷 ### L1-L4 對照表 | 維度 | L1 起步 | L2 發展 | L3 成熟 | L4 領先 | | ------ | ---------- | ----------------- | ------------ | ------------------- | | 策略 | 無明確策略 | 有基本計畫 | 數據驅動決策 | 預測性優化 | | 流程 | 臨時處理 | 有 SOP 但執行不一 | 自動化流程 | 持續改進循環 | | 關鍵字 | 直覺選詞 | 有研究但零散 | 系統化追蹤 | 意圖分群 + 競爭分析 | | 指標 | 不看數據 | 看基本指標 | 多維度追蹤 | 預警 + 歸因分析 | ### 前端色階分數以深淺色階視覺化，一眼辨識強弱： | 等級 | 色階 | 語意 | | ----------- | ------------ | ------ | | L4 / 4-5 分 | 黑底白字 | 強 | | L3 / 3 分 | 深灰底白字 | 中等 | | L2 / 2 分 | 淺灰底黑字 | 待改善 | | L1 / 1 分 | 極淺灰底灰字 | 弱 | E-E-A-T 評分（1-5）共用同一套色階邏輯。 ### 與其他框架的分工 | 框架 | 評估什麼 | 用在哪 | | ------------------------------------ | ---------------------- | ------------------ | | E-E-A-T（Google QRG） | 內容品質信號 | `/meeting-prep` S6 | | 5-Layer SEO Audit | 技術 → UX 五層缺口 | `/meeting-prep` S5 | | 人本七要素（Gene Hong） | 網站作為「人」的完整度 | `/meeting-prep` S7 | | **SEO 成熟度（Demand Metric 改編）** | **組織能力階段** | `/meeting-prep` S8 | 四個框架互補：E-E-A-T 看內容、Audit 看技術、七要素看人性、成熟度看組織。 ### 成熟度全系統整合（v3.3，2026-03-13）成熟度模型從 `/meeting-prep` S8 單點使用，擴展至全系統四層： | 層 | 整合點 | Eval 覆蓋 | | ---- | --------------------------------------------------------------------------------- | ----------------------------------------------------------------------- | | 生成 | `/generate-report` S5 成熟度感知行動建議 + `/meeting-prep` S10 `[LX→LY]` 升級標籤 | E2 `s10_maturity_upgrade_labeled` + E4 `report_action_maturity_labeled` | | API | `GET /meeting-prep/maturity-trend` 時間序列端點 | E5 vitest 5 cases | | 評估 | E1 meta↔S8 一致性 + E3 `s8_maturity_justified`（LLM-as-Judge 第 6 維度） | 4 新 evaluators + 1 新 LLM 維度 | | 前端 | `MaturityTrendChart.tsx` 4 條折線（Recharts）+ `SummaryBadges` 變化摘要 | — | **Eval 新增**（6 個）： | # | 名稱 | 類型 | Laminar Group | | --- | -------------------------------- | ------------------ | ------------------------------ | | E1 | `s8_meta_maturity_consistency` | Rule-based | `meeting_prep_structure` | | E2 | `s10_maturity_upgrade_labeled` | Rule-based | `meeting_prep_structure` | | E3 | `s8_maturity_justified` | LLM-as-Judge | `meeting_prep_quality`（新） | | E4 | `report_action_maturity_labeled` | Rule-based | `report-quality` | | E5 | maturity-trend API tests | vitest | N/A | | E6 | `maturity_progression_sanity` | Rule-based（延後） | `maturity_progression`（延後） | **`_push_laminar_score.py` 擴充**：新增 `--json-file` 批次模式，讀取 `dimensions.*.score` 正規化至 [0,1] 後推送。 --- ## Laminar Eval Groups 流程圖（從 README 搬入） > 原位於 README.md「Laminar Eval Groups」section。 ```mermaid flowchart LR subgraph Laminar["Laminar Dashboard Groups"] G1["retrieval_quality"] G2["report-quality"] G3["keyword-retrieval"] G4["retrieval-enhancement"] G5["extraction_quality"] G6["enrichment_quality"] G7["chat_quality"] G8["data-quality"] G9["report-quality-eval"] end subgraph Scripts["來源腳本"] S1["evals/eval_retrieval.py"] S2["scripts/_eval_report.py"] S3["scripts/_eval_laminar.py\n--group keyword-retrieval"] S4["scripts/_eval_laminar.py\n--group retrieval-enhancement"] S5["evals/eval_extraction.py"] S6["evals/eval_enrichment.py"] S7["evals/eval_chat.py"] S8["scripts/_eval_data_quality.py"] S9["scripts/_eval_laminar.py\n--mode report"] end subgraph Trigger["觸發方式"] CI["eval.yml\n每次 push main"] MAKE_EL["make eval-laminar"] MAKE_ES["make eval-semantic"] MANUAL["手動執行"] ETL_CI["etl-and-deploy.yml\nquality gate"] end subgraph Target["評估什麼"] T_SEARCH["POST /search\n關鍵字搜尋品質"] T_REPORT["POST /reports/generate\n週報生成品質"] T_ETL["Step 2 extract_qa.py\nQ&A 萃取品質"] T_ENRICH["scripts/enrich_qa.py\n同義詞 + 時效性"] T_CHAT["POST /chat\nRAG 問答品質"] T_DATA["output/qa_final.json\n資料集整體品質"] end S1 --> G1 S2 --> G2 S3 --> G3 S4 --> G4 S5 --> G5 S6 --> G6 S7 --> G7 S8 --> G8 S9 --> G9 CI --> S1 CI --> S5 MAKE_EL --> S3 MAKE_EL --> S4 MAKE_EL --> S9 MAKE_ES --> S3 MANUAL --> S2 MANUAL --> S6 MANUAL --> S7 MANUAL --> S8 ETL_CI --> S8 S1 --> T_SEARCH S3 --> T_SEARCH S4 --> T_SEARCH S2 --> T_REPORT S9 --> T_REPORT S5 --> T_ETL S6 --> T_ENRICH S7 --> T_CHAT S8 --> T_DATA ``` ### Eval Groups 速查表 | Laminar Group | 來源腳本 | 觸發方式 | 評估對象 | 指標 | | ------------------------ | -------------------------------------- | ------------------------------------------- | ------------------------- | ------------------------------------------------------------------------------------------------------------------------------------- | | `retrieval_quality` | `evals/eval_retrieval.py` | CI 自動（每次 push） | 關鍵字搜尋 | keyword_hit_rate, top1_category, top5_coverage | | `keyword-retrieval` | `_eval_laminar.py` | `make eval-laminar` | 關鍵字搜尋 | hit_rate, mrr, precision, recall, f1, ndcg, top1_cat, top5_cov | | `retrieval-enhancement` | `_eval_laminar.py --group` | `make eval-laminar` | 同義詞增強搜尋 | synonym_coverage, kw_hit_with_synonyms, freshness_rank | | `report-quality` | `_eval_report.py` | 手動 | 週報生成 | section_coverage, kb_links, research_cited | | `report-quality-eval` | `_eval_laminar.py --mode report` | `make eval-laminar` | 週報生成 | section_coverage, kb_links, research_cited, overall | | `extraction_quality` | `evals/eval_extraction.py` | CI 自動（graceful skip） | Q&A 萃取 | qa_count_in_range, keyword_coverage, no_admin, avg_confidence | | `enrichment_quality` | `evals/eval_enrichment.py` | 手動 | 離線 enrichment | kw_hit_with_synonyms, freshness_rank, synonym_coverage | | `chat_quality` | `evals/eval_chat.py` | 手動 | RAG 問答 | answer_keyword_coverage, top_source_category | | `data-quality` | `_eval_data_quality.py` | ETL CI / 手動 | 資料集整體 | qa_count, avg_confidence, category_distribution | | `meeting_prep_structure` | `evals/eval_meeting_prep_structure.py` | `make evaluate-meeting-prep-structure` / CI | Meeting-Prep 報告結構 | section_completeness, metadata_valid, citation_block_valid, question_count_valid, eeat_score_format, maturity_level_format 等 11 指標 | | `meeting_prep_grounding` | `evals/eval_meeting_prep_grounding.py` | `make evaluate-meeting-prep-grounding` / CI | Meeting-Prep 引用與接地性 | citation_id_resolution, citation_category_consistency, citation_count_in_range, s4_four_sources_populated, inline_citation_coverage | | `report_quality_v2` | `_eval_report.py` + `report-evaluator-l2.ts` | `make evaluate-report` / API 非同步 | 週報生成（三層） | composite_v2(≥0.69), section_coverage, has_kb_links, action_specificity(≥0.5), cross_metric_reasoning(≥0.25) | > **`report_quality_v2` 設計**：L1 `overall`（binary 飽和，72% 在 0.97-1.0）→ 三層架構：L1 結構護欄 + L2 連續 rule-based（6 指標）+ L3 LLM-as-Judge（3 維度）。`composite_v2` 公式：有 L3 時 L1:20%+L2:45%+L3:35%；無 L3 時 L1:30%+L2:70%。閾值 0.69 基於 44 份報告實測（BAD max=0.62, GOOD min=0.75, gap=0.13）。 > **注意**：Dashboard 中的 `v2.12-fixed`、`v2.12-1317items`、`retrieval-eval-20...` 等為歷史一次性 run（測試或版本驗證），不是固定 group。 --- ## 步驟 6：Laminar 離線評估（從 README 搬入） > 原位於 README.md「步驟 6」section。 ### 概述基於 Laminar SDK 的離線評估系統，自動監控檢索、萃取、RAG chat 三個環節的品質。所有評估皆無需 OpenAI API（pure Python / SQL 邏輯）。 ### 啟動方式 **前提**：安裝 Laminar SDK 並設定 API key ```bash pip install lmnr export LMNR_PROJECT_API_KEY= ``` **執行評估**： ```bash # 方式 1：Laminar 正式 eval run（推薦，20 cases 黃金集合） python scripts/_eval_laminar.py # 預設 top-k=5，group="retrieval-eval" python scripts/_eval_laminar.py --top-k 10 # 改變檢索深度 python scripts/_eval_laminar.py --group "v2.12" # 自訂 group 名稱 # 方式 2：其他評估腳本 python evals/eval_retrieval.py python evals/eval_extraction.py python evals/eval_chat.py ``` **Group 設計**： - 預設 `--group "keyword-retrieval"` 讓所有 eval run 進同一 group - Laminar Dashboard 上可畫趨勢折線圖，追蹤 5 個指標變化 - `concurrency_limit=1`：每次單個 run，避免並發上傳失敗 **檢視結果**： ``` # Laminar 儀表板 https://laminar.sh/app/evals ``` ### 評估維度 | 評估類型 | 檔案 | 測試集 | 評估指標（v2.12） | | ------------------- | -------------------------- | ----------------------------- | ---------------------------------------------- | | **Retrieval 品質** | `scripts/_eval_laminar.py` | golden_retrieval.json (20 筆) | Precision@K、Recall@K、F1 Score、Hit Rate、MRR | | **Extraction 品質** | `evals/eval_extraction.py` | golden_extraction.json | Q&A 計數、Keyword Coverage、無管理內容 | | **Chat 品質** | `evals/eval_chat.py` | 前 10 retrieval scenarios | 回答長度、來源涵蓋、關鍵字匹配 | ---

Research & Science

Observability, Monitoring & Analytics Integrations Research

評估系統