Text to SQL 功能

本篇將介紹如何在 MaiAgent 系統中使用 Text to SQL 功能，協助您使用日常對話輕鬆查詢資料庫內資訊

什麼是 Text to SQL？

Text to SQL（又稱為 Text2SQL），是一個能將自然語言問題（人類的日常用語）自動轉換成 SQL 資料庫查詢語句的智慧工具。簡單來說，就是讓 Agent 能夠「聽懂人話」並直接操作資料庫。

欲了解更多 Text2SQL 內容，請見：技術人員手冊—Text to SQL

想像你是便利商店老闆：

傳統方式：

• 你：「幫我查一下昨天賣了多少瓶可樂」

• 員工：「老闆，你要教我怎麼用收銀系統查詢...」

• 你：「點這裡、選那裡、輸入條件...」

需要手把手教學，較耗費時間。

有了 Text2SQL：

• 你：「幫我查一下昨天賣了多少瓶可樂」

• AI 員工：「好的！」💫 (自動產出查詢方法並調用資料庫) → 「昨天賣了87瓶可樂」✅

Text to SQL 的核心功能

自然語言問題 → AI 理解分析 → SQL 查詢語句 → 執行查詢 → 回傳結果

當你問 Agent「找出昨天賣最好的飲料」，Agent 會先分析你的問題，知道你要找「飲料」而且是「昨天」賣「最好」的，然後生成 SQL 語法去資料庫查詢，最後把結果「可樂」告訴你。

Text to SQL 可以協助 AI 做到的事情

具體應用場景

🏥 醫療診所

醫生問：「找出今天預約的糖尿病患者」
AI回答：「今天共有5位糖尿病患者預約：
- 王先生 10:00 回診
- 李太太 14:30 追蹤檢查
- 陳小姐 16:00 血糖監測」

🏫 學校管理

老師問：「這次考試有多少學生不及格？」
AI回答：「本次數學考試：
- 總人數：45人
- 不及格：8人（17.8%）
- 需要補考的學生名單已整理完成」

🏪 零售連鎖店

店經理問：「比較三間分店的月營收」
AI回答：「11月各分店營收比較：
- 台北店：$1,200,000 (↑15%)
- 台中店：$950,000 (↑8%)  
- 高雄店：$800,000 (↓3%)」

Text to SQL 的優勢

⚡ 效率提升

• 傳統方式：需要 SQL 專家寫查詢 → 30分鐘

• Text2SQL：自然語言提問 → 3秒鐘

🎯 降低門檻

• 不需要學習複雜的 SQL 語法

• 不需要記住資料庫結構

• 任何人都能查詢資料

📱 即時互動

• 問了就有答案

• 支援後續追問

• 動態調整查詢條件

如何在 MaiAgent 中使用 Text to SQL 功能

資料庫在左側選單的「AI 功能」→「資料庫」集中建立，一個資料庫可以給多個 Agent 使用，一個 Agent 也可以關聯多個資料庫。設定分成三步：

1. 建立並啟用資料庫

在「資料庫」頁點選「新增資料庫」，選擇資料庫類型：

• MaiAgent 資料庫：沒有自建資料庫時使用，上傳 Excel、CSV 或 JSON 檔案，系統自動建立資料表，不需要連線字串。見 MaiAgent 資料庫進行 Text to SQL。

• 外部資料庫：連接既有的 PostgreSQL、MySQL、SQL Server、Oracle 或 SynxDB，需要填寫連線字串，並先確認資料庫允許 MaiAgent 連入。

新建立的資料庫預設為停用，請開啟「啟用資料庫」後，Agent 才會查詢它。完整步驟、各資料庫的連線字串格式與網路檢查清單，見 建立與設定資料庫。

2. 將 Agent 切換為 Agent 模式

在 Agent 的 設定 點選左側導覽的「回答模式設定」，選擇 Agent 模式。

Text to SQL 只在 Agent 模式下可用。其他回答模式的 Agent，左側導覽的「資料庫設定」會鎖定，無法選擇資料庫。各回答模式的說明見 建立 Agent。

3. 關聯資料庫與 Agent

以下兩種方式擇一：

• 在 Agent 的 設定 點選左側導覽的「資料庫設定」，按「選擇資料庫」勾選要查詢的資料庫，再點選儲存。

• 在資料庫設定頁的「關聯 AI 助理」頁籤，把 Agent 移到右側後儲存，見 關聯 Agent 與群組權限。

設定完成後，就能在 Agent 的對話中用自然語言查詢資料，例如「上個月哪個產品銷售最多？」。

常見問題排除

• 連線失敗：檢查連線字串格式、帳號密碼，以及防火牆與白名單是否已開放，見 建立與設定資料庫：網路前置。

• Agent 沒有查資料庫：確認回答模式是 Agent 模式、資料庫已啟用，並已關聯到這個 Agent。

• Agent 只查資料庫、回覆說沒有知識庫檢索工具：Agent 模式下知識庫檢索也是一組工具（retrieve_text_nodes 等），開啟 啟用工具搜尋功能 時，這些工具和 Text to SQL 一樣要先被搜尋到才能呼叫，模型偶爾會跳過搜尋直接回答「沒有工具」。請在角色指令寫明「回答前先用 retrieve_text_nodes 查詢知識庫」，或關閉工具搜尋讓所有工具直接可用，見 為 Agent 配置工具；兩種模式的檢索差異見技術人員手冊 - 對話模式與 Agent 模式怎麼查知識庫。

• 想限制某些使用者只能查部分資料：查詢元資料只限制知識庫檢索，不會套用到 Text to SQL；資料庫的範圍只能用啟用／關聯 Agent、指定資料表 與角色權限控制，無法逐次請求限制。需要依使用者分流時，請為不同身分建立不同的 Agent 與資料庫連線（或唯讀帳號）。

• 查詢錯誤：確認表名和欄位名稱正確，並為資料表與欄位補上描述，見 編輯欄位描述。

• 權限不足：檢查資料庫帳號是否有這些資料表的讀取權限。

• 回應慢：檢查查詢複雜度，考慮加入索引，或用「指定資料表」縮小查詢範圍。

規格面的說明（唯讀保護、網路需求、大型 schema 的處理與查詢結果上限）見 技術人員手冊 - Text to SQL。

---

Text2SQL 讓 Agent 變成資料庫專家，任何人都能用自然語言快速獲取業務洞察，大幅提升數據驅動決策的效率！