自我LV1

1. 系統畫面

1. 系統流程圖

1. 系統概述

本系統是一套專為企業內部銷售數據表（[dbo].[ZSALEDAILYS]）設計的Text-to-SQL（自然語言轉 SQL）實時直連數據分析系統。

傳統大型語言模型（LLM）在處理數據分析時，常因「計算與邏輯能力不足」而產生數據幻覺（數據編造、統計錯誤）。本系統採用「AI 負責語法轉譯，實體資料庫負責真實運算」的雙引擎架構。系統直接與企業內部的 Microsoft SQL Server 2008 直連，將 AI 生成的 T-SQL 語法派發至實體資料庫執行，確保前端呈現的報表數據達到 100% 的商業嚴謹度與精確度。

二、 系統架構設計

本系統摒棄了將大批量數據預載至本地記憶體的傳統做法，演進為「即時編譯、輕量傳輸、直連執行」的現代化架構。

1. 系統模塊組件

• 前端交互與執行核心 (mcp_client_local_data_gemma4.py)：基於 Streamlit 框架構建。負責使用者 UI 交互、歷史紀錄管理、呼叫 Ollama（Llama 3.2）進行 Text-to-SQL 語法轉譯，並透過 SQLAlchemy 驅動直接與實體資料庫進行通訊與資料渲染。
• 資料供應與排程接口 (mcp_server_local_data_gemma4.py)：基於 SQLAlchemy 框架構建。提供底層資料連線池（Engine）的底層配置，內建高精度數據序列化機制，可作為獨立的 MCP（Model Context Protocol）後端服務接口。

2. 雙伺服器容災與穩定機制

為確保企業內部運作的超高可用性，Ollama API 呼叫採用雙路由備選機制：

• 主線路由：http://192.168.1.197:11434（遠端 GPU 伺服器，提供高效能推理）
• 備援路由：http://localhost:11434（本地端伺服器，當主線網路中斷時自動接管）
• 連線保護：網路請求內建 HTTPAdapter 與 Retry 機制（Max Retries = 2），全面防範區域網路抖動或模型超時（30秒）所引發的連線崩潰。

三、 核心運作流程

系統的數據轉譯與實時檢索流程共分為以下 4 大步驟：

步驟	階段名稱	技術機制與處理邏輯
1	自然語言輸入與過濾	使用者於 Streamlit 前端輸入中文查詢需求（例如：「2025年銷售金額最高的前3名品名」），系統透過 is_sales_related_query 函數進行關鍵字安全審查，通過後放行。
2	自然語言轉譯 (Text-to-SQL)	系統將需求與靜態定義的欄位清單（AVAILABLE_FIELDS）打包送至 Llama 3.2 模型。此時模型的 temperature 鎖死為 0.0，強迫 AI 嚴格執行高壓 Prompt 約束，僅輸出包裹在 [SQL_START] 與 [SQL_END] 之間的標準 T-SQL。
3	語法解析與擷取	網頁後台利用正則表達式（Regex）r'\[SQL_START\](.*?)\[SQL_END\]' 進行精確匹配，將獨立的 T-SQL 語法抽離，並以 st.code() 在前端建立獨立的語法複製區塊，方便系統管理員審查。
4	實體資料庫直連執行	系統讀取本地 .env 檔案中的安全認證環境變數，動態建立 mssql+pyodbc 的連線，透過 pd.read_sql_query 將 T-SQL 直接派發至 Microsoft SQL Server 2008 進行後端運算（如 GROUP BY、SUM、TOP 1）。資料庫在雲端/後端完成篩選排序後，僅回傳輕量化的結果集 DataFrame，由 Streamlit 渲染出 100% 精確的 Markdown 表格。

四、 核心轉譯規範（Prompt 工程防禦）

為了防止 AI 在生成語法時發生偏移或胡言亂語，系統在 generate_sql_only 中對 AI 施加了以下五大硬性行為約束：

1. 結構絕對隔離：SQL 語法必須且只能精確地包裹在 [SQL_START] 與 [SQL_END] 標籤之間。
2. 語義徹底剝奪：嚴禁模型生成任何 SQL 以外的解釋性文字、數據摘要、分析、問候語或結論，徹底杜絕文字幻覺。
3. 命名標準化：所有的中文欄位與表名必須加上標準的單個中括號（例如 [品名], [TK].[dbo].[ZSALEDAILYS]），嚴禁使用雙重中括號 [[...]]。
4. 版本鎖定 (SQL 2008)：明確限定排行必須使用 TOP N 語法，且限制其必須緊跟在最外層的 SELECT 後方。同時嚴禁使用 SQL 2012+ 以上才支援的 FORMAT 等高階函數。
5. 記憶隔離：不引入先前的對話記憶上下文（每次發送乾淨的 Prompt），每一次查詢均視為完全獨立的全新轉譯任務，防止上下文干擾。

五、 各模組原始碼說明

📄 1. 資料底層供應層 (mcp_server_local_data_gemma4.py)

主要功能為負責基礎連線配置，並提供 query_sales_data_local 與 get_all_sales_data 兩個對外接口。利用 json.dumps 搭配自訂的 lambda 函數，完美解決了微軟資料庫特有的 Decimal（高精度小數）型態在 Python 原生 JSON 序列化時會崩潰的硬傷。

📄 2. AI 前端執行核心 (mcp_client_local_data_gemma4.py)

整合了 UI 介面、Ollama 雙路由請求、正則表達式攔截器以及 execute_sql_mssql 直連引擎。當 AI 產出正確的 T-SQL 後，此模組會直接接管資料庫安全握手，並將最終結果透過 st.dataframe(use_container_width=True) 完美呈現在網頁右側面板。

六、 系統優勢與技術價值

• 記憶體零開銷：網頁端不需要在記憶體中維護龐大的資料集，不論生產環境的 [ZSALEDAILYS] 累積了幾百萬筆資料，前端網頁皆能秒級開啟。
• 語法原汁原味：因為直接在實體微軟 SQL Server 2008 上執行，AI 生成的 TOP N 等專屬語法能直接被完美支援，徹底解決了跨資料庫語法相容性的技術硬傷。
• 低風險與高安全性：前端對資料庫發動的均為唯讀（SELECT）的精準查詢，後端資料庫僅需運算及回傳過濾排序後的少量資料，有效保護老舊企業 ERP 資料庫免於因大數據傳輸而引發死鎖（Deadlock）或崩潰。
• 錯誤極易診斷：一旦 AI 寫錯語法，系統會直接捕捉 MSSQL 返回的實體錯誤（例如欄位不存在或語法錯誤），並引導使用者手動除錯，系統運維成本極低。

 

 

自我LV~