更新知識版本
此 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
| Key | Value |
|---|---|
| Request Method | PUT |
| 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
{
"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
| Field | Type | Detail | Required |
|---|---|---|---|
| file_ids | array | File ID(uuid)列表,會取代原有的檔案清單。狀態為 queued/processing/completed 時必須與現有集合相同 | true |
| metadata | object | 使用者自訂的描述資訊,會整個取代原有的 metadata。若要保留原有欄位,請先以「取得單一知識版本資料」API 取得後一併傳入 | true |
| name | string | Fileset 的名稱 | 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 Code | HTTP Status | 情境 |
|---|---|---|
| FILESET_001 | 404 | 指定的 Fileset 不存在 |
| FILESET_004 | 409 | Fileset 狀態為 queued/processing/completed,且傳入的 file_ids 與現有集合不同;回應中帶 state |
| FILESET_007 | 409 | 同一個 Fileset 同時被其他請求修改(版本衝突),請重新取得後再試 |
| FILE_009 | 404 | file_ids 中有不存在的檔案,回應中的 file_ids 列出找不到的 ID |
| — | 422 | 缺少必填欄位,或 metadata 不是物件 |
身份驗證錯誤(AUTH_001~AUTH_003)詳見「錯誤代碼說明-身份驗證類」章節;知識版本相關錯誤碼完整說明請參考 錯誤代碼說明-知識版本管理類。