# Fileset 知識版本建立流程

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

使用流程如下：

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

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

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

- 文件解析（parse）

- 內容切段（split into chunks）

- 向量化處理（embedding / indexing）

- 建立一個對應該次 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`：較完整的失敗細節，便於工程除錯與定位問題來源
