檔案上傳知識庫
檔案文件串接
Endpoint
POST https://api.maiagent.ai/api/knowledge-bases/{knowledgeBasePk}/files/
說明
上傳完成後，將檔案相關資訊提交至知識庫進行記錄和處理。
路徑參數
knowledgeBasePk
string
是
知識庫ID（UUID格式）
請求參數
files
array
是
包含檔案資訊的陣列
files[].file
string
是
檔案在雲端儲存的路徑
files[].filename
string
是
使用者希望保存的檔案名稱
files[].knowledgeBase
string
否
知識庫ID（UUID格式） 主要用途：此參數主要用於 API 的向下相容性和驗證目的（可以省略此參數）
files[].parser
string
否
解析器ID（UUID格式）
files[].labels
array
否
標籤陣列
files[].labels[].id
string
否
標籤ID（UUID格式）
files[].labels[].name
string
否
標籤名稱
files[].rawUserDefineMetadata
object
否
使用者自定義的元資料
範例請求
curl --location 'https://api.maiagent.ai/api/knowledge-bases/550e8400-e29b-41d4-a716-446655440000/files/' \
--header 'Authorization: Api-Key YOUR_API_KEY' \
--header 'Content-Type: application/json' \
--data '{
"files": [
{
"filename": "Products_example.xlsx",
"file": "media/chatbots/chatbot-file/d83c88aa-3874-49a6-b01e-1948ae48b747.xlsx",
"knowledgeBase": "550e8400-e29b-41d4-a716-446655440000",
"parser": "550e8400-e29b-41d4-a716-446655440000",
"labels": [
{
"id": "550e8400-e29b-41d4-a716-446655440000",
"name": "產品資料"
}
],
"rawUserDefineMetadata": {
"department": "sales",
"category": "product_catalog"
}
}
]
}'回應範例
{
"count": 1,
"next": null,
"previous": null,
"results": [
{
"id": "19ed09f0-a791-42a5-841f-c44faad2ef8b",
"filename": "Products_example.xlsx",
"file": "https://whizchat-media-prod-django.playma.app/media/chatbots/chatbot-file/d83c88aa-3874-49a6-b01e-1948ae48b747.xlsx",
"fileType": "xlsx",
"knowledgeBase": "550e8400-e29b-41d4-a716-446655440000",
"size": 582,
"status": {
"code": "initial",
"message": "檔案已上傳，等待處理"
},
"parser": {
"id": "550e8400-e29b-41d4-a716-446655440000",
"name": "Excel 解析器",
"provider": {
"name": "default",
"version": "1.0"
},
"order": 1
},
"labels": [
{
"id": "550e8400-e29b-41d4-a716-446655440000",
"name": "產品資料"
}
],
"rawUserDefineMetadata": {
"department": "sales",
"category": "product_catalog"
},
"createdAt": "1728375369000"
}
]
}錯誤處理
API 可能會回傳以下錯誤狀態碼和錯誤訊息：
400 - 請求錯誤
必填欄位缺失
{
"files": ["This field is required."],
"filename": ["This field is required."],
"file": ["This field is required."]
}修復建議：檢查請求 JSON 結構，確保包含必填的 files 陣列，以及每個檔案項目都有 filename 和 file 欄位。
檔案格式錯誤
{
"files": [
{
"file": ["Invalid file path format."]
}
]
}修復建議：確認 file 欄位包含正確的檔案路徑格式。路徑應該是完整的雲端儲存路徑，例如：media/chatbots/chatbot-file/xxx.xlsx。
UUID 格式錯誤
{
"detail": "Invalid UUID format for knowledgeBasePk"
}修復建議：確認路徑中的 knowledgeBasePk 是有效的 UUID 格式（例如：550e8400-e29b-41d4-a716-446655440000）。可先調用知識庫列表 API 獲取正確的 ID。
檔案重複上傳
{
"detail": "此檔案已經上傳過知識庫，請勿重複上傳。"
}修復建議：該檔案（基於 files[].file 路徑）已存在於知識庫中。如果需要重新上傳相同內容的檔案，請先刪除舊檔案記錄；如果是更新檔案內容，需要重新上傳檔案到雲端儲存獲得新的 files[].file 路徑。
不支援的檔案類型
{
"detail": "不支援解析的檔案類型: .xyz"
}修復建議：檢查檔案副檔名是否在支援列表中（.pdf, .docx, .xlsx, .txt, .mp3 等）。如果檔案格式不支援，請轉換為支援的格式後重新上傳。
檔案大小超過限制
{
"detail": "File size must be less than or equal to 104857600 bytes"
}修復建議：檔案大小超過 100MB 限制。請壓縮檔案、分割為多個較小檔案，或刪除檔案中不必要的內容後重新上傳。
檔案內容類型錯誤
{
"detail": "Invalid content type for .exe, allowed: {'.pdf': 'application/pdf', '.docx': 'application/vnd.openxmlformats-officedocument.wordprocessingml.document'}"
}修復建議：檔案的實際格式與副檔名不符，或副檔名不被系統支援。請確認檔案格式正確，並使用正確的副檔名。
檔案未提供
{
"detail": "未提供檔案"
}修復建議：請求中缺少檔案內容。確認 file 欄位包含有效的檔案路徑，且檔案已正確上傳至雲端儲存。
401 - 認證失敗
API Key 無效或缺失
{
"detail": "Authentication credentials were not provided."
}修復建議：檢查請求標頭是否包含正確的 Authorization 欄位。格式應為：Authorization: Api-Key YOUR_API_KEY。
API Key 格式錯誤
{
"detail": "Invalid API key format."
}修復建議：確認 API Key 格式正確。檢查是否使用了正確的前綴 Api-Key 而非 Bearer，並確認 API Key 本身沒有多餘的空格或字元。
403 - 權限不足
組織檔案上傳限制
{
"detail": "The organization has reached the file upload limit"
}修復建議：組織已達到檔案上傳容量限制。請刪除不需要的檔案釋放空間，或聯繫管理員升級組織方案以獲得更多容量。
無權限訪問知識庫
{
"detail": "You do not have permission to access this knowledge base."
}修復建議：確認當前 API Key 所屬的使用者或組織有權限訪問該知識庫。聯繫管理員檢查權限設定，或使用有權限的 API Key。
404 - 資源不存在
知識庫不存在
{
"detail": "Knowledge base not found."
}修復建議：確認 knowledgeBasePk 參數正確。可先調用知識庫列表 API 確認該知識庫是否存在，或檢查是否已被刪除。
解析器不存在
{
"parser": ["Invalid pk \"invalid-uuid\" - object does not exist."]
}修復建議：檢查提供的解析器 ID 是否正確。可省略此欄位使用系統預設解析器，或調用解析器列表 API 獲取有效的解析器 ID。
標籤不存在
{
"labels": ["Some label IDs do not exist in this knowledge base."]
}修復建議：確認提供的標籤 ID 存在於指定的知識庫中。可先調用知識庫標籤列表 API 獲取有效的標籤 ID，或移除不存在的標籤 ID。
413 - 請求實體過大
檔案大小超過伺服器限制
{
"detail": "Request entity too large"
}修復建議：檔案大小超過伺服器可處理的上限。將檔案分割為多個較小的檔案，或使用檔案壓縮工具減少檔案大小後重新上傳。
422 - 無法處理的實體
檔案解析失敗（例如：Excel 檔案損壞）
{
"detail": "無法讀取 Excel 文件，嘗試以下引擎均失敗：\n- 預設引擎錯誤訊息\n- calamine 引擎錯誤訊息\n- xlrd 引擎錯誤訊息\n- openpyxl 引擎錯誤訊息"
}修復建議：檔案可能損壞或格式異常。嘗試用 Excel 或其他軟體開啟檔案並重新保存，或將內容複製到新檔案中重新上傳。
檔案編碼問題
{
"detail": "Unable to detect file encoding or file is corrupted"
}修復建議：檔案編碼異常或檔案損壞。對於文字檔案，請確認使用 UTF-8 編碼保存；對於其他檔案，請檢查檔案完整性並重新生成檔案。
500 - 伺服器錯誤
檔案處理失敗
{
"detail": "File processing failed due to internal server error."
}修復建議：伺服器內部錯誤，通常是臨時性問題。請稍候重試，如果問題持續發生，請聯繫技術支援並提供錯誤發生的時間和檔案資訊。
資料庫連接失敗
{
"detail": "Database connection failed"
}修復建議：伺服器資料庫連接問題，通常是臨時性問題。請稍候重試，如果問題持續發生，請聯繫技術支援。
Last updated
Was this helpful?