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

# ナレッジベースとファイルライブラリ：仕組みと選び方

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/ja/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> 設定に従います |
| Web 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 Q\&A モードはワークスペースを読み書きしません（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/ja/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/ja/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)をご覧ください。簡単に言うと、**ナレッジベースは事前の整理にコストをかけ、回答ごとのコストを抑えます。ファイルライブラリは事前の整理がほとんど不要な代わりに、ファイルを読むたびにコストがかかります**。そのため、高頻度で繰り返す Q\&A にはナレッジベースが、元ファイル全体を時々必要とする作業にはファイルライブラリが適しています。

***

## 同じ 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 Q\&A モードでは、ナレッジベースのみを使用します。

両者の内容は自動同期されません。ファイルライブラリで編集した完成版を Agent の社外向け回答に使うには、別途ナレッジベースにアップロードする必要があります。

よく使われる三つの構成は次のとおりです。

| 構成            | 設定                                                                                        | 適した用途                                  |
| ------------- | ----------------------------------------------------------------------------------------- | -------------------------------------- |
| 社外向けカスタマーサポート | ナレッジベースのみ接続し、ファイルワークスペースは <mark style="color:blue;">使用しない</mark> にします                     | 公式サイト、LINE、API 連携での Q\&A に適しています       |
| プロジェクトアシスタント  | 規程や FAQ 用のナレッジベースを接続し、プロジェクトの元ファイル用に <mark style="color:blue;">ワークスペースを紐付ける</mark> を設定します | 同じチームが内部会話で規程を確認し、ドキュメントを作成する用途に適しています |
| 汎用の社内アシスタント   | ナレッジベースを接続し、ファイルワークスペースを <mark style="color:blue;">ユーザーが自分で接続する</mark> に設定します             | 各メンバーが自分のワークスペースを持ち込んで利用する用途に適しています    |

***

## お客様への説明例 <a href="#talking-points" id="talking-points"></a>

お客様への説明には、以下の表現を統一して使用することをお勧めします。

> **ナレッジベースは試験で使うカンニングペーパー、ファイルライブラリは宿題をするときに手元に置く教科書全体です。** 社外からの質問への回答は試験に似ており、最短で答えを見つけられるカンニングペーパーが必要なので、FAQ の整理やデータのクリーニングに手間をかけます。社内のドキュメント作成は宿題に似ており、元ファイル全体が必要で、保存すればそのまま使えます。

お客様からよく寄せられる追加の質問は次のとおりです。

* **「ファイルライブラリがあっても、ナレッジベースは必要ですか？」** 必要です。ファイルライブラリは MaiGPT と Agent の内部会話でのみ有効で、Web Widget、LINE、API 連携からは読み取れません。また、回答のたびにファイル全体を読むため、高頻度の Q\&A では遅くなり、コストも高くなります。
* **「ナレッジベースでもファイル全体を読めるのではありませんか？」** 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/ja/quickstart/rag.md)：ナレッジベースの解析、検索、調整可能なパラメーターを説明します
* [Function Calling](https://docs.maiagent.ai/tech/ja/advanced-genai-tech/function-calling.md)：Agent モードのツール呼び出しと実行上限を説明します
* [ファイルライブラリの Office オンライン編集（ONLYOFFICE Docs 連携）](https://docs.maiagent.ai/tech/ja/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/ja/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.
