跳至主要内容
版本:PrivStation 4.0.0
Markdown 原文

Commit 知識版本

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

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

  2. 將每段內容進行語意向量化(embedding)處理

  3. 提交後的版本具有穩定性與可追溯性,可在後續的 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​

KeyValue
Request MethodPOST
acceptapplication/json
AuthorizationBearer $PRIVAI_API_KEY
Content-Typeapplication/json

Path Parameters​

FieldTypeNoteRequired
fileset_idstringuuidtrue

Request Payload​

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

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

Field Explanation

FieldTypeDetailRequired
embedding_modelstring指定轉換成向量資料庫的模型,例如 apmic-embedding-v1false
parsing_modestring指定轉換的解析模式,可用值:HQ、FASTfalse
webhook_urlstring (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

KeyValue
Request MethodPOST
Content-Typeapplication/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"
]
}
FieldDetail
commit_fileset_statuscommit 結果:completed、partial_failed 或 failed
commit_fileset_err失敗說明,成功時為 null
failed_files[]處理失敗的檔案列表,id 為檔案 ID,error 為錯誤訊息。成功時為 null
inserted_file_ids[]成功寫入知識版本的檔案 ID 列表,成功時為 null

常見錯誤代碼​

Error CodeHTTP Status情境
FILESET_001404指定的 Fileset 不存在
FILESET_005400Fileset 內沒有任何檔案
FILESET_011400Fileset 中存在不支援的檔案型別,回應中帶 filetype
FILESET_003409Fileset 目前狀態為 queued/processing/completed,不可 commit;回應中帶 state
FILESET_022409上一次 commit 的取消仍在清理中
FILESET_007409同一個 Fileset 同時被其他請求修改(版本衝突)
—422parsing_mode 不是 HQ/FAST,或 webhook_url 不是合法 URL

以上為呼叫當下同步回傳的錯誤;commit 過程中個別檔案的失敗會反映在 Fileset 的 state(partial_failed/failed)、file_counts 與 Webhook 內容中。身份驗證錯誤(AUTH_001~AUTH_003)詳見「錯誤代碼說明-身份驗證類」章節;知識版本相關錯誤碼完整說明請參考 錯誤代碼說明-知識版本管理類。