目的

 

本文件為針對部署於離線繪圖筆電（獨立顯卡、約 8GB 記憶體）之 AI Agent 系統分析（SA），目標環境為機構設計研發人員使用的工作站。系統需兼顧：線下運作、不使用 Docker 打包、能在同時運行 CAD 等資源密集型應用下穩定工作；並強調維護性、可擴展性、資安與可自建部署能力。

 

會議決議摘要（整合 `meeting_record.txt`）

 

- 優先模型 inference：首選 `llama.cpp`（輕量、可直接在離線環境執行、僅需 API 功能）；次選 `Foundry Local`；需調查 `LM Studio CLI` 的可行性；`Ollama` 為備援（但會同時提供較多包裝功能，若只需 API 則不優先）。

- 評估範圍：需對 `llama.cpp`、`Foundry Local`、`LM Studio CLI`、`Ollama` 進行功能/效能/更新頻率/API 支援/維護風險比較。

- 上下文處理：注意某些 inference（例如 Ollama）在超過上下文限制時會回傳不穩定或奇怪錯誤；需在系統層級實作上下文管理（chunking、summarization、sliding window、condense+retrieve 等策略）。

- RAG 精準度：傳統單次檢索的 RAG 可能不夠精確，需評估現代方法（multi-round retrieval、reranking、answer verification、langextract 等）並在設計中留白以便整合實驗性方法。

- 架構分工：明確區分 `client`（繪圖筆電）與 `remote`（整合部 host）的責任分配，並評估 client 端資源占用（UI、agent client、本地 cache sqlite、local skills/mcp 工具、可能的小型本地推理）。

 

設計原則與約束（補充）

 

- inference 優先順序：`llama.cpp` > `Foundry Local` > `LM Studio CLI`（需確認）> `Ollama`（備援）。

- 評估指標：API 完整性、離線可用性、資源需求、上下文長度處理行為、更新頻率與社群活躍度、授權/商業化風險。

 

設計原則與約束

 

- 離線運行：系統可在無外網連線之環境下提供核心能力（推理、檢索、向量相似搜尋、文件匯入/處理）。

- 無 Docker：不以容器為部署單位（直接在 host 建置服務或以系統服務/虛擬環境包裝）。

- 最低資源假設：繪圖筆電約 8GB RAM、獨立 GPU（推理能力有限），後端 host 為機構設計整合部之伺服器。

- 資料存放：關聯式資料庫使用 PostgreSQL，向量資料使用 pgvector 擴充。

- 可複製部署：任何擁有本文件的人，應能依步驟在相同或相似環境自行架設系統。

 

需求概要

 

- 支援批次匯入文件（包含含文字與圖片之 PDF）。

- 支援多模態資料（圖片）。

- 提供 RESTful API 供前端或其他系統呼叫（研發人員可自行包裝前端給最終使用者）。

- RAG（Retrieval-Augmented Generation）對話流程，並能選擇/串接 MCP 工具與 Skills。

- 開源 AI 平台/模型選型須考量長期維護風險與商業化改變的影響。

 

技術選型建議（摘要與理由）

 

- 本地模型管理 / 推理平台：優先考慮 Ollama/Foundry Local、LLaMA.cpp（輕量推理）、vLLM（若有伺服器可用較高效能）。選型依據：是否支援離線、硬體相容性、社群活躍度與 API 支援。避免依賴易封閉或高度商業化的服務。

- 開源模型：考慮 Gemma3、Qwen 系列（視授權與可本地化狀況），如需極度輕量可考量 quantized LLaMA 類模型（搭配 LLaMA.cpp）。選型重點：許可證、量化與效能、社群活躍度、後續維護性。

- Agent 框架：LangChain / AutoGen / Dify / Coze 等均可評估，但以有穩定 Python API、易於擴充 MCP/Skill 插件的框架為主。若需圖形化流程編輯，可額外評估 Langflow、Dify 但注意版本/商業化風險。

- 向量 DB：採用 PostgreSQL + pgvector（已列為約束），優點為整合既有關聯資料與向量索引、易於維運與備份。

- 文件解析與多模態處理：PDF 使用 PyMuPDF / pdfminer 結合 OCR（Tesseract）處理掃描文字；圖片特徵抽取使用 CLIP 類 embedder 或模型內建視覺 encoder。

 

安全性與維護考量

 

- 網路與存取：後端主機位於整合部網段，採內部網路隔離、僅開放必要 API 端點；採用 TLS（內部 CA 或機構憑證）與 API token 驗證。

- 權限管理：文件上傳/查詢需有使用者認證，支援最少權限原則。

- 資料保護：重要資料庫備份與排程、磁碟層級或欄位加密（視需求）。

- 相依風險管理：列出不同元件可能的終止維護風險（例如某商業化 GUI 工具），並提供替代方案與降級路徑。

 

系統架構概要

 

- 使用者端（繪圖筆電）

  - 前端：輕量桌面 UI 或命令列工具，呼叫 RESTful API。

  - 本地 agent client：負責連線管理、臨時快取與小型本地推理（若筆電資源允許）。

  - 本地資源評估：

    - UI：單一桌面 icon 啟動頁面（Electron 或本地 Web UI）。

    - 本地快取：SQLite 作為本地 cache（對話短期緩存、技能快取）。

    - 本地 skills / MCP：可攜帶的 script 或小型程式，用以離線處理不需 remote 資源的任務。

    - 本地推理（可選）：若需要在 client 上執行少量推理，使用 quantized LLM 或 LLaMA.cpp 的輕量 inference 並限制記憶體使用。

- 後端（整合部 host）

  - API 層：RESTful API，負責認證、路由請求至檢索 / 推理 / 文件匯入服務。

  - 檢索層：PostgreSQL + pgvector（向量索引 / metadata）。

  - 推理層：本地模型服務（Ollama/Foundry/vLLM/LLaMA.cpp），負責生成回應與多模態 embed。

  - 文件處理 / 向量化：文件上傳後的解析 -> 清理 -> chunk -> embed -> 存入 pgvector。

  - MCP / Skills：一組可插拔工具（外部命令、內部服務、查詢函式），RAG 流程時會依策略選擇。

 

KM 系統 與 文件來源

 

- KM 系統代表已建立的文件存放系統，文件匯入程序需能從 KM 系統拉取（或由 KM 匯出檔案）並進行批次向量化匯入至 `pgvector`。

 

API 範例（最小集）

 

- POST /api/upload-batch : 批次上傳文件（multipart 或 ZIP），回傳處理任務 ID。

- GET /api/upload-status/{task_id} : 查詢匯入進度與錯誤。

- POST /api/query : 傳入 user prompt，回傳 RAG 回應（包含召回來源）。

- GET /api/doc/{id} : 下載已上傳的原始文件或其 metadata。

 

文件匯入與向量化流程

 

1. 上傳：使用 POST /api/upload-batch；支援 PDF、圖片、ZIP。

2. 前處理：

   - 若為 PDF：以 PyMuPDF 或 pdfminer 擷取文字與圖像區塊；若為掃描 PDF 則以 Tesseract OCR。

   - 圖片：標準化尺寸、必要時進行 OCR。

3. 切片（chunking）：依語意/段落或固定長度切片，為每片生成 metadata（來源、位置、頁碼）。

4. Embedding：對文字使用語言 embedder（或模型內嵌 encoder）；對圖像使用視覺 embedder（CLIP 或多模態模型），視需求可合併文本與圖像 embedding。

5. 存儲：將向量與 metadata 寫入 PostgreSQL + pgvector。

 

補充：上下文與 chunking 策略

 

- chunking：以語意/段落為主，並記錄來源 metadata（檔案、頁碼、段落索引）。

- context window 管理：當輸入或召回資料總 token 數超過 LLM inference 的限制時，依序使用：

  1) 篩選 / rerank：以相似度與可信度降序取 top-k。

  2) 精簡（condense）：使用 summarizer 將多個檢索片段合併為短摘要以降低 token 數。

  3) multi-round retrieval：在生成階段支援多輪檢索（先檢索、生成草稿、再檢索補強）。

  4) 若 inference 回傳異常（如 Ollama 在超限時行為）：以本系統的錯誤回退策略處理（重試、減少 context 或降級至 server-side summarizer）。

 

RAG 精準度提升建議

 

- reranking：使用跨編碼器（cross-encoder）或相對 heuristics 對初步召回結果 rerank。

- multi-hop / multi-round：對複雜查詢進行分段檢索與逐步構建答案。

- answer verification：在生成後以檢索的片段驗證答案，並標註置信度與來源。若置信度不足，標示為不確定並提示人工審核。

- 評估 langextract：將其列為準實驗項目，與 reranking/comprehension pipeline 做 A/B 測試。

 

RAG 對話流程（含 MCP 工具選用條件）

 

1. 接收 Query（含上下文、檔案參照、使用者偏好）。

2. 檢索階段：以向量搜尋近期相關片段，並以規則篩選（recency、可靠度、來源類別）。

3. MCP/Skill 選用：若問題屬於明確可由 Skill 解決的類型（例如：檔案轉換、CAD 指令呼叫、資料庫查詢），則優先呼叫該 Skill；條件包含：高信心水平、操作型任務、需外部系統互動。

4. 合成階段：將檢索到的片段與 Skill 輸出供 LLM 生成最終答案（若為多模態問題，同時供給視覺片段的 embedding）。

5. 回傳：API 將 result、所用來源與置信度回傳給使用者端；同時紀錄對話歷程與審計紀錄。

 

開發計畫（里程碑）

 

- M1（第 0–2 週）：環境準備與最小可行系統（MVP）規格

  - 建置 PostgreSQL + pgvector，建置基本 API skeleton。

  - 評估並安裝一個本地推理選項（首選 `llama.cpp`，備選 `Foundry Local`），進行基礎 API 互通測試。

- M2（第 3–6 週）：文件匯入與向量化 pipeline

  - 實作 PDF 解析、OCR 與 chunking，完成文字到向量的 pipeline。

  - 實作批次上傳 API 與任務狀態查詢。

- M3（第 7–10 週）：RAG 與基本對話 API

  - 實作檢索、prompt 組裝、RAG 回應路徑，加入基礎 MCP/Skill 呼叫框架。

  - 同時完成 RAG 精準度基準測試（包括 reranking / multi-round 的基礎實驗）。

- M4（第 11–14 週）：多模態支援與前端整合

  - 圖片/視覺 embedding 支援，前端示範頁面或 CLI 測試工具。

- M5（第 15–18 週）：安全性強化、備份、文件化與部署手冊

  - 實作認證、TLS、備份策略，完成可複製部署步驟與 .mmd 圖檔。

 

額外里程碑：模型 inference 評估（並行於 M1–M3）

 

- E1（第 0–4 週）：對 `llama.cpp`、`Foundry Local`、`LM Studio CLI`、`Ollama` 做功能矩陣比較：API 支援、離線能力、上下文限制行為、記憶體/CPU/GPU 使用、更新頻率、社群活躍度、授權風險。

- E2（第 4–6 週）：在測試資料集上做效能與穩定性測試（含超過上下文長度的邊界測試），記錄錯誤模式與回退策略。

 

驗收準則（每里程碑）

 

- 可在離線環境下，從上傳到檢索到回應完整走通一次。

- 批次匯入 100 篇文件至少完成 90% 處理成功率（測試樣本）。

- RAG 回答能回傳來源 metadata 且在測試用例中通過功能驗收。

 

可替代/降級策略（以降低單一技術風險）

 

- 推理層：若 Ollama 無法更新或授權改變，降級至 LLaMA.cpp 或其他可離線執行的 quantized inference。

- Agent 框架：若 LangFlow/Dify 商業化影響，回退到以 LangChain（純程式化）為主的實作。

 

交付物（包含 .mmd）

 

- 文件：重寫後之 SA 文件（本檔）。

- Mermaid 檔案（可由 Mermaid 轉圖）：

  - use_case.mmd（Use Case 圖）

  - uml_class.mmd（UML Class）

  - database_schema.mmd（Database Schema）

  - sequence_rag.mmd（RAG 對話 Sequence）

  - sequence_upload.mmd（文件上傳/向量化 Sequence）

 

下一步建議（快速清單）

 

- 立刻開始 `llama.cpp` 與 `Foundry Local` 的最小實作測試，並執行上下文邊界測試（包括刻意超出 inference 的 context 限制以觀察行為）。

- 決定 `LM Studio CLI` 是否可納入生產路線（取決於離線支援與 API 能力）。

- 建立範例 `.mmd` 文件並驗證可用於 Mermaid 轉圖。

 

後續建議

 

- 在初期實作階段鎖定一套「可量化的最小模型與平台」，完成 MVP 後再評估更換更大型模型或推理平台的成本。記錄所有外部套件版本與授權細節，確保未來能以替代實作降低風險。

 

附註

 

- 參考技術分析來源（代表需考量的面向）：各篇技術比較文章與社群討論（已由需求端提供），實際選型應以機構的法規、授權需求與硬體資源為最終決策依據。