# Text to SQL 功能

## **什麼是 Text to SQL？**

**Text to SQL**（又稱為 Text2SQL），是一個能將**自然語言問題**（人類的日常用語）自動轉換成 **SQL 資料庫查詢語句**的智慧工具。簡單來說，就是讓 AI 助理能夠「<mark style="color:blue;">聽懂人話</mark>」並直接操作資料庫。

{% hint style="info" %}
欲了解更多 Text2SQL 內容，請見：[技術人員手冊—Text to SQL](https://docs.maiagent.ai/tech/advanced-genai-tech/text-to-sql)
{% endhint %}

想像你是便利商店老闆：

**傳統方式：**

* 你：「幫我查一下昨天賣了多少瓶可樂」
* 員工：「老闆，你要教我怎麼用收銀系統查詢...」
* 你：「點這裡、選那裡、輸入條件...」

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

**有了 Text2SQL：**

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

### **Text to SQL 的核心功能**

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

當你問 AI 助理「找出昨天賣最好的飲料」，AI 助理會先分析你的問題，知道你要找「飲料」而且是「昨天」賣「最好」的，然後生成 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 功能

{% hint style="info" %}
使用前，您需要準備：企業關聯資料庫或 Excel 檔案(上傳至知識庫中)

若使用資料庫，建議您：

* 確保資料表結構清晰
* 建立適當的索引
* 維護資料品質
  {% endhint %}

### 1. 進入 AI 助理設定

* 選擇要設定的 AI 助理
* 切換至回答模式設定頁面

<div><figure><img src="https://1593648278-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2Fmzb5NG9GDzFP2YDKeYVl%2Fuploads%2Fgit-blob-f6c760fd5b0407a4d9558fe7fb10ff8a8bbb52d3%2F%E6%96%B0%E5%A2%9E%E7%B5%84%E7%B9%94%E6%88%90%E5%93%A1%20(7)%20(1).png?alt=media" alt=""><figcaption></figcaption></figure> <figure><img src="https://1593648278-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2Fmzb5NG9GDzFP2YDKeYVl%2Fuploads%2Fgit-blob-e2c3e73ffd40e5dd7828c6105331218414fc711b%2F%E6%96%B0%E5%A2%9E%E7%B5%84%E7%B9%94%E6%88%90%E5%93%A1%20(8)%20(1).png?alt=media" alt=""><figcaption></figcaption></figure></div>

### 2. 切換 AI 助理的回答模式至 Agent 模式

{% hint style="warning" %}
請務必切換至 Agent 模式，否則 AI 助理無法使用 Text to SQL 功能

每個回答模式的詳細介紹請參考：[建立 AI 助理](https://github.com/Playma-Co-Ltd/maiagent-user-guide-gitbook/blob/main/build/setup.md#xuan-ze-shi-he-de-hui-da-mo-shi-jian-li-zhi-ling)
{% endhint %}

<figure><img src="https://1593648278-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2Fmzb5NG9GDzFP2YDKeYVl%2Fuploads%2Fgit-blob-d86be7a233d62daf3cc9b13bda053a170853f093%2F%E6%96%B0%E5%A2%9E%E7%B5%84%E7%B9%94%E6%88%90%E5%93%A1%20(9)%20(1).png?alt=media" alt=""><figcaption></figcaption></figure>

### 3. 輸入企業內資料庫 URL

* 使用下拉選單選擇企業內使用的資料庫服務
* 輸入企業使用的資料庫服務 URL，以讓 MaiAgent 系統連接至資料庫內操作

{% hint style="info" %}

* MaiAgent 支援：
  * **MySQL**
  * **PostgreSQL**
  * **Oracle DB**
  * **Microsoft SQL Server (MSSQL)**
* maiagent 選項為套用 MaiAgent 知識庫中您已上傳的 Excel 檔案
  {% endhint %}

<div><figure><img src="https://1593648278-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2Fmzb5NG9GDzFP2YDKeYVl%2Fuploads%2Fgit-blob-b0015159b307dd351f17f57889ed0079cccddc52%2F%E6%96%B0%E5%A2%9E%E7%B5%84%E7%B9%94%E6%88%90%E5%93%A1%20(10).png?alt=media" alt=""><figcaption></figcaption></figure> <figure><img src="https://1593648278-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2Fmzb5NG9GDzFP2YDKeYVl%2Fuploads%2Fgit-blob-b42d84db3b492000661ccc098bf24d74a9397dd3%2F%E6%96%B0%E5%A2%9E%E7%B5%84%E7%B9%94%E6%88%90%E5%93%A1%20(11).png?alt=media" alt=""><figcaption></figcaption></figure></div>

{% hint style="danger" %}
請務必確認 URL 格式正確，並包含必要的連線資訊，例如：主機名稱、連接埠、資料庫名稱、使用者名稱和密碼。
{% endhint %}

#### MaiAgent

{% hint style="info" %}
請參考：[使用 MaiAgent 知識庫進行 Text to SQL](https://docs.maiagent.ai/database/text-to-sql-maiagent)
{% endhint %}

#### Microsoft SQL Server(MSSSQL)

連接已有的 MSSSQL 資料庫，貼上 MSSSQL 資料庫連線字串

📍請注意：需要確保資料庫 URL 是可以被 MaiAgent 服務訪問

<figure><img src="https://1593648278-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2Fmzb5NG9GDzFP2YDKeYVl%2Fuploads%2Fgit-blob-47fe3ba711365d2ddc28d0f587773a83cd4ef468%2Fimage.png?alt=media" alt=""><figcaption></figcaption></figure>

#### **MySQL**

連接已有的 MySQL 資料庫，貼上 MySQL 資料庫連線字串

📍請注意：需要確保資料庫 URL 是可以被 MaiAgent 服務訪問

<figure><img src="https://1593648278-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2Fmzb5NG9GDzFP2YDKeYVl%2Fuploads%2Fgit-blob-329cb7cb01073ddcec1099240d5f9a0baca095d0%2F%E6%88%AA%E5%9C%96%202025-04-25%20%E4%B8%8A%E5%8D%8810.45.19.png?alt=media" alt=""><figcaption></figcaption></figure>

#### **Oracle**

連接已有的 Oracle 資料庫，貼上 Oracle 資料庫連線字串

📍請注意：需要確保資料庫 URL 是可以被 MaiAgent 服務訪問

<figure><img src="https://1593648278-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2Fmzb5NG9GDzFP2YDKeYVl%2Fuploads%2Fgit-blob-0687b5b3b4e4fa616b4d1fb237030ed59fa813c3%2Fimage%20(214).png?alt=media" alt=""><figcaption></figcaption></figure>

#### **PostgreSQL**

連接已有的 PostgreSQL 資料庫，貼上 PostgreSQL 資料庫連線字串

📍請注意：需要確保資料庫 URL 是可以被 MaiAgent 服務訪問

<figure><img src="https://1593648278-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2Fmzb5NG9GDzFP2YDKeYVl%2Fuploads%2Fgit-blob-24cd0b16c511cfaa75fb8bea648f8f8617f37110%2F%E6%88%AA%E5%9C%96%202025-04-25%20%E4%B8%8A%E5%8D%8810.45.57.png?alt=media" alt=""><figcaption></figcaption></figure>

### **4. 按下儲存，保存設定**

<figure><img src="https://1593648278-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2Fmzb5NG9GDzFP2YDKeYVl%2Fuploads%2Fgit-blob-e2402a782e0f1bed5bf2792cb43c6bc98f82175d%2F%E6%96%B0%E5%A2%9E%E7%B5%84%E7%B9%94%E6%88%90%E5%93%A1%20(12).png?alt=media" alt=""><figcaption></figcaption></figure>

如此一來，AI 助理就能協助您快速查詢您的庫存、員工資訊等，並彙整出井然有序的報告及趨勢給您。

## **常見問題排除**

* **連線失敗**：檢查資料庫 URL 格式和網路連通性
* **查詢錯誤**：確認表名和欄位名稱正確
* **權限不足**：檢查資料庫使用者權限設定
* **回應慢**：檢查查詢複雜度，考慮加入索引

***

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