# Taiwan Building Code RAG — V4 升級全方位計畫

> **文件用途**：基於 V3 Benchmark 結論，結合 2025–2026 年最新業界架構趨勢，為三大系統（Hybrid RAG、Graph RAG、OKF-Wiki）各自制定下一階段的獨立升級路徑，並設計更嚴謹的評估框架。
>
> **原始提案**：此文件由使用者在另一個對話中整理，於 2026-08-14 正式納入專案文件體系。

---

## 📊 V3 現況回顧與核心矛盾

| 系統 | V3 得分 | 最大優點 | 最大痛點 |
|---|---|---|---|
| Hybrid RAG | 33% | 建置最快、成本最低 | 截斷失真、LLM 注意力分散 |
| Graph RAG | 67% | 零幻覺、精準數值條件 | Entity Extraction 失敗即全線崩潰 |
| OKF-Wiki | 70% | 最高準確率、跨章節推論 | 查詢慢、簡單問題也要完整導航 |

**核心洞察**：每個系統的「弱點」幾乎都是另一個系統的「優點」。這說明最佳策略並非三選一，而是先將各自升級到 V4 階段的上限，再開始設計融合架構。

---

## 🛠️ 第一部分：三大系統的 V4 升級策略

### 🔵 System 1：Hybrid RAG 升級 (Vector + BM25)

**根本問題**：法規文件的條文之間往往有強烈的上下文依賴（例如「第 X 條依前條規定…」），純粹的 chunk 切割會打斷這種語意依賴。

**V4 升級路徑：三層優化**

**Layer A — Contextual Chunk Enrichment（情境化區塊強化）**
> Anthropic 在 2024 年提出的 Contextual Retrieval 證實能將 RAG 的失效率降低 49%。
- 切塊前，先讓小模型（Gemini Flash）為每個 Chunk 生成一段 50 字以內的「微型情境摘要」（說明它屬於第幾章、關於什麼主題）。
- 將這段摘要**前綴**附加在 Chunk 文字的開頭一起存入向量庫，確保每個碎片都帶著自己的「身世」，大幅降低斷章取義。

**Layer B — Self-Querying Metadata Filter（自查詢過濾器）**
- 建立 ChromaDB 的 Metadata Schema（包含 `章節`、`條號`、`適用類別`，例如：住宅區、商業區、工業區）。
- 在查詢前，先讓 LLM 快速分析問題是否包含可萃取的過濾條件，若有則先過濾，再做向量搜尋。這可將候選 Chunk 數量從數百降到幾十，大幅提升 LLM 的集中度。

**Layer C — Parent-Child Chunk Strategy（父子文件優化）**
- 以小 Chunk（200 tokens）做精準向量匹配，但回傳給 LLM 時自動「上移」到父文件（整條條文或整節）來補充完整上下文，解決截斷問題。

---

### 🟠 System 2：Graph RAG 升級

**根本問題**：Leiden 社群演算法依賴靜態的前置 Entity Extraction，一旦 LLM 在建圖階段漏掉某個實體，後續查詢時就會出現「圖上找不到入口」的硬性失敗。

**V4 升級路徑：三重修復**

**Fix A — LazyGraphRAG（延遲建圖策略）**
> 微軟在 2025 年提出 LazyGraphRAG，大幅降低初期建圖成本。
- 不在建圖時就強行萃取所有實體，而是保留原始文本的索引，在**查詢時**才動態萃取與問題相關的局部子圖。
- 好處：可以先以較低成本建立一個「骨架圖」，遇到實際問題再動態補全，而不是事先完美但耗費 10 倍成本的全圖。

**Fix B — Graph-Vector 雙棲入口（Vector Seed + Graph Traversal）**
- 將圖譜中的每一個 Node（實體節點）的描述也向量化，存入一個輕量的向量索引。
- 查詢時先用向量相似度找到最接近的 2~3 個「種子節點 (Seed Nodes)」，再以這些節點為起點在圖上做鄰域擴展（BFS/DFS），徹底繞開「找不到精確實體名稱」的問題。
- 效果：這讓 Graph RAG 從「純精準比對」進化為「模糊語意入口 + 精準圖譜推理」的混合模式。

**Fix C — 預計算社群摘要（Community Summaries with k-core Hierarchy）**
- 用 Leiden 或 k-core 演算法將圖譜中相關條款叢集（例：「所有消防逃生相關條款」）預先計算為社群摘要。
- 遇到全局型問題（「請總結台灣建築法規中所有關於消防設施的要求」），直接讀取社群摘要，無需遍歷整個圖，速度從數十秒壓縮到幾秒。

---

### 🟢 System 3：OKF-Wiki Agent 升級

**根本問題**：Agent 缺乏路由記憶。每次遇到問題，它都從 MOC（目錄）開始重新翻，遇到簡單問題嚴重浪費。

**V4 升級路徑：賦予 Agent 記憶與自覺**

**Upgrade A — Semantic Caching（語意快取）**
- 建立一個輕量的 `navigation_cache.json`，紀錄問題語意向量與對應的「成功導航路徑（哪個子文件、哪個章節）」。
- 下次遇到語意相似度 > 0.85 的問題，直接跳過目錄導航，秒速定位到正確位置。

**Upgrade B — Specialized Tool Suite（工具特化）**
取代原來通用的 `read_file` 工具，改為以下三件式工具組：
  - `search_toc(keywords)` → 快速的正則/BM25 工具，瞬間回傳相關的 OKF 子文件清單。
  - `read_section(file, section_name)` → 直接讀取指定章節，避免 Agent 讀取整個文件。
  - `cross_reference_check(article_id)` → 專門追蹤條文中的「依前條」、「參照第 X 條」等交叉引用，自動補抓關聯條文。

**Upgrade C — Confidence-Based Routing（信心度分流）**
- 在 Agent 呼叫 LLM 前，先讓它輸出一個 `confidence` 分數（0~1）。
- 若信心度 > 0.9（代表問題簡單），直接跳過 TOC 導航，用 `search_toc` 一步到位；若信心度 < 0.5（代表問題複雜），才啟動完整的多步導航推理流程，避免資源浪費。

---

## ⚖️ 第二部分：V4 Benchmark 評估框架設計

過去的評估採用單一 LLM 給整題綜合分數，這有「裁判偏見」與「顆粒度太粗」兩個問題。V4 評估框架要走向**多維、可重現、可防禦**。

### 評估架構：三層式評估金字塔

```
        ┌──────────────────────┐
        │  Layer 3: Adversarial │  → 主動攻擊測試（幻覺、矛盾、拒絕）
        ├──────────────────────┤
        │  Layer 2: LLM Judge   │  → 多裁判辯論評分
        ├──────────────────────┤
        │  Layer 1: RAGAS Metrics│  → 客觀四維度指標
        └──────────────────────┘
```

### Layer 1：RAGAS 四維度客觀評估

採用 **RAGAS** 評估標準取代單純的主觀打分。考量到 API 配額成本，將不使用官方 RAGAS 套件，而是由「評估專用子代理人 (Subagent)」在背景人工推算以下四個客觀指標：

| 指標 | 含義 | 對應我們的關鍵痛點 |
|---|---|---|
| **Context Precision** | 找到的法規片段中，真正有用的比例 | 測試 Hybrid RAG 塞垃圾的問題 |
| **Context Recall** | 回答所需的法規，有沒有全部被找到 | 測試 Graph RAG 漏掉實體的問題 |
| **Faithfulness** | 最終答案是否 100% 來自檢索結果 | 測試三系統的幻覺率 |
| **Answer Relevancy** | 答案是否直接回答了問題 | 測試 OKF-Wiki 是否偏題 |

### Layer 2：Multi-Judge 多裁判辯論評分

> 2026 年業界標準：單一裁判模型因 Position Bias（偏愛答案位置靠前的選項）而不可信。

- **主審**：Gemini 3.1 Pro → 根據 Ground Truth 給出初步分數與評分理由。
- **交叉詰問者**：以另一次 LLM 呼叫扮演「魔鬼代言人」，嘗試找出主審評分的漏洞（例如：「答案引用了條號，但內容實際上對嗎？」）。
- **裁決**：最終分數由主審考量詰問後重新裁定，並輸出評分理由鏈 (Reasoning Chain)。

### Layer 3：Adversarial Dataset（對抗性測試題庫）

建議在題庫中加入以下三類壓力測試：

**A. 幻覺拒絕測試 (Rejection Test)**
> 「請問建築法規中，關於『智慧建築能源優化補貼』的計算方式為何？」
- **正確行為**：系統應回答「本法規中未明確規範此議題，建議查閱相關能源法規」。
- **失敗行為**：系統捏造一個聽起來合理的補貼公式。

**B. 前提矛盾測試 (Premise Contradiction Test)**
> 「在住宅區興建大型石化廠，廠區的防火距離應為多少公尺？」
- **正確行為**：系統應先指出「住宅區依法不得設置大型石化廠（前提矛盾）」，而非盲目回答防火距離。
- **失敗行為**：系統直接查詢石化廠的防火距離並給出數字。

**C. 跨章節依賴測試 (Cross-Reference Test)**
> 「請問 B 類建築物（依第三章定義）若位於地震二區（依附表一），其結構計算需採用哪種標準？」
- **正確行為**：系統必須同時讀取第三章（B 類定義）、附表一（地震分區）、及相應的結構設計章節，才能給出完整答案。
- **測試目標**：這是 OKF-Wiki 的優勢題型，也是 Hybrid RAG 最容易失敗的地方。

### 評估工具選型建議

| 工具 | 用途 | 推薦場景 |
|---|---|---|
| **Subagent-Driven Evaluation** | RAGAS 四維度 + 多裁判辯論 | 每次實驗都跑，免 API Key 且支援高階推理 |
| **DeepEval** | Pytest 整合，CI/CD 品質閘門 | 未來若有經費建立外部 API Key 時可轉移 |
| **Giskard** | 紅隊測試、合規文件生成 | 若要對外展示或發表論文時使用 |

---

## 🗺️ 執行優先順序建議

> [!IMPORTANT]
> **建議戰略：先有尺，再量物。**
> 在優化任何系統之前，先建立可信的 V4 評估框架（Layer 1 RAGAS + 對抗性題庫），確保後續每次改動都有可比較的數字依據。

```
Phase 0（1~2 天）  → 建立 Subagent 評估 Prompt + 設計 10 道 Adversarial 題目
Phase 1（3~5 天）  → 對 V3 三系統派發 Subagent 跑 RAGAS 基線，取得各系統的四維度分數
Phase 2（1 週）    → 選定一個系統（建議優先升級 Hybrid RAG，成本最低）實作 V4 改良
Phase 3（按需）    → 同步升級 Graph RAG（Fix B → Graph-Vector 雙棲入口最划算）
Phase 4（按需）    → 升級 OKF-Wiki Agent 工具特化
Phase 5（最終）    → 設計 Query Routing 融合架構，整合三大系統優點
```

---

## 📚 參考技術資源

- [Anthropic Contextual Retrieval Blog](https://www.anthropic.com/news/contextual-retrieval)
- [Microsoft GraphRAG GitHub](https://github.com/microsoft/graphrag)
- [Microsoft LazyGraphRAG](https://www.microsoft.com/en-us/research/blog/lazygraphrag-setting-a-new-standard-for-quality-and-cost/)
- [RAGAS Framework Docs](https://docs.ragas.io/)
- [DeepEval RAG Evaluation](https://docs.confident-ai.com/)
