跳轉到

例外狀況處理

在 PrivAI 中，錯誤資訊分為兩種揭露方式：同步 API 錯誤回應 與 非同步背景流程錯誤資訊。

同步 API 錯誤回應

當錯誤發生在 API 請求驗證或同步處理階段時，系統會以以下格式回傳：

plain text { "error_message":"Error message in English", "error_code":"ERROR_CODE", ...(Inherent Payload) }

其中：

  • error_message：提供可讀性高的英文錯誤訊息

  • error_code：提供可程式化處理的錯誤代碼

  • Inherent Payload：依錯誤情境附帶的補充欄位，例如 state、file_ids、fileset_id、quality 等

若遇到 API 回傳此類錯誤，請查閱 9. 錯誤代碼說明。

常見同步錯誤情境

同步 API 錯誤通常包含以下類型：

  • 身份驗證失敗，例如缺少 Authorization header 或 API Key 無效

  • 請求參數格式錯誤，例如互斥欄位同時出現或 cursor 參數不合法

  • 指定的資源不存在，例如 file、fileset、prompt 不存在

  • 資源狀態不允許當前操作，例如 fileset 尚未完成、fileset 不可 commit 或不可 update

  • 請求內容不合法，例如上傳不支援的檔案格式或 messages 結構不符合規範

Chat Completions 與多 Filesets 的同步錯誤補充

在 Chat Completions API 中，若使用 RAG 功能，除了既有的 fileset 驗證外，也需注意以下規則：

  • fileset_id 與 fileset_ids 不可同時使用；若同時帶入，系統會回傳同步錯誤

  • fileset_ids 中任一 fileset 不存在、不可使用或狀態異常時，整個 request 會失敗

  • fileset_ids: [] 不視為錯誤，系統會視為未指定 fileset，不執行 RAG

非同步背景流程錯誤

當錯誤發生在 commit 已提交後的背景流程中，例如：

  • consumer 執行失敗

  • parse 失敗

  • split 失敗

  • indexing / embedding 失敗

  • 其他非同步後處理失敗

此類錯誤通常無法由當次 API response 即時回傳。

因此系統會將錯誤資訊寫入 File 或 Fileset 關聯資料中，供後續查詢。

建議使用下列 API 查看背景流程的實際處理結果與失敗資訊：

  • GET /v1/files/{file_id}

  • GET /v1/filesets/{fileset_id}

  • GET /v1/filesets/{fileset_id}/files

補充說明

非同步背景流程錯誤主要出現在知識版本建立與檔案處理流程中。

這類錯誤與一般聊天 API 的同步驗證錯誤不同，通常代表：

  • 請求本身已被接受

  • 但後續背景工作在執行過程中失敗

  • 因此需要改由查詢資源狀態與 metadata 來判斷實際失敗原因

若 Fileset 最終狀態為 failed、partial_failed 或 cancelled，建議再進一步查看相關 File 或 Fileset File 的失敗資訊。

fail_reason 與 fail_detail

為了讓使用者與工程師都能更快理解問題，系統會在 metadata 中保留以下欄位：

  • fail_reason：適合直接顯示給使用者或客戶端工程師閱讀的失敗原因摘要

  • fail_detail：較完整的錯誤細節、處理歷史、內部流程資訊或 fallback 原因，便於除錯與排查

使用建議

  • 當使用者需要快速理解「發生了什麼問題」時，優先查看 fail_reason

  • 當工程師需要定位更細的錯誤來源或追查背景流程失敗原因時，建議查看 fail_detail

  • 若同時存在同步錯誤與背景流程失敗資訊，應以實際 API response 與後續查詢結果綜合判讀

若遇到同步 API 錯誤，請查閱 錯誤代碼說明章節。

若 API 已成功接受請求但後續流程仍失敗，請優先查詢相關資源的 metadata 欄位。

建議排查順序

當發生錯誤時，建議依照以下順序進行排查：

  1. 先確認 API response 是否已直接回傳 error_code 與 error_message

  2. 若有同步錯誤，先根據錯誤代碼確認請求參數、資源存在性與資源狀態

  3. 若請求已成功送出但結果異常，請改查：

  4. GET /v1/files/{file_id}

  5. GET /v1/filesets/{fileset_id}

  6. GET /v1/filesets/{fileset_id}/files

  7. 檢查：

  8. state

  9. file_counts

  10. metadata.fail_reason

  11. metadata.fail_detail

  12. 若為 Chat Completions + 多 filesets 情境，請另外確認：

  13. 是否同時傳入 fileset_id 與 fileset_ids

  14. fileset_ids 中是否包含不存在或不可用的 fileset

  15. 是否誤將空陣列 [] 當作 RAG 查詢來源