# Commit 知識版本

![](https://privstation-docs.apmic.ai/img/notion/82495af97f7e.png)

此 API 用於將指定的 Fileset 提交為一個可查詢的知識版本。一旦執行 Commit，系統會：

1. 針對 Fileset 中所有檔案根據**解析模式**進行內容解析與切段

1. 將每段內容進行語意向量化（embedding）處理

1. 提交後的版本具有穩定性與可追溯性，可在後續的 RAG 查詢中指定使用

此 API 為非同步處理：呼叫成功會立即回傳 **202 Accepted**，Fileset 狀態變為 `queued`，實際處理結果請透過「取得單一知識版本資料」API 查詢 `state`，或以 `webhook_url` 接收通知。完整流程詳見「Fileset 知識版本建立流程」章節。  
**備註：Commit 完成（**`completed`**）的 Fileset 無法再更換檔案、也無法再次 Commit；若需更新內容，請以「複製知識版本」API 建立複本，或建立新的 Fileset 並重新 Commit。**

```bash
curl -X 'POST' \
  'http://127.0.0.1:8000/v1/filesets/{fileset_id}/commit' \
  -H 'accept: application/json' \
  -H "Authorization: Bearer $PRIVAI_API_KEY" \
  -H 'Content-Type: application/json' \
  -d '{
    "parsing_mode": "HQ",
    "webhook_url": "https://example.com/webhook"
  }'
```

#### Request Headers

| Key | Value |
| --- | --- |
| Request Method | POST |
| accept | application/json |
| Authorization | `Bearer $PRIVAI_API_KEY` |
| Content-Type | application/json |

#### Path Parameters

| Field | Type | Note | Required |
| --- | --- | --- | --- |
| fileset_id | string | uuid | true |

#### Request Payload

Request Body 為選填，可整個省略。

```json
{
  "embedding_model": "apmic-embedding-v1",
  "parsing_mode": "HQ",
  "webhook_url": "https://example.com/webhook"
}
```

**Field Explanation**

| Field | Type | Detail | Required |
| --- | --- | --- | --- |
| embedding_model | string | 指定轉換成向量資料庫的模型，例如 `apmic-embedding-v1` | false |
| parsing_mode | string | 指定轉換的解析模式，可用值：`HQ`、`FAST` | false |
| webhook_url | string (url) | commit 處理完成或失敗時，系統會以 POST 方式通知此 URL。取消 commit 時不會發送通知 | false |

#### Response Body

**Status Code：202 Accepted**

```json
{
  "detail": "Commit fileset with ID: xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx"
}
```

#### 可 Commit 的狀態

| Fileset 狀態 | 可否 Commit |
| --- | --- |
| `draft`、`failed`、`partial_failed`、`cancelled` | 可以（`failed`／`partial_failed`／`cancelled` 會重新處理 Fileset 內所有檔案） |
| `queued`、`processing`、`completed` | 不可以，回傳 `FILESET_003`（409） |

剛取消 commit 的 Fileset（`cancelled`），若系統仍在清理上一次的處理，再次 Commit 會回傳 `FILESET_022`（409），請稍後再試。

#### Webhook Request Content

若有帶 `webhook_url`，commit 結束（`completed`、`partial_failed`、`failed`）時系統會發送一次通知。Webhook 發送失敗不會影響 commit 結果。  
**Request Headers**

| Key | Value |
| --- | --- |
| Request Method | POST |
| Content-Type | application/json |

**Request Body（成功）**

```json
{
  "commit_fileset_status": "completed",
  "commit_fileset_err": null,
  "failed_files": null,
  "inserted_file_ids": null
}
```

**Request Body（部分或全部失敗）**

```json
{
  "commit_fileset_status": "partial_failed",
  "commit_fileset_err": "4/6 files processed",
  "failed_files": [
    {
      "id": "18b8b0f0-83c1-41a0-ba58-40774c8dfb99",
      "fail_reason": null,
      "error": "parsing error message",
      "step": null
    }
  ],
  "inserted_file_ids": [
    "3fa85f64-5717-4562-b3fc-2c963f66afa6"
  ]
}
```

| Field | Detail |
| --- | --- |
| commit_fileset_status | commit 結果：`completed`、`partial_failed` 或 `failed` |
| commit_fileset_err | 失敗說明，成功時為 null |
| failed_files[] | 處理失敗的檔案列表，`id` 為檔案 ID，`error` 為錯誤訊息。成功時為 null |
| inserted_file_ids[] | 成功寫入知識版本的檔案 ID 列表，成功時為 null |

#### 常見錯誤代碼

| Error Code | HTTP Status | 情境 |
| --- | --- | --- |
| FILESET_001 | 404 | 指定的 Fileset 不存在 |
| FILESET_005 | 400 | Fileset 內沒有任何檔案 |
| FILESET_011 | 400 | Fileset 中存在不支援的檔案型別，回應中帶 `filetype` |
| FILESET_003 | 409 | Fileset 目前狀態為 `queued`／`processing`／`completed`，不可 commit；回應中帶 `state` |
| FILESET_022 | 409 | 上一次 commit 的取消仍在清理中 |
| FILESET_007 | 409 | 同一個 Fileset 同時被其他請求修改（版本衝突） |
| — | 422 | `parsing_mode` 不是 `HQ`／`FAST`，或 `webhook_url` 不是合法 URL |

以上為呼叫當下同步回傳的錯誤；commit 過程中個別檔案的失敗會反映在 Fileset 的 `state`（`partial_failed`／`failed`）、`file_counts` 與 Webhook 內容中。身份驗證錯誤（`AUTH_001`～`AUTH_003`）詳見「錯誤代碼說明-身份驗證類」章節；知識版本相關錯誤碼完整說明請參考 [錯誤代碼說明-知識版本管理類](https://privstation-docs.apmic.ai/latest/privai-400/錯誤代碼說明-知識版本管理類.md)。
