建立與設定資料庫

本篇將介紹如何在 MaiAgent 中建立與設定資料庫，包含上傳檔案建立資料表、連接外部資料庫、以及欄位描述設定

MaiAgent 的資料庫管理功能讓您可以在平台上集中管理 Agent 所使用的資料庫連線。搭配 Text to SQL 功能，Agent 就能透過自然語言直接查詢資料庫中的資料。

關於 Text to SQL 的概念介紹，請參考：Text to SQL 功能

MaiAgent 支援兩種資料庫類型：

• MaiAgent 資料庫：上傳 Excel / CSV / JSON 檔案，系統自動建立資料表。適合沒有自建資料庫的使用者

• 外部資料庫：連接既有的 PostgreSQL、MySQL、SQL Server（MSSQL）、Oracle 或 SynxDB 資料庫

網路前置（外部資料庫）

連接外部資料庫之前，請先和貴單位的 IT 或資料庫管理員確認以下事項。只使用 MaiAgent 資料庫（上傳試算表）時，不需要這些設定。

• 允許 MaiAgent 連入：連線由 MaiAgent 主動連到您的資料庫（按「測試連線」時與 Agent 每次查詢時），資料庫不需要主動連到 MaiAgent。

• 開放連接埠：預設為 PostgreSQL 5432、MySQL 3306、SQL Server 1433、Oracle 1521、SynxDB 5432（依部署設定）；改過埠號時，以「連線字串」中 主機位址:連接埠 的埠號為準。

• MaiAgent 雲端服務：資料庫有防火牆或安全群組時，把 MaiAgent 的對外 IP 加入白名單（請洽 MaiAgent 窗口索取），只開放上述連接埠。

• 地端／私有雲部署：確認 MaiAgent 主機與資料庫主機之間的網段與連接埠可以互通即可，資料庫不需要開放到網際網路。

• 使用唯讀帳號：為 MaiAgent 建立專用的唯讀帳號，只授予 Agent 需要的資料表；含個資等敏感欄位的資料表，可另建只含必要欄位的檢視表（View）再授權。「指定資料表」只縮小 Agent 參考的範圍，真正讀得到哪些資料，仍由這個帳號的權限決定。

平台如何擋下寫入語法、各資料庫的唯讀保護程度，以及網路需求的完整說明，見技術人員手冊 Text to SQL：唯讀保護 與 網路需求。

建立資料庫

1. 進入資料庫管理頁面

從左側導航欄進入「AI 功能」區塊，點擊「資料庫」。頁面分為兩個頁籤：MaiAgent 資料庫與外部資料庫。

點選右上角的「新增資料庫」按鈕開始建立。

資料庫管理頁面，顯示 MaiAgent 資料庫列表

若按鈕為灰色無法點擊，代表您的角色尚未被授予建立資料庫的權限。請聯繫組織管理員設定權限。

2. 選擇資料庫類型

選擇您要建立的資料庫類型，點擊對應的卡片後按「下一步」：

• MaiAgent 資料庫：適合上傳試算表檔案，不需要連線字串

• PostgreSQL / MySQL / SQL Server / Oracle / SynxDB：連接企業既有的外部資料庫

步驟一：選擇資料庫類型

3. 填寫基本資訊

MaiAgent 資料庫

欄位	必填	說明
資料庫名稱	是	例如「2024 年度銷售資料」
說明	否	補充說明資料庫的用途或內容

MaiAgent 資料庫不需要輸入連線字串，系統會自動處理資料儲存。建立完成後再上傳試算表檔案即可。

步驟二：MaiAgent 資料庫設定畫面

外部資料庫

欄位	必填	說明
資料庫名稱	是	例如「企業 ERP 資料庫」
說明	否	補充說明資料庫的用途或內容
連線字串	是	資料庫的連線 URL
指定資料表	否	限制 Agent 可查詢的資料表，以逗號分隔

連線字串格式如下（欄位下方也會顯示所選類型的格式）：

PostgreSQL:   postgresql://使用者名稱:密碼@主機位址:連接埠/資料庫名稱
MySQL:        mysql+pymysql://使用者名稱:密碼@主機位址:連接埠/資料庫名稱
SQL Server:   mssql+pyodbc://使用者名稱:密碼@主機位址:連接埠/資料庫名稱?driver=ODBC+Driver+18+for+SQL+Server&TrustServerCertificate=yes&Encrypt=no
Oracle:       oracle+oracledb://使用者名稱:密碼@主機位址:連接埠/?service_name=服務名稱
SynxDB:       postgresql://使用者名稱:密碼@主機位址:連接埠/資料庫名稱

請務必確認連線字串格式正確，並包含必要的連線資訊。開頭必須與上方格式一致，否則會顯示「連線字串格式不正確」而無法進入下一步。也請確認資料庫已允許 MaiAgent 連入，請參考 網路前置。

步驟二：外部資料庫（PostgreSQL）設定畫面

填寫連線字串後，建議點擊「測試連線」按鈕來驗證連線是否正常（也可以跳過測試直接儲存）：

• 連線成功：代表 MaiAgent 可以正常存取您的資料庫

• 連線失敗：請檢查連線字串格式、帳號密碼，以及防火牆、白名單與連接埠是否已依 網路前置 開放

若您的資料庫包含大量資料表，可以在「指定資料表」欄位中輸入要開放的資料表名稱（例如 customers, orders, products），以提升查詢效率及安全性。留空表示查詢所有資料表。

4. 設定角色權限

最後一步是設定哪些角色可以存取這個資料庫。在「快速選擇權限範圍」中選擇其一：

• 全部角色：允許組織內所有角色的成員使用此資料庫

• 排除預設角色：僅允許自訂角色使用，排除預設角色

• 自訂選擇角色：手動選擇特定角色，將需要授權的角色從「可選角色」移至「已選角色」

步驟三：快速選擇權限範圍

若暫時不需要設定角色權限，可以直接跳過此步驟，之後再從資料庫設定頁面的「角色權限」頁籤進行調整。

5. 完成建立

確認所有設定後，點擊「建立資料庫」（MaiAgent 資料庫）或「儲存」（外部資料庫）按鈕。建立成功後會進入資料庫設定頁面，可以進行後續操作。

新建立的資料庫預設為停用狀態。請在「基本資訊」頁籤開啟「啟用資料庫」並儲存，或在資料庫列表中切換「啟用」開關，Agent 才會在 Text to SQL 查詢中使用此資料庫。

建立完成後，別忘了將資料庫關聯至 Agent，Agent 才能使用這個資料庫進行查詢。請參考：關聯 Agent 與群組權限

上傳檔案建立資料表（MaiAgent 資料庫）

建立 MaiAgent 資料庫後，進入設定頁面切換至「表格管理」頁籤，點擊「上傳表格檔案」按鈕，選擇檔案或拖曳至上傳區後點擊「上傳」。

表格管理頁籤，資料表依來源檔案分組顯示

支援的檔案格式

格式	副檔名	說明
Excel	.xlsx、.xls	每個工作表（Sheet）會各自建立一張資料表
CSV	.csv	逗號分隔值檔案
JSON	.json、.jsonl	JSON 格式資料檔案

上傳後，系統會在背景自動解析檔案結構並建立資料表。資料表會依來源檔案分組列出，並顯示處理狀態：

狀態	說明
待處理	檔案已上傳，等待系統處理
處理中	系統正在解析檔案並建立資料表
成功	資料表建立完成，Agent 可以查詢
失敗	建立過程發生錯誤，可將滑鼠移至錯誤圖示查看原因
刪除中	正在背景移除資料表
刪除失敗	移除未完成，可再刪一次

來源檔案名稱下方標示 「來自知識庫」 的資料表，不是在這裡上傳的，而是知識庫上傳結構化檔案時改用資料庫同步過來的；同一份檔案在知識庫與資料庫各有一份，刪除其中一邊不會影響另一邊。

資料表名稱與重複上傳

• 資料表名稱由系統產生：table_<檔名>_<10 碼雜湊>。檔名取上傳檔案的名稱去掉副檔名、只保留中英文、數字與底線，最長 45 個字元；雜湊由這次上傳的檔案 ID 與工作表名稱算出。例如上傳 2024 銷售.xlsx 的「Q1」工作表，會得到 table_2024銷售_ 加 10 碼雜湊的名稱。Agent 查詢時看的是這個名稱，建議在 表格描述 寫明它是哪份檔案的哪個工作表。

• Excel 的每個工作表各建一張資料表，建立成功的資料表會自動加入資料庫的 指定資料表。

• 再次上傳同名檔案不會覆蓋：每次上傳都是新的檔案 ID，雜湊不同，所以會建立另一組資料表，舊的資料表與欄位描述原樣保留，Agent 會同時看到兩組。要更新資料，請先在 表格管理 刪除舊資料表（或整個來源檔案），再上傳新檔；刪除後欄位描述不會保留，請先記下。

• 從知識庫同步過來的資料表（標示 來自知識庫）命名規則相同，刪除時兩邊互不影響。

檔案格式注意事項

• 第一列（Row）必須為欄位名稱

• 每個欄位的資料型態應保持一致（例如：價格欄位都是數字）

• 避免合併儲存格

• 避免重複的欄位名稱

• Excel 檔案中，每個工作表（Sheet）只能包含一個表格

若資料表建立失敗，常見原因包括：檔案格式不正確或損毀、欄位名稱包含特殊字元、欄位名稱重複、同一欄位中的資料型態不一致。

編輯欄位描述

欄位描述是提升 Text to SQL 查詢準確度的關鍵設定。Agent 會參考欄位描述來理解資料的含義，從而產生更精確的 SQL 查詢。

例如，您的資料表有一個欄位叫 status，Agent 可能不知道它代表什麼。但如果加上描述「訂單狀態，可能的值為：pending（待處理）、completed（已完成）、cancelled（已取消）」，Agent 就能正確理解這個欄位的含義。

如何編輯

MaiAgent 資料庫：在「表格管理」頁籤中，點擊資料表操作欄的「編輯」圖示，開啟「編輯表格資訊」視窗，即可填寫「表格描述」與每個欄位的「欄位描述」，完成後點擊「儲存」。視窗中會顯示填寫進度（例如「已設定 3 / 10 個欄位」）。

編輯表格資訊：填寫表格描述與欄位描述

外部資料庫：在「基本資訊」頁籤下方的「資料表結構描述」區塊，點擊「新增表格」，填寫「表格名稱」與「欄位與用途說明」，完成後點擊「儲存」。

撰寫建議

好的欄位描述能顯著提升 AI 查詢的準確度：

欄位名稱	較差的描述	較好的描述
amt	金額	訂單總金額（新台幣），包含稅金和運費
cust_lvl	等級	客戶等級，A 級為年消費超過 100 萬的 VIP 客戶，B 級為年消費 10-100 萬，C 級為其他
reg	區域	客戶所在地理區域，可能的值為：北部、中部、南部、東部、離島

管理既有資料庫

編輯資料庫

在資料庫列表中，點擊操作欄的「編輯」圖示即可進入設定頁面。

資料庫設定頁面：基本資訊頁籤

設定頁面包含以下頁籤：

頁籤	說明	適用類型
基本資訊	編輯名稱、說明、啟用狀態；外部資料庫另可變更連線字串、指定資料表與資料表結構描述	全部
表格管理	上傳檔案、管理資料表與欄位描述	僅 MaiAgent
關聯 AI 助理	指定哪些 Agent 可以使用此資料庫	全部
角色權限	設定角色的存取權限	全部

基於安全考量，外部資料庫的連線字串會以遮罩顯示密碼。若要修改，點擊「變更」後輸入新的完整連線字串。

啟用 / 停用

在資料庫列表中，透過「啟用」開關可以快速切換狀態。停用後 Agent 將暫時無法查詢此資料庫，但設定和資料會保留。

刪除資料庫

在資料庫列表的操作欄點 刪除，會開啟 「刪除資料庫」 確認視窗，顯示「確定要刪除「資料庫名稱」嗎？」。MaiAgent 資料庫的視窗另有 「刪除前請留意」 提醒：此資料庫的表格可能來自知識庫的檔案同步，希望完整清除時，建議也到知識庫檢查是否有需要一併刪除的檔案；刪除後此資料庫及其所有表格資料將無法恢復。外部資料庫則提示「刪除後，此資料庫連線設定將無法恢復」。按 確認刪除 後執行。

刪除資料庫是不可逆的操作。

• MaiAgent 資料庫：刪除後，所有透過上傳檔案建立的資料表都會被一併移除；從知識庫同步來的資料表，其知識庫端的檔案仍會保留

• 外部資料庫：僅移除 MaiAgent 中的連線設定，不會影響原始資料庫中的資料