RAGnarok 功能與技術規格說明書

?? 思考可以構成一座橋，讓我們通向新知識。—— 普朗克

1 寫作目標（Functional Specification, FS）

• 目標：將用戶需求轉化為系統具體功能設計的藍圖，為后續開發、測試、維護等階段提供清晰、準確、可操作的依據。

• 范圍 (Scope)：

  類別	內容
  用戶相關	用戶分類、畫像、目標、頻率、期望
  場景相關	RAG 調度、知識庫查詢等業務場景
  功能定義	每個功能的行為、入口、邏輯
  系統邊界	技術邊界、處理容量、兼容性
  開發安排	Alpha / Beta 功能劃分
  數據要求	數據收集內容、方式與含義
  驗收標準	何時算完成、如何測試
  術語定義	LLM、MCP、Pipeline、RAG 等
  風險與應對	潛在技術、用戶、市場不確定因素

2 概念與術語

3 產品描述

3.1 項目簡述

RAGnarok 是一站式智能問答平臺，提供模塊化 Pipeline 架構與 MCP 協議，幫助開發者、企業與普通用戶低成本構建 RAG 應用。

3.2 用戶畫像

3.3 典型場景

1. 開發者：二次開發、插件集成、實時監控。
2. 企業運營：跨系統集成、數據安全、私有化部署。
3. 日常問答：信息查詢、知識檢索、智能問答。

4 產品功能（Alpha + Beta）

4.1 Alpha 已交付

• 知識庫管理：多源文檔導入、向量化、權限隔離。
• 核心 RAG 流程：檢索 → 重排 → 生成，支持 SSE 流式輸出。
• 工作流編排 (API)：JSON 定義 Pipeline，后端執行。

4.2 Beta 新增

5 顯性與隱性依賴

• 知識庫質量直接決定 RAG 答復質量。
• Pipeline 執行依賴 MCP 協議的統一結構。

6 潛在問題與解決方案

7 系統能力邊界

• 并發用戶：基于水平擴展，可支撐萬級 QPS；單實例上限取決于硬件。
• 高峰負載：動態資源調度，自動擴容。
• 單請求數據量：推薦 ≤ 2?MB，超限時分頁處理。
• 瀏覽器支持：Chrome / Edge / Firefox / Safari 最新正式版。

8 產品目標（學期 OKR）

9 技術棧與架構

• 后端：FastAPI + SQLAlchemy + PostgreSQL + Qdrant + MinIO (+ Redis 可選)
• 前端：React + React?Flow + Zustand
• DevOps：Docker / Helm / GitHub Actions → K8s
• Observability：Prometheus, Grafana, OpenTelemetry, Sentry

(Front: React?Flow) ─? server(API) ─? core(engine) ─? toolkit(drivers)
       ▲                    │                 │
       └─ WebSocket(SSE) ?──┘         observability

10 Beta 路線圖

任務追蹤：全部通過 飛書文檔

11 驗收標準（Beta）

• 功能可用：新增功能在演示環境完整跑通。
• 性能達標：常規調用 ≤?1?s；異常鏈路自動回退。
• 安全通過：無越權訪問，插件運行受沙盒限制。
• 測試通過：CI 自動化測試全綠，覆蓋率 ≥?80?%。
• 文檔同步：用戶手冊、API 文檔與代碼一致。

12 風險與應對