Presigned 檔案上傳模式

檔案串接上傳檔案

目前在 MaiAgent 上需要上傳檔案的地方有兩處

1. 知識庫文件上傳

2. 訊息用到的附件上傳

Presigned 上傳模式

MaiAgent 支援 Presigned 上傳模式，此模式允許客戶端直接將檔案上傳至雲端儲存（如 S3），而不需經過伺服器中繼。使用此模式時，伺服器僅負責生成具有時效性與安全性的 Presigned URL，客戶端利用該 URL 直接進行檔案上傳。

與傳統上傳模式的差異：

1. 資料流向

   • 傳統模式：檔案須經過伺服器，再由伺服器上傳到雲端儲存。

   • Presigned 模式：檔案由客戶端直接上傳至雲端，避免伺服器處理檔案的負擔。

2. 效能與成本

   • 傳統模式可能導致伺服器資源消耗過大，並增加資料傳輸成本。

   • Presigned 模式減少伺服器負載，提高效能並降低傳輸成本。

3. 安全性

   • Presigned URL 包含簽名與有效期，確保上傳請求僅限於授權用戶在指定時間內使用。

此模式特別適合大檔案或高頻率上傳的場景，提升效率的同時保持高度的安全性。

預簽上傳流程圖

傳統上傳流程圖

---

Presigned 上傳檔案

以下描述如何使用 MaiAgent 提供的 API 完成檔案的 Presigned 上傳過程。

1. 取得 Presigned URL

Endpoint

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

說明

客戶端向伺服器發送請求，取得一個 Presigned URL，該 URL 用於直接上傳檔案至雲端儲存。

請求參數

參數名稱	型別	必填	說明
filename	string	是	上傳檔案的名稱
modelName	string	是	模組名稱，用於分類上傳的檔案用途 知識庫請填寫chatbot-file 訊息附件請填寫attachment
fieldName	string	是	檔案字段名稱，用於標識檔案用途
fileSize	integer	是	檔案大小（以位元組為單位）

範例請求

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

回應範例

{
    "url": "https://s3.ap-northeast-1.amazonaws.com/whizchat-media-prod-django.playma.app",
    "fields": {
        "key": "media/chatbots/chatbot-file/d83c88aa-3874-49a6-b01e-1948ae48b747.xlsx",
        "x-amz-algorithm": "AWS4-HMAC-SHA256",
        "x-amz-credential": "AKIATIVCN4X5JXWAP43M/20241129/ap-northeast-1/s3/aws4_request",
        "x-amz-date": "20241129T012318Z",
        "policy": "eyJleHBpcmF0aW9uIjogIjIwMjQtMTEtMjlUMDI6MjM6MThaIiwgImNvbmRpdGlvbnMiOiBbWyJjb250ZW50LWxlbmd0aC1yYW5nZSIsIDAsIDEwNDg1NzYwMF0sIHsiYnVja2V0IjogIndoaXpjaGF0LW1lZGlhLXByb2QtZGphbmdvLnBsYXltYS5hcHAifSwgeyJrZXkiOiAibWVkaWEvY2hhdGJvdHMvY2hhdGJvdC1maWxlL2Q4M2M4OGFhLTM4NzQtNDlhNi1iMDFlLTE5NDhhZTQ4Yjc0Ny54bHN4In0sIHsieC1hbXotYWxnb3JpdGhtIjogIkFXUzQtSE1BQy1TSEEyNTYifSwgeyJ4LWFtei1jcmVkZW50aWFsIjogIkFLSUFUSVZDTjRYNUpYV0FQNDNNLzIwMjQxMTI5L2FwLW5vcnRoZWFzdC0xL3MzL2F3czRfcmVxdWVzdCJ9LCB7IngtYW16LWRhdGUiOiAiMjAyNDExMjlUMDEyMzE4WiJ9XX0=",
        "x-amz-signature": "0254b3baa65c3a69eaeeccd0a3d027bc7952c1587cc96437c096eb1b76e1d692"
    }
}

---

2. 上傳檔案至雲端儲存

說明

使用從上述步驟取得的 url 和 fields，直接將檔案上傳至雲端儲存。

範例請求

curl --location 'https://s3.ap-northeast-1.amazonaws.com/whizchat-media-prod-django.playma.app' \
--form 'key="media/chatbots/chatbot-file/d83c88aa-3874-49a6-b01e-1948ae48b747.xlsx"' \
--form 'x-amz-algorithm="AWS4-HMAC-SHA256"' \
--form 'x-amz-credential="AKIATIVCN4X5JXWAP43M/20241129/ap-northeast-1/s3/aws4_request"' \
--form 'x-amz-date="20241129T012318Z"' \
--form 'policy="eyJleHBpcmF0aW9uIjogIjIwMjQtMTEtMjlUMDI6MjM6MThaIiwgImNvbmRpdGlvbnMiOiBbWyJjb250ZW50LWxlbmd0aC1yYW5nZSIsIDAsIDEwNDg1NzYwMF0sIHsiYnVja2V0IjogIndoaXpjaGF0LW1lZGlhLXByb2QtZGphbmdvLnBsYXltYS5hcHAifSwgeyJrZXkiOiAibWVkaWEvY2hhdGJvdHMvY2hhdGJvdC1maWxlL2Q4M2M4OGFhLTM4NzQtNDlhNi1iMDFlLTE5NDhhZTQ4Yjc0Ny54bHN4In0sIHsieC1hbXotYWxnb3JpdGhtIjogIkFXUzQtSE1BQy1TSEEyNTYifSwgeyJ4LWFtei1jcmVkZW50aWFsIjogIkFLSUFUSVZDTjRYNUpYV0FQNDNNLzIwMjQxMTI5L2FwLW5vcnRoZWFzdC0xL3MzL2F3czRfcmVxdWVzdCJ9LCB7IngtYW16LWRhdGUiOiAiMjAyNDExMjlUMDEyMzE4WiJ9XX0="' \
--form 'x-amz-signature="0254b3baa65c3a69eaeeccd0a3d027bc7952c1587cc96437c096eb1b76e1d692"' \
--form 'file=@"/Users/maiagent/Downloads/Products_example.png"'

---