# Fileset 知識版本建立流程

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

#### 使用流程

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

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

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

    - 文件解析（parse）：依 Commit 時指定的 `parsing_mode` 解析；若該檔案已有可用的解析結果則直接沿用。

    - 內容切段（split into chunks）

    - 向量化處理與建立索引（embedding ／ indexing）

1. 全部檔案處理結束後，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 取得，錯誤代碼請參考 [錯誤代碼說明-知識版本管理類](https://privstation-docs.apmic.ai/latest/privai-400/錯誤代碼說明-知識版本管理類.md)。

#### 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 知識版本](https://privstation-docs.apmic.ai/latest/privai-400/commit-知識版本.md)。
