Commit 知識版本

此 API 用於將指定的 Fileset 提交為一個可查詢的知識版本。一旦執行 Commit,系統會:
-
針對 Fileset 中所有檔案根據解析模式進行內容解析與切段
-
將每段內容進行語意向量化(embedding)處理
-
提交後的版本具有穩定性與可追溯性,可在後續的 RAG 查詢中指定使用
此 API 為非同步處理:呼叫成功會立即回傳 202 Accepted,Fileset 狀態變為 queued,實際處理結果請透過「取得單一知識版本資料」API 查詢 state,或以 webhook_url 接收通知。完整流程詳見「Fileset 知識版本建立流程」章節。
備註:Commit 完成(completed)的 Fileset 無法再更換檔案、也無法再次 Commit;若需更新內容,請以「複製知識版本」API 建立複本,或建立新的 Fileset 並重新 Commit。
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 為選填,可整個省略。
{
"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
{
"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(成功)
{
"commit_fileset_status": "completed",
"commit_fileset_err": null,
"failed_files": null,
"inserted_file_ids": null
}
Request Body(部分或全部失敗)
{
"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)詳見「錯誤代碼說明-身份驗證類」章節;知識版本相關錯誤碼完整說明請參考 錯誤代碼說明-知識版本管理類。