> 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/maiagent-user-guide/ja/build/knowledge-base/km.md).

# ナレッジベースの概要

ナレッジベースの概要：ナレッジベースとは何か、できること（ドキュメント、FAQ、Web コンテンツの検索に基づく質問応答）、ファイルのアップロードとナレッジベースの作成への入口を説明します。

## ナレッジベースとは？ <a href="#what-is-knowledge-base" id="what-is-knowledge-base"></a>

ナレッジベースは、Agent が質問に回答する際の情報源です。Agent はまず、質問に最も関連するチャンクをナレッジベースから検索し、その内容に基づいて回答します。Agent のタスクに関連する内容のみをアップロードしてください。無関係なデータが参考情報として使われると、回答の精度が低下する場合があります。検索の仕組みについては、[技術者マニュアル - RAG ナレッジベース検索システム](https://docs.maiagent.ai/tech/quickstart/rag)をご覧ください。

## ナレッジベースでできること <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>」です。[検索テスト](/maiagent-user-guide/ja/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 モデル、検索チャンク数など                                                                  | [ナレッジベースの作成方法：基本設定](/maiagent-user-guide/ja/build/knowledge-base/km-basic-settings.md) |
| <mark style="color:blue;">ドキュメント</mark>                                        | ドキュメントのアップロード、表示、編集、一括操作                                                                                  | このページ                                                                                  |
| <mark style="color:blue;">FAQ よくある質問</mark>                                    | 質問と回答のペア                                                                                                  | [FAQ の作成方法](/maiagent-user-guide/ja/build/knowledge-base/faq.md)                       |
| <mark style="color:blue;">タグ管理</mark>、<mark style="color:blue;">メタデータ管理</mark> | 使用できるタグとメタデータフィールドの定義                                                                                     | [ドキュメント管理：タグとメタデータ](/maiagent-user-guide/ja/build/knowledge-base/tags-and-metadata.md) |
| <mark style="color:blue;">AI 検索</mark>                                         | 質問による検索結果のテスト、AI 要約の追加                                                                                    | [検索テスト](/maiagent-user-guide/ja/build/knowledge-base/test-search-result.md)            |
| <mark style="color:blue;">API 連携</mark>                                        | プログラムでドキュメントをアップロードし、このナレッジベースを検索するための説明とサンプルです。ナレッジベース ID、使用する Embedding／Reranker モデル、関連する Agent が入力済みです | [開発者ツール](/maiagent-user-guide/ja/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>」をクリックします（まだ作成していない場合は、先に[ナレッジベースの作成方法：基本設定](/maiagent-user-guide/ja/build/knowledge-base/km-basic-settings.md)をご覧ください）
3. 設定ページに入ったら、左側の「<mark style="color:blue;">ドキュメント</mark>」をクリックします
4. ページ右上の青い「<mark style="color:blue;">ファイルをアップロード</mark>」ボタンをクリックし、Agent に参照させたい情報をアップロードします

<figure><img src="https://2584873290-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FTvHx8hgwYGDTLD3A7xoW%2Fuploads%2Fgit-blob-072720130209ef8453f2ca21a6a95c8b6296dec4%2Fknowledge-base-epub-upload-dialog.png?alt=media" alt="ナレッジベースのアップロード画面の対応形式には EPUB が含まれます"><figcaption><p>アップロード画面には EPUB とその他の対応ファイル形式が表示されます</p></figcaption></figure>

{% hint style="info" %}

* ナレッジベースの容量はプランによって異なります
* ファイルが大きい場合やデータ量が多い場合、アップロード後の処理に時間がかかることがあります。
  {% endhint %}

<figure><img src="https://2584873290-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FTvHx8hgwYGDTLD3A7xoW%2Fuploads%2Fgit-blob-12fa488c87c8faad401ab5aa06df2f0ab7c7d431%2Fimage%20(194)%20(1).png?alt=media" alt=""><figcaption></figcaption></figure>

「<mark style="color:blue;">処理状況</mark>」欄で進捗を確認できます。

<figure><img src="https://2584873290-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FTvHx8hgwYGDTLD3A7xoW%2Fuploads%2Fgit-blob-5e2300562aa874f413e7b2d4f271e2a6c06aaeb9%2F%E8%9E%A2%E5%B9%95%E6%93%B7%E5%8F%96%E7%95%AB%E9%9D%A2%202025-09-26%20175144.png?alt=media" alt=""><figcaption></figcaption></figure>

### ドキュメント一覧の項目と処理状況 <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>」で絞り込めます。項目には、ファイル名、ファイル形式、ファイルサイズ、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> | 削除が完了していません                | もう一度削除します。失敗が続く場合は MaiAgent にお問い合わせください                                                                                                                                  |

{% hint style="success" %}
現在、ナレッジベースは以下のファイル形式に対応しています。

* 表計算ドキュメント：`.xls, .xlsx, .csv, .ods`
* ワープロドキュメント：`.doc, .docx, .odt, .pdf, .md, .txt`
* プレゼンテーション：`.ppt, .pptx, .odp`
* Web ドキュメント：`.html, .htm`
* データ形式：`.json, .jsonl`
* 電子書籍：`.epub`
* 音声ファイル：`.wav, .mp3, .m4a, .aac`
* 動画ファイル：`.mp4`
  {% endhint %}

Outlook の `.pst`（メールボックスのアーカイブ）と `.msg`（個別のメール）はアップロードできません。メールをナレッジベースに追加するには、メールソフトで `.eml` または PDF として保存してからアップロードしてください。拡張子の完全な一覧は、[技術者マニュアル - Parser 解析ツール](https://docs.maiagent.ai/tech/quickstart/parser#document-parsers)をご覧ください。

### 構造化ファイルの行数上限 <a href="#table-row-limit" id="table-row-limit"></a>

CSV、Excel、JSON、JSONL などの表形式ファイルでは、アップロード画面で最初に行数が計算されます（「行数を計算中…」と表示されます）。1000 行を超えるファイルは一覧に行数が表示されます。<mark style="color:blue;">アップロード</mark>をクリックすると「<mark style="color:blue;">ファイルの行数が推奨上限を超えています</mark>」画面が開き、上限超過または読み取り不能のファイルが一覧表示され、次の3つの選択肢が提示されます。

| ボタン                                           | 動作                                                                                                                                                                                                 |
| --------------------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| <mark style="color:blue;">データベースを使用</mark>    | <mark style="color:blue;">データベース</mark>機能に移動し、Text to SQL で検索できるテーブルとしてファイルをアップロードします。[データベースの作成と設定](/maiagent-user-guide/ja/build/database/create-database.md#upload-file-to-create-table)をご覧ください |
| <mark style="color:blue;">問題のあるファイルを削除</mark> | 上限超過または読み取り不能のファイルを今回のアップロード一覧から除外し、残りのファイルのみをアップロードします                                                                                                                                            |
| <mark style="color:blue;">そのままアップロード</mark>   | 通常どおりアップロードします。ファイルは多数のチャンクに分割され、表全体の集計や絞り込みを伴う質問では検索精度が低くなります                                                                                                                                     |

判断の目安：「特定の行の内容」（例：ある商品の仕様）を尋ねる場合は、ナレッジベースで問題ありません。「何件あるか」「どれが条件に合うか」「合計や並べ替え」など、表全体を調べる必要がある質問には、データベースを使用してください。

#### ナレッジベースでの表ファイルの分割と引用 <a href="#table-file-chunking" id="table-file-chunking"></a>

MaiAgent Parser で CSV、Excel（`.xls`、`.xlsx`、`.ods`）を解析する場合：

* 各ワークシートは1つの Markdown テーブルに変換されます（CSV はファイル全体で1つの表です。複数のワークシートがある場合は、各表の前にワークシート名が見出しとして追加されます）。最初の行がヘッダーになります。
* 1つのファイルから読み取るのは先頭 5,000 行までです。それ以降の行はナレッジベースに入りません。
* 変換した表は、通常のドキュメント分割ルールに従ってチャンクに分割されます。**1行が独立した検索単位になるわけではありません**。1つのチャンクには通常、連続する複数行が含まれ、ヘッダーは表の先頭のチャンクにのみ含まれます。検索と引用はチャンク単位で行われ、引用元は該当行を含むチャンクを指し、行番号は表示されません。
* 非表示の行やワークシートも読み取られます。Agent に渡したくないデータは、あらかじめ削除してください。

各行を個別に検索・引用できるようにするには、各行を1件の FAQ に整理してください（[Excel 一括インポート](/maiagent-user-guide/ja/build/knowledge-base/faq.md#bulk-import-faq-excel)を利用できます）。または、[データベース](/maiagent-user-guide/ja/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>

ナレッジベースにアップロードされたデータはチャンクに分割されます。これには以下の利点があります。

* **検索精度の向上**：小さなチャンクがクエリにより正確に一致し、無関係な内容の影響を防ぎます
* **応答速度の最適化**：処理が速くなり、計算リソースの消費を抑えます
* **内容の関連性の向上**：各チャンクが1つのテーマに集中し、より的確な情報を提供します
* **保守・管理の容易さ**：更新、追跡、品質管理がしやすくなります
* **AI モデルの制限への対応**：入力長の上限超過を防ぎ、情報の完全性を確保します

#### チャンクの内容の編集・表示 <a href="#edit-view-chunk-content" id="edit-view-chunk-content"></a>

ドキュメントのチャンクを確認できます。

1. ナレッジベースのドキュメントページに入り、「<mark style="color:blue;">編集</mark>」をクリックします
2. 分割された内容を確認し、表示したいチャンクをクリックします

画面には、このチャンクの全内容が Markdown 形式で表示されます。ドキュメント詳細ページでは、次の2つの表示を切り替えられます。

* <mark style="color:blue;">Chunk カード</mark>：チャンクごとに1枚のカードで文字数とヒット数を表示します。開くとチャンクの内容を編集できます。
* <mark style="color:blue;">ドキュメント全体</mark>：すべてのチャンクを原文の順に結合して1つのドキュメントに戻し、右側のトラックで各 chunk の範囲を示します。<mark style="color:blue;">chunk マーカーを表示</mark>を有効にすると、奇数と偶数の chunk を異なる背景色で区別します。琥珀色の背景の段落は隣接する2つの chunk に属しています（overlap にあたり、表示は1回のみです）。トラックにマウスを合わせると、その chunk の全範囲が強調表示されます。「1つの文が2つのチャンクの間で分割されていないか」を確認する際に、最も直感的な表示です。

<div><figure><img src="https://2584873290-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FTvHx8hgwYGDTLD3A7xoW%2Fuploads%2Fgit-blob-41e18fc4ea11f8fde9c16945dc0f8db37db8607d%2Fimage%20(158).png?alt=media" alt=""><figcaption></figcaption></figure> <figure><img src="https://2584873290-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FTvHx8hgwYGDTLD3A7xoW%2Fuploads%2Fgit-blob-3b62b64ce2512088b08c4e9614367c2a2b6ee433%2Fimage%20(160).png?alt=media" alt=""><figcaption></figcaption></figure></div>

#### 元のドキュメントの編集 <a href="#edit-source-document" id="edit-source-document"></a>

1. 編集ページで「<mark style="color:blue;">ドキュメントを表示</mark>」をクリックします

<figure><img src="https://2584873290-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FTvHx8hgwYGDTLD3A7xoW%2Fuploads%2Fgit-blob-33f80dbb3c38ad40757d626d7e6d57de5a2e3d59%2F%E8%9E%A2%E5%B9%95%E6%93%B7%E5%8F%96%E7%95%AB%E9%9D%A2%202025-08-20%20094550.png?alt=media" alt=""><figcaption></figcaption></figure>

2. 編集ページに移動すると、テキストボックスにドキュメントの Markdown が表示されます

テキストボックスで元のドキュメントを編集できます。すべてのファイル形式でこの方法を利用できます。編集が終わったら「<mark style="color:blue;">保存</mark>」をクリックして変更を保存します。

<div><figure><img src="https://2584873290-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FTvHx8hgwYGDTLD3A7xoW%2Fuploads%2Fgit-blob-0fdbaef7bd72e5fdb9692c1ac8134456a26ea90e%2F%E8%9E%A2%E5%B9%95%E6%93%B7%E5%8F%96%E7%95%AB%E9%9D%A2%202025-08-20%20094933.png?alt=media" alt=""><figcaption></figcaption></figure> <figure><img src="https://2584873290-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FTvHx8hgwYGDTLD3A7xoW%2Fuploads%2Fgit-blob-0fdbaef7bd72e5fdb9692c1ac8134456a26ea90e%2F%E8%9E%A2%E5%B9%95%E6%93%B7%E5%8F%96%E7%95%AB%E9%9D%A2%202025-08-20%20094933.png?alt=media" alt=""><figcaption></figcaption></figure></div>

{% 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>**タブ**：文ごとに時間、話者、内容を表示します。<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;">TXT をダウンロード</mark>（プレーンテキスト、閲覧や編集向け）または<mark style="color:blue;">SRT をダウンロード</mark>（タイムライン付きの字幕形式）を選択できます。

Agent が検索するのは文字起こしのテキストです。認識ミスを修正するには、上記の[元のドキュメントの編集](#edit-source-document)の手順でチャンクを編集してください。音声の文字起こし料金については、[Credits 料金制度](/maiagent-user-guide/ja/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>    | はい       | 選択したファイルを別のナレッジベースに移動します。[ナレッジベースのファイル移動](/maiagent-user-guide/ja/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" %}
パーサーを変更すると、選択したすべてのファイルが直ちに再解析され、新しいパーサーの課金ルールに従って再度課金されます。課金方法については、[使用量の計算](/maiagent-user-guide/ja/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 監視](/maiagent-user-guide/ja/build/agent-ops/evaluations.md)から会話をエクスポートしてください。
* **処理中のドキュメントも削除できます**：「初期化中」または「処理中」のドキュメントを削除すると、解析ジョブは自動的に停止し、追加の Credits は差し引かれません。
* **元に戻せません**：内容を復元するには再アップロードが必要で、解析とベクトル化の料金が再度発生します。

### タグとメタデータの一括管理 <a href="#batch-manage-labels-metadata" id="batch-manage-labels-metadata"></a>

この2つのボタンは、事前にファイルを選択する必要はありません。どちらも「ダウンロード → 編集 → アップロード」の同じ手順で、このナレッジベースの**すべて**のファイルをまとめて処理します。

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>」で作成し、新しいテンプレートをダウンロードしてください。タグとメタデータの説明は、[ドキュメント管理：タグとメタデータ](/maiagent-user-guide/ja/build/knowledge-base/tags-and-metadata.md)をご覧ください。
{% endhint %}

## よくある質問 <a href="#faq" id="faq"></a>

### ナレッジベース内にフォルダーを作れますか？ <a href="#faq-folders" id="faq-folders"></a>

ナレッジベースにはフォルダーや入れ子のディレクトリはなく、すべてのドキュメントが1つの一覧に表示されます。分類には次の2つの方法があります。

* **同じナレッジベース内で分類する**：タグとメタデータを付け、タグで絞り込むか Agent の検索範囲を制限します。[ドキュメント管理：タグとメタデータ](/maiagent-user-guide/ja/build/knowledge-base/tags-and-metadata.md)と[ナレッジベースのタグフィルタリング](/maiagent-user-guide/ja/build/agent/label-filter.md)をご覧ください。
* **権限や検索設定を分けて管理する**：複数のナレッジベースに分け、同じ Agent に複数のナレッジベースを関連付けます。[1つの Agent で複数のナレッジベースを使用する](/maiagent-user-guide/ja/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)してください。クローラーからインポートするページでは、URL が重複したときにスキップするか上書きするかを別途選択できます。[クロールしたページの手動インポート](/maiagent-user-guide/ja/build/knowledge-base/scrape-website.md#manual-import)をご覧ください。

### チャンクサイズ（chunk size）と重複（overlap）は調整できますか？ <a href="#faq-chunk-size" id="faq-chunk-size"></a>

ナレッジベース設定ページにはチャンクサイズと重複の設定はなく、ドキュメントの分割方法は選択したパーサーによって決まります。検索結果が十分でない場合は、次の項目を調整できます。

* **パーサー**：別のパーサーで再解析すると、異なるチャンクが生成されます。[パーサー（Parser）とは？](/maiagent-user-guide/ja/build/knowledge-base/km-basic-settings.md#what-is-parser)をご覧ください
* **検索チャンク数**：各回答で参照するチャンクの数です。デフォルトは 12 です。[検索チャンク](/maiagent-user-guide/ja/build/knowledge-base/km-basic-settings.md#retrieval-chunk)をご覧ください
* **類似度のしきい値と Reranker**：関連性が不十分なチャンクを除外します。[類似度のしきい値](/maiagent-user-guide/ja/build/knowledge-base/km-basic-settings.md#similarity-cutoff)をご覧ください
* **チャンクの内容そのもの**：各チャンクが単独で理解できるように、チャンクや元のドキュメントを直接編集します。[チャンクの内容の編集・表示](#edit-view-chunk-content)をご覧ください

調整後は、同じ質問セットで[検索テスト](/maiagent-user-guide/ja/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 メールは `.eml` または PDF、Pages／Keynote などは `.docx`／`.pptx`／PDF、プレーンテキスト系の形式は `.txt` または `.md` として保存します。

### Markdown、HTML、クローラーからインポートした Web ページの書式は保持されますか？ <a href="#faq-format-preservation" id="faq-format-preservation"></a>

ナレッジベースは**元のファイルを保持します**（ドキュメント詳細や引用元からダウンロードできます）が、検索には解析後のテキストを使用します。すべての形式のドキュメントは Markdown テキストに変換してからチャンクに分割され、「ドキュメントを表示」で表示されるのはこの Markdown です。

* **`.md`**：内容はそのまま Markdown として扱われます。見出しの階層、リスト、表はチャンクのテキストに保持され、画像は `![]()` リンクとしてテキスト内に残ります。
* **`.html`／`.htm`**：MaiAgent Parser (Offline) によって Markdown に変換されます。見出しと表は Markdown の見出しと表に変換され、ナビゲーションバーやスクリプトなど、本文以外の要素は除去されます。
* **クローラーでインポートした Web ページ**：インポート時点で、ページの主要な内容はすでに Markdown になっています（[クローラーの使い方](/maiagent-user-guide/ja/build/knowledge-base/scrape-website.md#results-and-import-history)を参照）。ファイル名はページのタイトルに `.md` を付けたものになります。システムは元の URL をこのドキュメントの `url` メタデータに自動的に書き込みます。そのため、Agent がこのドキュメントを引用すると、ユーザーが引用をクリックした際に元の Web ページが直接開きます。また、`crawl_source`、`crawl_executed_at`、`crawl_version` の3つのシステムメタデータに、元のクロールリクエスト、インポート日時、上書き回数が記録されます。これらのフィールドはモデルには送信されません。

見出しのテキストはチャンクに残りますが、チャンクには「所属するセクション」の構造情報がありません。Agent が回答時にセクション名やトピックを示せるようにするには、各チャンクの内容が単独で理解できることを確認するか、セクション名を[メタデータ](/maiagent-user-guide/ja/build/knowledge-base/tags-and-metadata.md)に記載して「検索時に使用」を有効にしてください。

### 重複する内容や矛盾する内容をシステムが自動的に検出しますか？ <a href="#faq-duplicate-content" id="faq-duplicate-content"></a>

検出しません。ナレッジベースはドキュメント間の内容を比較しません。重複してアップロードした場合や、新旧のバージョンが共存している場合、両方の内容が検索されて Agent に渡され、Agent が旧版と新版を同時に引用する可能性があります。自動的な重複排除は、クローラーでインポートする際に URL に基づいて行われるもののみです（スキップ／上書き／重複を許可）。[クローラーの使い方](/maiagent-user-guide/ja/build/knowledge-base/scrape-website.md#step-execution)を参照してください。推奨する方法は次のとおりです。

* [メタデータ](/maiagent-user-guide/ja/build/knowledge-base/tags-and-metadata.md)でバージョンとステータスを記録し、ドキュメントを更新する際は古いファイルを削除してからアップロードするか、[元のドキュメントを編集](#edit-source-document)してください。
* [検索テスト](/maiagent-user-guide/ja/build/knowledge-base/test-search-result.md)に一般的な質問を入力し、同じ質問で内容が一致しない複数のチャンクが同時にヒットするか確認してください。
* [会話プラットフォーム分析](/maiagent-user-guide/ja/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 ページが公開 Web ページの場合は、[クローラー](/maiagent-user-guide/ja/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/maiagent-user-guide/ja/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.