icey1287/SuperMew

SuperMew – 可稽核的 RAG 優先智能體平台

簡介 – SuperMew 是一個自託管的 AI 智能體框架，它將每次使用者互動視為持久且可重放的工作流，而非一次性的 HTTP 呼叫。它將對話執行緒、執行（Runs）、事件和檢查點串聯起來，使得聊天可以暫停以供人在迴路（HITL）審查，稍後恢復，並完全稽核。

核心理念

• 持久化領域物件 – Thread、Message、Run、Event、Checkpoint、DocumentVersion 儲存在 PostgreSQL（中繼資料）和 Milvus（向量區塊）中。這允許您重放或除錯任何過去的互動。
• 兩階段文件發布 – 新的文件版本在隔離的候選作用域中建立，經過驗證後，透過 PostgreSQL CAS 操作原子性地切換。正在進行的查詢永遠不會看到半成品的索引。
• 混合 RAG 管線 – 密集向量搜尋（Milvus）+ 原生 BM25 透過互補排名融合（Reciprocal Rank Fusion）融合，可選地重新排序，判斷證據品質，並可以回退到單一 HyDE 或步驟回退重寫。所有中間步驟都記錄在 UI 視覺化的 rag_trace 中。
• 技能/工具註冊表 – 固定版本的技能（知識庫查詢、天氣、唯讀 SQL、網路研究、沙箱程式碼執行、受限 HTTPS JSON）在註冊表中宣告。每個工具的架構僅在執行的權限檢查後向智能體揭露，並且護欄強制執行允許/拒絕/核准策略。
• 模型控制平面 – 管理員定義模型設定檔（無機密資訊）並將其分配給四個角色：Answer、Fast、Grader、Evaluator。當建立 Run 或評估作業時，確切的模型快照被凍結，保證可重現性。
• RAG 評估框架 – 版本化資料集、基準比較、CI 閘門式品質檢查和持久評估工作程序允許您自動測量正確性、有據性、相關性、完整性、不支援的主張和衝突揭露。
• 安全與驗證 – 短生命週期的記憶體存取權杖、儲存在 HttpOnly Cookie 中的輪替不透明重新整理權杖、RBAC、每端點速率限制 HMAC、CSP/標頭，以及帶有 AST 和 RLS 檢查的唯讀 SQL 沙箱。

為什麼重要 – 透過持久化每一步，SuperMew 使得以下成為可能：

1. 稽核 確切地哪些文件、工具和模型輸出產生了回應。
2. 恢復 在人工審查者添加澄清後暫停的對話。
3. 版本控制 知識庫和模型設定，而不破壞現有的執行。
4. 基準測試 在類似生產的環境中端到端測試 RAG 管線。

---

架構概覽

元件	技術	角色
API 伺服器	FastAPI (Python 3.12)	HTTP、SSE、驗證、執行緒/執行編排、靜態前端服務
索引工作程序	Python 模組 backend.workers.indexing	建立不可變的文件版本，寫入 Milvus 向量，管理候選作用域
RAG 評估工作程序	Python 模組 backend.workers.evaluation	執行離線評估作業，計算指標，儲存結果
向量儲存	Milvus (密集 + 原生 BM25)	快速最近鄰檢索
中繼資料儲存	PostgreSQL + SQLAlchemy + Alembic	執行緒、執行、事件、模型快照、文件目錄
快取 / 低延遲通知	Redis	事件推送、速率限制計數器
物件儲存	MinIO (由工作程序使用)	上傳的原始文件
前端	Vite + Vue 3 + TypeScript + Pinia	聊天、技能中心、管理面板、評估工作台 UI

---

開始使用（本地開發）

1. 先決條件 – Python 3.12+、uv 套件管理器、Node 20+、Docker Compose。
2. 設定 – 將 .env.example 複製為 .env 並填寫：
   • 模型識別碼 (MODEL、FAST_MODEL、…)
   • JWT_SECRET_KEY (≥32 個隨機字元)
   • 可選的管理員邀請碼。
3. 啟動相依性 – docker compose up -d (Postgres, Redis, etcd, MinIO, Milvus, Attu)。
4. 安裝 Python 相依性 – uv sync --frozen。
5. 建置前端 – cd frontend && npm ci && npm run build && cd ..。
6. 執行遷移和健全性檢查 –

   uv run --frozen alembic upgrade head
   uv run --frozen python -m backend.tools.registry_cli validate
   

7. 啟動三個程序 – ./scripts/start.sh (API, 索引工作程序, 評估工作程序)。使用 --no-reload 停用熱重載。
8. 開啟 http://127.0.0.1:8000/ 存取 UI，http://127.0.0.1:8000/docs 存取 OpenAPI，http://127.0.0.1:8080/ 存取 Milvus Attu。

---

生產環境檢查清單（摘要）

• 在監督程序（systemd, k8s 等）下部署相同的三個服務（API, 索引工作程序, 評估工作程序），確保它們共用相同的程式碼版本和 UPLOAD_DIR。
• 設定 APP_ENV=production 並提供 JWT、速率限制 HMAC、資料庫密碼和模型供應商金鑰的真實機密資訊。
• 啟用安全 Cookie (AUTH_REFRESH_COOKIE_SECURE=true)。
• 在 API 之前啟動工作程序，執行健康檢查，然後在公開公共端點之前執行最小端到端測試（建立執行緒、上傳文件、執行 RAG 查詢、啟動小型評估作業）。
• 定期執行清理任務 python -m backend.auth.cleanup 以修剪過期的重新整理權杖帳本。

---

典型使用案例

使用案例	SuperMew 如何協助
企業知識庫問答	上傳 PDF/文件，對其進行版本控制，並讓智能體透過混合搜尋檢索，同時保留稽核軌跡。
人在迴路支援	在 Checkpoint 處暫停執行，讓審查者編輯或核准工具呼叫，然後在不丟失上下文的狀況下恢復。
受監管環境	帶有嚴格允許清單、沙箱程式碼執行和策略驅動的工具護欄的唯讀 SQL 助手滿足合規需求。
模型/RAG 基準測試	定義資料集，執行評估工作程序，與基準進行比較，並根據品質指標閘門發布。
自訂技能整合	透過註冊表添加新的 HTTP-JSON 工具或特定領域的技能；平台自動處理版本控制、權限檢查和 UI 暴露。

---

長話短說

SuperMew 是一個全棧開源平台，用於建置依賴檢索增強生成（RAG）的生產級 AI 智能體。它強調持久性、可稽核性、人在迴路控制和安全的版本化工具。如果您需要一個自託管的 RAG 系統，其中每一步都可以檢查、重放或閘門，SuperMew 提供了完整的堆疊——從基於 PostgreSQL 的事件溯源到基於 Vue 的 UI 和強大的評估框架。