> For the complete documentation index, see [llms.txt](https://docs.maiagent.ai/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.maiagent.ai/build/knowledge-base/km.md).

# 知識庫總覽

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

## 知識庫是什麼？ <a href="#what-is-knowledge-base" id="what-is-knowledge-base"></a>

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

{% hint style="info" %}
**知識庫和檔案庫的差別**：知識庫是讓 Agent「找答案」的參考資料，回答時先檢索相關片段；[檔案庫](/work/file-library.md) 用來存放與處理日常工作檔案，MaiGPT 需要時會整份讀取，也能修改並保留版本。比較表見 [檔案庫和知識庫有什麼不同](/work/file-library.md#vs-knowledge-base)。
{% endhint %}

## 知識庫可以做什麼？ <a href="#what-can-knowledge-base-do" id="what-can-knowledge-base-do"></a>

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

### 📋 **標籤管理文件** <a href="#tag-document-management" id="tag-document-management"></a>

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

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

### 🔐 **選擇性開放文件權限** <a href="#selective-document-permissions" id="selective-document-permissions"></a>

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

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

### ❓ **建立 FAQ** <a href="#create-faq" id="create-faq"></a>

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

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

### 📊 **傳入文件的 Metadata** <a href="#document-metadata-input" id="document-metadata-input"></a>

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

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

### 🔍 **搜尋測試** <a href="#search-testing" id="search-testing"></a>

您可以測試不同問題的檢索結果，驗證 AI 是否找到正確的資料片段（知識庫設定頁左側的選單名稱是 「<mark style="color:blue;">AI 搜尋</mark>」，見 [搜尋測試](/build/knowledge-base/test-search-result.md)）

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

## 知識庫設定頁的分頁 <a href="#knowledge-base-settings-tabs" id="knowledge-base-settings-tabs"></a>

在知識庫列表點 「<mark style="color:blue;">編輯</mark>」 進入設定頁後，左側選單依序是：

| 分頁                                                                           | 管什麼                                                                 | 詳細說明                                                       |
| ---------------------------------------------------------------------------- | ------------------------------------------------------------------- | ---------------------------------------------------------- |
| <mark style="color:blue;">基本</mark>                                          | 名稱、描述、Embedding／Reranker 模型、檢索片段數、關聯 AI 助理與權限等                      | [如何建立知識庫：基本設置](/build/knowledge-base/km-basic-settings.md) |
| <mark style="color:blue;">標籤管理</mark>、<mark style="color:blue;">元資料管理</mark> | 定義可用的標籤與元資料欄位                                                       | [文件管理：標籤及元資料](/build/knowledge-base/tags-and-metadata.md)  |
| <mark style="color:blue;">文件</mark>                                          | 上傳、檢視、編輯文件與批次操作                                                     | 本頁                                                         |
| <mark style="color:blue;">FAQ 常見問題</mark>                                    | 問答對                                                                 | [如何建立 FAQ 常見問題](/build/knowledge-base/faq.md)              |
| <mark style="color:blue;">AI 搜尋</mark>                                       | 用問題測試檢索結果，可加 AI 摘要                                                  | [搜尋測試](/build/knowledge-base/test-search-result.md)        |
| <mark style="color:blue;">API 串接</mark>                                      | 用程式上傳文件、搜尋這個知識庫的說明與範例，已代入知識庫 ID、所用的 Embedding／Reranker 模型與關聯的 Agent | [開發者工具](/org/developer.md#integration-docs)                |

## 如何上傳知識庫？ <a href="#how-to-upload-knowledge-base" id="how-to-upload-knowledge-base"></a>

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

1. 進入左側功能欄 「<mark style="color:blue;">AI 功能</mark>」 → 「<mark style="color:blue;">知識庫</mark>」
2. 找到要上傳的知識庫，在操作欄點選「<mark style="color:blue;">編輯</mark>」（若尚未建立，請先參考 [如何建立知識庫：基本設置](/build/knowledge-base/km-basic-settings.md)）
3. 進入設定頁後，點選左側的「<mark style="color:blue;">文件</mark>」
4. 在頁面右上方點選「<mark style="color:blue;">上傳檔案</mark>」藍色按鈕，上傳您想讓 Agent 知道的資料

<figure><img src="https://1593648278-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2Fmzb5NG9GDzFP2YDKeYVl%2Fuploads%2Fgit-blob-d9f8ed5b6fb58f8ca7dacd1c9d86d30b26b10838%2Fknowledge-base-upload-dialog.png?alt=media" alt="上傳檔案視窗列出已支援的副檔名，包含 EPUB、EML、MSG 與圖片格式"><figcaption><p>上傳檔案視窗會列出 EPUB 與其他可使用的檔案格式</p></figcaption></figure>

{% hint style="info" %}

* 根據不同的方案會提供不同大小的知識庫容量
* 如果您的檔案較大或資料量較多，上傳後系統可能需要一些時間處理。
  {% endhint %}

<figure><img src="https://1593648278-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2Fmzb5NG9GDzFP2YDKeYVl%2Fuploads%2Fgit-blob-bbccb9631a2a7e4100a142b72f051b5c36add012%2Fknowledge-base-email-files.png?alt=media" alt="文件列表中，郵件檔及拆出的 PDF、CSV 的處理狀態皆為完成"><figcaption><p>在文件列表的處理狀態欄查看解析結果</p></figcaption></figure>

您可於 「<mark style="color:blue;">處理狀態</mark>」 欄位中檢視處理進度。

### 文件列表的欄位與處理狀態 <a href="#file-list-columns-and-status" id="file-list-columns-and-status"></a>

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

| 處理狀態                                  | 意思             | 可以做什麼                                                                                                                                                                                                                      |
| ------------------------------------- | -------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| <mark style="color:blue;">初始化</mark>  | 已上傳，排隊等待處理     | 等待即可；大量上傳時等待時間會拉長                                                                                                                                                                                                          |
| <mark style="color:blue;">處理中</mark>  | 正在解析、切片與向量化    | 等待；可按 <mark style="color:blue;">重新整理</mark> 更新狀態                                                                                                                                                                           |
| <mark style="color:blue;">完成</mark>   | Agent 已可檢索這份文件 | 點 <mark style="color:blue;">編輯</mark> 檢視片段、標籤與元資料                                                                                                                                                                          |
| <mark style="color:blue;">失敗</mark>   | 解析或向量化失敗       | 點選狀態旁的紅色驚嘆號可看 <mark style="color:blue;">失敗原因</mark> 與 <mark style="color:blue;">失敗時間</mark>；按操作欄的 <mark style="color:blue;">重新解析</mark> 用同一個解析器再試一次，或在 <mark style="color:blue;">解析器</mark> 欄改選其他解析器（選定後立即重新解析），也可以刪除後重新上傳 |
| <mark style="color:blue;">刪除中</mark>  | 背景正在移除文件與向量    | 等待；批量刪除時這類文件會被略過                                                                                                                                                                                                           |
| <mark style="color:blue;">刪除失敗</mark> | 移除未完成          | 再刪一次；持續失敗請洽 MaiAgent                                                                                                                                                                                                       |

{% hint style="success" %}
目前知識庫支援的檔案類型：

* 試算表文件：`.xls, .xlsx, .csv, .ods`
* 文書處理文件：`.doc, .docx, .odt, .pdf, .md, .txt`
* 簡報文件：`.ppt, .pptx, .odp`
* 網頁文件：`.html, .htm`
* 資料格式：`.json, .jsonl`
* 電子書：`.epub`
* 郵件：`.eml, .msg`
* 音訊文件：`.wav, .mp3, .m4a, .aac`
* 視訊文件：`.mp4`
* 圖片：`.gif, .jpeg, .jpg, .png, .tiff, .webp`（僅限使用多模態 Embedding 模型的知識庫）
  {% endhint %}

完整的副檔名清單見 [技術人員手冊 - Parser 解析工具](https://docs.maiagent.ai/tech/quickstart/parser#document-parsers)。

### 郵件檔（.msg、.eml）與內嵌附件 <a href="#email-files" id="email-files"></a>

例如，品管人員收到供應商寄來的檢驗信，報告 PDF 與週報試算表（CSV）都夾在信裡。把 Outlook 另存的 `.msg`（或其他郵件軟體匯出的 `.eml`）直接上傳到知識庫，Agent 就能回答「這封信是誰寄的、哪天寄的」，也能查到附件報告裡的內容，不必先把信和附件一個個另存成 PDF。

上傳方式與其他檔案相同。郵件檔只能用 <mark style="color:blue;">MaiAgent Parser</mark> 解析，上傳視窗的解析器選單也只會列出它。

<figure><img src="https://1593648278-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2Fmzb5NG9GDzFP2YDKeYVl%2Fuploads%2Fgit-blob-e5cda1bd8f6cd2a723da59c9bfbf266dea5e6a61%2Fknowledge-base-email-upload.png?alt=media" alt="上傳視窗已選取 EML 郵件檔，解析器為 MaiAgent Parser"><figcaption><p>郵件檔與其他文件一樣從上傳檔案視窗加入</p></figcaption></figure>

#### 信件本身會讀到什麼 <a href="#email-body-content" id="email-body-content"></a>

郵件檔會成為一份文件，內容依序是：

* **信件資訊**：主旨、寄件者、收件者、副本（CC）與寄件日期。寄件者與收件者同時保留顯示名稱與 Email 位址；密件副本（BCC）不會讀入。
* **內文**：優先讀純文字內文；信件只有 HTML 格式時，轉成文字後讀入。
* **附件清單**：列出這封信夾帶的附件檔名。

<figure><img src="https://1593648278-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2Fmzb5NG9GDzFP2YDKeYVl%2Fuploads%2Fgit-blob-5c42c2b5ca6b5e01f8284df51030beeef6e4875f%2Fknowledge-base-email-body.png?alt=media" alt="郵件文件的解析內容包含主旨、寄件者、收件者、日期、內文與 PDF、CSV 附件檔名"><figcaption><p>郵件本身成為可檢索的文件，保留信件資訊與附件清單</p></figcaption></figure>

{% hint style="info" %}

* 只有數位簽章（S/MIME 簽署）的信件會正常讀取；**加密**的信件因為沒有收件者的私鑰無法開啟，會顯示為失敗，不會加入一封空信。
* 會議邀請信只讀得到信件資訊與內文，邀請檔（`.ics`）裡的會議時間與地點不會讀入。
* Outlook 的 `.pst`（整個信箱的封存檔）與 `.mbox` 不支援，請在郵件軟體中把需要的信件逐封另存為 `.msg` 或 `.eml` 再上傳。
  {% endhint %}

#### 內嵌附件會拆成獨立文件 <a href="#email-attachments" id="email-attachments"></a>

信件處理完成後，系統會把信裡的附件逐一取出，在同一個知識庫建立成獨立的文件，跟直接上傳的檔案一樣解析、參與檢索：

* **檔名**：沿用附件原本的檔名，會出現在文件列表中。
* **解析器**：每個附件各自自動偵測，例如掃描的 PDF 會改用能辨識圖片的解析器，不沿用信件的 MaiAgent Parser。
* **只拆一層**：信中夾帶的另一封信（附件本身是 `.msg` 或 `.eml`）不會再拆開，也不會列在附件清單上。

不是每個附件都會建立成文件：

| 附件                                                            | 結果                                                                          |
| ------------------------------------------------------------- | --------------------------------------------------------------------------- |
| 知識庫支援的文件格式（PDF、Word、Excel、PowerPoint、文字檔等）                    | 建立成獨立文件                                                                     |
| 圖片                                                            | 知識庫使用多模態 Embedding 模型時才建立；同時小於 50 KB 且長邊小於 200 px 的圖片視為簽名檔的 Logo 或社群圖示，一律略過 |
| 音訊、影片                                                         | 不建立，避免自動產生語音轉文字費用；需要時請另外直接上傳                                                |
| 不支援的格式（例如 `.exe`），以及 Outlook 以 RTF 格式寄出時打包所有附件的 `winmail.dat` | 不建立，只出現在信件的附件清單上；不影響同一封信的其他附件                                               |

* 一封信最多拆出 50 個附件。
* 組織的檔案上傳額度用完時，不會再拆出附件。

#### 附件與原始信件的關聯 <a href="#email-attachment-metadata" id="email-attachment-metadata"></a>

每個拆出來的附件文件會自動帶上一組系統元資料，記錄它來自哪一封信。這些元資料會顯示在文件列表上，也可以在列表上方的搜尋框輸入原始信件的文件 ID、信件主旨或寄件者，找出同一封信拆出的附件：

| 元資料                         | 內容              |
| --------------------------- | --------------- |
| `email_source_file_id`      | 原始信件在知識庫中的文件 ID |
| `email_subject`             | 信件主旨            |
| `email_from`                | 寄件者             |
| `email_date`                | 寄件日期            |
| `email_attachment_filename` | 附件原始檔名          |

<figure><img src="https://1593648278-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2Fmzb5NG9GDzFP2YDKeYVl%2Fuploads%2Fgit-blob-59af57bf5e5421107cbfc38f76cb35935ef05dd2%2Fknowledge-base-email-metadata.png?alt=media" alt="附件文件的元資料記錄原始信件的主旨、寄件者、日期與附件檔名"><figcaption><p>可用信件主旨或寄件者搜尋同一封郵件拆出的附件</p></figcaption></figure>

這些系統元資料建立時沒有開啟「檢索時使用」，不會用來篩選檢索結果。元資料的用途與設定方式見 [文件管理：標籤及元資料](/build/knowledge-base/tags-and-metadata.md)。

#### 刪除信件或附件 <a href="#delete-email-files" id="delete-email-files"></a>

* **刪除信件**：從這封信拆出來的附件文件會一併刪除。
* **只刪除某個附件**：信件與其他附件不受影響；之後重新解析這封信，也不會再把已刪除的附件建立回來。

#### 郵件檔處理失敗時 <a href="#email-file-errors" id="email-file-errors"></a>

點選 <mark style="color:blue;">失敗</mark> 狀態旁的紅色驚嘆號，可開啟 <mark style="color:blue;">失敗原因</mark> 視窗：

| 失敗原因                               | 意思                                  | 怎麼處理                                    |
| ---------------------------------- | ----------------------------------- | --------------------------------------- |
| 此郵件已加密（S/MIME），沒有收件者私鑰無法開啟，未加入知識庫。 | 信件內容經過加密                            | 請收件者在郵件軟體中解密後，另存一份未加密的信件再上傳             |
| 此 S/MIME 郵件已損毀或無法解析。               | 簽章或加密的信封格式損壞                        | 從郵件軟體重新匯出這封信再上傳                         |
| 此 .msg 檔案已損毀，或不是有效的 Outlook 郵件。    | 檔案不完整，或副檔名是 `.msg` 但內容不是 Outlook 郵件 | 在 Outlook 中重新另存為 `.msg`，或改存成 `.eml` 再上傳 |

上傳時若檔案超過大小上限，會在上傳當下被擋下。損毀的郵件檔可能在解析時顯示失敗，請依失敗原因重新匯出或改存成其他支援格式。

### 結構化檔案的列數上限 <a href="#table-row-limit" id="table-row-limit"></a>

CSV、Excel、JSON、JSONL 這類表格型檔案，加入 「<mark style="color:blue;">上傳檔案</mark>」 視窗後會先計算列數（顯示「計算列數中…」），算完在檔名下方標示列數。超過 1000 列的檔案，列數旁會以橘字提示建議改用「資料庫」功能管理；讀不到內容的檔案會以紅字標示「無法讀取的檔案」。

<figure><img src="https://1593648278-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2Fmzb5NG9GDzFP2YDKeYVl%2Fuploads%2Fgit-blob-6a42a1dc2450bcb06980e8fbeacbaa218ee6a204%2Fknowledge-base-upload-row-count.png?alt=media" alt="上傳檔案視窗中，1200 列的 CSV 檔名下方以橘字標示列數與改用資料庫的建議"><figcaption><p>超過 1000 列的表格檔會在上傳清單標示列數與建議</p></figcaption></figure>

清單中有超過上限或無法讀取的檔案時，按 <mark style="color:blue;">上傳</mark> 會先跳出 「<mark style="color:blue;">檔案列數超過建議上限</mark>」 確認視窗：

<figure><img src="https://1593648278-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2Fmzb5NG9GDzFP2YDKeYVl%2Fuploads%2Fgit-blob-0e4b3589368caa652b0bc82f8be0bed96142e455%2Fknowledge-base-row-limit-confirm.png?alt=media" alt="檔案列數超過建議上限確認視窗，提供取消與仍然上傳兩個按鈕"><figcaption><p>確認視窗只有取消與仍然上傳兩個選擇</p></figcaption></figure>

| 按鈕                                    | 作用                                                                                                                                                                                     |
| ------------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| <mark style="color:blue;">取消</mark>   | 回到上傳視窗，可按檔案右側的刪除圖示把該檔從清單移除，只上傳其餘檔案；或改到 <mark style="color:blue;">資料庫</mark> 功能把檔案上傳成可用 Text to SQL 查詢的資料表，見 [建立與設定資料庫](/build/database/create-database.md#upload-file-to-create-table) |
| <mark style="color:blue;">仍然上傳</mark> | 照常上傳。檔案會被切成大量片段，整張表的統計、篩選類問題檢索效果較差                                                                                                                                                     |

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

#### 表格檔在知識庫裡怎麼切、怎麼引用 <a href="#table-file-chunking" id="table-file-chunking"></a>

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

* 每個工作表會轉成一張 Markdown 表格（CSV 整檔一張；一個檔案有多個工作表時，各表前面會加上工作表名稱作為標題），第一列作為表頭。
* Excel 每個工作表最多讀取前 100,000 列，CSV 整份讀取（只受上傳檔案大小上限限制）。「最多讀取前 5,000 列」只適用於在對話中直接附加的表格檔，不適用於上傳到知識庫的檔案。
* 轉成的表格再依一般文件的切片規則切成片段，**一列不是獨立的檢索單位**：一個片段通常包含連續多列，表頭只出現在表格開頭的片段。檢索與引用都以片段為單位，引用來源會指向包含該列的片段，不會標出列號。
* 隱藏的列與工作表一樣會被讀取，不想交給 Agent 的資料請先刪除。

要讓每一列都能被單獨找到並引用，請把每列整理成一筆 FAQ（可用 [Excel 批量匯入](/build/knowledge-base/faq.md#bulk-import-faq-excel)），或改用[資料庫](/build/database/create-database.md#upload-file-to-create-table)讓 Agent 以 SQL 查詢。

### 查看資料 <a href="#view-data" id="view-data"></a>

#### 資料片段說明 <a href="#chunk-description" id="chunk-description"></a>

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

* **提升檢索精確度**：小片段更精確匹配查詢，避免無關內容干擾
* **優化回應速度**：處理更快，減少計算資源消耗
* **增強內容相關性**：每個片段聚焦單一主題，提高針對性
* **便於維護管理**：易於更新、追蹤和品質控制
* **符合 AI 模型限制**：避免超出輸入長度，確保資訊完整性

#### 編輯、查看片段內容 <a href="#edit-view-chunk-content" id="edit-view-chunk-content"></a>

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

1. 進入知識庫的文件頁面，在要查看的文件操作欄點按「<mark style="color:blue;">編輯</mark>」
2. 文件詳情頁上方顯示 chunk 數、重組後字元數與總命中次數，右上角可切換兩種檢視：

* <mark style="color:blue;">整篇文件</mark>（預設）：把所有片段依原文順序拼回一整篇，左側軌道標出每個 chunk 的範圍。<mark style="color:blue;">顯示 chunk 標記</mark> 預設開啟，奇數與偶數 chunk 的軌道以不同顏色區分，琥珀色底的段落同時屬於相鄰兩個 chunk（即 overlap，只顯示一次），滑鼠移到軌道上會高亮該 chunk 的完整範圍。要檢查「一個句子有沒有被切在兩個片段中間」時用這個檢視最直覺。
* <mark style="color:blue;">Chunk 卡片</mark>：每個片段一張卡片，顯示字數與命中次數。點卡片會開啟視窗顯示此片段的完整內容；視窗中的 <mark style="color:blue;">編輯欄位</mark> 用來設定這個片段的標籤與元資料，<mark style="color:blue;">查看原文</mark> 可開啟原始文件。要修改片段文字，請用下方的[編輯原始文件](#edit-source-document)。

<figure><img src="https://1593648278-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2Fmzb5NG9GDzFP2YDKeYVl%2Fuploads%2Fgit-blob-8509c1d0c798cf6fb0c0ef607a01da156b6f8d94%2Fknowledge-base-file-whole-document.png?alt=media" alt="文件詳情頁的整篇文件檢視，左側軌道標出 chunk 範圍，右上角有整篇文件、Chunk 卡片與檢視文件按鈕"><figcaption><p>整篇文件檢視</p></figcaption></figure>

<figure><img src="https://1593648278-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2Fmzb5NG9GDzFP2YDKeYVl%2Fuploads%2Fgit-blob-81ff67fcb2a7b00682586dde909a81f7597bee2d%2Fknowledge-base-file-chunk-cards.png?alt=media" alt="文件詳情頁的 Chunk 卡片檢視，每張卡片顯示片段內容、字數與命中次數"><figcaption><p>Chunk 卡片檢視</p></figcaption></figure>

<figure><img src="https://1593648278-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2Fmzb5NG9GDzFP2YDKeYVl%2Fuploads%2Fgit-blob-8080958e442639d715ea3be2733536c56e7dd918%2Fknowledge-base-chunk-detail.png?alt=media" alt="片段視窗顯示完整內容、字數、命中次數，以及查看原文與編輯欄位按鈕"><figcaption><p>點卡片開啟的片段視窗</p></figcaption></figure>

#### 編輯原始文件 <a href="#edit-source-document" id="edit-source-document"></a>

1. 在文件詳情頁右上角點擊「<mark style="color:blue;">檢視文件</mark>」
2. 開啟的編輯畫面左側是頁面列表，右側文字框會顯示該文件的 Markdown 格式

可在文字框中編輯文件內容，所有檔案格式都可以依此方法編輯。尚未修改時「<mark style="color:blue;">儲存</mark>」為灰色；修改完成後按下「<mark style="color:blue;">儲存</mark>」即可保存編輯結果。文字框上方的提示說明儲存會影響哪些內容：

* `.txt`、`.md`、`.csv`、`.json` 等文本檔：「儲存會同步更新原始檔案。」
* PDF、Word、簡報等其他檔案：「僅更新搜尋用文字，原始檔案不受影響。」滑鼠移到 「<mark style="color:blue;">哪些是文本檔？</mark>」 可看完整清單。

<figure><img src="https://1593648278-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2Fmzb5NG9GDzFP2YDKeYVl%2Fuploads%2Fgit-blob-2fc3205afc03e0c1216eb4cbbeea5d8e1507ba41%2Fknowledge-base-view-document-editor.png?alt=media" alt="檢視文件的編輯畫面，左側頁面列表，右側 Markdown 文字框，上方提示儲存會同步更新原始檔案"><figcaption><p>文本檔的編輯畫面，右上角為儲存按鈕</p></figcaption></figure>

{% hint style="info" %}
**資料管理提醒**

* 建議在編輯前先備份重要內容
* 編輯原始文件後，系統會重新進行片段分割
  {% endhint %}

### 音訊與影片：逐字稿檢視器 <a href="#media-transcription-viewer" id="media-transcription-viewer"></a>

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

* **左側播放器**：音訊顯示檔名、時長與播放列；影片直接播放。播放時右側逐字稿會跟著捲動並高亮目前的句子，點任一句可跳到該時間點。
* <mark style="color:blue;">**逐字稿**</mark>**&#x20;分頁**：逐句列出時間、語者與內容。<mark style="color:blue;">純文字</mark> 可切成不含時間的版本，<mark style="color:blue;">複製</mark> 把整份逐字稿複製到剪貼簿。
* <mark style="color:blue;">**語者管理**</mark>**&#x20;分頁**：辨識出的語者預設以編號標示，可在 <mark style="color:blue;">語者標籤</mark> 改成真實稱呼（例如「客服」「客戶」）後按 <mark style="color:blue;">儲存</mark>，逐字稿會同步更新。
* <mark style="color:blue;">**下載逐字稿**</mark>：可選 <mark style="color:blue;">下載 TXT</mark>（純文字，適合閱讀與編輯）或 <mark style="color:blue;">下載 SRT</mark>（字幕格式，含時間軸）。

Agent 檢索時用的是逐字稿文字；要修正辨識錯誤的內容，請改用上方的[編輯原始文件](#edit-source-document)流程編輯片段。語音轉文字的計費見 [Credits 計費制度](/others/credits.md)。

## 文件批次操作 <a href="#batch-operations" id="batch-operations"></a>

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

| 按鈕                                       | 需要先勾選 | 做什麼                                                               |
| ---------------------------------------- | ----- | ----------------------------------------------------------------- |
| <mark style="color:blue;">批量修改解析器</mark> | 是     | 把勾選的檔案改用同一個解析器並**立即重新解析**                                         |
| <mark style="color:blue;">批量刪除</mark>    | 是     | 刪除勾選的檔案                                                           |
| <mark style="color:blue;">搬移檔案</mark>    | 是     | 把勾選的檔案搬到另一個知識庫，見 [知識庫檔案搬移](/build/knowledge-base/km-file-move.md) |
| <mark style="color:blue;">批量管理元資料</mark> | 否     | 用 Excel 一次匯出、修改並匯入**全部**檔案的元資料                                    |
| <mark style="color:blue;">批量管理標籤</mark>  | 否     | 用 Excel 一次匯出、修改並匯入**全部**檔案的標籤                                     |

### 批量修改解析器 <a href="#batch-change-parser" id="batch-change-parser"></a>

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

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

{% hint style="warning" %}
更換解析器會立刻重新解析所有勾選的檔案，並依新解析器的計費規則重新計費。計費方式見 [用量計算](/others/usage.md#failed-and-reparse)。
{% endhint %}

### 批量刪除 <a href="#batch-delete" id="batch-delete"></a>

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

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

#### 刪除後會發生什麼 <a href="#what-happens-after-delete" id="what-happens-after-delete"></a>

* **新的回答立即不再引用**：送出刪除的當下，這份文件的片段與引用節點就會從檢索範圍移除，之後的對話與搜尋測試都找不到它；「刪除中」只是背景清除向量資料與檔案本體的過程，不會再被檢索到。
* **歷史對話的引用會消失**：先前對話裡引用到這份文件的訊息文字會保留，但「查看引用節點」不會再列出來自這份文件的片段，點引用也無法再開啟原始文件。需要保留引用紀錄時，請在刪除前先從 [Agent 監控](/build/agent-ops/evaluations.md)匯出對話。
* **正在處理中的文件也能刪**：狀態為「初始化」或「處理中」的文件刪除後，解析工作會自行中止，不會另外扣點。
* **無法復原**：要恢復內容只能重新上傳，重新上傳會再計一次解析與向量化費用。

### 批量管理標籤、批量管理元資料 <a href="#batch-manage-labels-metadata" id="batch-manage-labels-metadata"></a>

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

1. 在「<mark style="color:blue;">下載標籤</mark>」／「<mark style="color:blue;">下載元資料</mark>」區點「<mark style="color:blue;">下載標籤檔案</mark>」／「<mark style="color:blue;">下載元資料檔案</mark>」，取得目前所有檔案的 Excel。
   * 標籤檔：每一列是一個檔案、每一欄是一個標籤，已套用的格子標 `v`。要加標籤就填 `v`，要移除就清空。
   * 元資料檔：每一列是一個檔案、每一欄是一個元資料欄位，直接改格子裡的值。
2. 在 Excel 修改後，回到「<mark style="color:blue;">上傳更新標籤</mark>」／「<mark style="color:blue;">上傳更新元資料</mark>」區，拖曳檔案或點「<mark style="color:blue;">瀏覽檔案</mark>」選擇剛改好的 `.xlsx`／`.xls`。
3. 點「<mark style="color:blue;">上傳並更新</mark>」。成功時會顯示「已更新 N/M 筆記錄」；部分列有問題時會顯示失敗筆數，其餘仍會更新。

{% hint style="info" %}
請保留下載檔案的欄位標題與檔案列，只修改格子裡的值，不要自行新增 Excel 裡沒有的標籤或元資料欄位；要新增標籤或元資料欄位，先到左側的「<mark style="color:blue;">標籤管理</mark>」／「<mark style="color:blue;">元資料管理</mark>」建立，再下載新的範本。標籤與元資料本身的說明見 [文件管理：標籤及元資料](/build/knowledge-base/tags-and-metadata.md)。
{% endhint %}

## 常見問題 <a href="#faq" id="faq"></a>

### 知識庫裡可以建資料夾嗎？ <a href="#faq-folders" id="faq-folders"></a>

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

* **同一個知識庫內分類**：用標籤與元資料標記文件，再依標籤篩選或限制 Agent 的檢索範圍，見 [文件管理：標籤及元資料](/build/knowledge-base/tags-and-metadata.md) 與 [知識庫標籤過濾](/build/agent/label-filter.md)。
* **需要分開管理權限或檢索設定**：拆成多個知識庫，再讓同一個 Agent 關聯多個知識庫，見 [一個 Agent 使用多個知識庫](/build/knowledge-base/km-basic-settings.md#one-agent-multiple-knowledge-bases)。

### 上傳同名的檔案會覆蓋舊檔嗎？ <a href="#faq-duplicate-filename" id="faq-duplicate-filename"></a>

不會。檔名相同的檔案會成為另一筆文件，舊檔仍留在知識庫中，兩份內容都會被檢索到。要更新內容時，請先刪除舊檔再上傳新檔，或直接 [編輯原始文件](#edit-source-document)。爬蟲匯入的頁面可以另外選擇網址重複時要略過或覆蓋，見 [手動匯入爬取頁面](/build/knowledge-base/scrape-website.md#manual-import)。

### 片段大小（chunk size）與重疊（overlap）可以調整嗎？ <a href="#faq-chunk-size" id="faq-chunk-size"></a>

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

* **解析器**：換一種解析器重新解析，切出來的片段會不同，見 [解析器（Parser）是什麼？](/build/knowledge-base/km-basic-settings.md#what-is-parser)
* **檢索片段數量**：每次回答參考的片段數，預設 12，見 [檢索片段](/build/knowledge-base/km-basic-settings.md#retrieval-chunk)
* **相似度門檻值與 Reranker**：排除不夠相關的片段，見 [相似度門檻值](/build/knowledge-base/km-basic-settings.md#similarity-cutoff)
* **片段內容本身**：直接編輯片段或原始文件，讓每個片段可以獨立理解，見 [編輯、查看片段內容](#edit-view-chunk-content)

調整後用同一組問題跑 [搜尋測試](/build/knowledge-base/test-search-result.md) 比較前後差異。地端部署需要調整切片參數時，請洽 MaiAgent 窗口。

### 上傳了不支援的檔案類型會怎樣？ <a href="#faq-unsupported-file-type" id="faq-unsupported-file-type"></a>

上傳視窗的檔案選擇器只會列出[支援的檔案類型](#how-to-upload-knowledge-base)，清單以外的格式選不到，也不會建立文件。用 API 上傳時，沒有任何解析器支援的副檔名會被拒絕，`detail` 為「不支援解析的檔案類型」，見[技術人員手冊 - 知識庫 API 的錯誤排查](https://docs.maiagent.ai/tech/api-integration/knowledge-base-api#troubleshooting)。

遇到不支援的格式，請先轉成清單內的格式再上傳：Outlook 的 `.pst` 信箱封存檔請把需要的信件逐封另存為 `.msg` 或 `.eml`（見 [郵件檔（.msg、.eml）與內嵌附件](#email-files)）、Pages／Keynote 等另存為 `.docx`／`.pptx`／PDF、純文字類另存為 `.txt` 或 `.md`。

### Markdown、HTML 與爬蟲匯入的網頁，格式會保留嗎？ <a href="#faq-format-preservation" id="faq-format-preservation"></a>

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

* **`.md`**：內容原樣當作 Markdown，標題層級、清單與表格都保留在片段文字中，圖片以 `![]()` 連結的形式留在文字裡。
* **`.html`／`.htm`**：由 MaiAgent Parser (Offline) 轉成 Markdown，標題與表格會對應成 Markdown 標題與表格，導覽列、腳本等非內文元素會被捨棄。
* **爬蟲匯入的網頁**：匯入時已是網頁主要內容的 Markdown（見[如何使用爬蟲](/build/knowledge-base/scrape-website.md#results-and-import-history)），檔名取自頁面標題並加上 `.md`。系統會自動把來源網址寫進這份文件的 `url` 元資料，所以 Agent 引用這份文件時，使用者點引用會直接開啟原始網頁；另有 `crawl_source`、`crawl_executed_at`、`crawl_version` 三個系統元資料記錄來源爬取請求、匯入時間與覆蓋次數，這些欄位不會送給模型。

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

### 系統會自動找出重複或互相矛盾的內容嗎？ <a href="#faq-duplicate-content" id="faq-duplicate-content"></a>

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

* 用[元資料](/build/knowledge-base/tags-and-metadata.md)記錄版本與狀態，更新文件時先刪除舊檔再上傳，或直接[編輯原始文件](#edit-source-document)。
* 以[搜尋測試](/build/knowledge-base/test-search-result.md)輸入常見問題，檢查同一個問題是否同時命中多份內容不一致的片段。
* 用[對話平台分析](/serve/daily-operations/reply/inbox-analysis.md)的「幻覺回應」「知識庫缺口」分類找出因內容衝突而答錯的對話。

### 可以把 Notion 頁面匯入知識庫嗎？ <a href="#faq-notion-import" id="faq-notion-import"></a>

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

* 匯出成 Markdown／HTML 時，頁面內的圖片會以連結或壓縮檔內的獨立檔案存在，不會被辨識成文字；只需要文字內容時用這種方式。
* 圖片中的資訊也要被檢索時，匯出成 PDF 並選擇 Vision Parser 解析，或把圖片檔另外上傳到使用多模態 Embedding 模型的知識庫，見[技術人員手冊 - 圖像辨識支援](https://docs.maiagent.ai/tech/quickstart/tu-xiang-bian-shi-zhi-yuan)。
* Notion 頁面是公開網頁時，也可以用[爬蟲](/build/knowledge-base/scrape-website.md)定期同步。


---

# Agent Instructions
This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com.

## Querying This Documentation
If you need additional information that is not directly available in this page, you can query the documentation by asking a question.

Perform an HTTP GET request on the following URL with the `ask` and `goal` query parameters:

```
GET https://docs.maiagent.ai/build/knowledge-base/km.md?ask=<question>&goal=<user_goal>
```

`ask` is the immediate question: it should be specific, self-contained, and written in natural language.
`goal` is what the user is ultimately trying to achieve, the reason they need the answer. Sharing it helps GitBook give you a better, more relevant answer. A goal is most helpful when it describes the outcome the user wants rather than restating the question. For example, with `ask=how do I create an API token`, a goal like `automate deployments from our CI pipeline` lets GitBook tailor the answer to that use case.

The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.