Presigned ファイルアップロードモード

ファイル連携によるファイルアップロード

現在 MaiAgent でファイルのアップロードが必要となる箇所は 2 か所あります。

1. ナレッジベースへのドキュメントアップロード

2. メッセージで使用する添付ファイルのアップロード

Presigned アップロードモード

MaiAgent は Presigned アップロードモードに対応しています。このモードでは、クライアント側がサーバーを経由せずに、ファイルを直接クラウドストレージ（S3 など）へアップロードできます。このモードを使用する場合、サーバーは有効期限とセキュリティを備えた Presigned URL の生成のみを担当し、クライアントはその URL を利用して直接ファイルをアップロードします。

従来のアップロードモードとの違い：

1. データの流れ

   • 従来モード：ファイルはサーバーを経由し、サーバーがクラウドストレージへアップロードします。

   • Presigned モード：ファイルはクライアントから直接クラウドへアップロードされ、サーバーがファイルを処理する負担を回避できます。

2. パフォーマンスとコスト

   • 従来モードはサーバーリソースの消費が過大になり、データ転送コストが増加する可能性があります。

   • Presigned モードはサーバー負荷を軽減し、パフォーマンスを向上させ、転送コストを削減します。

3. セキュリティ

   • Presigned URL には署名と有効期限が含まれており、アップロードリクエストが認可されたユーザーによって指定された時間内にのみ使用されることを保証します。

このモードは、特に大容量ファイルや高頻度のアップロードのシーンに適しており、効率を高めると同時に高いセキュリティを維持できます。

事前署名アップロードのフロー図

従来のアップロードのフロー図

---

Presigned ファイルアップロード

以下では、MaiAgent が提供する API を使用してファイルの Presigned アップロードを完了する手順を説明します。ナレッジベースのシーンでは 3 つのステップ（Step 1 → 2 → 3）をすべて実行する必要があり、メッセージ添付ファイルのシーンでは Step 1 → 2 のみで完了します。

1. Presigned URL を取得する

Endpoint

POST https://api.maiagent.ai/api/v1/upload-presigned-url/

説明

クライアントはサーバーにリクエストを送信し、ファイルをクラウドストレージへ直接アップロードするための Presigned URL を取得します。

リクエストパラメータ

パラメータ名	型	必須	説明
filename	string	はい	アップロードするファイルの名前
modelName	string	はい	モジュール名。アップロードするファイルの用途を分類するために使用します ナレッジベースの場合はchatbot-fileを指定します メッセージ添付ファイルの場合はattachmentを指定します
fieldName	string	はい	ファイルフィールド名。ファイルの用途を識別するために使用します
fileSize	integer	はい	ファイルサイズ（バイト単位）。実際の binary サイズと完全に一致している必要があります。一致しない場合、Step 2 で S3 に拒否されます

リクエスト例

curl --location 'https://api.maiagent.ai/api/v1/upload-presigned-url/' \
--header 'Authorization: Api-Key YOUR_API_KEY' \
--header 'Content-Type: application/json' \
--data '{
    "filename": "document.pdf",
    "modelName": "chatbot-file",
    "fieldName": "file",
    "fileSize": 178329
}'

レスポンス例

{
    "url": "https://s3.ap-northeast-1.amazonaws.com/whizchat-media-prod-django.playma.app",
    "fields": {
        "key": "media/chatbots/chatbot-file/86572e41-16ba-45dd-b049-28c69f77ffb0.pdf",
        "x-amz-algorithm": "AWS4-HMAC-SHA256",
        "x-amz-credential": "ASIATIVCN4X5XXXXXXXX/20260522/ap-northeast-1/s3/aws4_request",
        "x-amz-date": "20260522T020727Z",
        "x-amz-security-token": "IQoJb3JpZ2luX2VjEEoa...（とても長い STS token）",
        "policy": "eyJleHBpcmF0aW9uIjog...（base64 policy）",
        "x-amz-signature": "617e10d1db034ab351d3735de5c56287ecc926dbfe5b5884d2ce67deed363004"
    }
}

Production 環境では AWS STS の短期認証情報を使用します（x-amz-credential は ASIA で始まります）。レスポンスの fields オブジェクトには x-amz-security-token フィールドが含まれます。Step 2 のアップロード時には、すべての fields フィールド（x-amz-security-token を含む）を一字一句漏れなく付与する必要があります。漏れがあると S3 に拒否されます。

Presigned URL の有効期限は約 1 時間です。取得後はできるだけ早く使用してください。

---

2. ファイルをクラウドストレージへアップロードする

説明

上記のステップで取得した url と fields を使用して、ファイルをクラウドストレージへ直接アップロードします。fields オブジェクト内のすべてのフィールドを必ず付与してください（x-amz-security-token を含む）。フィールドのリストをハードコードせず、今後 AWS が新しいフィールドを追加した場合でも、動的に組み立てることで漏れを防ぐことができます。

アップロードが成功すると、S3 は HTTP 204 No Content（空の body）を返します。

リクエスト例（curl、STS token を含む）

curl --location 'https://s3.ap-northeast-1.amazonaws.com/whizchat-media-prod-django.playma.app' \
--form 'key="media/chatbots/chatbot-file/86572e41-16ba-45dd-b049-28c69f77ffb0.pdf"' \
--form 'x-amz-algorithm="AWS4-HMAC-SHA256"' \
--form 'x-amz-credential="ASIATIVCN4X5XXXXXXXX/20260522/ap-northeast-1/s3/aws4_request"' \
--form 'x-amz-date="20260522T020727Z"' \
--form 'x-amz-security-token="IQoJb3JpZ2luX2VjEEoa..."' \
--form 'policy="eyJleHBpcmF0aW9uIjog..."' \
--form 'x-amz-signature="617e10d1db034ab351d3735de5c56287ecc926dbfe5b5884d2ce67deed363004"' \
--form 'file=@"/path/to/document.pdf"'

リクエスト例（Python、動的に組み立てる、推奨される方法）

import requests

# Step 1: 取得 Presigned URL
presign = requests.post(
    'https://api.maiagent.ai/api/v1/upload-presigned-url/',
    headers={'Authorization': 'Api-Key YOUR_API_KEY'},
    json={
        'modelName': 'chatbot-file',
        'fieldName': 'file',
        'filename': 'document.pdf',
        'fileSize': 178329,
    },
).json()

# Step 2: 把 fields 整個塞，所有欄位（含 x-amz-security-token）自動帶上
with open('/path/to/document.pdf', 'rb') as f:
    s3_response = requests.post(
        presign['url'],
        data=presign['fields'],
        files={'file': f},
    )
assert s3_response.status_code == 204, s3_response.text

file_key = presign['fields']['key']  # Step 3 要用的值

---

3. ファイルをナレッジベースに登録する（ナレッジベースのシーンのみ必要）

Endpoint

POST https://api.maiagent.ai/api/v1/knowledge-bases/{knowledgeBasePk}/files/

説明

Step 2 が完了すると、ファイルの binary は S3 に存在しますが、まだナレッジベースには登録されていません。この API を呼び出してアップロード結果を KnowledgeBaseFile として登録することで、システムが解析・分割・インデックス作成を開始します。

file フィールドには Step 1 のレスポンスの fields.key（MaiAgent S3 内部の相対パス）を入力する必要があり、任意の外部 URL ではありません。外部 URL（例：パートナーシステムのダウンロードリンク）を受け取った場合は、まず GET でファイルをダウンロードしてから、Step 1 → 2 → 3 を実行してください。

パスパラメータ

パラメータ名	型	説明
knowledgeBasePk	string	ナレッジベースの一意の識別子（UUID）

リクエストパラメータ

パラメータ名	型	必須	説明
files	array	はい	作成するファイルのリスト。一度に複数をバッチ作成できます
files[].filename	string	はい	元のファイル名
files[].file	string	はい	Step 1 のレスポンスの fields.key（相対パス、URL ではありません）
files[].parser	string	いいえ	parser の UUID を指定します。指定しない場合はナレッジベースのデフォルトを使用します
files[].labels	array	いいえ	ファイルラベル（{id, name} オブジェクトの配列）
files[].rawUserDefineMetadata	object	いいえ	ユーザー定義の metadata

リクエスト例

curl --location 'https://api.maiagent.ai/api/v1/knowledge-bases/86401a64-ad89-4847-a709-f4ccfa0af7b9/files/' \
--header 'Authorization: Api-Key YOUR_API_KEY' \
--header 'Content-Type: application/json' \
--data '{
    "files": [
        {
            "filename": "document.pdf",
            "file": "media/chatbots/chatbot-file/86572e41-16ba-45dd-b049-28c69f77ffb0.pdf"
        }
    ]
}'

レスポンス例

[
    {
        "id": "86572e41-16ba-45dd-b049-28c69f77ffb0",
        "filename": "document.pdf",
        "file": "https://media.maiagent.ai/media/chatbots/chatbot-file/86572e41-16ba-45dd-b049-28c69f77ffb0.pdf",
        "fileType": "pdf",
        "knowledgeBase": {
            "id": "86401a64-ad89-4847-a709-f4ccfa0af7b9",
            "name": "私のナレッジベース"
        },
        "size": 178329,
        "status": "initial",
        "parser": {
            "id": "535c5b86-0534-4d0a-abfe-82f3d37e769a",
            "name": "MaiAgent Parser",
            "provider": "maiagent",
            "order": 0,
            "supportsDiarization": false
        },
        "labels": [],
        "rawUserDefineMetadata": {},
        "createdAt": "1779425272000"
    }
]

ファイルステータス（status）

値	説明
initial	作成直後、処理待ち
processing	解析・分割・インデックス作成中
done	処理完了、検索可能
failed	処理失敗

---

よくあるエラーとトラブルシューティング

Q：S3 が The AWS Access Key Id you provided does not exist in our records を返す

A：Step 2 で x-amz-security-token を付与し忘れているか、期限切れの access key / S3 endpoint をハードコードしています。必ず Step 1 でその都度返される url と fields を使用し、fields オブジェクト全体をそのまま Step 2 に付与してください。

Q：S3 が Policy Condition failed を返す

A：通常は Step 1 の fileSize が実際の binary サイズと一致していないことが原因です。実際のファイルサイズを再計算し、Step 1 をやり直してください。

Q：Step 3 が 400 を返し、file フィールドに問題があると表示される

A：file には Step 1 のレスポンスの fields.key（例：media/chatbots/chatbot-file/xxx.pdf）を入力する必要があります。Step 3 のレスポンスの full URL でも、任意の外部 URL でもありません。

Q：すでに外部 URL（例：パートナーシステムのダウンロードリンク）を持っていますが、そのまま Step 3 に渡せますか？

A：できません。Step 3 の file フィールドは MaiAgent 自社 S3 の相対 key です。まず GET でその外部 URL のファイルを取得してから、Step 1 → 2 → 3 を実行してください。

Q：Step 3 の後、ファイルがずっと status: processing のままです

A：解析時間はファイルのサイズやタイプによって異なり、大容量ファイルの場合は数分かかることがあります。GET /api/v1/knowledge-bases/{KB_ID}/files/{file_id}/ でステータスをポーリングし、done になって初めて AI 助理に検索されるようになります。