agent sa doc detail

# AI Agent 知識庫系統 — SA 系統架構與開發計畫

---

| 項目 | 內容 |
| -------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| 文件名稱 | AI Agent 知識庫系統 — 系統架構設計與開發計畫書 |
| 文件版本 | v2.0 |
| 建立日期 | 2026-02-26 |
| 文件類型 | SA（System Architecture）設計與開發計畫 |
| 文件狀態 | 待團隊審查 |
| 前置文件 | `ai_agent_frameworks_analysis_report.md`（評估完成）`<br>semantic_kernel_analysis_report.md`（評估完成）`<br>react_implementation_analysis.md`（評估完成）`<br>DEPLOYMENT_ANALYSIS.md`（評估完成）`<br>LOCAL_DEPLOYMENT_GUIDE.md`（評估完成） |

---

## 目錄

1. [技術選型決議（已定案）](#1-技術選型決議已定案)
2. [系統總體架構](#2-系統總體架構)
3. [模組設計與元件規格](#3-模組設計與元件規格)
4. [資料流程設計](#4-資料流程設計)
5. [API 介面規格](#5-api-介面規格)
6. [資料庫設計](#6-資料庫設計)
7. [部署架構與環境規格](#7-部署架構與環境規格)
8. [開發階段計畫](#8-開發階段計畫)
9. [人力配置與分工](#9-人力配置與分工)
10. [驗收標準](#10-驗收標準)
11. [風險與應對](#11-風險與應對)
12. [附錄：技術選型推論摘要](#12-附錄技術選型推論摘要)

---

## 1. 技術選型決議（已定案）

> 以下決議基於前階段完成的 5 份技術評估報告，涵蓋 11 個框架的六維度分析（技術能力、離線支援、維護性、Windows 支援、後端獨立性、自託管自由度）。評估過程詳見附錄 §12。

### 1.1 技術棧總表

| 層級 | 選定技術 | 決策理由 |
| ----------------------- | ------------------------ | -------------------------------------------------------------- |
| **Agent 編排層** | Semantic Kernel (Python) | 六維度冠軍、MIT 授權、GA 穩定、.NET/Python 雙語言、支援 Ollama |
| **知識庫平台層** | Dify (Self-hosted) | BaaS API 最友好、視覺化工作流、43 模型提供者、文件最完整 |
| **文件解析層** | RAGFlow (DeepDoc) | 複雜 PDF/表格/圖片解析首選、OpenAI 相容 API、2000 檔批次實測 |
| **本地 LLM 推理** | Ollama | 全框架統一支援、零配置、模型庫豐富（Llama 3、Mistral、Phi 等） |
| **向量資料庫** | PostgreSQL + pgvector | 與主資料庫統一，減少運維複雜度，效能滿足中型規模需求 |
| **主資料庫** | PostgreSQL 16 | Dify 原生支援、企業級穩定、pgvector 擴充即可兼做向量庫 |
| **快取** | Redis 7 | Dify 原生支援、Session / Rate Limit / 任務佇列 |
| **前端框架** | Next.js 15 + React 19 | Fork Dify 官方前端模板二次開發，TypeScript |
| **反向代理** | Nginx | 統一入口、SSL 終結、靜態資源快取 |
| **容器化** | Docker Compose | 一鍵部署、環境一致性、所有元件統一編排 |
| **CI/CD** | GitHub Actions | 自動化建置、測試、部署 |

### 1.2 明確排除項

| 排除方案 | 排除理由 |
| --------------- | ------------------------------------------------------------- |
| AutoGen | 已進入維護模式（EOL），官方建議遷移至 Agent Framework |
| AutoGPT | Polyform Shield 授權禁止競爭使用，強制 WSL2，門檻最高 |
| MaxKB | GPL-3.0 授權傳染風險，不適合閉源商業產品 |
| GraphRAG | 無原生 REST API，僅 CLI，依賴 Azure OpenAI，服務化成本過高 |
| Agent Framework | RC1 尚未 GA，API 可能變動；列為**Phase 3 預研遷移對象** |

---

## 2. 系統總體架構

### 2.1 架構總覽圖

```
┌─────────────────────────────────────────┐
│ 使用者觸及點 │
│ 瀏覽器 / 嵌入式 Widget / 行動裝置 │
└──────────────────┬──────────────────────┘
│ HTTPS
┌───────────▼───────────┐
│ Nginx (反向代理) │
│ SSL 終結 / 路由分發 │
│ :80 / :443 │
└───┬───────┬───────┬───┘
│ │ │
┌───────────────▼┐ ┌──▼──┐ ┌─▼──────────────┐
│ 自訂前端 (A) │ │(B) │ │ Dify Web UI │
│ Next.js 15 │ │API │ │ (管理後台) │
│ :3000 │ │Gate │ │ :80/console │
└───────┬────────┘ │way │ └───────┬────────┘
│ │:443 │ │
└─────┬─────┤/api │──────────┘
│ └──┬──┘
│ │
┌─────────────▼────────▼──────────────┐
│ 應用服務層 │
│ ┌──────────────┐ ┌───────────────┐ │
│ │ Dify API │ │ 自訂 Backend │ │
│ │ Server │ │ (FastAPI) │ │
│ │ :5001 │ │ :8000 │ │
│ │ │ │ │ │
│ │ • Chat API │ │ • 使用者管理 │ │
│ │ • Workflow │ │ • 權限控制 │ │
│ │ • Knowledge │ │ • 批次匯入 │ │
│ │ Base API │ │ 排程器 │ │
│ │ • BaaS API │ │ • 系統監控 │ │
│ └──────┬───────┘ └───────┬───────┘ │
│ │ │ │
│ ┌──────▼─────────────────▼───────┐ │
│ │ Semantic Kernel (Agent 層) │ │
│ │ • Plugin 管理 │ │
│ │ • Function Calling 迴圈 │ │
│ │ • 多 Agent 編排 │ │
│ │ • RAG Pipeline │ │
│ └──────┬──────────────────┬──────┘ │
└─────────┤ ├─────────┘
│ │
┌──────────────▼───┐ ┌──────────▼──────────┐
│ 資料儲存層 │ │ LLM 推理層 │
│ │ │ │
│ PostgreSQL :5432 │ │ Ollama :11434 │
│ ├ 主資料庫 │ │ ├ llama3.1 (8B) │
│ ├ pgvector │ │ ├ mistral (7B) │
│ └ Dify 元資料 │ │ ├ nomic-embed-text │
│ │ │ └ (可擴充) │
│ Redis :6379 │ │ │
│ ├ Session │ │ Azure OpenAI (備援) │
│ ├ 任務佇列 │ │ ├ GPT-4o │
│ └ Rate Limit │ │ └ text-embedding-3 │
└───────────────────┘ └──────────────────────┘
│
┌──────────────▼───────────┐
│ 文件解析層 (按需啟用) │
│ RAGFlow :9380 │
│ ├ DeepDoc 引擎 │
│ ├ 複雜 PDF / 表格解析 │
│ └ OpenAI 相容 API │
└──────────────────────────┘
```

### 2.2 架構設計原則

| 原則 | 說明 |
| ----------------------------- | ------------------------------------------------------------------- |
| **API-First** | 所有功能均透過 REST API 暴露，前端 100% 透過 API 互動 |
| **Platform + SDK 混合** | Dify 處理知識庫 / 工作流等「平台級」功能；SK 處理「Agent 編排」邏輯 |
| **LLM 可替換** | 統一透過 Ollama 本地 + Azure OpenAI 雲端雙通道，隨時切換 |
| **漸進式複雜度** | Phase 1 用 Dify 內建 RAG，Phase 2 才接 RAGFlow 處理複雜文件 |
| **資料不外洩** | 預設 On-Premises 部署，本地 LLM 推理，無資料離開內網 |

---

## 3. 模組設計與元件規格

### 3.1 模組清單

| 模組編號 | 模組名稱 | 負責元件 | 對外介面 |
| -------- | ---------------- | ------------------------------- | -------------------- |
| M01 | 使用者認證與授權 | 自訂 Backend (FastAPI) | REST API |
| M02 | 知識庫管理 | Dify Knowledge Base API | REST API (BaaS) |
| M03 | 文件批次匯入 | 自訂 Backend + Dify API | REST API + WebSocket |
| M04 | AI 對話引擎 | Dify Chat API + SK Agent | REST API (Streaming) |
| M05 | 工作流引擎 | Dify Workflow | REST API |
| M06 | Agent 編排引擎 | Semantic Kernel | 內部 SDK 呼叫 |
| M07 | 文件深度解析 | RAGFlow DeepDoc API | REST API |
| M08 | 系統監控與日誌 | 自訂 Backend + Prometheus | REST API + Dashboard |
| M09 | 前端應用 | Next.js + React | Web UI |
| M10 | 嵌入式 Widget | React Component (iframe/script) | script / iframe |

### 3.2 各模組詳細規格

#### M01 — 使用者認證與授權

```
目的：管控系統存取，支援多租戶與角色權限
技術：FastAPI + JWT + PostgreSQL

角色定義：
┌─────────────────────────────────────────────────┐
│ super_admin → 系統管理、模型配置、用戶管理 │
│ kb_admin → 知識庫 CRUD、文件匯入管理 │
│ user → 問答對話、歷史記錄查閱 │
│ api_client → 僅限 API 存取（Service Account） │
└─────────────────────────────────────────────────┘

權限矩陣：
┌──────────────┬─────────┬──────────┬──────┬────────────┐
│ 功能 │ super │ kb_admin │ user │ api_client │
├──────────────┼─────────┼──────────┼──────┼────────────┤
│ 模型管理 │ ✅ │ ❌ │ ❌ │ ❌ │
│ 使用者管理 │ ✅ │ ❌ │ ❌ │ ❌ │
│ 知識庫 CRUD │ ✅ │ ✅ │ ❌ │ ❌ │
│ 文件匯入 │ ✅ │ ✅ │ ❌ │ ✅ │
│ 對話問答 │ ✅ │ ✅ │ ✅ │ ✅ │
│ 查看監控 │ ✅ │ ✅ │ ❌ │ ❌ │
└──────────────┴─────────┴──────────┴──────┴────────────┘
```

#### M02 — 知識庫管理

```
目的：封裝 Dify Knowledge Base API，提供統一的知識庫管理介面
技術：FastAPI (Proxy) → Dify REST API

核心功能：
1. 建立知識庫 POST /api/v1/datasets
2. 刪除知識庫 DELETE /api/v1/datasets/{id}
3. 上傳文件 POST /api/v1/datasets/{id}/documents
4. 刪除文件 DELETE /api/v1/datasets/{id}/documents/{doc_id}
5. 查詢分段 GET /api/v1/datasets/{id}/documents/{doc_id}/segments
6. 知識庫檢索測試 POST /api/v1/datasets/{id}/retrieve

Dify 端對應 API（已驗證可用）：
• POST /v1/datasets → 建立知識庫
• POST /v1/datasets/{id}/document/create_by_file → 上傳文件
• POST /v1/datasets/{id}/document/create_by_text → 建立文字段落
• GET /v1/datasets/{id}/documents → 列出文件
• DELETE /v1/datasets/{id}/documents/{doc_id} → 刪除文件
• POST /v1/datasets/{id}/retrieve → 知識庫檢索
```

#### M03 — 文件批次匯入

```
目的：支援大量文件（100-2000 檔）的非同步批次匯入與進度追蹤
技術：FastAPI + Redis Queue + Dify API + (選配) RAGFlow API

匯入流程：
┌──────────┐ ┌──────────────┐ ┌─────────────┐ ┌──────────────┐
│ 前端上傳 │───▶│ 自訂 Backend │───▶│ Redis Queue │───▶│ Worker 進程 │
│ 多檔 │ │ 接收 & 驗證 │ │ 任務排隊 │ │ 逐檔處理 │
└──────────┘ └──────────────┘ └─────────────┘ └──────┬───────┘
│
┌────────────────────┤
▼ ▼
┌───────────┐ ┌──────────────┐
│ Dify API │ │ RAGFlow API │
│ (一般文件) │ │ (複雜 PDF) │
└───────────┘ └──────────────┘

進度追蹤機制：
• 批次 Job ID → Redis Hash 儲存各檔案狀態
• WebSocket 即時推送進度給前端
• 狀態：queued → processing → chunking → embedding → done / error

支援格式：
• 文字類：.txt, .md, .csv, .json, .html
• 文件類：.pdf, .docx, .xlsx, .pptx
• 複雜文件（交由 RAGFlow）：掃描 PDF, 含表格 PDF, 圖文混排

檔案大小限制：
• 單檔上限：50MB（可配置）
• 批次上限：500 檔 / 次
• 日限額：2000 檔 / 知識庫（可配置）
```

#### M04 — AI 對話引擎

```
目的：提供帶知識庫 RAG 的 AI 對話能力
技術：Dify Chat Messages API + Semantic Kernel Agent

對話流程：
┌──────────┐ ┌─────────────┐ ┌──────────────────────────────┐
│ 使用者 │───▶│ 自訂 Backend│───▶│ Dify /v1/chat-messages API │
│ 提問 │ │ (鑒權+路由) │ │ │
└──────────┘ └─────────────┘ │ 內部流程： │
│ 1. 意圖辨識 │
┌─────────────│ 2. 知識庫檢索 (RAG) │
│ │ 3. Prompt 組裝 │
▼ │ 4. LLM 生成回覆 │
┌──────────────┐ │ 5. 引用來源附加 │
│ SSE Streaming│◀────│ │
│ 回覆串流 │ └──────────────────────────────┘
└──────────────┘

Dify Chat API 呼叫規格（已確認）：
POST /v1/chat-messages
Headers: Authorization: Bearer {api_key}
Body: {
"inputs": {},
"query": "使用者問題",
"response_mode": "streaming", // streaming | blocking
"conversation_id": "xxx", // 空值=新對話
"user": "user_id",
"files": [] // 選配：附件
}
Response: SSE event stream
event: message → 文字片段
event: message_end → 結束，含 metadata + retriever_resources（引用來源）

進階場景 — SK Agent 編排：
當對話需要多工具協作時，由 SK 接手：
┌─────────────────────────────────────────────────┐
│ SK ChatCompletionAgent │
│ FunctionChoiceBehavior.Auto() │
│ max_auto_invoke_attempts = 5 │
│ │
│ 已註冊 Plugins： │
│ ├ KnowledgeBasePlugin → 呼叫 Dify 知識庫 API │
│ ├ WebSearchPlugin → 即時網路搜尋 │
│ ├ CalculatorPlugin → 數學計算 │
│ ├ DateTimePlugin → 日期時間查詢 │
│ └ DatabasePlugin → 結構化資料查詢 │
│ │
│ ReAct 迴圈： │
│ Think → Act (invoke plugin) → Observe → repeat │
└─────────────────────────────────────────────────┘
```

#### M06 — Agent 編排引擎（Semantic Kernel）

```
目的：提供超越單輪 RAG 的多步驟推理與多 Agent 協作能力
技術：Semantic Kernel Python SDK

SK Kernel 初始化配置：
kernel = Kernel()

# LLM 服務（雙通道）
kernel.add_service(OllamaChatCompletion(model="llama3.1")) # 本地
kernel.add_service(AzureChatCompletion(deployment="gpt-4o")) # 雲端備援

# Plugins 註冊
kernel.add_plugin(KnowledgeBasePlugin(), "knowledge_base")
kernel.add_plugin(WebSearchPlugin(), "web_search")

# Agent 設定
agent = ChatCompletionAgent(
kernel=kernel,
name="enterprise_agent",
instructions="你是企業知識庫助手...",
function_choice_behavior=FunctionChoiceBehavior.Auto(
maximum_auto_invoke_attempts=5
)
)

多 Agent 編排模式（Phase 2）：
┌───────────────────────────────────────────────────┐
│ SequentialOrchestration（順序） │
│ 使用者問題 → 分類 Agent → 知識庫 Agent → 摘要 │
│ │
│ HandoffOrchestration（交接） │
│ 通用 Agent ──transfer_to──▶ 專家 Agent │
│ │
│ GroupChatOrchestration（群聊） │
│ Manager 調度 N 個 Agent 協作回答複雜問題 │
└───────────────────────────────────────────────────┘
```

---

## 4. 資料流程設計

### 4.1 文件匯入流程（End-to-End）

```
使用者前端 Backend Dify 資料庫
│ │ │ │ │
│ 選擇多個檔案 │ │ │ │
│───────────────────▶│ │ │ │
│ │ POST /api/v1/import │ │ │
│ │ (multipart/form-data) │ │ │
│ │───────────────────────▶│ │ │
│ │ │ 驗證檔案格式/大小 │ │
│ │ │ 建立 Batch Job │ │
│ │ │──────────────────────────────────────────▶│
│ │ │ │ INSERT batch_job │
│ │ { batch_id: "xxx" } │ │ │
│ │◀───────────────────────│ │ │
│ │ │ │ │
│ │ WS /ws/import/{batch} │ │ │
│ │───────────────────────▶│ │ │
│ │ │ │ │
│ │ │ ── Worker Loop ── │ │
│ │ │ for each file: │ │
│ │ │ │ │
│ │ │ POST /v1/datasets/ │ │
│ │ │ {id}/document/ │ │
│ │ │ create_by_file │ │
│ │ │────────────────────▶│ │
│ │ │ │ 自動分段 & 向量化 │
│ │ │ │──────────────────▶│
│ │ │ { doc_id, status } │ │
│ │ │◀────────────────────│ │
│ │ │ │ │
│ │ WS: { file: "a.pdf", │ │ │
│ │ status: "done", │ │ │
│ │ progress: "3/10" } │ │ │
│ │◀───────────────────────│ │ │
│ 即時進度更新 │ │ │ │
│◀───────────────────│ │ │ │
│ │ │ │ │
│ │ WS: { status: "complete", │ │
│ │ total: 10, success: 9, failed: 1 } │ │
│ │◀───────────────────────│ │ │
```

### 4.2 AI 對話流程（帶 RAG）

```
使用者前端 Backend Dify API Ollama/Azure
│ │ │ │ │
│ 輸入問題 │ │ │ │
│───────────────────▶│ │ │ │
│ │ POST /api/v1/chat │ │ │
│ │──────────────────▶│ │ │
│ │ │ 鑒權 + 取得 │ │
│ │ │ conversation_id │ │
│ │ │ │ │
│ │ │ POST /v1/chat-messages │
│ │ │ response_mode=streaming │
│ │ │─────────────────────▶│ │
│ │ │ │ │
│ │ │ │ 1. 意圖理解 │
│ │ │ │ 2. 知識庫向量檢索 │
│ │ │ │ (pgvector) │
│ │ │ │ 3. 組裝 Prompt │
│ │ │ │ (query + context)│
│ │ │ │ │
│ │ │ │ POST /api/chat │
│ │ │ │────────────────────▶│
│ │ │ │ │
│ │ │ │ SSE: token stream │
│ │ │ SSE: event stream │◀────────────────────│
│ │ SSE: 文字串流 │◀─────────────────────│ │
│ 即時顯示回覆 │◀─────────────────│ │ │
│◀───────────────────│ │ │ │
│ │ │ │ │
│ │ SSE: message_end │ │ │
│ │ + 引用來源清單 │ │ │
│ 顯示參考文件 │◀─────────────────│ │ │
│◀───────────────────│ │ │ │
```

### 4.3 Agent 多步驟推理流程（SK ReAct）

```
使用者問題: "上季度營收較去年同期成長多少？並用圖表呈現趨勢"

SK ChatCompletionAgent
┌────────────────────────────────────────────────────────────┐
│ │
│ Iteration 1 (Think → Act → Observe) │
│ ├ [THINK] LLM 判斷需要查詢財報數據 │
│ ├ [ACT] invoke KnowledgeBasePlugin.search │
│ │ query="上季度營收去年同期" │
│ └ [OBSERVE] 返回：2025Q3 營收 5.2B, 2024Q3 營收 4.8B │
│ │
│ Iteration 2 (Think → Act → Observe) │
│ ├ [THINK] 需要計算成長率 │
│ ├ [ACT] invoke CalculatorPlugin.calculate │
│ │ expression="(5.2 - 4.8) / 4.8 * 100" │
│ └ [OBSERVE] 返回：8.33% │
│ │
│ Iteration 3 (Think → 直接回答) │
│ ├ [THINK] 資訊已足夠，組裝最終回覆 │
│ └ [RESPOND] "上季度營收 52 億，較去年同期成長 8.33%..." │
│ + 圖表數據 JSON（交由前端 rendering） │
│ │
└────────────────────────────────────────────────────────────┘
```

---

## 5. API 介面規格

### 5.1 API 總覽

| 分類 | Endpoint | Method | 說明 |
| ------------------ | -------------------------------------------- | -------------- | --------------------------- |
| **認證** | `/api/v1/auth/login` | POST | 登入取得 JWT |
| | `/api/v1/auth/refresh` | POST | 刷新 Token |
| | `/api/v1/auth/logout` | POST | 登出 |
| **使用者** | `/api/v1/users` | GET/POST | 使用者清單 / 建立 |
| | `/api/v1/users/{id}` | GET/PUT/DELETE | 使用者 CRUD |
| **知識庫** | `/api/v1/datasets` | GET/POST | 知識庫清單 / 建立 |
| | `/api/v1/datasets/{id}` | GET/PUT/DELETE | 知識庫 CRUD |
| | `/api/v1/datasets/{id}/documents` | GET/POST | 文件清單 / 上傳 |
| | `/api/v1/datasets/{id}/documents/{doc_id}` | DELETE | 刪除文件 |
| | `/api/v1/datasets/{id}/retrieve` | POST | 知識庫檢索測試 |
| **批次匯入** | `/api/v1/import/batch` | POST | 建立批次匯入任務 |
| | `/api/v1/import/batch/{batch_id}` | GET | 查詢批次狀態 |
| | `/ws/import/{batch_id}` | WS | 即時進度推送 |
| **對話** | `/api/v1/chat` | POST | 發送對話訊息（SSE 串流） |
| | `/api/v1/chat/conversations` | GET | 對話列表 |
| | `/api/v1/chat/conversations/{id}` | GET/DELETE | 對話詳情 / 刪除 |
| | `/api/v1/chat/conversations/{id}/messages` | GET | 對話訊息歷史 |
| **Agent** | `/api/v1/agent/invoke` | POST | 呼叫 SK Agent（多步驟推理） |
| | `/api/v1/agent/workflows` | GET/POST | 工作流清單 / 建立 |
| **系統** | `/api/v1/system/health` | GET | 健康檢查 |
| | `/api/v1/system/models` | GET | 可用模型清單 |
| | `/api/v1/system/stats` | GET | 系統統計（文件數/對話數等） |

### 5.2 關鍵 API 詳細規格

#### POST `/api/v1/chat` — 對話（核心 API）

```json
// Request
POST /api/v1/chat
Headers:
Authorization: Bearer {jwt_token}
Content-Type: application/json
Accept: text/event-stream

Body:
{
"query": "什麼是公司的請假規定？",
"dataset_ids": ["ds_001", "ds_002"],
"conversation_id": "conv_xxx", // null = 新對話
"response_mode": "streaming", // "streaming" | "blocking"
"model_preference": "local", // "local" (Ollama) | "cloud" (Azure)
"enable_agent": false // true = 啟用 SK Agent 多步驟推理
}

// Response (SSE Stream)
event: message
data: {"content": "根據", "role": "assistant"}

event: message
data: {"content": "公司員工手冊第五章", "role": "assistant"}

...

event: message_end
data: {
"conversation_id": "conv_xxx",
"message_id": "msg_yyy",
"metadata": {
"model": "llama3.1:8b",
"tokens": { "prompt": 1250, "completion": 380 },
"latency_ms": 2340,
"retriever_resources": [
{
"dataset_id": "ds_001",
"document_name": "員工手冊_v3.pdf",
"segment_id": "seg_123",
"score": 0.92,
"content": "第五章請假規定：員工享有年假..."
}
]
}
}
```

#### POST `/api/v1/import/batch` — 批次匯入

```json
// Request
POST /api/v1/import/batch
Headers: Authorization: Bearer {jwt_token}
Content-Type: multipart/form-data

Form Fields:
dataset_id: "ds_001"
indexing_technique: "high_quality" // "high_quality" | "economy"
process_rule: {
"mode": "automatic", // "automatic" | "custom"
"rules": {
"pre_processing_rules": [
{ "id": "remove_extra_spaces", "enabled": true },
{ "id": "remove_urls_emails", "enabled": false }
],
"segmentation": {
"separator": "###",
"max_tokens": 1000
}
}
}
files[]: [file1.pdf, file2.docx, ...] // 最多 500 檔

// Response
{
"batch_id": "batch_20260226_001",
"total_files": 15,
"status": "queued",
"websocket_url": "/ws/import/batch_20260226_001",
"estimated_time_seconds": 120
}
```

---

## 6. 資料庫設計

### 6.1 ER Diagram（自訂 Backend 部分）

```
┌──────────────────┐ ┌──────────────────────┐ ┌────────────────────────┐
│ users │ │ user_roles │ │ roles │
├──────────────────┤ ├──────────────────────┤ ├────────────────────────┤
│ id UUID │──┐ │ user_id UUID (FK) │ ┌──│ id UUID │
│ email TEXT │ └─▶│ role_id UUID (FK) │◀─┘ │ name TEXT │
│ password TEXT │ │ created_at TIMESTAMP │ │ permissions JSONB │
│ display_name TEXT │ └──────────────────────┘ └────────────────────────┘
│ is_active BOOL │
│ created_at TS │ ┌──────────────────────┐ ┌────────────────────────┐
│ updated_at TS │ │ conversations │ │ messages │
└──────────────────┘ ├──────────────────────┤ ├────────────────────────┤
│ │ id UUID │──┐ │ id UUID │
│ │ user_id UUID (FK)│ └─▶│ conversation_id UUID │
│ │ dataset_ids JSONB │ │ role TEXT │
│ │ dify_conv_id TEXT │ │ content TEXT │
│ │ title TEXT │ │ metadata JSONB │
└───────────────▶│ model_used TEXT │ │ tokens_used INT │
│ created_at TS │ │ latency_ms INT │
│ updated_at TS │ │ sources JSONB │
└──────────────────────┘ │ created_at TS │
└────────────────────────┘
┌──────────────────────┐ ┌──────────────────────────┐
│ batch_import_jobs │ │ batch_import_files │
├──────────────────────┤ ├──────────────────────────┤
│ id UUID │──┐ │ id UUID │
│ user_id UUID (FK)│ └─▶│ job_id UUID (FK) │
│ dataset_id TEXT │ │ filename TEXT │
│ total_files INT │ │ file_size BIGINT │
│ status TEXT │ │ status TEXT │
│ success_cnt INT │ │ dify_doc_id TEXT │
│ failed_cnt INT │ │ error_message TEXT │
│ created_at TS │ │ started_at TS │
│ completed_at TS │ │ completed_at TS │
└──────────────────────┘ └──────────────────────────┘

┌──────────────────────┐
│ api_keys │
├──────────────────────┤
│ id UUID │
│ user_id UUID (FK)│
│ key_hash TEXT │
│ name TEXT │
│ permissions JSONB │
│ expires_at TS │
│ last_used TS │
│ created_at TS │
└──────────────────────┘
```

### 6.2 表格說明

| 表格 | 用途 | 預估資料量（1年） |
| ---------------------- | -------------------------- | ----------------- |
| `users` | 系統使用者帳號 | ~500 筆 |
| `roles` | 角色定義（4 個固定角色） | 4 筆 |
| `user_roles` | 使用者-角色關聯 | ~500 筆 |
| `conversations` | 對話 Session 記錄 | ~50,000 筆 |
| `messages` | 對話訊息明細（含引用來源） | ~500,000 筆 |
| `batch_import_jobs` | 批次匯入任務記錄 | ~2,000 筆 |
| `batch_import_files` | 批次匯入各檔案狀態 | ~100,000 筆 |
| `api_keys` | API 金鑰管理 | ~100 筆 |

> **注意**：知識庫本身（Dataset / Document / Segment / Vector）儲存在 **Dify 自帶的 PostgreSQL** 中，自訂 Backend 不重複儲存。

---

## 7. 部署架構與環境規格

### 7.1 Docker Compose 服務清單

```yaml
# docker-compose.yml 服務編排
services:
# ── 自訂元件 ──────────────────────────
frontend: # Next.js 自訂前端 :3000
backend: # FastAPI 自訂 Backend :8000
worker: # 批次匯入 Worker (內部)

# ── Dify 平台 ─────────────────────────
dify-api: # Dify API Server :5001
dify-worker: # Dify 非同步 Worker (內部)
dify-web: # Dify 管理後台 :3001

# ── 基礎設施 ──────────────────────────
postgres: # PostgreSQL 16 + pgvector :5432
redis: # Redis 7 :6379
nginx: # Nginx 反向代理 :80 / :443

# ── LLM 推理 ──────────────────────────
ollama: # Ollama 本地 LLM :11434

# ── 選配（Phase 2）────────────────────
# ragflow: # RAGFlow 文件深度解析 :9380
```

### 7.2 硬體規格

| 環境 | CPU | RAM | 磁碟 | GPU | 說明 |
| -------- | ----- | ----- | ---------- | ------------------ | -------------------------- |
| 開發環境 | 4 核 | 16 GB | 100 GB SSD | 選配 | 開發者本機 Docker Desktop |
| 測試環境 | 8 核 | 32 GB | 200 GB SSD | 選配 | 功能測試 + 效能基準測試 |
| 生產環境 | 16 核 | 64 GB | 500 GB SSD | NVIDIA T4 16GB ×1 | 含 Ollama GPU 推理 |
| 生產(輕) | 8 核 | 32 GB | 200 GB SSD | 無（CPU 推理） | 不跑本地 LLM，僅用雲端 API |

### 7.3 網路拓撲

```
┌──────────────────────────┐
│ 企業內網 (172.16.0.0/16) │
│ │
│ ┌──────────────────┐ │
使用者 ───────┼──▶│ Nginx :443 │ │
(HTTPS) │ │ (唯一入口) │ │
│ └────────┬─────────┘ │
│ │ │
│ Docker Network │
│ (ai-agent-net) │
│ 172.20.0.0/16 │
│ ┌─────┬──────┬─────┐ │
│ │ │ │ │ │
│ FE BE Dify Ollama │
│ .10 .11 .12 .13 │
│ │ │
│ PG Redis │
│ .20 .21 │
│ │
└───────────┬──────────────┘
│ (選配 - 雲端 LLM 備援)
▼
┌──────────────────────────┐
│ Azure OpenAI │
│ (outbound :443 only) │
└──────────────────────────┘
```

---

## 8. 開發階段計畫

### 8.1 總覽甘特圖

```
Phase 0: 環境建置 ██░░░░░░░░░░░░░░░░░░░░░░░░░░░░ Week 1-2
Phase 1: 核心功能 MVP ░░██████████░░░░░░░░░░░░░░░░░░ Week 3-8
Phase 2: 進階功能 ░░░░░░░░░░░░██████████░░░░░░░░ Week 9-14
Phase 3: 優化與擴充 ░░░░░░░░░░░░░░░░░░░░░░████████ Week 15-20
─────────────────────────────────
W1 W4 W7 W10 W13 W16 W20
```

### 8.2 Phase 0 — 環境建置（Week 1–2）

| Sprint 0 Task | 負責人 | 產出物 | 驗收標準 |
| -------------------------- | ------ | ----------------------------------- | ----------------------------------------- |
| T0-1 建立 Git Repository | 全體 | GitHub Repo + Branch 策略 | main / develop / feature/* 分支就位 |
| T0-2 Docker Compose 編排 | 後端 | `docker-compose.yml` | `docker compose up -d` 一鍵啟動全部服務 |
| T0-3 Dify 部署與配置 | 後端 | Dify 運行於 :5001 | 可透過 Console 建立知識庫 |
| T0-4 Ollama 安裝與模型 | AI | Ollama + llama3.1:8b 模型 | `ollama run llama3.1` 正常回覆 |
| T0-5 PostgreSQL + pgvector | 後端 | 資料庫 Schema Migration | 所有表格建立完成，可連線 |
| T0-6 Next.js 專案初始化 | 前端 | 前端專案 + Tailwind CSS + shadcn/ui | `npm run dev` 可開啟首頁 |
| T0-7 FastAPI 專案初始化 | 後端 | Backend 專案 + JWT 鑒權 | `/api/v1/system/health` 回傳 200 |
| T0-8 CI/CD Pipeline | DevOps | GitHub Actions workflow | Push → Build → Test 自動執行 |

### 8.3 Phase 1 — 核心功能 MVP（Week 3–8）

> **目標**：可供內部試用的最小可用產品，涵蓋基本問答 + 知識庫管理

#### Sprint 1（Week 3–4）：認證 + 知識庫管理

| Task ID | 功能 | 技術實作 | 驗收標準 |
| ------- | ---------------------- | ---------------------------------- | ------------------------------------- |
| T1-1 | 使用者登入/登出 | FastAPI + JWT + bcrypt | 登入後取得 Token，過期自動刷新 |
| T1-2 | 角色與權限管理 | RBAC middleware | 不同角色存取不同 API 返回正確 403/200 |
| T1-3 | 知識庫 CRUD（後端） | FastAPI → Dify Knowledge Base API | 可透過 API 建立/刪除/列出知識庫 |
| T1-4 | 知識庫管理頁面（前端） | Next.js + React + Shadcn | 可視化建立、列出、刪除知識庫 |
| T1-5 | 單檔上傳文件 | Multipart → Dify Document API | 上傳 PDF 後，Dify 自動分段並向量化 |
| T1-6 | 文件列表與刪除 | Dify Document API | 可查看知識庫內所有文件並刪除 |

#### Sprint 2（Week 5–6）：AI 對話核心

| Task ID | 功能 | 技術實作 | 驗收標準 |
| ------- | --------------------- | ----------------------------------- | ------------------------------------- |
| T2-1 | 對話 API（串流回覆） | FastAPI → Dify Chat API (SSE) | 問答回覆以 SSE 串流方式逐字顯示 |
| T2-2 | 對話紀錄持久化 | PostgreSQL conversations + messages | 重新整理頁面後對話歷史保留 |
| T2-3 | RAG 引用來源顯示 | 解析 Dify retriever_resources | 回覆下方顯示「參考來源」及原始段落 |
| T2-4 | 對話 UI（前端） | React Chat 元件 + SSE 處理 | 類 ChatGPT 介面，支援 Markdown 渲染 |
| T2-5 | 多對話 Session 管理 | 前端左側列 + 後端 CRUD | 可建立/切換/刪除多個對話 |
| T2-6 | 模型切換（本地/雲端） | Dify Model Provider 配置 | 可在設定頁切換 Ollama ↔ Azure OpenAI |

#### Sprint 3（Week 7–8）：批次匯入 + MVP 交付

| Task ID | 功能 | 技術實作 | 驗收標準 |
| ------- | ------------------ | ------------------------------ | ---------------------------------- |
| T3-1 | 批次匯入 API | FastAPI + Redis Queue + Worker | POST 上傳 50 檔啟動非同步處理 |
| T3-2 | 批次匯入進度追蹤 | WebSocket + Redis Hash | 前端即時顯示各檔案處理狀態與進度條 |
| T3-3 | 匯入錯誤處理與重試 | Worker retry logic + DLQ | 失敗檔案可單獨重試，不影響其他檔案 |
| T3-4 | 批次匯入 UI | React Upload + Progress 元件 | 拖放上傳 → 進度條 → 結果摘要 |
| T3-5 | MVP 整合測試 | Playwright E2E 測試 | 10 個核心場景全部通過 |
| T3-6 | MVP 部署到測試環境 | Docker Compose | 測試環境可供團隊試用 |

> **Phase 1 交付物**：可部署的 MVP 系統，支援知識庫管理、文件上傳/批次匯入、AI 對話問答（含 RAG 引用來源）

### 8.4 Phase 2 — 進階功能（Week 9–14）

#### Sprint 4（Week 9–10）：SK Agent 整合

| Task ID | 功能 | 技術實作 | 驗收標準 |
| ------- | -------------------- | ----------------------------------- | -------------------------------- |
| T4-1 | SK Kernel 初始化模組 | Semantic Kernel Python SDK | Kernel 成功載入 Ollama + Plugins |
| T4-2 | KnowledgeBase Plugin | SK Plugin → Dify Retrieve API | Agent 可透過 Plugin 查詢知識庫 |
| T4-3 | Agent 對話 API | `/api/v1/agent/invoke` + SSE | 多步驟推理回覆正確且可串流 |
| T4-4 | Agent 模式切換 UI | 前端 toggle: 一般 RAG ↔ Agent 模式 | 使用者可手動切換對話模式 |

#### Sprint 5（Week 11–12）：嵌入式 Widget + 進階 RAG

| Task ID | 功能 | 技術實作 | 驗收標準 |
| ------- | -------------------------- | ----------------------------------- | ---------------------------------------- |
| T5-1 | 嵌入式 Chat Widget | React 獨立元件 + iframe/script 嵌入 | 第三方網站 `<script>` 一行嵌入即可使用 |
| T5-2 | Widget 客製化 API | 品牌色、標題、預設問題等配置 | 透過 URL params 或 JS config 客製外觀 |
| T5-3 | RAGFlow 整合（複雜文件） | RAGFlow Docker + DeepDoc API | 掃描 PDF、含表格文件正確解析並建立索引 |
| T5-4 | 智慧路由：一般 vs 複雜文件 | 後端依副檔名/大小自動路由 | PDF > 10MB 或手動指定 → 走 RAGFlow 解析 |

#### Sprint 6（Week 13–14）：系統管理 + 監控

| Task ID | 功能 | 技術實作 | 驗收標準 |
| ------- | -------------- | --------------------- | ------------------------------------------ |
| T6-1 | 系統儀表板 | React + Recharts | 顯示文件數、對話數、Token 用量、回應延遲 |
| T6-2 | API Key 管理 | 自訂 Backend CRUD | 可建立/撤銷 API Key，支援到期日設定 |
| T6-3 | 操作日誌與稽核 | PostgreSQL audit_logs | 所有關鍵操作（上傳/刪除/設定變更）留下紀錄 |
| T6-4 | 使用量限額控制 | Redis Rate Limiter | 每使用者每分鐘/每日 Token 限額可配置 |

### 8.5 Phase 3 — 優化與擴充（Week 15–20）

| Sprint | 重點 | 關鍵任務 |
| --------- | --------------------------------- | -------------------------------------------- |
| Sprint 7 | 效能優化 + 壓力測試 | 批次匯入 500 檔壓測、對話併發 100 user 壓測 |
| Sprint 8 | 多 Agent 編排（SK Orchestration） | Sequential + Handoff 模式整合、工作流設計 UI |
| Sprint 9 | Agent Framework 預研 | 評估 AF GA 進度、概念驗證 MCP/A2A 協議整合 |
| Sprint 10 | 正式上線準備 | 安全掃描、備份策略、災難復原演練、SOP 文件 |

### 8.6 里程碑總覽

| 里程碑 | 日期 | 交付物 | 決策點 |
| ------ | ------------ | ------------------------------------------ | --------------------------------- |
| M0 | Week 2 結束 | 開發環境全部就緒 | — |
| M1 | Week 8 結束 | **MVP 上線**（內部試用） | 收集回饋決定 P2 優先序 |
| M2 | Week 14 結束 | **正式版 v1.0**（含 Agent + Widget） | 決定是否啟動 Agent Framework 遷移 |
| M3 | Week 20 結束 | **正式上線 + SLA 承諾** | — |

---

## 9. 人力配置與分工

### 9.1 團隊組成

| 角色 | 人數 | 職責 | 投入比例 |
| -------------- | ---- | ----------------------------------------------------- | ----------- |
| SA / Tech Lead | 1 | 架構設計、技術決策、Code Review、跨模組協調 | 100% |
| 後端工程師 | 2 | FastAPI Backend、Dify API 整合、SK Agent 整合、Worker | 100% |
| 前端工程師 | 1 | Next.js 前端、Chat UI、嵌入式 Widget | 100% |
| AI 工程師 | 1 | SK Plugin 開發、Prompt 調優、RAG 效果優化、模型評估 | 80% |
| DevOps / SRE | 1 | Docker 編排、CI/CD、監控告警、部署自動化 | 50%（兼職） |
| QA 測試 | 1 | 功能測試、E2E 測試、壓力測試 | 50%（兼職） |

### 9.2 Phase 1 每週分工（範例）

```
Week 3 Week 4 Week 5 Week 6
後端 A T1-1 登入 T1-3 知識庫API T2-1 對話API T2-2 對話持久化
後端 B T1-2 RBAC T1-5 檔案上傳 T2-3 RAG引用 T2-6 模型切換
前端 T1-4 知識庫頁面 T1-6 文件列表 T2-4 Chat UI T2-5 多Session
AI Dify配置調優 Prompt模板設計 RAG效果測試 Ollama模型選型
```

---

## 10. 驗收標準

### 10.1 Phase 1 MVP 驗收標準

| 編號 | 驗收項目 | 通過條件 |
| ----- | -------------------- | ------------------------------------------------ |
| AC-01 | 使用者可登入系統 | 輸入帳密 → 3 秒內進入主頁 |
| AC-02 | 可建立知識庫 | 建立 → 知識庫列表正確顯示 |
| AC-03 | 可上傳單一文件 | 上傳 10MB PDF → 60 秒內分段完成 |
| AC-04 | 可批次上傳 50 個檔案 | 50 檔上傳 → 全部完成、進度即時更新 |
| AC-05 | 可進行 AI 對話 | 提問 → 3 秒內開始串流回覆 |
| AC-06 | 對話顯示引用來源 | 回覆下方顯示至少 1 個文件引用（含片段） |
| AC-07 | 對話歷史持久化 | 重新整理頁面 → 歷史對話與訊息完整保留 |
| AC-08 | 角色權限控制 | user 角色無法存取知識庫管理頁面 |
| AC-09 | Docker 一鍵部署 | `docker compose up -d` → 5 分鐘內所有服務正常 |
| AC-10 | 本地 LLM 可用 | 斷開外網 → Ollama 仍可正常回覆問答 |

### 10.2 效能指標（SLA 目標）

| 指標 | 目標值 | 測量方式 |
| ----------------- | ------------------------------- | -------------- |
| 對話首 Token 延遲 | ≤ 3 秒 (本地) / ≤ 2 秒 (雲端) | P95 percentile |
| 對話完整回覆延遲 | ≤ 15 秒 (500 tokens) | P95 percentile |
| 文件上傳至可搜尋 | ≤ 60 秒 / 檔（10MB PDF） | 端到端計時 |
| 批次匯入吞吐量 | ≥ 100 檔 / 小時 | 50 檔批次測試 |
| API 可用性 | ≥ 99.5% | 每日健康檢查 |
| 併發使用者 | ≥ 50 人同時對話 | k6 壓力測試 |

---

## 11. 風險與應對

| 風險 ID | 風險描述 | 機率 | 影響 | 應對策略 |
| ------- | ----------------------------------- | ---- | ---- | ---------------------------------------------- |
| R-01 | Ollama 本地推理效能不足（回覆過慢） | 中 | 高 | 啟用 Azure OpenAI 雲端備援；升級 GPU 規格 |
| R-02 | Dify API 不滿足特定業務需求 | 低 | 中 | 透過自訂 Backend 擴充，不直接改 Dify 原始碼 |
| R-03 | Dify 版本升級導致 API 不相容 | 中 | 中 | API Proxy 層隔離；升級前先在測試環境驗證 |
| R-04 | 批次匯入大量檔案時 OOM | 中 | 高 | Worker 控制併發數（max 5）、檔案大小限制 |
| R-05 | RAGFlow 硬體資源需求高（16GB RAM） | 低 | 低 | Phase 2 才啟用，且為選配；輕量場景用 Dify 內建 |
| R-06 | Semantic Kernel Python SDK 版本更新 | 低 | 低 | 鎖定版本號；追蹤 changelog |
| R-07 | Agent Framework GA 延期 | 中 | 低 | 僅列為 Phase 3 預研，不影響主線開發 |
| R-08 | 前端開發人力不足（僅 1 人） | 中 | 中 | 使用 shadcn/ui 元件庫加速；優先核心頁面 |

---

## 12. 附錄：技術選型推論摘要

> 本節摘錄前階段 5 份評估報告的核心結論，作為 §1 技術決議的依據。

### 12.1 評估報告索引

| 報告 | 核心結論 |
| ------------------------------------------ | ---------------------------------------------------------------- |
| `ai_agent_frameworks_analysis_report.md` | 六維度評比：SK 🥇 > AF 🥈 > CAMEL 🥉 > Dify 第4；AutoGen 已 EOL |
| `semantic_kernel_analysis_report.md` | SK 架構深度分析：隱式 ReAct 迴圈、五種編排模式、12 個 LLM 連接器 |
| `react_implementation_analysis.md` | ReAct 實作比較：SK 最大 5 次自動迴圈、支援 async 並行函數呼叫 |
| `DEPLOYMENT_ANALYSIS.md` | 13 專案部署分析：Dify 最推薦非工程師平台、SK 純 SDK 最靈活 |
| `LOCAL_DEPLOYMENT_GUIDE.md` | 本地部署實測：Dify 一鍵 Docker、Ollama 全框架支援 |

### 12.2 關鍵決策理由

**為何選 Semantic Kernel 而非 LangChain？**

- SK 為 Microsoft 官方維護，.NET + Python 雙語言，企業整合首選
- 六維度（技術、離線、維護、Windows、獨立性、自託管）全數滿分
- GA 穩定版，LangChain 社群大但 API 頻繁變動

**為何選 Dify 而非 MaxKB？**

- MaxKB 的 GPL-3.0 授權對閉源商業產品有傳染風險
- Dify 提供最友好的 BaaS API + 官方前端模板，開發者體驗最佳
- Dify 130k Stars，社群最活躍，維護性風險最低

**為何選 PostgreSQL + pgvector 而非 Milvus / ChromaDB？**

- 與 Dify 主資料庫統一，減少運維元件數量
- 中型規模（< 500 萬向量）效能足夠
- 需要時可平滑遷移至 Milvus

**為何 Agent Framework 列為 Phase 3 而非現在使用？**

- RC1 階段，API 可能變動，不適合立即用於生產
- 評估報告建議「新專案可直接採用 AF」，但「現階段 SK GA 更穩定」
- Phase 3 預研，待 AF GA 後評估遷移成本

---

> **文件結束** — 本文件為可執行的系統架構設計與開發計畫，請團隊成員審閱後提出修改建議，確認後即可進入 Phase 0 環境建置。

agent sa doc detail

Comments...

Add Comment...

Latest Posts

agent sa doc detail

agent sa doc

local agent

Categories