跳至主要内容
版本:PrivStation 4.0.0
Markdown 原文

Fileset 知識版本建立流程

在 PrivAI 中,Fileset Commit 是將一組已上傳的檔案正式轉換為可查詢的知識版本(Knowledge Version)的動作。

使用流程​

  1. 將一個或多個檔案(file_id)加入指定的 Fileset(「新增知識版本」或「更新知識版本」API)。

  2. 呼叫 POST /v1/filesets/{fileset_id}/commit 提交該 Fileset(「Commit 知識版本」API)。API 受理後立即回應 202 Accepted,實際處理於背景非同步進行。

  3. 系統會對 Fileset 內的每個檔案依序進行:

    • 文件解析(parse):依 Commit 時指定的 parsing_mode 解析;若該檔案已有可用的解析結果則直接沿用。

    • 內容切段(split into chunks)

    • 向量化處理與建立索引(embedding / indexing)

  4. 全部檔案處理結束後,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 為陣列,最新的紀錄排在最前面,每筆紀錄包含:

FieldDetail
timestamp發生時間(ISO8601)
error_type錯誤類型
error_message錯誤訊息,便於工程除錯與定位問題來源
reason失敗原因分類(選填),便於使用者或客戶端工程師快速理解問題
step失敗發生的處理步驟(選填)
extra其他補充資訊(選填)

若 Commit 時有提供 webhook_url,系統也會在 Commit 結束時主動發送結果通知,詳見 Commit 知識版本。