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

更新知識版本

此 API 用於更新指定 Fileset 的檔案清單(file_ids)、Metadata 與名稱。
你可以透過此操作,以傳入的內容完全取代原有 Fileset 的檔案清單、Metadata 與名稱(不是部分合併)。
Key Constraints:

  • 當 Fileset 狀態為 queued、processing、completed 時,僅能傳入與現有完全相同的 file_ids 集合(無法新增或移除檔案),否則回傳 FILESET_004(409);但仍可更新 metadata 與 name。

  • 當 Fileset 狀態為 draft、failed、partial_failed、cancelled 時,可完整替換 file_ids、metadata、name。

  • 也就是說,已 commit 完成的 Fileset 並非完全不可變,只是不能更換所包含的檔案。如需變更檔案內容,請以「複製知識版本」API 建立複本,或建立新的 Fileset 後重新 Commit。

curl -X 'PUT' \
'http://127.0.0.1:8000/v1/filesets/{fileset_id}' \
-H 'accept: application/json' \
-H "Authorization: Bearer $PRIVAI_API_KEY" \
-H 'Content-Type: application/json' \
-d '{
"file_ids": [
"3fa85f64-5717-4562-b3fc-2c963f66afa6",
"8871d153-e495-41a0-a862-289095802781"
],
"metadata": {
"tag": ["policy", "operation", "draft"]
},
"name": "Company Policy Files v2.0"
}'

Request Headers​

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

Path Parameters​

FieldTypeNoteRequired
fileset_idstringuuidtrue

Request Payload​

{
"file_ids": [
"3fa85f64-5717-4562-b3fc-2c963f66afa6",
"8871d153-e495-41a0-a862-289095802781"
],
"metadata": {
"tag": ["policy", "operation", "draft"]
},
"name": "Company Policy Files v2.0"
}

Field Explanation

FieldTypeDetailRequired
file_idsarrayFile ID(uuid)列表,會取代原有的檔案清單。狀態為 queued/processing/completed 時必須與現有集合相同true
metadataobject使用者自訂的描述資訊,會整個取代原有的 metadata。若要保留原有欄位,請先以「取得單一知識版本資料」API 取得後一併傳入true
namestringFileset 的名稱true

Response Body​

{
"object": "fileset",
"id": "a1ecdb5d-e2a5-4aec-8925-b0648a5c0e21",
"name": "Company Policy Files v2.0",
"metadata": {
"tag": ["policy", "operation", "draft"],
"embedding_model": null,
"parsing_mode": null
},
"state": "draft",
"created_at": "2025-01-01T00:00:00.000Z",
"committed_at": null,
"updated_at": "2025-01-01T00:05:00.000Z",
"file_counts": {
"draft": 1,
"queued": 0,
"processing": 0,
"completed": 0,
"failed": 0,
"total": 1
}
}

Field Explanation
回傳「知識版本物件」章節列表內容。metadata.embedding_model、metadata.parsing_mode 為系統欄位,由系統依最近一次 commit 帶出。

常見錯誤代碼​

Error CodeHTTP Status情境
FILESET_001404指定的 Fileset 不存在
FILESET_004409Fileset 狀態為 queued/processing/completed,且傳入的 file_ids 與現有集合不同;回應中帶 state
FILESET_007409同一個 Fileset 同時被其他請求修改(版本衝突),請重新取得後再試
FILE_009404file_ids 中有不存在的檔案,回應中的 file_ids 列出找不到的 ID
—422缺少必填欄位,或 metadata 不是物件

身份驗證錯誤(AUTH_001~AUTH_003)詳見「錯誤代碼說明-身份驗證類」章節;知識版本相關錯誤碼完整說明請參考 錯誤代碼說明-知識版本管理類。