**繁體中文** | [English](README_EN.md)

# 台灣建築技術規則 AI 檢索架構評測：Hybrid RAG vs. Graph RAG vs. OKF-Wiki

實作並客觀評測三套 AI 知識檢索架構，對象是台灣《建築技術規則建築設計施工編》（389 條法規）。使用 15 道含跨章節推論、數值計算與例外但書的實務題目，量化測試各架構從建置成本到檢索生成的真實表現。

---

## 📊 量化榜單 (Benchmark V4.1)

採用 RAGAS 五維度量表 + 人工標準答案 (Ground Truth) 評定：

| 系統架構 | Context Precision | Context Recall | Faithfulness | Answer Relevancy | Answer Correctness | **5D 總均** |
| :--- | :---: | :---: | :---: | :---: | :---: | :---: |
| 🏆 **OKF-Wiki**（Markdown 階層導航） | 0.52 | 0.59 | 0.56 | **0.98** | **0.89** | **0.71** |
| 🥈 **Hybrid RAG**（向量 + BM25） | **0.58** | **0.69** | **0.58** | 0.71 | 0.62 | 0.64 |
| 🥉 **Graph RAG**（知識圖譜三元組） | 0.29 | 0.40 | 0.25 | 0.57 | 0.51 | 0.40 |

| 系統 | 優勢 | 主要限制 |
| :--- | :--- | :--- |
| OKF-Wiki | 正確率最高 (0.89)，跨章節綜合推論強 | Agent 多輪翻閱目錄，跨章節查詢耗時 |
| Hybrid RAG | 召回率最高 (0.69)，建置成本最低，查詢 ~0.9s | 切塊邊界易截斷法條脈絡，引入雜訊 |
| Graph RAG | 查詢最快 (~0.6s)，精準鎖定實體數值關聯 | 前期萃取成本高；細部但書易遺漏 |

> 完整逐題紀錄：[V4.1 評測報告](docs/benchmark_v4_report.md) | 歷史參考：[V3 報告](docs/benchmark_v3_report.md)

---

## 📂 文件索引

| 文件 | 說明 |
| :--- | :--- |
| [📋 題目與標準答案速查](docs/qa_reference.md) | 15 道評測題目 + 人工標準答案，人類可讀版 |
| [V4.1 詳細評測報告](docs/benchmark_v4_report.md) | 15 題逐題數據、檢索文本、三階段審查紀錄 |
| [三大資料庫架構建置指南](docs/three_rag_infrastructure_guide.md) | 建置工法、模型選型、Mermaid 架構圖 |
| [V4 升級計畫](docs/v4_upgrade_plan.md) | 三大系統下一階段升級技術規格 |
| [專案進度手冊](docs/PROJECT_STATUS.md) | 新 Agent 快速定位，目前狀態與下一步任務 |
| [V3 基準報告](docs/benchmark_v3_report.md) | 早期人工主觀評測（歷史參考） |

---

## 📐 RAGAS 五維度說明

1. **Context Precision**：檢索文本中真正有用的比例；夾帶無關條文扣分。
2. **Context Recall**：是否涵蓋標準答案所需的全部法條與例外但書。
3. **Faithfulness**：回答是否 100% 來自檢索內容；依賴預訓練記憶補充法規視為 Unfaithful。
4. **Answer Relevancy**：回答是否直接切中提問，不答非所問。
5. **Answer Correctness**：與人工標準答案在技術數值與語意上的吻合度。
6. **棄權處分**：回覆「無法回答」者，Faithfulness / Relevancy / Correctness 強制 0 分。

---

## 🔍 底層技術棧

1. **Hybrid RAG** — ChromaDB (向量) + Rank-BM25 (關鍵字) + RRF 重排；依「編/章/節/條/項/款」結構切塊，保留完整層級。
2. **Graph RAG** — LLM 萃取 389 條法規為三元組，建立 NetworkX 圖；向量搜尋定位入口實體，再 1-Hop 展開並回溯原文。
3. **OKF-Wiki** — 純 Markdown 階層目錄 + `_index.md` 雙向連結；Agent 持有讀檔工具，從目錄頂層逐步導航至目標條文，零向量庫依賴。

---

## 🚀 評測流水線

```
[題庫 15 題] → 45 位 Generator Subagents → 檢索腳本/OKF翻閱 → 答卷 JSON
[標準答案]  → 45 位 Evaluator Subagents  → 初步檢驗→嚴格查核→綜合評定 → RAGAS 分數
                                                                    ↓
                                                           V4.1 完整評測報告
```

三階段：**Generation（答題）→ Evaluation（審查）→ Aggregation（腳本解析日誌，自動彙整報告）**

---

## 🎯 技術選型指南

| 場景 | 推薦 | 核心理由 |
| :--- | :--- | :--- |
| 初期驗證、PoC、預算有限 | **Hybrid RAG** | 建置快、召回 0.69、無圖譜萃取費用 |
| 高合規、醫療、密集條件關係 | **Graph RAG** | 實體關聯精準，查詢極快；需補足原文對照 |
| 跨章節調查、企業知識庫助理 | **OKF-Wiki** | 正確率 0.89，Markdown 易由工程師直接維護 |

---

## 🔮 Roadmap（詳見 [V4 升級計畫](docs/v4_upgrade_plan.md)）

1. **Hybrid RAG — Contextual Chunk Enrichment（Phase 1，優先）**：切塊時注入章節脈絡摘要；同步導入 Self-Querying Metadata Filter 與 Parent-Child Chunk Strategy。
2. **Graph RAG — Graph-Vector 雙棲入口**：節點描述向量化，語意定位種子節點後展開圖譜；預計算 Leiden 社群摘要。
3. **OKF-Wiki — Hybrid Routing**：向量快速定位起點目錄，再 Agent 接手周邊導航。
4. **最終：多架構融合路由**：依問題特徵智慧分流至最適系統。
