# AI Agent 系統架構設計書（SA）
---
| 項目 | 內容 |
| -------- | ----------------------------------------------------- |
| 文件版本 | v4.0 |
| 建立日期 | 2026-03-02 |
| 文件狀態 | 可執行（待 Phase 0 PoC 驗收後更新 §3、§5） |
| 適用場景 | 機構設計研發、光學自動化、產線站點 AI 整合 |
| 相關圖檔 | `diagrams/` 資料夾內 8 個 `.mmd` 檔案（詳見附錄） |
> **本文件說明**：以 v2.0 的模組化架構與 Sprint 開發計畫為骨架，採用 v3.1 的技術選型（Ollama + Qwen3-1.7B、AnythingLLM + pgvector、FastAPI、Python MCP SDK），去除 Docker、Redis、Semantic Kernel 等依賴，簡化為可立即執行的方案。
---
## 目錄
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. 技術選型決議（已定案）
### 1.1 技術棧總表
| 層級 | 選定技術 | 決策理由 |
| ------------------ | ------------------------------------- | ------------------------------------------------------------ |
| LLM 推理引擎 | Ollama | Windows 原生、OpenAI 相容 API (:11434)、零配置、模型庫豐富 |
| 推理模型 | Qwen3-1.7B Q4_K_M | 全節點統一版本、~1.5GB VRAM、硬體門檻低 |
| 嵌入模型 | nomic-embed-text | 輕量（~270MB VRAM）、離線支援、語意品質佳 |
| 知識庫平台 | AnythingLLM Server | MIT 授權、無 Docker 安裝選項、管理介面友善，支援 pgvector |
| 向量資料庫（主庫） | PostgreSQL 15+ + pgvector | 與關聯式 DB 共用同一 PG 實例，減少運維複雜度 |
| 向量資料庫（副本） | PostgreSQL 15+ + pgvector（邊緣節點） | 邊緣節點本地安裝，離線可查詢，差異 SQL 包同步 |
| API 後端 | FastAPI（Python 3.11+） | 輕量、非同步、易整合 MCP |
| 工具調用框架 | Python MCP SDK | 標準協議、LLM 與工具解耦 |
| 工具路由引擎 | Python 規則字典（intent_router） | 補償 1.7B Function Calling 不穩定，詳見 §3.5 |
| 中央 / 邊緣資料庫 | PostgreSQL 15+ | 向量存儲（pgvector）、節點管理、版本控管、告警紀錄、對話歷史 |
| 邊緣對話資料庫 | SQLite | 對話歷史與同步狀態（向量資料已改由 pgvector 負責） |
| Log 收集 | MQTT + WebSocket + HTTP | 多頻率適配，支援各種設備輸出協議 |
### 1.2 明確排除項
| 排除方案 | 排除理由 |
| --------------- | --------------------------------------------------- |
| Docker Compose | 初期約束，不使用容器化 |
| Dify | 核心部署依賴 Docker Compose |
| RAGFlow | 最低需求 16GB RAM + Docker |
| Semantic Kernel | 對 LLM Function Calling 依賴過高，1.7B 不穩定 |
| Redis | 簡化架構，邊緣節點改用 SQLite，任務佇列改為同步處理 |
| 雲端 LLM API | 離線環境無法使用（可保留為有網路時的備援） |
---
## 2. 系統總體架構
圖檔： [ai_gen_docs/diagrams/system-architecture.mmd](ai_gen_docs/diagrams/system-architecture.mmd)
### 2.1 架構總覽圖
```
┌──────────────────────────────────────────────────┐
│ 客戶端層 │
│ 機構整合平台 光學自動化設備 產線站點 │
│ Web / Desktop 嵌入式 / 工控 HMI Edge │
└───────┬───────────────┬──────────────────┬───────┘
│ RESTful API │ │ WebSocket
└───────────────┴──────────────────┘
│ LAN
┌────────────────────────────▼──────────────────────────┐
│ 中央 AI 伺服器（專用機） │
│ M01 API Gateway (FastAPI :8000) │
│ ├─ M04 AI 對話引擎 (Ollama + Qwen3-1.7B) │
│ ├─ M05 MCP 工具調用引擎 (規則引擎 + MCP SDK :8002) │
│ ├─ M02 知識庫管理 (AnythingLLM :3001 + pgvector) │
│ ├─ M06 邊緣同步服務 (:8001) │
│ └─ M08 系統監控 │
└─────────────────────────┬─────────────────────────────┘
LAN 同步通道 │
┌──────────────────────┬─┴────────────────────┐
↓ ↓ ↓
研發工作站 光學自動化站 產線站點
Ollama 1.7B Ollama 1.7B Ollama 1.7B
pgvector 副本（唯讀） pgvector 副本（唯讀） pgvector 副本（唯讀）
CAD MCP（本地） 量測 MCP（本地） Log MCP + 告警推送
```
### 2.2 模組清單
| 模組 | 名稱 | 部署位置 | 對外介面 |
| ---- | ------------------ | -------------------------------- | -------------------- |
| M01 | API Gateway 與認證 | 中央伺服器 | REST API |
| M02 | 知識庫管理 | 中央伺服器 | REST API |
| M03 | 文件向量化處理 | 中央伺服器（AnythingLLM 內部） | 內部服務 |
| M04 | AI 對話引擎 | 所有節點 | REST API（SSE 串流） |
| M05 | MCP 工具調用引擎 | 所有節點（工具依節點類型不同） | REST API + 內部 SDK |
| M06 | 邊緣節點同步服務 | 中央（服務端）/ 各邊緣（客戶端） | REST API |
| M07 | 產線 Log 分析 | 產線站點 | MQTT / WS / HTTP |
| M08 | 系統監控 | 中央伺服器 | REST API |
### 2.3 關鍵約束條件
| 約束 | 內容 |
| ------------------ | ------------------------------------------------------------------------- |
| **模型上限** | Qwen3-1.7B；Function Calling 不穩定，改用規則引擎工具路由（詳見 §3.5） |
| **離線需求** | 所有邊緣節點支援完全離線，恢復 LAN 後自動同步知識庫副本 |
| **CAD 軟體** | AutoCAD、CATIA、Creo、NX、PROE、SolidWorks、中望（共 7 套，嚴格分期實作） |
| **容器化** | 初期不使用 Docker，所有服務原生安裝於 Windows |
| **外出使用** | 研發筆電假設不需外出離線（可隨時連回 LAN） |
---
## 3. 模組設計與元件規格
### M01 — API Gateway 與使用者認證
```
目的：統一入口、JWT 鑒權、請求路由至各模組
技術：FastAPI (Python 3.11+) + PyJWT + bcrypt
角色定義：
admin → 系統管理、節點管理、模型配置
kb_admin → 知識庫文件 CRUD
user → 問答對話、工具調用
api_client → 僅 API 存取（服務帳號，供各客戶端使用）
權限矩陣：
┌──────────────────┬─────────┬──────────┬──────┬────────────┐
│ 功能 │ admin │ kb_admin │ user │ api_client │
├──────────────────┼─────────┼──────────┼──────┼────────────┤
│ 節點管理 │ ✅ │ ❌ │ ❌ │ ❌ │
│ 知識庫 CRUD │ ✅ │ ✅ │ ❌ │ ❌ │
│ 文件上傳 │ ✅ │ ✅ │ ❌ │ ✅ │
│ 對話問答 │ ✅ │ ✅ │ ✅ │ ✅ │
│ MCP 工具調用 │ ✅ │ ✅ │ ✅ │ ✅ │
│ 系統監控 │ ✅ │ ✅ │ ❌ │ ❌ │
└──────────────────┴─────────┴──────────┴──────┴────────────┘
```
---
### M02 — 知識庫管理
```
目的：封裝 AnythingLLM API，提供統一知識庫管理介面
技術：FastAPI Proxy → AnythingLLM Server (:3001) + PostgreSQL + pgvector（主庫）
核心功能：
1. 建立知識庫（Workspace） POST /api/knowledge/workspace
2. 上傳文件 POST /api/knowledge/upload
3. 語意搜尋 GET /api/knowledge/search
4. 分類管理 GET /api/knowledge/categories
5. 版本查詢 GET /api/knowledge/version
知識庫分類與同步範圍：
┌─────────────────┬──────────────────────────────┬────────────────┐
│ 分類 (scope) │ 內容 │ 同步到哪些節點 │
├─────────────────┼──────────────────────────────┼────────────────┤
│ common │ 通用設計規範、材料手冊 │ 所有節點 │
│ engineering │ 機構設計文件、CAD 指令說明 │ 研發工作站 │
│ optics │ 光學設備手冊、量測規範 │ 光學自動化站 │
│ production │ 產線 SOP、歷史異常案例 │ 產線站點 │
└─────────────────┴──────────────────────────────┴────────────────┘
```
---
### M03 — 文件向量化處理
圖檔： [ai_gen_docs/diagrams/document-import-flow.mmd](ai_gen_docs/diagrams/document-import-flow.mmd)
```
目的：文件上傳後自動向量化，由 AnythingLLM 觸發，不需額外開發
技術：AnythingLLM 內建解析 + nomic-embed-text（透過 Ollama）
支援格式：
直接向量化： .txt .md .pdf .docx .csv
提取文字後： .dxf .dwg（提取標註文字 → 向量化）
向量化流程（全自動，由 AnythingLLM 管理）：
上傳文件
→ AnythingLLM 解析切段
→ Ollama nomic-embed-text 向量化（只跑一次，中央伺服器執行）
→ 寫入 PostgreSQL + pgvector 主庫
→ 更新版本號（格式：v{YYYYMMDD}-{序號}）
→ 記錄差異文件 ID 到 PostgreSQL kb_versions 表
```
---
### M04 — AI 對話引擎
圖檔： [ai_gen_docs/diagrams/rag-chat-flow.mmd](ai_gen_docs/diagrams/rag-chat-flow.mmd)
```
目的：帶知識庫 RAG 的 AI 對話，支援 SSE 串流回覆
技術：Ollama API (:11434) + Qwen3-1.7B + PostgreSQL + pgvector（邊緣節點本地 or 中央主庫）
對話流程：
使用者問題
→ POST /api/chat（API Gateway 鑒權）
→ pgvector 語意搜尋（邊緣節點本地 or 中央主庫，依節點）
→ 組裝 Prompt（RAG 片段 + 對話歷史，≤ 2,000 tokens 建議值）
→ Ollama Qwen3-1.7B 生成回覆（SSE 串流輸出）
→ 儲存對話歷史（邊緣 SQLite / 中央 PostgreSQL）
→ 回傳回覆 + 引用來源清單
Context Window 管理：
Qwen3-1.7B 支援 32K tokens，但建議送入量控制 ≤ 2,000 tokens
產線 Log 場景：滑動視窗 5 分鐘 → 統計摘要 → 異常候選行 → LLM 分析
```
---
### M05 — MCP 工具調用引擎
圖檔： [ai_gen_docs/diagrams/mcp-tool-call-flow.mmd](ai_gen_docs/diagrams/mcp-tool-call-flow.mmd)
```
目的：管理所有 MCP Server，提供工具調用能力
補償 Qwen3-1.7B Function Calling 不穩定的核心機制
技術：Python MCP SDK + 規則路由引擎（intent_router.py）
⚠️ 架構原則：LLM 不做工具選擇決策，由規則引擎負責。
兩段式工具調用流程：
使用者輸入
→ [規則引擎] 關鍵字比對 → 決定使用哪個 MCP 工具
→ [LLM] 從輸入中萃取執行所需參數（few-shot prompt 輔助）
→ [MCP SDK] 執行工具
→ [LLM] 組裝自然語言回覆
規則路由字典（intent_router.py 摘要）：
┌───────────────────┬────────────────────────────────────────────┐
│ 意圖 key │ 比對關鍵字（任一符合即觸發） │
├───────────────────┼────────────────────────────────────────────┤
│ cad_query │ 查詢指令、怎麼建立、如何繪製、CAD 指令 │
│ cad_execute │ 幫我執行、建立螺孔、建立特徵、幫我在 │
│ pmi_create_project│ 建立專案、新增專案、建立 ECO │
│ pmi_create_task │ 建立任務、新增任務、指派工作 │
│ knowledge_search │ 查詢、說明、什麼是、規範、標準 │
└───────────────────┴────────────────────────────────────────────┘
無比對 → 純 RAG 問答（不呼叫 MCP 工具）
已定義 MCP Server：
cad/ → CAD MCP（部署於研發工作站）
pmi/ → PMI/LPC MCP（部署於中央伺服器）
measurement/ → 量測設備 MCP（部署於光學自動化站）
log/ → Log 分析 MCP（部署於產線站點）
knowledge/ → 知識庫查詢 MCP（所有節點）
各場景可靠度：
RAG 知識庫查詢 ✅ 高 純文字，無 Function Calling
CAD 指令查詢 ✅ 高 規則比對選工具，LLM 僅萃取關鍵字
CAD 執行操作 ⚠️ 中 複雜參數需 few-shot prompt，加入確認步驟
PMI/LPC 任務建立 ✅ 高 結構化欄位，few-shot 輔助
量測數據整理 ✅ 高 模板驅動，LLM 做格式轉換
產線 Log 分析 ✅ 高 規則 + 模式比對，LLM 生成摘要語言
升級路徑（無需修改 MCP 介面）：
VRAM ≥ 2.5GB → 換 Qwen3-4B → 部分場景可改回 Function Calling
VRAM ≥ 4.5GB → 換 Qwen2.5-7B → 全面啟用 Function Calling
```
---
### M06 — 邊緣節點同步服務
圖檔： [ai_gen_docs/diagrams/knowledge-sync-flow.mmd](ai_gen_docs/diagrams/knowledge-sync-flow.mmd)
```
目的：維護中央主庫與各邊緣節點 pgvector 副本的版本一致性
技術：FastAPI（同步服務端 :8001）+ Python 背景服務（客戶端）
同步流程：
中央主庫文件更新 → 版本號遞增（v{YYYYMMDD}-{序號}）
邊緣客戶端每 5 分鐘 → GET /api/sync/check?node_id=...¤t_version=...
→ 版本落後：中央同步服務查詢差異向量包
SELECT id, document_id, content, embedding FROM document_vectors
WHERE document_id = ANY(diff_ids) AND scope = ANY(node_scope)
→ 序列化為 JSON 陥列包（對小文件量 < 50MB。大量文件分批傳輸）
→ 邊緣節點收到向量包 → INSERT INTO document_vectors ... ON CONFLICT DO UPDATE
→ 回報 POST /api/sync/ack
離線期間：使用本地 pgvector 查詢，結果可能略舊
恢復連線：自動補同步，不需人工介入
```
---
### M07 — 產線 Log 分析
```
目的：多通道收集設備 Log，LLM 分析異常模式，主動推送告警
技術：MQTT + WebSocket + HTTP 收集 + Qwen3-1.7B 分析 + WebSocket 推送
Log 收集通道：
MQTT → broker localhost:1883，topics: factory/+/log, factory/+/sensor
WebSocket → port: 9001
HTTP → endpoint: /log/ingest
Context 壓縮策略（避免超過建議送入量）：
原始 Log → 滑動視窗（最近 5 分鐘）
→ 統計摘要（每類 Log 出現次數、最大/最小值）
→ 異常候選（僅保留偏離正常範圍條目）
→ 送給 LLM（壓縮至 < 2,000 tokens）
告警等級：
critical → LLM 判定嚴重 or 規則引擎觸發 → 立即 WebSocket 推送
warning → LLM 判定一般異常 → 記錄，累積每小時報表
info → LLM 判定正常 → 只記錄定期摘要
```
---
### M08 — 系統監控
```
目的：顯示各節點同步狀態、服務健康度、告警統計
技術：FastAPI REST API
端點：
GET /api/system/health → 各服務狀態（Ollama / AnythingLLM / PostgreSQL）
GET /api/system/nodes → 所有節點狀態、同步版本、最後上線時間
GET /api/system/stats → 對話數、工具調用數、告警數
```
---
## 4. 資料流程設計
### 4.1 文件匯入流程
```
文件負責人
→ AnythingLLM Web UI 上傳文件（:3001）
→ nomic-embed-text 自動向量化（中央伺服器執行）
→ 寫入 PostgreSQL + pgvector 主庫，版本號遞增
→ PostgreSQL kb_versions 記錄差異 document_ids
→ 邊緣節點下次同步時取得差異向量 SQL 包 → INSERT/UPDATE 本地 pgvector
```
### 4.2 AI 對話流程（RAG）
```
使用者問題
→ POST /api/chat（API Gateway JWT 鑒權）
→ pgvector 語意搜尋（邊緣節點本地 or 中央主庫）
→ 組裝 Prompt（RAG 片段 + 歷史，≤ 2,000 tokens）
→ Ollama Qwen3-1.7B（SSE 串流）
→ 儲存對話（SQLite / PostgreSQL）
→ 回傳回覆 + 引用來源
```
### 4.3 MCP 工具調用流程
```
使用者指令
→ POST /api/tool-call（API Gateway JWT 鑒權）
→ 規則引擎 intent_router：關鍵字比對 → 選定工具
→ LLM 參數萃取 prompt（few-shot）→ 取得結構化參數
→ MCP SDK → MCP Server → 實際工具執行
→ LLM 組裝自然語言回覆
→ 回傳結果 + 工具執行紀錄（工具名、參數、狀態、延遲）
```
### 4.4 邊緣離線問答流程
```
邊緣節點（LAN 斷線中）
→ 使用者問題 → POST /api/chat（本地 API Gateway）
→ 本地 pgvector 語意搜尋（邊緣節點 PostgreSQL）
→ 本地 Ollama Qwen3-1.7B 推理
→ 回傳結果（可能使用略舊的知識庫版本）
恢復 LAN 後：
→ 同步客戶端偵測到版本落後
→ 自動下載差異包，更新本地副本
```
---
## 5. API 介面規格
### 5.1 API 端點總覽
| 分類 | Method | 路徑 | 說明 |
| ------------------ | ------ | ----------------------------- | ---------------------------- |
| **健康檢查** | GET | `/api/health` | 服務狀態確認 |
| **對話** | POST | `/api/chat` | RAG 問答（SSE 串流） |
| | POST | `/api/tool-call` | MCP 工具調用問答 |
| | GET | `/api/conversations` | 對話歷史清單 |
| | DELETE | `/api/conversations/{id}` | 刪除對話 |
| **知識庫** | POST | `/api/knowledge/upload` | 文件上傳 |
| | GET | `/api/knowledge/search` | 語意搜尋 |
| | GET | `/api/knowledge/categories` | 分類清單 |
| | GET | `/api/knowledge/version` | 目前版本號查詢 |
| **同步** | GET | `/api/sync/check` | 節點版本比對（邊緣節點呼叫） |
| | GET | `/api/sync/patch` | 下載差異向量包 |
| | POST | `/api/sync/ack` | 同步完成回報 |
| **MCP 工具** | GET | `/api/mcp/tools` | 列出可用工具 |
| | POST | `/api/mcp/invoke` | 直接調用指定工具 |
| **告警** | WS | `/ws/alerts` | 訂閱產線告警推送 |
| **系統** | GET | `/api/system/health` | 各服務狀態 |
| | GET | `/api/system/nodes` | 節點狀態清單 |
| | GET | `/api/system/stats` | 系統統計數據 |
### 5.2 核心 API 詳細規格
#### POST `/api/chat` — RAG 問答（SSE 串流）
```json
// Request
{
"query": "M8 螺絲的建議鎖固扭矩是多少？",
"node_id": "ws-01",
"conversation_id": "conv_abc123"
}
// Response（SSE 串流）
event: delta
data: {"content": "根據公司設計規範第三章，"}
event: delta
data: {"content": "M8 螺絲的建議扭矩為 25 N·m"}
event: done
data: {
"conversation_id": "conv_abc123",
"sources": [
{ "document": "機械設計規範_v3.2.pdf", "page": 42, "score": 0.94,
"excerpt": "M8 鎖固扭矩：25 N·m（乾燥狀態）" }
],
"model_used": "qwen3:1.7b",
"latency_ms": 850
}
```
#### POST `/api/tool-call` — MCP 工具調用問答
```json
// Request
{
"query": "幫我在 SolidWorks 的目前零件建立 M8 深 20mm 的螺孔",
"node_id": "ws-01",
"context": { "software": "SolidWorks", "version": "2024" }
}
// Response
{
"answer": "已成功建立 M8 深度 20mm 的螺孔特徵（Feature ID: feat_001）",
"tool_calls": [
{
"tool": "cad_execute_command",
"args": { "software": "SolidWorks", "command": "InsertHole",
"params": { "type": "M8", "depth": 20, "unit": "mm" } },
"result": { "status": "success", "feature_id": "feat_001" },
"latency_ms": 1850
}
],
"intent_matched": "cad_execute",
"latency_ms": 2800
}
```
#### GET `/api/sync/check` — 節點版本比對
```json
// Request
GET /api/sync/check?node_id=ws-01¤t_version=v20260228-003&scope=engineering
// Response（有差異）
{
"status": "outdated",
"latest_version": "v20260302-001",
"diff_document_ids": ["doc_123", "doc_456"],
"diff_size_bytes": 524288,
"sync_url": "/api/sync/patch?ids=doc_123,doc_456"
}
```
---
## 6. 資料庫設計
### 6.1 儲存架構總覽
| 儲存類型 | 技術 | 位置 | 用途 |
| --------------------- | ------------------------- | ---------- | --------------------------------------- |
| 向量資料庫（主庫） | PostgreSQL 15+ + pgvector | 中央伺服器 | 知識庫語意向量（Master） |
| 向量資料庫（副本） | PostgreSQL 15+ + pgvector | 各邊緣節點 | 離線知識庫查詢，差異 SQL 包同步 |
| 關聯式（中央 + 邊緣） | PostgreSQL 15+ | 所有節點 | 向量與關聯式統一一實例，不另安裝向量 DB |
| 對話歷史（邊緣） | SQLite | 各邊緣節點 | 對話歷史、同步狀態（輕量輔助 DB） |
| 原始媒體 | 本地磁碟 / NAS | 中央伺服器 | 原始圖片、影片、DXF/DWG |
### 6.2 PostgreSQL 資料表（中央伺服器 + 邊緣節點均適用）
> **安裝 pgvector**：`CREATE EXTENSION IF NOT EXISTS vector;`
> **AnythingLLM 設定**：環境變數 `VECTOR_DB=pgvector`、`PGVECTOR_CONNECTION_STRING=postgresql://user:pass@localhost/anythingllm`
```sql
-- ① pgvector 擴充（各節點 PostgreSQL 均需執行）
CREATE EXTENSION IF NOT EXISTS vector;
-- ② 向量文件表（主庫完整版 / 副本僅存 scope 內資料）
CREATE TABLE document_vectors (
id UUID PRIMARY KEY DEFAULT gen_random_uuid(),
document_id VARCHAR(50) NOT NULL, -- 對應 kb_versions.document_ids 內的 ID
scope VARCHAR(50) NOT NULL, -- common / engineering / optics / production
content TEXT NOT NULL, -- 切段原文
embedding vector(768) NOT NULL, -- nomic-embed-text 輸出維度
metadata JSONB, -- { filename, page, category }
created_at TIMESTAMP NOT NULL DEFAULT NOW()
);
CREATE INDEX ON document_vectors USING ivfflat (embedding vector_cosine_ops);
CREATE INDEX ON document_vectors (document_id);
CREATE INDEX ON document_vectors (scope);
```
```sql
-- ③ 邊緣節點管理（僅中央伺服器）
CREATE TABLE nodes (
id VARCHAR(50) PRIMARY KEY, -- "ws-01"
type VARCHAR(20) NOT NULL, -- engineering / optics / production
scope VARCHAR(50), -- 知識庫同步範圍
last_seen TIMESTAMP,
last_sync_version VARCHAR(30),
status VARCHAR(20) DEFAULT 'offline'
);
-- 知識庫版本紀錄
CREATE TABLE kb_versions (
version VARCHAR(30) PRIMARY KEY, -- "v20260302-001"
created_at TIMESTAMP NOT NULL DEFAULT NOW(),
document_ids JSONB,
description TEXT
);
-- 告警紀錄
CREATE TABLE alerts (
id SERIAL PRIMARY KEY,
node_id VARCHAR(50),
severity VARCHAR(20) NOT NULL, -- critical / warning / info
message TEXT NOT NULL,
raw_excerpt TEXT,
created_at TIMESTAMP NOT NULL DEFAULT NOW(),
acknowledged_at TIMESTAMP
);
-- MCP 工具調用日誌
CREATE TABLE tool_call_logs (
id SERIAL PRIMARY KEY,
node_id VARCHAR(50),
tool_name VARCHAR(100),
intent VARCHAR(50), -- 規則引擎比對結果
args JSONB,
result JSONB,
status VARCHAR(20), -- success / error
latency_ms INT,
created_at TIMESTAMP NOT NULL DEFAULT NOW()
);
```
### 6.3 SQLite 資料表（邊緣節點）
```sql
CREATE TABLE conversations (
id TEXT PRIMARY KEY,
title TEXT,
created_at TEXT,
updated_at TEXT
);
CREATE TABLE messages (
id TEXT PRIMARY KEY,
conversation_id TEXT REFERENCES conversations(id),
role TEXT NOT NULL, -- user / assistant
content TEXT NOT NULL,
sources TEXT, -- JSON：引用來源
tool_calls TEXT, -- JSON：工具調用紀錄
latency_ms INTEGER,
created_at TEXT
);
CREATE TABLE sync_state (
key TEXT PRIMARY KEY,
value TEXT
-- 記錄：current_version, last_sync_time, sync_status
);
```
---
## 7. 部署架構與環境規格
### 7.1 中央伺服器
**建議硬體規格**：CPU 8 核 / RAM 16GB / GPU VRAM 4GB+ / SSD 500GB
| 服務 | 技術 | Port | 說明 |
| ---------------- | ---------------------- | ----- | -------------------------------- |
| API Gateway | FastAPI (Python 3.11+) | 8000 | 統一入口、路由、JWT 鑒權 |
| 推理引擎 | Ollama + Qwen3-1.7B | 11434 | LLM 推理 + nomic-embed-text 嵌入 |
| 知識庫管理 | AnythingLLM Server | 3001 | 文件管理介面 + pgvector 主庫 |
| 邊緣同步服務 | FastAPI（子應用） | 8001 | 差異計算、版本推送 |
| MCP Orchestrator | Python MCP SDK | 8002 | MCP Server 統一調用 |
```
/opt/ai-agent/
├── gateway/ # FastAPI API Gateway
│ ├── main.py
│ └── routers/
│ ├── chat.py
│ ├── tool_call.py
│ ├── knowledge.py
│ └── sync.py
├── sync-service/ # 邊緣同步服務
│ ├── server.py
│ └── client.py
├── mcp-servers/
│ ├── knowledge/ # 知識庫查詢 MCP（所有節點）
│ ├── cad/ # CAD MCP（研發工作站）
│ │ ├── adapters/
│ │ │ ├── base.py # ICADAdapter 抽象類別
│ │ │ ├── autocad.py # Phase 1
│ │ │ ├── solidworks.py # Phase 1
│ │ │ ├── catia.py # Phase 2
│ │ │ └── nx.py # Phase 2
│ │ └── server.py
│ ├── pmi/ # PMI/LPC MCP（中央伺服器）
│ ├── measurement/ # 量測設備 MCP（光學自動化站）
│ └── log/ # Log 分析 MCP（產線站點）
├── models/ # Ollama 模型存放
└── anythingllm/ # AnythingLLM 設定與資料
```
### 7.2 邊緣節點規格
| 節點類型 | 最低 VRAM | 本地服務 |
| ------------ | --------- | --------------------------------------------------- |
| 研發工作站 | 2GB | Ollama 1.7B + PostgreSQL + pgvector 副本 + CAD MCP |
| 光學自動化站 | 2GB | Ollama 1.7B + PostgreSQL + pgvector 副本 + 量測 MCP |
| 產線站點 | 2GB | Ollama 1.7B + PostgreSQL + pgvector 副本 + Log MCP |
```
C:\ai-agent\
├── ollama\ # Ollama 執行檔與模型
├── postgresql\ # PostgreSQL 15 + pgvector（本地向量庫）
│ ├── data\ # DB 資料目錄
│ └── pg_hba.conf # 僅允許本地連線
├── mcp-servers\
│ └── cad\ # 依節點類型安裝對應 MCP
├── sync-client\ # 同步客戶端（背景服務）
└── config.yaml # 節點設定
```
```yaml
# config.yaml 範例（研發工作站）
node:
id: "ws-01"
type: "engineering"
scope: ["common", "engineering"]
sync:
server_url: "http://192.168.1.100:8001"
check_interval_seconds: 300
retry_on_failure: true
ollama:
host: "http://localhost:11434"
default_model: "qwen3:1.7b"
embed_model: "nomic-embed-text"
num_gpu_layers: 28 # 設計軟體未開啟時（1.7B 共 28 層）
num_gpu_layers_low: 8 # 設計軟體高負載時
database:
host: "localhost"
port: 5432
name: "ai_agent"
user: "ai_agent"
# 合併向量與關聯式資料庫，不另載其他向量 DB
# 中央伺服器為完整主庫，邊緣節點仅存 scope 內的向量副本
```
---
## 8. 開發階段計畫
### 8.1 總覽甘特圖
```
Phase 0: PoC 驗證 ██████░░░░░░░░░░░░░░░░░░░░░░░░░░ Week 1-3
Phase 1: 核心功能 ░░░░░░████████████░░░░░░░░░░░░░░ Week 4-7
Phase 2: 擴展場景 ░░░░░░░░░░░░░░░░░░██████████████ Week 8-12
Phase 3: 優化完整 ░░░░░░░░░░░░░░░░░░░░░░░░░░████████ Week 13-16
──────────────────────────────────────
W1 W4 W7 W10 W13 W16
```
### 8.2 Phase 0 — PoC 驗證（Week 1–3）
> **目標**：驗證最核心技術鏈路（中央推理 + 邊緣副本 + 規則引擎 + AutoCAD MCP），確認可行性再展開。
| Task ID | 任務 | 產出物 | 工時估算 |
| ------- | ---------------------------------------- | -------------------------------------- | -------- |
| P0-T1 | 中央伺服器 Ollama + AnythingLLM 建置 | 推理服務可用、知識庫可上傳 | 2 天 |
| P0-T2 | 研發工作站邊緣節點安裝 | Ollama 1.7B 可離線推理 | 2 天 |
| P0-T3 | API Gateway 基礎骨架 + JWT | `/api/chat`、`/api/tool-call` 可通 | 3 天 |
| P0-T4 | 規則引擎 intent_router + AutoCAD MCP PoC | 自然語言 → AutoCAD 指令成功 | 5 天 |
| P0-T5 | 知識庫上傳 + 邊緣副本同步驗證 | 差異同步可用、離線問答準確率 > 80% | 3 天 |
**PoC 通過標準**：
- [ ] AutoCAD MCP 工具調用至少一個場景成功（規則引擎正確選工具）
- [ ] 離線狀態下知識庫查詢回應時間 < 5 秒
- [ ] 邊緣副本與主庫同步完成，版本一致
**決策點**：PoC 驗收後決定是否繼續 Phase 1，以及是否調整規則引擎字典完整度。
---
### 8.3 Phase 1 — 核心功能（Week 4–7）
> **目標**：研發工作站場景全部可試用（知識庫問答 + CAD MCP + PMI MCP + 邊緣離線）。
#### Sprint 1（Week 4–5）：知識庫 + 對話核心
| Task ID | 功能 | 驗收標準 |
| ------- | -------------------------------- | ---------------------------------------------- |
| T1-1 | M01 API Gateway 完整開發 | 所有端點可用，JWT 鑒權正確（401/403 回傳正確） |
| T1-2 | M02 知識庫管理 API（上傳、搜尋） | 上傳 PDF → 60 秒內完成向量化，可被查詢 |
| T1-3 | M04 對話引擎（RAG + SSE 串流） | 問答回覆以 SSE 串流逐字顯示，含引用來源 |
| T1-4 | 對話歷史持久化（SQLite） | 重新整理頁面後對話歷史保留 |
#### Sprint 2（Week 6–7）：MCP 工具 + 同步服務
| Task ID | 功能 | 驗收標準 |
| ------- | --------------------------------- | ------------------------------------------- |
| T2-1 | M05 規則引擎 intent_router 完整版 | 所有意圖類型比對正確，無比對時走 RAG |
| T2-2 | CAD MCP AutoCAD 完整適配器 | 指令查詢 + 執行操作均可用 |
| T2-3 | CAD MCP SolidWorks 完整適配器 | 指令查詢 + 執行操作均可用 |
| T2-4 | PMI/LPC MCP Server | 建立/查詢/更新任務均可用 |
| T2-5 | M06 邊緣同步服務完整開發 | 差異同步、版本號、ack 機制全部可用 |
| T2-6 | 研發工作站一鍵部署腳本 | `install-workstation.ps1` 10 分鐘完成安裝 |
> **Phase 1 交付物**：研發工作站場景可供試用，涵蓋 AutoCAD / SolidWorks MCP + PMI MCP + 知識庫問答 + 邊緣離線能力。
---
### 8.4 Phase 2 — 擴展場景（Week 8–12）
| Task ID | 功能 | 前置條件 | 驗收標準 |
| ------- | ------------------------- | ----------------------------------- | ----------------------------- |
| T3-1 | M07 Log MCP（三通道收集） | 確認 Log 格式與頻率 | MQTT / WS / HTTP 三通道均可收 |
| T3-2 | 主動告警推送（WebSocket） | T3-1 完成 | 異常偵測後 < 3 秒推送 |
| T3-3 | 產線站點邊緣部署 | T3-2 完成 | 離線 Log 分析可用 |
| T3-4 | 量測設備 MCP Server | 確認設備 SDK 與文件 | 自然語言設定量測參數成功 |
| T3-5 | 光學自動化站邊緣部署 | T3-4 完成 | 離線量測分析可用 |
| T3-6 | CATIA MCP 適配器 | **確認 CAA V5 API 授權 ⚠️** | 基本指令查詢可用 |
| T3-7 | NX MCP 適配器 | **確認 NX Open 授權 ⚠️** | 基本指令查詢可用 |
| T3-8 | M08 節點監控儀表板 | Phase 1 完成 | 顯示所有節點同步狀態與版本 |
> **Phase 2 交付物**：三類邊緣節點全部可試用，產線告警上線，CATIA/NX 視授權確認後決定。
---
### 8.5 Phase 3 — 優化與完整（Week 13–16）
| Task ID | 任務 | 說明 |
| ------- | ---------------------- | --------------------------------------- |
| P3-T1 | Creo / PROE MCP 適配器 | J-Link API 整合 |
| P3-T2 | 中望 CAD MCP 適配器 | ZWCAD API 整合 |
| P3-T3 | 效能優化與壓力測試 | 10 工作站同時離線查詢，回應 < 5 秒 |
| P3-T4 | 安全強化 + SOP 文件 | API 存取控制、本地資料加密 |
| P3-T5 | 多節點監控完整版 | 推理狀態、告警統計、工具調用成功率 |
| P3-T6 | 模型升級評估 | 若 VRAM 允許，評估換 4B/7B 移除規則引擎 |
### 8.6 里程碑總覽
| 里程碑 | 時間 | 交付物 | 決策點 |
| ------ | ------------ | ---------------------------- | ------------------------------ |
| M0 | Week 3 結束 | **PoC 驗收** | 確認技術選型，決定繼續 Phase 1 |
| M1 | Week 7 結束 | **研發工作站場景上線** | 收集回饋，決定 Phase 2 優先序 |
| M2 | Week 12 結束 | **三類節點全部上線** | 決定是否升級模型（4B / 7B） |
| M3 | Week 16 結束 | **正式上線** | — |
---
## 9. 人力配置與分工
### 9.1 團隊組成
| 角色 | 人數 | 職責 | 投入比例 |
| -------------- | ---- | ---------------------------------------------------- | ----------- |
| SA / Tech Lead | 1 | 架構設計、技術決策、Code Review、跨模組協調 | 100% |
| 後端工程師 | 2 | FastAPI Gateway、MCP Server 開發、同步服務 | 100% |
| AI 工程師 | 1 | 規則引擎維護、Prompt 調優、RAG 效果優化、Ollama 調參 | 80% |
| DevOps | 1 | PowerShell 部署腳本、節點安裝、監控設定 | 50%（兼職） |
| QA | 1 | 功能測試、MCP 工具場景測試 | 50%（兼職） |
### 9.2 Phase 1 每週分工
```
Week 4 Week 5 Week 6 Week 7
後端 A T1-1 Gateway T1-2 知識庫API T2-2 CAD AutoCAD T2-5 同步服務
後端 B T1-3 對話引擎 T1-4 歷史持久化 T2-3 CAD SolidWorks T2-6 部署腳本
AI 工程師 規則引擎設計 T2-1 intent_router T2-4 PMI MCP Prompt 調優
DevOps 環境安裝驗收 config.yaml 模板 安裝腳本 v1 安裝腳本 v2
QA 測試案例設計 — T1 整合測試 T2 整合測試
```
---
## 10. 驗收標準
### 10.1 功能驗收
| 編號 | 驗收項目 | 通過條件 |
| ----- | ------------------- | ---------------------------------------------- |
| AC-01 | 邊緣節點離線問答 | LAN 斷線後仍可查詢，回應時間 < 5 秒 |
| AC-02 | 知識庫副本自動同步 | 主庫更新後，節點恢復連線時自動補同步 |
| AC-03 | AutoCAD 指令查詢 | 自然語言查詢 → 規則引擎選工具 → 正確指令清單 |
| AC-04 | SolidWorks 操作執行 | 自然語言 → SW COM API 執行，操作成功 |
| AC-05 | PMI/LPC 任務建立 | 自然語言 → PMI 系統新增任務成功 |
| AC-06 | 產線 Log 異常偵測 | 異常 Log 注入 → 3 秒內 WebSocket 告警 |
| AC-07 | 量測數據整理報表 | 自然語言請求 → 匯出 CSV 報表成功 |
| AC-08 | 知識庫文件上傳 | 上傳 PDF → 60 秒內完成向量化，可被查詢 |
| AC-09 | MCP 工具選擇正確率 | 規則引擎比對正確率 ≥ 95%（基於測試語句集） |
### 10.2 效能指標
| 指標 | 目標值 |
| --------------------- | ---------------------------------- |
| 一般問答首 Token 延遲 | 邊緣節點 ≤ 2 秒（Qwen3-1.7B） |
| MCP 工具調用完成時間 | ≤ 4 秒（規則路由 + CAD API 呼叫） |
| 產線告警推送延遲 | 異常偵測後 ≤ 3 秒 |
| 知識庫同步速度 | LAN 100Mbps 環境下 1GB < 2 分鐘 |
| 節點自動同步頻率 | 預設每 5 分鐘檢查一次 |
---
## 11. 風險評估
| 風險 ID | 描述 | 嚴重度 | 應對策略 |
| ------- | -------------------------------- | ------ | ----------------------------------------------------------------------- |
| R-01 | CATIA/NX API 需商業授權 | 🔴 高 | Phase 2 前優先確認授權；Phase 1 只做 AutoCAD/SolidWorks |
| R-02 | 各節點硬體差異，老設備 VRAM 不足 | 🟢 低 | 1.7B 僅需 ~2GB VRAM，硬體門檻已大幅降低 |
| R-03 | 知識庫副本同步在 LAN 不穩時失敗 | 🟡 中 | 副本唯讀設計、支援手動觸發、retry 3 次機制 |
| R-04 | 產線 Log 量超過建議送入量 | 🟡 中 | 滑動視窗 + 統計摘要壓縮，送入 < 2,000 tokens |
| R-05 | 7 套 CAD API 差異大，開發工時高 | 🔴 高 | 嚴格分期，Phase 1 只做 AutoCAD/SolidWorks，每期驗收後評估 ROI |
| R-06 | 設計軟體與 Ollama 共用 VRAM 衝突 | 🟡 中 | 動態調整 `OLLAMA_NUM_GPU_LAYERS`（28/8），提供快捷腳本切換 |
| R-07 | PMI/LPC 系統 API 未開放 | 🟡 中 | 事先確認 API 存取方式；備案為 RPA 自動化 |
| R-08 | 1.7B Function Calling 不穩定 | 🔴 高 | 規則引擎補位（§3.5）；PoC 驗證規則字典完整度；規則比對正確率列入 AC-09 |
| R-09 | 1.7B 複雜推理品質偏低 | 🟡 中 | 結構化 Prompt 模板；few-shot 示例；複雜指令加確認步驟 |
---
## 12. 待釐清事項
在正式進入 Phase 0 前，以下問題需要確認：
| # | 問題 | 影響範圍 | 優先度 |
| - | ------------------------------------------- | ---------------------------------- | ------ |
| 1 | 中央伺服器實際硬體規格（CPU / RAM / GPU）？ | 決定可承載節點數量與服務穩定性 | 🟡 中 |
| 2 | 產線 Log 更新頻率（毫秒 / 秒 / 分鐘）？ | 決定 Log MCP 緩衝策略 | 🔴 高 |
| 3 | CATIA / NX 版本及 Developer API 授權狀況？ | 決定 Phase 2 CAD 整合可行性 | 🔴 高 |
| 4 | PMI/LPC 系統是否有開放 REST API 文件？ | 決定 PMI MCP 封裝方式（API / RPA） | 🟡 中 |
| 5 | 量測設備使用哪個廠商 SDK（是否有文件）？ | 決定量測 MCP 開發工時 | 🟡 中 |
| 6 | 各邊緣節點最低硬體規格（最老的設備）？ | 確認老設備是否達 ~2GB VRAM | 🟢 低 |
| 7 | 知識庫文件預估數量與更新頻率？ | 決定同步頻率與副本大小 | 🟢 低 |
---
## 附錄：專案檔案結構
### 圖檔清單（`diagrams/`）
| 檔案名稱 | 類型 | 對應章節 | 說明 |
| ---------------------------- | --------------- | -------------- | --------------------------------------------- |
| `system-architecture.mmd` | flowchart (TB) | §2.1 | 系統整體架構（中央伺服器 + 三類邊緣節點） |
| `document-import-flow.mmd` | flowchart (TD) | §3 M03, §4.1 | 文件匯入 → 解析 → 向量化 → 寫入 pgvector |
| `rag-chat-flow.mmd` | sequenceDiagram | §3 M04, §4.2 | RAG 對話流程（JWT → pgvector → LLM → SSE） |
| `mcp-tool-call-flow.mmd` | sequenceDiagram | §3 M05, §4.3 | MCP 工具調用（規則引擎兩段式流程） |
| `knowledge-sync-flow.mmd` | sequenceDiagram | §3 M06, §4.4 | pgvector 差異同步（SQL 向量包 INSERT） |
| `log-analysis-flow.mmd` | flowchart (TD) | §3 M07 | 產線 Log 分析與 WebSocket 告警推送 |
| `db-schema-er.mmd` | erDiagram | §6 | PostgreSQL + SQLite 資料表 ER 圖 |
| `development-gantt.mmd` | gantt | §8 | Phase 0–3 開發甘特圖（Week 1–16） |
```
ai-agent-system/
├── docs/
│ ├── AI_Agent_SA_v4.md # 本文件
│ └── diagrams/ # .mmd 流程圖（共 8 個）
│ ├── system-architecture.mmd
│ ├── document-import-flow.mmd
│ ├── rag-chat-flow.mmd
│ ├── mcp-tool-call-flow.mmd
│ ├── knowledge-sync-flow.mmd
│ ├── log-analysis-flow.mmd
│ ├── db-schema-er.mmd
│ └── development-gantt.mmd
├── gateway/ # FastAPI API Gateway
│ ├── main.py
│ └── routers/
│ ├── chat.py
│ ├── tool_call.py
│ ├── knowledge.py
│ └── sync.py
├── mcp-servers/
│ ├── knowledge/
│ ├── cad/
│ │ ├── adapters/
│ │ │ ├── base.py # ICADAdapter 抽象類別
│ │ │ ├── autocad.py # Phase 1
│ │ │ ├── solidworks.py # Phase 1
│ │ │ ├── catia.py # Phase 2
│ │ │ └── nx.py # Phase 2
│ │ └── server.py
│ ├── pmi/
│ ├── measurement/
│ └── log/
├── sync-service/
│ ├── server.py # 中央同步服務端
│ └── client.py # 邊緣節點同步客戶端
└── deploy/
├── install-server.ps1
├── install-workstation.ps1
├── install-production.ps1
└── config-templates/
├── workstation-config.yaml
├── optics-config.yaml
└── production-config.yaml
```
---
> **文件狀態**：本文件為可執行的系統架構設計書，§3（模組規格詳細技術參數）與 §5（API 規格）的技術細節待 Phase 0 PoC 驗收後依實際結果更新。
*最後更新：2026-03-02（v4.0：以 v2.0 模組化架構為骨架，統一採用 v3.1 技術棧；簡化複雜度，移除 Docker / Semantic Kernel / Redis 依賴）*
Comments...
No Comments Yet...