> 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/tech/quickstart/knowledge-base-vs-file-library.md).

# 知識庫 vs 檔案庫：運作原理與選用依據

給 SI、售前與導入工程師：知識庫與檔案庫在 MaiAgent 裡怎麼運作、在哪些對話平台生效、權限與可見範圍、容量與檔案格式限制、計費差異，以及同一個 Agent 並用時的架構與對客戶的建議說法。

知識庫與檔案庫都能放文件，但模型拿到資料的方式完全不同：**知識庫把文件切成段落、建好索引，回答時只把檢索到的片段交給模型；檔案庫保存整份原檔，由 Agent 用工具整份讀取，必要時直接改寫。**

本頁寫給 SI、售前與導入工程師，說明兩者的運作原理，以及「為什麼這樣選」。給客戶看的選用說明、常見誤用與「我要做什麼 → 放哪裡」決策表放在使用手冊的 [知識庫 vs 檔案庫：用途差異與選用時機](https://docs.maiagent.ai/work/file-library/vs-knowledge-base)，本頁不重複。

***

## 運作方式差異 <a href="#how-they-work" id="how-they-work"></a>

|              | 知識庫（RAG）                                         | 檔案庫                                                                           |
| ------------ | ------------------------------------------------ | ----------------------------------------------------------------------------- |
| **資料怎麼進來**   | 解析 → 切塊 → 以 Embedding 模型向量化 → 寫入向量資料庫            | 原檔存進物件儲存；文件會解析供讀取，但**不做向量化**                                                  |
| **模型拿到什麼**   | 與問題最相關的幾個段落                                      | Agent 主動讀取的整份檔案內容（長文件可分段讀）                                                    |
| **怎麼找到資料**   | 語意＋關鍵字混合檢索（知識庫開啟時再經 Reranker 重新排序），並套用查詢元資料與標籤過濾 | 依工作區目錄與檔名找檔，沒有語意檢索                                                            |
| **AI 能不能修改** | 不能；管理員可在後台編修檔案內容或重新上傳                            | 可以；Agent 依使用者權限寫回檔案、改名、搬移或刪除                                                  |
| **版本**       | 無版本紀錄                                            | 工作區異動都有紀錄；可編輯格式（md、txt、sql、json、csv、docx、xlsx、pptx）的檔案內容保留最近 20 個版本，其他格式不保留版本 |

### 知識庫：先建索引，回答時檢索片段 <a href="#knowledge-base-retrieval" id="knowledge-base-retrieval"></a>

上傳到知識庫的檔案依序經過解析、切塊、向量化，寫入向量資料庫後才能被檢索。回答時，平台依知識庫與 Agent 的設定取回段落（Agent 的 <mark style="color:blue;">檢索區塊最大數量</mark> 預設 12 段），知識庫開啟 Reranker 時再重新排序，最後交給模型。完整流程與可調參數見 [RAG 知識庫檢索系統](https://docs.maiagent.ai/tech/quickstart/rag.md)。

Agent 模式下，知識庫以工具的形式交給模型：模型可以多次檢索段落，也能用 `read_file` 分頁讀取知識庫裡的整份檔案（每次預設 500 行、最多 2,000 行）。純文字類檔案（例如 `.txt`、`.md`）從原檔讀取，其他格式則由解析後的段落文字重組，行號以重組後的文字為準。因此知識庫「也能讀整份」，但前提仍是檔案已經解析並建好索引，適合查證細節，不適合當作大量改寫的工作區。

### 檔案庫：原檔保存，Agent 用工具整份讀寫 <a href="#file-library-tools" id="file-library-tools"></a>

檔案庫的檔案以原檔保存在檔案工作區。對話掛上工作區後，Agent 會拿到一組檔案工具：

| 工具用途     | 行為與限制                                                                                         |
| -------- | --------------------------------------------------------------------------------------------- |
| 瀏覽、找檔    | 列出工作區目錄、依檔名搜尋（每次最多回傳 20 筆）                                                                    |
| 讀取       | 把檔案載入對話後讀取內容；每次呼叫最多 5 份，可再次呼叫讀更多                                                              |
| 寫入       | `.md`、`.txt`、`.sql`、`.json`、`.csv` 可直接寫回；`.docx`、`.xlsx`、`.pptx` 需要 Agent 啟用 Code Interpreter |
| 改名、搬移、刪除 | 每次最多 20 個檔案                                                                                   |

讀取內容時：

* **純文字檔**（txt、md、csv、json 等）：整份讀入，單次最多 50,000 個字元。
* **PDF、Office、音檔與圖片**：解析後依頁、投影片、工作表或固定段落分段讀取；單次回傳上限為模型上下文的 10%，最多 25,000 tokens，長文件不會一次全部讀入。
* 檔案還在解析中時無法讀取，要等解析完成。

讀進來的內容會放進模型的上下文。同一回合讀很多份大檔，可能超過模型上下文上限，所以 Agent 會分批處理；這也是用檔案庫回答大量重複問題，處理時間與用量會偏高的原因。

***

## 在哪些對話平台生效 <a href="#channels" id="channels"></a>

| 對話平台                                          | 知識庫             | 檔案庫                                                   |
| --------------------------------------------- | --------------- | ----------------------------------------------------- |
| MaiGPT                                        | ✅ 使用者可選擇要查詢的知識庫 | ✅ 使用者自行掛載工作區                                          |
| Agent 的 <mark style="color:blue;">內部對話</mark> | ✅               | ✅ 依 Agent 的 <mark style="color:blue;">檔案工作區</mark> 設定 |
| 網頁 Widget、LINE、API 串接等其他對話平台                  | ✅               | ❌ 一律不讀也不寫                                             |

檔案工作區只在同時符合下列條件時生效，否則該次對話完全不會拿到檔案工具，也不會看到工作區內容：

1. 送出訊息的是組織的成員帳號；聯絡人（Contact）或匿名訪客不適用。
2. 組織已開通檔案庫。
3. 對話在 MaiGPT，或在 Agent 的 <mark style="color:blue;">內部對話</mark>，且 Agent 的檔案工作區不是 <mark style="color:blue;">不使用</mark>。
4. Agent 的回答模式是 Agent 模式：檔案工具只在 Agent 模式提供，RAG 問答模式不會讀寫工作區（MaiGPT 本身是 Agent 模式）。

對外客服要讀的資料，請一律放知識庫。

***

## 權限與可見範圍 <a href="#permissions" id="permissions"></a>

兩者的權限模型不同：知識庫的範圍跟著 **Agent 與查詢條件**走，檔案庫跟著 **送訊息的成員本人**走。

### 知識庫 <a href="#knowledge-base-permissions" id="knowledge-base-permissions"></a>

* 管理權限：組織擁有者可管理所有知識庫；其他成員要透過角色被授予該知識庫的權限。
* MaiGPT：使用者只能選擇自己角色可讀取的知識庫。
* Agent 掛載的知識庫：對這個 Agent 的所有對話一律生效，不依送訊息者的個人權限過濾。要依使用者限制可檢索的文件，請用 [查詢元資料（Query Metadata）](https://docs.maiagent.ai/tech/identity-and-access/zhi-shi-guan-li-quan-xian-query-metadata-cha-xun-yuan-zi-liao-zong-lan.md) 或標籤過濾，不要只靠角色指令。

### 檔案庫 <a href="#file-library-permissions" id="file-library-permissions"></a>

* 權限來自組織的自訂角色：檔案庫共有六項權限（是否顯示檔案庫、個人空間、組織空間檢視、組織空間編輯、建立共用空間、可被邀請加入共用空間），預設角色不能授予。設定方式見使用手冊的 [檔案庫：開通與權限](https://docs.maiagent.ai/work/file-library#availability-and-permissions)。
* 空間：<mark style="color:blue;">我的檔案</mark> 只有本人能用；<mark style="color:blue;">組織共用檔案</mark> 依組織空間檢視／編輯權限；共用空間依授權角色開放。AI 產出的檔案預設存進本人 <mark style="color:blue;">我的檔案</mark> 裡的 <mark style="color:blue;">暫存區</mark>。
* Agent 綁定工作區時：
  * 設定綁定的人需要該工作區的編輯權限，而且不能直接綁定空間的最上層。
  * 每則訊息都依**送訊息者自己的檔案庫權限**判斷：能編輯的人，Agent 可以讀寫工作區；只能檢視的人，Agent 只讀不改，產出存到他自己的暫存區；沒有檢視權限的人，該次對話不參考工作區內容，並會告知使用者。

{% hint style="info" %}
因為檔案庫依送訊息者本人的權限判斷，同一個綁定工作區的 Agent，不同同仁問同一個問題，可能因權限不同而拿到不同範圍的資料。知識庫則相反：Agent 掛了什麼就查什麼，除非另外用查詢元資料限縮。
{% endhint %}

***

## 容量與檔案格式 <a href="#limits" id="limits"></a>

| 項目   | 知識庫                                                                                                                                          | 檔案庫                                                                                                                                    |
| ---- | -------------------------------------------------------------------------------------------------------------------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------- |
| 單檔大小 | 依平台設定，預設 100 MB                                                                                                                              | 10 MB                                                                                                                                  |
| 支援格式 | 文件（PDF、Word、PowerPoint、Excel、CSV、ODF、EPUB、HTML、Markdown、TXT、JSON／JSONL）、郵件（EML、MSG）、圖片（PNG、JPG、GIF、WebP、BMP、TIFF）、音訊與影片（WAV、MP3、M4A、AAC、MP4） | PDF、DOC、DOCX、PPT、PPTX、XLS、XLSX、CSV、TXT、MD、JSON、HTML、PNG、JPG、JPEG、GIF、WebP、MP3、WAV、M4A、MP4                                              |
| 其他   | Excel 每個工作表最多讀取前 100,000 列                                                                                                                   | 資料夾最多 10 層、批次移動／刪除每次最多 200 個檔案、可編輯格式的檔案內容保留最近 20 個版本（格式見上方運作方式表）                                                                       |
| 線上編輯 | 不提供                                                                                                                                          | `.docx`、`.xlsx`、`.pptx`（目前僅 SaaS），見 [檔案庫 Office 線上編輯](https://docs.maiagent.ai/tech/platform-development/onlyoffice-online-editing.md) |

***

## 計費差異 <a href="#billing" id="billing"></a>

|     | 知識庫                                         | 檔案庫                                               |
| --- | ------------------------------------------- | ------------------------------------------------- |
| 上傳時 | 解析與向量化（Embedding）計費                         | 只有圖片辨識、掃描頁 OCR 等解析計費；不做向量化，新版本也一樣                 |
| 存放  | 原始檔案儲存費＋向量儲存費                               | 檔案庫儲存費與解析產生的衍生檔案儲存費，沒有向量儲存費                       |
| 回答時 | 每次檢索的問題向量化與 Reranker（有開啟時）計費；送進模型的只有段落，輸入較短 | 讀進來的整份內容都算進模型的輸入 token；讀取 PDF、Office、音檔或圖片時另計解析費用 |

費率見使用手冊 [Credits 計費制度](https://docs.maiagent.ai/others/credits) 與其中的 [檔案庫儲存費](https://docs.maiagent.ai/others/credits#file-library-storage)。簡單說，**知識庫把成本花在事前整理，每次回答便宜；檔案庫事前幾乎不用整理，成本花在每次讀檔**。所以高頻、重複的問答適合知識庫，偶爾需要完整原檔的工作適合檔案庫。

***

## 同一個 Agent 並用的架構 <a href="#use-together" id="use-together"></a>

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> | 使用者在對話中自行選擇要掛上的檔案工作區         |

MaiGPT 固定是「讓使用者自行掛載」。兩邊都設定時，Agent 在 <mark style="color:blue;">內部對話</mark> 的同一回合會同時拿到知識庫工具與檔案工具，由模型依問題決定呼叫哪一邊；知識庫的檢索不會搜到工作區的檔案，檔案工具也讀不到知識庫。對外對話平台與 RAG 問答模式則只會用到知識庫。

兩邊的內容不會自動同步：在檔案庫改好的定稿，要讓 Agent 對外回答時，需要另外上傳到知識庫。

常見的三種架構：

| 架構     | 設定                                                          | 適合                 |
| ------ | ----------------------------------------------------------- | ------------------ |
| 對外客服   | 只掛知識庫，檔案工作區 <mark style="color:blue;">不使用</mark>            | 官網、LINE、API 串接的問答  |
| 專案助理   | 掛知識庫放規章與 FAQ，再 <mark style="color:blue;">綁定工作區</mark> 放專案原檔 | 同一個團隊在內部對話中查規範、寫文件 |
| 通用內部助理 | 掛知識庫，檔案工作區設為 <mark style="color:blue;">讓使用者自行掛載</mark>      | 每位同仁各自帶自己的工作區來用    |

***

## 對客戶的建議說法 <a href="#talking-points" id="talking-points"></a>

對客戶介紹時，建議統一使用以下說法：

> **知識庫是考試時的小抄，檔案庫是寫作業時手邊的整本課本。** 對外回答問題像考試，要的是最快能找到答案的小抄，所以要花功夫整理 FAQ、清洗資料；內部撰寫文件像寫作業，要的是完整的原檔，放進去就能用。

客戶常見的追問：

* **「有檔案庫了，還需要知識庫嗎？」** 需要。檔案庫只在 MaiGPT 與 Agent 的內部對話生效，網頁 Widget、LINE、API 串接讀不到；而且每次回答都要整份讀檔，高頻問答又慢又貴。
* **「知識庫不是也能讀整份檔案嗎？」** Agent 模式下可以分頁讀取知識庫裡的檔案，但檔案要先解析、建索引，AI 也不能修改、沒有版本。要讓 AI 改寫、彙整原檔，用檔案庫。
* **「同一份資料兩邊都要放嗎？」** 看用途。原檔在檔案庫維護，整理好的定稿或 FAQ 再上傳到知識庫，兩邊不會自動同步。
* **「不同部門看到的資料能不一樣嗎？」** 檔案庫依每位同仁自己的權限判斷；知識庫則用查詢元資料或標籤過濾限縮範圍。

要怎麼選、常見放錯的情況，直接把使用手冊的 [知識庫 vs 檔案庫：用途差異與選用時機](https://docs.maiagent.ai/work/file-library/vs-knowledge-base) 給客戶，裡面有「我要做什麼 → 放哪裡」決策表。

***

## 相關頁面 <a href="#related" id="related"></a>

* [RAG 知識庫檢索系統](https://docs.maiagent.ai/tech/quickstart/rag.md)：知識庫的解析、檢索與可調參數
* [Function Calling](https://docs.maiagent.ai/tech/advanced-genai-tech/function-calling.md)：Agent 模式的工具呼叫與執行上限
* [檔案庫 Office 線上編輯（ONLYOFFICE Docs 整合）](https://docs.maiagent.ai/tech/platform-development/onlyoffice-online-editing.md)
* 使用手冊：[知識庫 vs 檔案庫：用途差異與選用時機](https://docs.maiagent.ai/work/file-library/vs-knowledge-base)
* 使用手冊：[檔案庫](https://docs.maiagent.ai/work/file-library)、[知識庫](https://docs.maiagent.ai/build/knowledge-base)


---

# 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/tech/quickstart/knowledge-base-vs-file-library.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.
