For the complete documentation index, see llms.txt. This page is also available as Markdown.

Presigned 檔案上傳模式

檔案串接上傳檔案

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

  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,該 URL 用於直接上傳檔案至雲端儲存。

請求參數

參數名稱
型別
必填
說明

filename

string

上傳檔案的名稱

modelName

string

模組名稱,用於分類上傳的檔案用途

知識庫請填寫chatbot-file

訊息附件請填寫attachment

fieldName

string

檔案字段名稱,用於標識檔案用途

fileSize

integer

檔案大小(以位元組為單位),必須與實際 binary 大小完全一致,否則 Step 2 會被 S3 拒絕

範例請求

回應範例


2. 上傳檔案至雲端儲存

說明

使用從上述步驟取得的 urlfields,直接將檔案上傳至雲端儲存。fields 物件中每一個欄位都必須帶上(包含 x-amz-security-token);不要寫死欄位清單,若 AWS 後續加新欄位,動態組裝可避免漏帶。

上傳成功時 S3 回應 HTTP 204 No Content(空 body)

範例請求(curl,含 STS token)

範例請求(Python,動態組裝,推薦做法)


3. 註冊檔案到知識庫(知識庫場景才需要)

Endpoint

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

說明

Step 2 完成後,檔案 binary 已在 S3,但還沒進入知識庫。需要呼叫此 API 把上傳結果註冊成 KnowledgeBaseFile,系統才會開始解析、切片、建索引。

路徑參數

參數名稱
型別
說明

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

範例請求

回應範例

檔案狀態(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 即時回傳的 urlfields,把 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 助理檢索。

Last updated

Was this helpful?