ナレッジベースの利用—作成と操作

本ガイドでは、公開 REST API を使用してナレッジベース内のファイルを管理する方法と、統合アプリケーションの例について説明します。

概要

MaiAgent は、開発者が API を通じてナレッジベースのファイルを管理できる機能を提供しています。開発者はワークスペース内で、ナレッジベースに対して以下の操作を行えます:

• 新しいファイルをナレッジベースにアップロードする

• ナレッジベース内のすべてのファイルを照会する

• 既存ファイルの情報を更新する

• 単一またはバッチでファイルを削除する

📘 重要なお知らせ

API を使用する際は、すべての操作で認証のために有効な API Key が必要です。お使いの API Key が該当する権限を備えていることをご確認ください。

---

ナレッジベースの操作

ナレッジベースの作成

ナレッジベースの利用を開始する前に、まず少なくとも1 つのナレッジベースを作成する必要があります。ナレッジベースを作成する際は、そのナレッジベースで使用する Embedding Model、Reranker Model、ナレッジベース名、およびこのナレッジベースを使用できる AI アシスタントなどの情報を指定する必要があります。

以上の設定情報は、スクリプト化して指定することができます。以下はナレッジベースを作成するリクエストの例です:

{
  "embeddingModel": "550e8400-e29b-41d4-a716-446655440000", // Embedding Model ID
  "rerankerModel": "550e8400-e29b-41d4-a716-446655440000", // Reranker Model ID
  "name": "内部トレーニングマニュアル",
  "description": "このナレッジベースは内部トレーニング用であり、ユーザーマニュアル、製品マニュアル、エラー対応マニュアルを含み、新人教育のみに使用します",
  "numberOfRetrievedChunks": 12, //  検索するチャンク数を指定
  "enableRerank": true,
  "chatbots": [
    {
      "id": "550e8400-e29b-41d4-a716-446655440000"
    }
  ],
  "groups": [
    {
      "id": "550e8400-e29b-41d4-a716-446655440000"
    }
  ]
}

送信して HTTPS レスポンスを取得できれば作成成功を意味し、このナレッジベースに対して操作を行えるようになります。

ID による単一ナレッジベースの操作

単一のナレッジベースに対してファイル管理を開始する前に、まずナレッジベースの一意の識別子(id)を取得する必要があります。

ナレッジベースの id を取得するには？

1. 作成したばかりのナレッジベースの id を取得する

スクリプトで作成したばかりのナレッジベースについては、作成完了後に HTTPS が id を含むレスポンスを返します。レスポンス内の id がそのナレッジベースの id 値を表します。

1. その他の作成済みナレッジベースの id を取得する

すべてのナレッジベースを取得するレスポンス内容から、必要とする対応するナレッジベースの id を取得できます。API ドキュメントをご参照ください: ナレッジベース(新版)

ナレッジベースのファイルを照会する

ファイル照会 エンドポイントは、ナレッジベース内のすべてのファイルを一覧表示するために使用できます。クエリパラメータを使用して特定のタイプ、ステータスのファイルを絞り込んだり、特定のキーワードを検索したりできます。照会したいナレッジベースの id をエンドポイント内の {knowledgeBasePK} の位置に追加すると、特定のナレッジベースに対して照会を行えます。

エンドポイント

GET /api/knowledge-bases/{knowledgeBasePk}/files/

ファイルステータス値(key 値は Status)

エンドポイントのレスポンスに基づいて、各ファイルの処理状況を確認できます。状況は以下のいくつかに分かれており、done と表示されていれば、ファイルの処理が完了し LLM が回答の検索に使用できる状態であることを意味します:

• initial - 初期化

• processing - 処理中

• done - 完了

• deleting - 削除中

• deleted - 削除済み

• failed - 失敗

このエンドポイントでは、fileType を設定して照会するファイルタイプを指定できます。例: pdf、docx、txt、xlsx など

例: すべての PDF ファイルを照会する

Shell/Bash

# API 呼び出し例 (Shell)
curl -X GET "https://api.maiagent.ai/api/knowledge-bases/550e8400-e29b-41d4-a716-446655440000/files/?fileType=example&knowledgeBase=550e8400-e29b-41d4-a716-446655440000&page=1&pageSize=1&query=example&status=deleted" \
  -H "Authorization: Api-Key YOUR_API_KEY"

# 実行前に YOUR_API_KEY を置き換え、リクエストデータをご確認ください。

---

ファイルの操作

ナレッジベースへのファイルのアップロード

エンドポイント

POST /api/knowledge-bases/{knowledgeBasePk}/files/

このエンドポイントを使用すると、ファイルを直接ナレッジベースにアップロードできます。アップロード時にパラメータを通じて、そのファイルの情報を指定できます。例:

• rawUserDefineMetadata: ファイルのメタデータ

• labels: ファイルの分類ラベル

例: 単一ファイルのアップロード—製品マニュアル

リクエスト構造の例

アップロードするファイル内容とナレッジベースを指定できます。

{
  "files": [
    {
      "filename": "製品マニュアル.pdf",
      "file": "https://my-product-bucket.s3.ap-northeast-1.amazonaws.com/products/laptop-dell-xps-15.jpg?X-Amz-Algorithm=AWS4-HMAC-SHA256&X-Amz-Credential=AKIAIOSFODNN7EXAMPLE%2F20251030%2Fap-northeast-1%2Fs3%2Faws4_request&X-Amz-Date=20251030T143000Z&X-Amz-Expires=3600&X-Amz-SignedHeaders=host&X-Amz-Signature=abcdef1234567890abcdef1234567890abcdef1234567890abcdef1234567890",
      "knowledgeBase": {
        "id": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
        "name": "内部トレーニングナレッジベース"
      },
      "parser": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
      "labels": [
        {
          "id": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
          "name": "新人トレーニング"
        }
      ],
    },
  ]
}

レスポンスには、新しく作成されたファイルオブジェクトが含まれ、システムが自動生成したファイル ID も含まれます。

複数のファイルを異なるナレッジベースにアップロードすることもできます。

例: 複数のファイルを異なるナレッジベースにアップロードする

{
  "files": [
    {
      "filename": "新人教育マニュアル.pdf",
      "file": "https://my-product-bucket.s3.ap-northeast-1.amazonaws.com/products/laptop-dell-xps-15.jpg?X-Amz-Algorithm=AWS4-HMAC-SHA256&X-Amz-Credential=AKIAIOSFODNN7EXAMPLE%2F20251030%2Fap-northeast-1%2Fs3%2Faws4_request&X-Amz-Date=20251030T143000Z&X-Amz-Expires=3600&X-Amz-SignedHeaders=host&X-Amz-Signature=abcdef1234567890abcdef1234567890abcdef1234567890abcdef1234567891",
      "knowledgeBase": {
        "id": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
        "name": "内部トレーニングナレッジベース"
      },
    },
    {
      "filename": "D256 製品説明ドキュメント.pdf",
      "file": "https://my-product-bucket.s3.ap-northeast-1.amazonaws.com/products/laptop-dell-xps-15.jpg?X-Amz-Algorithm=AWS4-HMAC-SHA256&X-Amz-Credential=AKIAIOSFODNN7EXAMPLE%2F20251030%2Fap-northeast-1%2Fs3%2Faws4_request&X-Amz-Date=20251030T143000Z&X-Amz-Expires=3600&X-Amz-SignedHeaders=host&X-Amz-Signature=abcdef1234567890abcdef1234567890abcdef123456",
      "knowledgeBase": {
        "id": "3fa85f64-5717-4562-b3fc-2c963f655o2l1",
        "name": "対外カスタマーサポートデータベース"
      },
    }
  ]
}

ご注意ください: 単一ファイルの上限は 100MB を超えることはできません。超えた場合は正しく処理されず、HTTP がエラーメッセージを返します。

既存ファイルの情報を更新する

ファイル情報更新 エンドポイントを使用して、アップロード済みファイルの情報(ファイル名、ラベル、カスタムメタデータなど)を変更できます。ファイルに更新がある場合、再アップロードする必要はなく、スクリプトを通じて直接情報を変更できます。

エンドポイント

PUT /api/knowledge-bases/{knowledgeBasePk}/files/{id}/

リクエスト例

{
  "filename": "製品マニュアル改訂版.pdf",
  "file": "https://ecommerce-products.s3.us-west-2.amazonaws.com/images/electronics/smartphones/iphone-15-pro-max-256gb-natural-titanium.png?X-Amz-Algorithm=AWS4-HMAC-SHA256&X-Amz-Credential=AKIAI44QH8DHBEXAMPLE%2F20251030%2Fus-west-2%2Fs3%2Faws4_request&X-Amz-Date=20251030T120000Z&X-Amz-Expires=7200&X-Amz-SignedHeaders=host&X-Amz-Security-Token=FwoGZXIvYXdzEBYaDH...truncated...&X-Amz-Signature=8c9d1e2f3a4b5c6d7e8f9a0b1c2d3e4f5a6b7c8d9e0f1a2b3c4d5e6f7a8b9c0d",
  "knowledgeBase": {
    "id": "550e8400-e29b-41d4-a716-446655440000"
  },
  "labels": [
    {
      "id": "550e8400-e29b-41d4-a716-446655440000",
    }
  ],
  "rawUserDefineMetadata": {
    "editDate": "2025/10/30",
    "lastEditBy": "Wang",
    "version": "online"
  }
}

ファイルの削除

単一ファイルの削除

エンドポイント

DELETE /api/knowledge-bases/{knowledgeBasePk}/files/{id}

このエンドポイントを使用すると、ナレッジベースから単一のファイルを削除できます。削除する際は、エンドポイントの {id} の位置に削除したいファイルの id を指定する必要があります。

例

Shell/Bash

# API 呼び出し例 (Shell)
curl -X DELETE "https://api.maiagent.ai/api/knowledge-bases/550e8400-e29b-41d4-a716-446655440000/files/550e8400-e29b-41d4-a716-446655440000/" \
  -H "Authorization: Api-Key YOUR_API_KEY"

# 実行前に YOUR_API_KEY を置き換え、リクエストデータをご確認ください。

正常に削除されると、API は 204 ステータスコードを返します。このファイルは、以後 LLM が回答の参考として使用できなくなります。

ファイルのバッチ削除

複数のファイルを一度に削除したい場合は、ファイルバッチ削除 エンドポイントを使用すると、管理効率を高められます。

エンドポイント

POST /api/knowledge-bases/{knowledgeBasePk}/files/batch-delete/

リクエスト例の値

{
  "ids": [
    "550e8400-e29b-41d4-a716-446655440000",
    "550e8400-e29b-41d4-a716-446655449198",  
    "kdlkjf029-e2b-41d4-adk06-dklwie091874"
  ]
}

複数のファイル id を渡すことで、システムが一度に複数のファイルを削除するのを助けます。

このエンドポイントは単一のナレッジベース内のファイルのみバッチ削除でき、ナレッジベースをまたいでバッチ削除を行うことはできません。

---

ユースケース

ナレッジベースファイル管理 API には、多くの実際の応用シーンがあります。例:

1. ドキュメント更新の自動化

製品ドキュメントが Git リポジトリで更新された際に、CI/CD フローを通じて最新バージョンを自動的にナレッジベースにアップロードできます。これにより、AI アシスタントが常に最新の製品情報にアクセスできるようになります。

フローの例

1

ドキュメント更新の commit を検出する

2

該当ファイルが既に存在するかを照会する

MaiAgent API を使用して、ナレッジベース内に一致するファイルがあるかを照会します。

3

ファイルを更新/アップロードする

存在する場合は情報の部分更新エンドポイントで更新し、存在しない場合はファイルアップロードエンドポイントで新しいファイルをアップロードします。

2. コンテンツ管理システムとの統合

MaiAgent をコンテンツ管理システム (CMS) として使用する場合は、管理画面を構築して、コンテンツ編集者が以下を行えるようにできます

• 新しいコンテンツファイルをアップロードする

• ラベルを使用してコンテンツを整理する

• 特定のタイプのコンテンツを検索・絞り込みする

• 期限切れコンテンツをバッチ削除する

---

まとめ

MaiAgent の公開 REST API を使用すると、ナレッジベースのファイルをより効率的に管理できます。具体的には:

• ナレッジベースの作成

• ファイルの照会と絞り込み

• 新しいファイルのアップロード

• ファイル情報の更新

• 単一またはバッチでのファイル削除

次のステップ

• 完全な API リファレンスドキュメントを確認して、MaiAgent API サービスの利用を開始しましょう

• MaiAgent WebChat SDK を探索して、API 統合を簡素化しましょう