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

新增知識版本

此 API 用於建立一個新的 Fileset,作為後續知識組織與查詢的單位。
開發者可以指定該 Fileset 的名稱、Metadata 以及要包含的檔案 ID 清單(file_ids)。新建立的 Fileset 狀態為 draft,需再透過「Commit 知識版本」API 建立為可查詢的知識版本。完整流程詳見「Fileset 知識版本建立流程」章節。

curl -X 'POST' \
'http://127.0.0.1:8000/v1/filesets' \
-H 'accept: application/json' \
-H "Authorization: Bearer $PRIVAI_API_KEY" \
-H 'Content-Type: application/json' \
-d '{
"file_ids": [
"3fa85f64-5717-4562-b3fc-2c963f66afa6"
],
"metadata": {
"tag": ["policy", "operation"]
},
"name": "Company Policy Files v1.0"
}'

Request Headers​

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

Request Payload​

{
"file_ids": [
"3fa85f64-5717-4562-b3fc-2c963f66afa6"
],
"metadata": {
"tag": ["policy", "operation"]
},
"name": "Company Policy Files v1.0"
}

Field Explanation

FieldTypeDetailRequired
file_idsarrayFile ID(uuid)列表。此欄位必須帶入,可為空陣列或 null(建立不含檔案的 Fileset,但 commit 前至少需加入一個檔案)。任一 ID 不存在時回傳 FILE_009true
metadataobject使用者自訂的描述資訊false
namestringFileset 的名稱,若沒指定系統會自動產生,格式為 fileset_YYYYMMDD_hh:mmfalse
idstringuuid,指定 Fileset ID;若沒有指定則由系統自動產生。指定的 ID 已存在時回傳 FILESET_002false

Response Body​

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

Field Explanation
回傳「知識版本物件」章節列表內容。HTTP Status 為 200。尚未 commit 的 Fileset,metadata.embedding_model 與 metadata.parsing_mode 為 null。

常見錯誤代碼​

Error CodeHTTP Status情境
FILESET_002409以 id 指定的 Fileset ID 已存在
FILE_009404file_ids 中有不存在的檔案,回應中的 file_ids 列出找不到的 ID
—422缺少 file_ids、ID 不是合法 uuid,或帶入未定義的欄位

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