Fileset 知識版本建立流程
在 PrivAI 中,Fileset Commit 是將一組已上傳的檔案正式轉換為可查詢的知識版本(Knowledge Version)的動作。
使用流程
-
將一個或多個檔案(
file_id)加入指定的 Fileset(「新增知識版本」或「更新知識版本」API)。 -
呼叫
POST /v1/filesets/{fileset_id}/commit提交該 Fileset(「Commit 知識版本」API)。API 受理後立即回應202 Accepted,實際處理於背景非同步進行。 -
系統會對 Fileset 內的每個檔案依序進行:
-
文件解析(parse):依 Commit 時指定的
parsing_mode解析;若該檔案已有可用的解析結果則直接沿用。 -
內容切段(split into chunks)
-
向量化處理與建立索引(embedding / indexing)
-
-
全部檔案處理結束後,Fileset State 轉為
completed、partial_failed或failed。只有completed或partial_failed的 Fileset 可用於資料參考搜尋與 Chat Completions。
知識版本的不可變性
-
Fileset 一旦 Commit 成功(
completed),其檔案組成即固定:之後只能更新名稱與 metadata,不能再增減檔案,也不能再次 Commit。 -
若需要以不同的檔案內容建立新版本,請先以「複製知識版本」API 建立複本,再更新複本的檔案組成並 Commit 複本。原本的知識版本不受影響,查詢時可繼續指定原版本以確保結果一致。
-
狀態為
draft、failed、partial_failed或cancelled的 Fileset 可以調整檔案組成並重新 Commit;重新 Commit 會清除該 Fileset 先前的索引資料,並重新處理所有檔案。 -
Commit 進行中(
queued、processing)的 Fileset 不能更新檔案組成、不能刪除,也不能重複 Commit;可透過「取消 Commit 知識版本」API 中止。
Fileset File State 與 file_counts
Fileset Commit 過程中,每個檔案在該 Fileset 內都會有獨立的 Fileset File State。
Fileset File State 代表該檔案在該 Fileset 內的 Commit / 知識庫建立狀態,而非檔案本身的解析狀態。
file_counts 即以 Fileset File State 為基準統計。
同一個 File 可被多個 Fileset 使用,因此不同 Fileset 中的狀態可能不同。詳見「File Parse State、Fileset File State 與 Fileset State 的差異」章節。
Commit 失敗與錯誤觀察方式
Commit 流程中的錯誤可分為兩類:
1. 同步 API 錯誤
若錯誤發生在 API 請求驗證階段,系統會直接以 API error response 回傳,例如:
-
Fileset 不存在
-
Fileset 狀態不可 Commit(例如已是
completed,或正在queued/processing) -
Fileset 內沒有任何檔案
-
Fileset 內含不支援的檔案格式
-
版本衝突(同一 Fileset 同時被其他請求更新)
此類錯誤可直接從 POST /v1/filesets/{fileset_id}/commit 的 HTTP response 取得,錯誤代碼請參考 錯誤代碼說明-知識版本管理類。
2. 非同步背景流程錯誤
若錯誤發生在 Commit 已受理後的背景流程中,例如:
-
文件解析失敗
-
文件切段失敗
-
向量化或索引建立失敗
-
Commit 被取消,流程中止或部分中止
-
處理逾時而被標示為失敗
由於此時 API 已無法即時回傳最終錯誤,系統會將失敗資訊寫入對應的檔案資料中,供後續查詢。建議透過以下 API 觀察實際狀態與失敗資訊:
-
GET /v1/filesets/{fileset_id}:觀察 Fileset State 與file_counts -
GET /v1/filesets/{fileset_id}/files:觀察各檔案的 Fileset File State,可搭配files_state參數篩選failed的檔案 -
GET /v1/files/{file_id}:觀察檔案的解析狀態與失敗紀錄
若檔案處理失敗,檔案物件的 metadata.fail_detail 會記錄失敗資訊。fail_detail 為陣列,最新的紀錄排在最前面,每筆紀錄包含:
| Field | Detail |
|---|---|
| timestamp | 發生時間(ISO8601) |
| error_type | 錯誤類型 |
| error_message | 錯誤訊息,便於工程除錯與定位問題來源 |
| reason | 失敗原因分類(選填),便於使用者或客戶端工程師快速理解問題 |
| step | 失敗發生的處理步驟(選填) |
| extra | 其他補充資訊(選填) |
若 Commit 時有提供 webhook_url,系統也會在 Commit 結束時主動發送結果通知,詳見 Commit 知識版本。