OceanRAG 系統說明

專為中小企業設計的零外部依賴企業知識問答平台

功能特色

1. 智慧問答引擎

採用 SSE（Server-Sent Events）即時串流回答。支援多輪對話，查詢前執行意圖分類與 查詢改寫（Query Rewriting），再進入向量搜尋流程。核心技術包含 Jina v5 (1024-dim) 向量模型與 Groq LLM 生成引擎，首 token 回應延遲約 500ms 起。

每個回答都會標示引用來源 [1][2] 標籤，點擊可直接查看原始文件段落，含 PDF bounding box 精準定位。

• 三層門控（3-layer）：意圖分類、向量閾值、NLI 信心評分，層層把關不符合的查詢。
• 來源追溯：每個回答附帶引用來源 [1][2] 標籤，點擊可查看原始文件段落。
• 信心查核：逐句分析回答是否有文件依據，標示需要注意的推論內容，採用 NLI 事實查核。

2. 事實查核引擎（NLI Pipeline）

採用 Erlangshen-Roberta-330M-NLI 模型進行 NLI 推論，對 LLM 回答逐句拆分為可驗證的聲明（Claim），再與原始文件比對，輸出三級結果：

• Entail（支持）：回答內容與原始文件一致，可信度高。
• Neutral（中性）：文件中找不到直接支持，可能是 LLM 推論產物，需要使用者自行確認。
• Contradict（矛盾）：回答與原始文件矛盾，AI 幻覺可能性高，BLOCK 級別直接攔截回答。

最終輸出三級信心結果：PASS（多數 Entail）、WARN（Neutral 居多）、BLOCK（Contradict），BLOCK 級別的回答不會顯示給使用者，改為提示資訊不足。

3. 三層門控機制（Gatekeeping）

三層門控是 OceanRAG 在 LLM 生成回答前的多重品質把關機制：

• A-layer（意圖分類）：判斷查詢是否為知識庫問題，約 10%～15% 的非相關查詢在此被攔截。
• B-layer（品質閾值）：向量相似度閾值 0.4 + Reranker 精排閾值 0.6，雙重把關，不達標不送 LLM。實測約 30%～50% 的查詢在此被攔截，有效降低成本。
• C-layer（NLI 信心評分）：對生成結果逐句驗證，BLOCK 級別直接攔截，約 5%～10% 的回答在此被過濾。

4. 文件 ETL Pipeline（8 階段）

文件上傳後自動進入全自動化處理流程：

1. 解析：偵測檔案類型並解析，支援 PDF.js / mammoth.js / SheetJS，含 magic number 格式驗證。
2. 清洗：去除冗餘格式、特殊字元，保留語義完整性。
3. 切塊（Chunking）：依語意段落分割，預設 512 tokens/chunk，overlap 64 tokens。
4. 摘要：對每個 chunk 產生語義摘要，輔助 reranker 精準比對。
5. 向量化：透過 Jina v5 embedding API 生成 1024-dim 語義向量。
6. 品質檢測：5 維度品質分數，滿分 100，60 分以下警示，通過才可入庫。
7. 入庫：向量寫入 LanceDB，metadata 寫入 SQLite，atomic transaction 確保一致性。
8. 通知：處理完成後通知管理員進行審閱。

5. 四層授權架構（RBAC Pre-filter）

每個請求依序通過以下四層驗證：

1. JWT Cookie + Session 驗證：未認證回傳 401。
2. 角色檢查：employee / dept_admin / master_admin 三級角色，不符合回傳 403。
3. 機密等級比對：用戶 clearance_level 必須大於等於文件 clearance_level，否則不回傳任何資料（null 值強制轉型，防止繞過）。
4. 部門歸屬 + 功能權限矩陣：跨部門存取需授權，功能權限矩陣控制各項操作。

RBAC pre-filter 在 LanceDB 向量搜尋前執行，確保超出權限的資料根本不會被搜尋到。

6. 其他功能模組

• 用量統計與儀表板：三層 drill-down（部門 → 使用者 → 查詢），Chart.js 圖表，KPI 計算，CSV 匯出。
• AI 模型管理：generation / embedding / reranker / routing 各自可切換，健康探測 endpoint，熱切換不重啟。
• 文件審閱：PDF.js 即時預覽、mammoth.js Word 渲染，支援批量操作、品質分數。
• 風險監控：EXP_DECAY 加權風險分數（滿分 100，60 分警示 / 80 分嚴重警報），冷卻機制 4 小時。

核心效果對比

以下對比展示 OceanRAG 與傳統 RAG 方案在各項關鍵指標上的差異，突顯系統的設計優勢。

成本結構分析

OceanRAG 在成本控制上具備顯著優勢。相比 Groq 或 OpenAI 等 token 付費方案，OceanRAG 搭配 B-layer 門控可攔截約 30%～50% 的無效查詢，避免消耗 LLM 呼叫成本。同時 Embedding 只在文件入庫時執行一次，查詢只做 query embedding，不會重複消耗。

系統架構（Tiered Architecture）

OceanRAG 採用四層獨立架構，層間以 X-Service-Token 通訊，IP CIDR 白名單保護，限流 30 req/min/IP。

T1 前端介面     | HTML/JS，auth-guard.js 權限控管，SSE 即時串流
T2 RAG 引擎     | 向量搜尋 + RBAC Pre-filter + LLM 管理 + NLI 驗證
T3 文件處理     | 8 階段 ETL Pipeline（解析→清洗→切塊→摘要→向量化→品質檢測→入庫→通知）
T4 平台管理     | 使用者管理、認證授權、安全事件、系統設定

為什麼不用 PostgreSQL / Redis？ OceanRAG 刻意選擇 SQLite 而非 PostgreSQL，因為在 1,000 名用戶以下的企業場景，SQLite 的效能已經足夠，且零部署依賴大幅降低維運成本。同理 LanceDB 取代 Pinecone / Weaviate，以本地檔案形式儲存向量，不需要額外的向量資料庫服務。關於資料庫升級分支的細節請參閱部署章節。

查詢流程（11 步驟）

以下為一次完整查詢的處理流程：

1. 請求發送 — T1 前端發出查詢，攜帶 JWT httpOnly Cookie 與 session_id。
2. 身份驗證 — T4 驗證 JWT 簽章、角色權限、機密等級、部門歸屬。
3. A-layer 意圖分類 — 判斷是否為知識庫相關查詢，非相關查詢提早攔截。
4. 查詢改寫 — 根據 session 歷史對話改寫查詢，提升檢索精準度。
5. RBAC Pre-filter — 根據使用者 clearance_level 與 department_id 過濾，超出權限的文件完全不參與搜尋。
6. 向量搜尋 — LanceDB 搜尋 top-K 候選（預設 K=20），向量相似度閾值 0.4。
7. Reranker 精排 — 對 top-K 結果重排序（閾值 0.6），不達標不送 LLM（B-layer 門控）。
8. LLM 生成 — 將 B-layer 通過的 Context 送入 Groq LLM，SSE 串流回傳至 T1。
9. NLI 事實查核（C-layer） — 對生成結果逐句拆分為 claim，比對 NLI 模型，輸出 PASS / WARN / BLOCK。
10. 結果輸出 — PASS/WARN 的結果附帶引用來源回傳，BLOCK 則回傳提示訊息。
11. 稽核記錄 — 完整查詢鏈路寫入 audit_logs。

雙 RAG 系統

OceanRAG 支援兩種查詢模式，可動態切換：

• 標準模式（Standard RAG）：文件庫內精準搜尋，top-K 預設 5 筆，適合已知範圍的快速問答。
• 深入模式（Deep RAG）：跨文件跨時間深度搜尋，top-K 預設 20 筆，搭配意圖識別與查詢改寫，適合需要交叉比對多份文件的複雜查詢（如「比較 2023 與 2024 的營收差異」）。搭配釘選模式可進行多輪深度問答。

安全議題與設計

OceanRAG 採用多層縱深防禦（Defence in Depth）策略，每一層獨立運作，確保單點失守不會導致整體安全崩潰。

管理儀表板

用量統計

儀表板提供三層 drill-down 分析：部門總覽（各部門 token 消耗與查詢次數）→ 使用者明細（個別使用者用量趨勢）→ 查詢記錄（每筆查詢的 token、文件來源、門控結果）。可匯出 CSV 供財務或管理層分析。

• KPI 指標：當日查詢數、B-layer 與 NLI BLOCK 比例、平均回應時間。
• 配額管理：對每個部門設定查詢上限，超過配額自動暫停，防止預算超支。
• 警示線：當部門用量達到 80% 配額時自動通知管理員。

AI 模型管理

OceanRAG 將 AI 模型依角色分類，每個角色可獨立切換，熱切換不需重啟服務。

每個角色都有獨立的健康探測 endpoint，可即時檢查模型是否正常運作，切換模型後 30 秒內自動驗證可用性。

雙日誌系統

OceanRAG 建立兩套互補的日誌系統，確保完整的可追溯性：

1. 對話紀錄（Conversation Logs）

記錄每筆查詢的完整鏈路，包含原始問題、LLM 回答、NLI 評分結果，以 session_id 串聯，方便使用者回顧歷史對話。

• 標記是否觸發 B-layer 門控（檢索品質不足）。
• 記錄 NLI WARN/BLOCK 事件，追蹤 LLM 幻覺發生頻率。
• 保存查詢改寫前後的 Prompt 記錄。

2. 稽核日誌（Audit Logs）

記錄所有系統操作：登入 / 登出、文件上傳 / 審閱 / 下架、權限變更等。每筆記錄不可刪除、不可竄改。

• SQLite DELETE trigger 保護：audit_logs 禁止 DELETE 操作，trigger 在任何刪除嘗試時自動回滾，確保記錄永久保存。
• SHA-256 雜湊鏈：每筆記錄的 hash 值包含前一筆記錄的 hash，形成不可竄改的鏈式結構，任何單筆竄改都會導致後續驗證失敗。
• 稽核匯出 API：管理員可透過 /api/audit/export 匯出完整的稽核記錄（CSV / JSON），供法規遵循使用。

開發計畫

1. MCP 伺服器（Model Context Protocol）

OceanRAG 計畫支援 MCP 伺服器，讓 OceanRAG 成為任何 AI Agent 的知識來源。Claude、GPT-4 等透過 MCP 協議直接查詢 OceanRAG 的文件庫，實現跨平台知識共享。

2. API 與 Web 整合

開放 RESTful API 供第三方系統整合，包含查詢、文件管理、使用者管理等端點。Web 搜尋整合允許在知識庫不足時，自動從網路搜尋補充答案。

3. Agent Teams

多 Agent 協作模式，讓不同角色的 AI Agent 分工處理複雜任務（如研究、分析、報告），每個 Agent 都受到 OceanRAG 的權限控制與稽核追蹤。

模型選擇指南

OceanRAG 的核心理念是「開源可商用」，以下是各模型角色的選擇考量：

部署升級

1. 相容性與環境需求

• 作業系統：Windows / macOS / Linux 均可
• Python：3.10+
• GPU：NLI 模型建議有 GPU（CPU 也可但較慢）
• 硬體最低：Mac Mini M4（約 2 萬台幣）即可運行完整系統

2. 部署方式

• 本地伺服器：最簡單的部署方式，適合單一辦公室。四個 Tier 各自啟動，透過 proxy 統一入口。
• 私有雲：適合多據點企業，可將 T2/T3/T4 部署在私有雲，T1 前端透過 VPN 存取。

3. 資料庫升級分支

OceanRAG 目前使用 SQLite + LanceDB 作為零依賴方案。未來若使用者量超過 1,000 人，可考慮以下升級路徑：

• SQLite → PostgreSQL：支援併發寫入、更精細的權限控制、更好的備份機制。
• LanceDB → Pinecone / Weaviate：支援分散式向量搜尋、更大規模的文件庫。

架構設計已預留抽象層，切換資料庫不需修改業務邏輯。