跳轉到

Fileset 知識版本建立流程

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

使用流程如下：

  1. 使用者先將多個檔案（file_id）加入指定的 Fileset

  2. 呼叫 /v1/filesets/{fileset_id}/commit API，提交該 Fileset

  3. 系統會將這些檔案的內容依序進行：

  4. 文件解析（parse）

  5. 內容切段（split into chunks）

  6. 向量化處理（embedding / indexing）

  7. 建立一個對應該次 commit 的不可變知識版本

每次 Commit 都會產生一個獨立版本，之後在查詢（RAG）時可指定該版本來確保一致性。若需更新內容，需透過重新指定檔案並再次 Commit。

Fileset commit 過程中，每個 file 在該 Fileset 內都會有獨立的 Fileset File State。

Fileset File State 代表該檔案在該 Fileset 內的 commit / 知識庫建立狀態，而非檔案本身的 parse 狀態。

file_counts 即以 Fileset File State 為基準統計。

同一個 File 可被多個 Fileset 使用，因此不同 Fileset 中的狀態可能不同。

Commit 失敗與錯誤觀察方式

Commit 流程中的錯誤可分為兩類：

1. 同步 API 錯誤

若錯誤發生在 API 請求驗證階段，系統會直接以 API error response 回傳，例如：

  • Fileset 不存在

  • Fileset 狀態不可 commit

  • Fileset 內沒有任何檔案

  • version conflict

  • 指定的 file_id 不存在

此類錯誤可直接從 /v1/filesets/{fileset_id}/commit 的 HTTP response 取得。

2. 非同步背景流程錯誤

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

  • consumer 執行失敗

  • 文件解析失敗

  • 文件切段失敗

  • 向量化或索引建立失敗

  • 取消提交後流程中止或部分中止

由於此時 API 已無法即時回傳最終錯誤，系統會將失敗資訊寫入對應的 File 或 Fileset 關聯資料中，供後續查詢。

建議透過以下 API 觀察實際狀態與失敗資訊：

  • GET /v1/filesets/{fileset_id}

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

  • GET /v1/files/{file_id}

若檔案或流程失敗，相關 metadata 會包含：

  • fail_reason：失敗原因摘要，便於使用者或客戶端工程師快速理解問題

  • fail_detail：較完整的失敗細節，便於工程除錯與定位問題來源