知識庫總覽

知識庫總覽：知識庫是什麼、能做什麼（文件、FAQ、網頁內容的檢索問答），以及上傳檔案與建立知識庫的入口。

知識庫是什麼？

知識庫是 Agent 回答問題時的資料來源：Agent 會先從知識庫找出與問題最相關的片段，再依這些片段回答。請只上傳與 Agent 任務相關的內容，不相關的資料可能被當成參考依據，讓回答失準。檢索的運作原理見 技術人員手冊 - RAG 知識庫檢索系統。

知識庫可以做什麼？

藉由知識庫的以下功能，您可以：

📋 標籤管理文件

您可以為每個文件加入多個標籤，建立系統化的分類架構

• 範例：為「帳篷手冊」加上 #帳篷 #新手 #搭建教學 標籤

🔐 選擇性開放文件權限

您可以根據用戶身分設定不同的文件存取權限，實現差異化服務

• 範例：產品價格表僅在 VIP 會員對話中開放，成本資料僅在內部對話中開放

❓ 建立 FAQ

您可以將常見問題整理成標準問答集，確保回覆一致性、完整性

• 範例：「帳篷保固幾年？」→ 標準答案：「我們提供3年保固服務」

📊 傳入文件的 Metadata

您可以為文件加入版本、更新日期、適用範圍等詳細資訊，方便未來維護文件

• 範例：文件版本 v2.1、更新日期 2024/11/28、適用產品「山岳系列帳篷」

🔍 搜尋測試

您可以測試不同問題的檢索結果，驗證 AI 是否找到正確的資料片段（知識庫設定頁左側的選單名稱是 「AI 搜尋」，見 搜尋測試）

• 範例：輸入「帳篷搭建步驟」→ 檢查 AI 是否找到正確的搭建教學片段

知識庫設定頁的分頁

在知識庫列表點 「編輯」 進入設定頁後，左側選單依序是：

分頁	管什麼	詳細說明
基本	名稱、解析器、Embedding／Reranker 模型、檢索片段數等	如何建立知識庫：基本設置
文件	上傳、檢視、編輯文件與批次操作	本頁
FAQ 常見問題	問答對	如何建立 FAQ 常見問題
標籤管理、元資料管理	定義可用的標籤與元資料欄位	文件管理：標籤及元資料
AI 搜尋	用問題測試檢索結果，可加 AI 摘要	搜尋測試
API 串接	用程式上傳文件、搜尋這個知識庫的說明與範例，已代入知識庫 ID、所用的 Embedding／Reranker 模型與關聯的 Agent	開發者工具

如何上傳知識庫？

例如，出版社的知識庫管理員想讓 Agent 查找產品電子書的內容。他將 EPUB 電子書上傳到產品知識庫，等待處理完成後，就能像使用 PDF 或 Word 文件一樣，讓 Agent 從書中查找資料來回答問題。

1. 進入左側功能欄 「AI 功能」 → 「知識庫」

2. 找到要上傳的知識庫，在操作欄點選「編輯」（若尚未建立，請先參考 如何建立知識庫：基本設置）

3. 進入設定頁後，點選左側的「文件」

4. 在頁面右上方點選「上傳檔案」藍色按鈕，上傳您想讓 Agent 知道的資料

上傳視窗會列出 EPUB 與其他可使用的檔案格式

• 根據不同的方案會提供不同大小的知識庫容量

• 如果您的檔案較大或資料量較多，上傳後系統可能需要一些時間處理。

您可於 「處理狀態」 欄位中檢視處理進度。

文件列表的欄位與處理狀態

列表上方可輸入關鍵字搜尋名稱、ID、標籤或元資料（以空格分隔多個關鍵字），並用 「全部狀態」「全部檔案類型」 篩選。欄位包含檔案名稱、檔案類型、檔案大小、Chunks 數量、向量儲存空間、處理狀態、等待時間（檔案從上傳到開始處理的排隊時間）、處理時間、解析器、建立時間與來源。來源 欄顯示 「爬蟲」 標籤的文件來自爬蟲匯入，點標籤可直接跳到該次爬取請求（需有爬蟲權限）。

處理狀態	意思	可以做什麼
初始化	已上傳，排隊等待處理	等待即可；大量上傳時等待時間會拉長
處理中	正在解析、切片與向量化	等待；可按 重新整理 更新狀態
完成	Agent 已可檢索這份文件	點 編輯 檢視片段、標籤與元資料
失敗	解析或向量化失敗	將滑鼠移到狀態上可看 失敗原因 與 失敗時間；可在操作欄換一個解析器後按 重新解析，或刪除後重新上傳
刪除中	背景正在移除文件與向量	等待；批量刪除時這類文件會被略過
刪除失敗	移除未完成	再刪一次；持續失敗請洽 MaiAgent

目前知識庫支援的檔案類型：

• 試算表文件：.xls, .xlsx, .csv, .ods

• 文書處理文件：.doc, .docx, .odt, .pdf, .md, .txt

• 簡報文件：.ppt, .pptx, .odp

• 網頁文件：.html, .htm

• 資料格式：.json, .jsonl

• 電子書：.epub

• 音訊文件：.wav, .mp3, .m4a, .aac

• 視訊文件：.mp4

Outlook 的 .pst（信箱封存檔）與 .msg（單封郵件）無法上傳。要把郵件放進知識庫，請先在郵件軟體中另存為 .eml 或 PDF 再上傳。完整的副檔名清單見 技術人員手冊 - Parser 解析工具。

結構化檔案的列數上限

CSV、Excel、JSON、JSONL 這類表格型檔案，上傳視窗會先計算列數（顯示「計算列數中…」）。超過 1000 列的檔案會在清單上標示列數，按 上傳 時跳出 「檔案列數超過建議上限」 視窗，列出超過上限與無法讀取的檔案，並提供三個選擇：

按鈕	作用
改用資料庫	前往 資料庫 功能，把檔案上傳成可用 Text to SQL 查詢的資料表，見 建立與設定資料庫
移除問題檔案	把超過上限或無法讀取的檔案從這次上傳清單移除，只上傳其餘檔案
仍然上傳	照常上傳。檔案會被切成大量片段，整張表的統計、篩選類問題檢索效果較差

判斷方式：問的是「某一列的內容」（例如某個商品的規格）用知識庫沒問題；問的是「有幾筆」「哪些符合條件」「加總或排序」這類要掃整張表的問題，請改用資料庫。

表格檔在知識庫裡怎麼切、怎麼引用

用 MaiAgent Parser 解析 CSV、Excel（.xls、.xlsx、.ods）時：

• 每個工作表會轉成一張 Markdown 表格（CSV 整檔一張；一個檔案有多個工作表時，各表前面會加上工作表名稱作為標題），第一列作為表頭。

• 一個檔案最多讀取前 5,000 列，之後的列不會進入知識庫。

• 轉成的表格再依一般文件的切片規則切成片段，一列不是獨立的檢索單位：一個片段通常包含連續多列，表頭只出現在表格開頭的片段。檢索與引用都以片段為單位，引用來源會指向包含該列的片段，不會標出列號。

• 隱藏的列與工作表一樣會被讀取，不想交給 Agent 的資料請先刪除。

要讓每一列都能被單獨找到並引用，請把每列整理成一筆 FAQ（可用 Excel 批量匯入），或改用資料庫讓 Agent 以 SQL 查詢。

查看資料

資料片段說明

當資料上傳至知識庫時，資料會被分為片段，這麼做有以下好處：

• 提升檢索精確度：小片段更精確匹配查詢，避免無關內容干擾

• 優化回應速度：處理更快，減少計算資源消耗

• 增強內容相關性：每個片段聚焦單一主題，提高針對性

• 便於維護管理：易於更新、追蹤和品質控制

• 符合 AI 模型限制：避免超出輸入長度，確保資訊完整性

編輯、查看片段內容

您可以查看您的文件分段內容：

1. 進入知識庫的文件頁面，點按「編輯」

2. 查看分段內容，點擊要查看的片段

畫面會以 Markdown 格式顯示此片段的完整內容。文件詳情頁有兩種檢視可切換：

• Chunk 卡片：每個片段一張卡片，顯示字數與命中次數，點開可編輯片段內容。

• 整篇文件：把所有片段依原文順序拼回一整篇，右側軌道標出每個 chunk 的範圍；開啟 顯示 chunk 標記 後，奇數與偶數 chunk 以不同底色區分，琥珀色底的段落同時屬於相鄰兩個 chunk（即 overlap，只顯示一次），滑鼠移到軌道上會高亮該 chunk 的完整範圍。要檢查「一個句子有沒有被切在兩個片段中間」時用這個檢視最直覺。

編輯原始文件

1. 在編輯頁面點擊「檢視文件」

1. 進入編輯頁面，文字框中會顯示該文件的 Markdown 格式

可在文字框中編輯您的原始文件，所有檔案格式都可以依此方法編輯。完成後按下「儲存」即可保存您的編輯結果。

資料管理提醒

• 建議在編輯前先備份重要內容

• 編輯原始文件後，系統會重新進行片段分割

音訊與影片：逐字稿檢視器

音訊（.wav、.mp3、.m4a、.aac）與影片（.mp4）上傳後，系統會先轉成帶時間戳的逐字稿再切片。在這類文件的詳情頁按 「檢視文件」 開啟的不是 Markdown 編輯器，而是逐字稿檢視器：

• 左側播放器：音訊顯示檔名、時長與播放列；影片直接播放。播放時右側逐字稿會跟著捲動並高亮目前的句子，點任一句可跳到該時間點。

• 逐字稿 分頁：逐句列出時間、語者與內容。純文字 可切成不含時間的版本，複製 把整份逐字稿複製到剪貼簿。

• 語者管理 分頁：辨識出的語者預設以編號標示，可在 語者標籤 改成真實稱呼（例如「客服」「客戶」）後按 儲存，逐字稿會同步更新。

• 下載逐字稿：可選 下載 TXT（純文字，適合閱讀與編輯）或 下載 SRT（字幕格式，含時間軸）。

Agent 檢索時用的是逐字稿文字；要修正辨識錯誤的內容，請改用上方的編輯原始文件流程編輯片段。語音轉文字的計費見 Credits 計費制度。

文件批次操作

「文件」頁的列表最左欄可以勾選檔案，勾選後上方會顯示「已選擇 N 項」，再用列表上方的按鈕一次處理多個檔案。沒有「更新」權限的成員，這些按鈕會顯示為無法使用。

按鈕	需要先勾選	做什麼
批量修改解析器	是	把勾選的檔案改用同一個解析器並立即重新解析
批量刪除	是	刪除勾選的檔案
搬移檔案	是	把勾選的檔案搬到另一個知識庫，見 知識庫檔案搬移
批量管理元資料	否	用 Excel 一次匯出、修改並匯入全部檔案的元資料
批量管理標籤	否	用 Excel 一次匯出、修改並匯入全部檔案的標籤

批量修改解析器

勾選檔案後點「批量修改解析器」，在「解析器」下拉選單選擇要改用的解析器，按「儲存」。一次只能處理同一種檔案類型的檔案（例如全部是 PDF）；勾選到不同類型時會提示請選擇相同檔案類型，請用「全部檔案類型」篩選後再勾選。

選擇「自動偵測（預設）」時，系統會依每個檔案的內容自行決定解析器，PPT、含圖片的 Word 與掃描 PDF 可能改用 Vision Parser。

更換解析器會立刻重新解析所有勾選的檔案，並依新解析器的計費規則重新計費。計費方式見 用量計算。

批量刪除

勾選檔案後點「批量刪除」，確認視窗會顯示「確定要刪除所選的 N 個檔案嗎？」，按「確認刪除」送出。刪除後 Agent 無法再搜尋到這些內容，且無法復原。

刪除是在背景進行的：送出後列表會先顯示「刪除中」，完成才消失。若勾選的檔案裡有已在刪除中的檔案，會提示「N 個文件正在刪除中，已略過」，其餘檔案照常刪除。

刪除後會發生什麼

• 新的回答立即不再引用：送出刪除的當下，這份文件的片段與引用節點就會從檢索範圍移除，之後的對話與搜尋測試都找不到它；「刪除中」只是背景清除向量資料與檔案本體的過程，不會再被檢索到。

• 歷史對話的引用會消失：先前對話裡引用到這份文件的訊息文字會保留，但「查看引用節點」不會再列出來自這份文件的片段，點引用也無法再開啟原始文件。需要保留引用紀錄時，請在刪除前先從 Agent 監控匯出對話。

• 正在處理中的文件也能刪：狀態為「初始化」或「處理中」的文件刪除後，解析工作會自行中止，不會另外扣點。

• 無法復原：要恢復內容只能重新上傳，重新上傳會再計一次解析與向量化費用。

批量管理標籤、批量管理元資料

這兩個按鈕不必先勾選檔案，點開後都是同一套「下載 → 編輯 → 上傳」流程，一次處理這個知識庫全部檔案：

1. 在「下載標籤」／「下載元資料」區點「下載標籤檔案」／「下載元資料檔案」，取得目前所有檔案的 Excel。

   • 標籤檔：每一列是一個檔案、每一欄是一個標籤，已套用的格子標 v。要加標籤就填 v，要移除就清空。

   • 元資料檔：每一列是一個檔案、每一欄是一個元資料欄位，直接改格子裡的值。

2. 在 Excel 修改後，回到「上傳更新標籤」／「上傳更新元資料」區，拖曳檔案或點「瀏覽檔案」選擇剛改好的 .xlsx／.xls。

3. 點「上傳並更新」。成功時會顯示「已更新 N/M 筆記錄」；部分列有問題時會顯示失敗筆數，其餘仍會更新。

請保留下載檔案的欄位標題與檔案列，只修改格子裡的值，不要自行新增 Excel 裡沒有的標籤或元資料欄位；要新增標籤或元資料欄位，先到左側的「標籤管理」／「元資料管理」建立，再下載新的範本。標籤與元資料本身的說明見 文件管理：標籤及元資料。

常見問題

知識庫裡可以建資料夾嗎？

知識庫沒有資料夾或巢狀目錄，所有文件都在同一份清單中。要分類時有兩種做法：

• 同一個知識庫內分類：用標籤與元資料標記文件，再依標籤篩選或限制 Agent 的檢索範圍，見 文件管理：標籤及元資料 與 知識庫標籤過濾。

• 需要分開管理權限或檢索設定：拆成多個知識庫，再讓同一個 Agent 關聯多個知識庫，見 一個 Agent 使用多個知識庫。

上傳同名的檔案會覆蓋舊檔嗎？

不會。檔名相同的檔案會成為另一筆文件，舊檔仍留在知識庫中，兩份內容都會被檢索到。要更新內容時，請先刪除舊檔再上傳新檔，或直接 編輯原始文件。爬蟲匯入的頁面可以另外選擇網址重複時要略過或覆蓋，見 手動匯入爬取頁面。

片段大小（chunk size）與重疊（overlap）可以調整嗎？

知識庫設定頁沒有片段大小與重疊的選項，文件怎麼切由所選的解析器決定。檢索結果不理想時，可以調整的是：

• 解析器：換一種解析器重新解析，切出來的片段會不同，見 解析器（Parser）是什麼？

• 檢索片段數量：每次回答參考的片段數，預設 12，見 檢索片段

• 相似度門檻值與 Reranker：排除不夠相關的片段，見 相似度門檻值

• 片段內容本身：直接編輯片段或原始文件，讓每個片段可以獨立理解，見 編輯、查看片段內容

調整後用同一組問題跑 搜尋測試 比較前後差異。地端部署需要調整切片參數時，請洽 MaiAgent 窗口。

上傳了不支援的檔案類型會怎樣？

上傳視窗的檔案選擇器只會列出支援的檔案類型，清單以外的格式選不到，也不會建立文件。用 API 上傳時，沒有任何解析器支援的副檔名會被拒絕，detail 為「不支援解析的檔案類型」，見技術人員手冊 - 知識庫 API 的錯誤排查。

遇到不支援的格式，請先轉成清單內的格式再上傳：Outlook 郵件存成 .eml 或 PDF、Pages／Keynote 等另存為 .docx／.pptx／PDF、純文字類另存為 .txt 或 .md。

Markdown、HTML 與爬蟲匯入的網頁，格式會保留嗎？

知識庫會保留原始檔（可從文件詳情或引用來源下載），但檢索用的是解析後的文字：所有格式的文件解析後都統一成 Markdown 文字再切片，「檢視文件」看到的就是這份 Markdown。

• .md：內容原樣當作 Markdown，標題層級、清單與表格都保留在片段文字中，圖片以 ![]() 連結的形式留在文字裡。

• .html／.htm：由 MaiAgent Parser (Offline) 轉成 Markdown，標題與表格會對應成 Markdown 標題與表格，導覽列、腳本等非內文元素會被捨棄。

• 爬蟲匯入的網頁：匯入時已是網頁主要內容的 Markdown（見如何使用爬蟲），檔名取自頁面標題並加上 .md。系統會自動把來源網址寫進這份文件的 url 元資料，所以 Agent 引用這份文件時，使用者點引用會直接開啟原始網頁；另有 crawl_source、crawl_executed_at、crawl_version 三個系統元資料記錄來源爬取請求、匯入時間與覆蓋次數，這些欄位不會送給模型。

標題文字會留在片段裡，但片段沒有「所屬章節」的結構資訊；要讓 Agent 回答時能說出章節或主題，請確認每個片段內容可獨立理解，或把章節名稱寫進元資料並開啟「檢索時使用」。

系統會自動找出重複或互相矛盾的內容嗎？

不會。知識庫不會比對文件之間的內容，重複上傳或新舊版本並存時，兩份內容都可能被檢索到並一起交給 Agent，Agent 可能同時引用舊版與新版。唯一的自動去重是爬蟲匯入時依網址判斷（略過／覆蓋／允許重複），見如何使用爬蟲。建議的做法：

• 用元資料記錄版本與狀態，更新文件時先刪除舊檔再上傳，或直接編輯原始文件。

• 以搜尋測試輸入常見問題，檢查同一個問題是否同時命中多份內容不一致的片段。

• 用對話平台分析的「幻覺回應」「知識庫缺口」分類找出因內容衝突而答錯的對話。

可以把 Notion 頁面匯入知識庫嗎？

知識庫沒有 Notion 匯入功能；MaiGPT 的 Notion 連接器只能在對話當下查詢頁面，不會把內容存進知識庫。要讓 Agent 長期參考 Notion 內容，請在 Notion 用「匯出」把頁面匯出成 Markdown、HTML 或 PDF 後上傳：

• 匯出成 Markdown／HTML 時，頁面內的圖片會以連結或壓縮檔內的獨立檔案存在，不會被辨識成文字；只需要文字內容時用這種方式。

• 圖片中的資訊也要被檢索時，匯出成 PDF 並選擇 Vision Parser 解析，或把圖片檔另外上傳到使用多模態 Embedding 模型的知識庫，見技術人員手冊 - 圖像辨識支援。

• Notion 頁面是公開網頁時，也可以用爬蟲定期同步。