File Parse State、Fileset File State 與 Fileset State 的差異
在 PrivAI 中,檔案解析、知識版本建立,以及知識版本內單一檔案的處理進度,分別屬於不同層次的狀態資訊。為避免狀態語意混淆,PrivAI 將狀態區分為以下三種類型:
-
File Parse State
-
Fileset File State
-
Fileset State
這三者彼此相關,但代表的意義不同,應分別理解與使用。
File Parse State
File Parse State 表示「單一檔案在某一種解析模式下的文件解析進度」,例如檔案是否已完成高解析(HQ)或低解析(LQ)的內容抽取。
此狀態記錄於 File 物件的 metadata.parsed_results 中,各解析模式各自擁有獨立的 parsing_state:
-
PDF 與圖片檔:同時具有
HQ(高解析)與LQ(低解析)兩組結果。 -
其他格式(Word、文字、試算表、CSV 等):只有一組
STD(標準解析)結果。
parsing_state 的可能值:
-
draft -
queued -
parsing -
completed -
failed
PDF 檔案範例如下:
{
"metadata": {
"parsed_results": {
"HQ": {
"parsing_state": "completed",
"character_count": 2639,
"page_count": 5,
"failed_page_numbers": []
},
"LQ": {
"parsing_state": "draft"
}
},
"fail_detail": []
}
}
非 PDF / 圖片檔案範例如下:
{
"metadata": {
"parsed_results": {
"STD": {
"parsing_state": "completed",
"character_count": 1024
}
},
"fail_detail": []
}
}
File Parse State 僅表示檔案本身在特定解析模式下的處理結果,不代表該檔案是否已被某個 Fileset 成功建立為可問答的知識版本內容。
換言之,即使某個檔案的 HQ 解析已完成,也不代表它已能在某個 Fileset 中被檢索與使用。
Fileset File State
Fileset File State 表示「某個檔案在某個 Fileset 內的 Commit / 建庫狀態」。
此狀態會出現在 GET /v1/filesets/{fileset_id}/files 的回傳結果中(state 欄位),用來表示該檔案在指定 Fileset 內,是否已完成知識版本建立流程;used_quality 則表示該檔案在此 Fileset 中實際採用的解析結果(HQ、LQ 或 STD)。其可能狀態包含:
-
draft -
queued -
processing -
completed -
failed
範例如下(節錄):
{
"object": "fileset.file",
"id": "18b8b0f0-83c1-41a0-ba58-40774c8dfb99",
"filename": "2024清明.pdf",
"filetype": "application/pdf",
"state": "completed",
"used_quality": "HQ"
}
Fileset File State 的重點在於:它描述的是同一份檔案在特定 Fileset 中的處理結果,而不是檔案本身的解析狀態。
因此,同一個 File 若被加入多個不同的 Fileset,便可能在不同 Fileset 中擁有不同的 Fileset File State。例如:
-
在 Fileset A 中已完成 Commit,因此狀態為
completed -
在 Fileset B 中尚未 Commit,因此狀態為
draft -
在 Fileset C 中 Commit 失敗,因此狀態為
failed
這些狀態彼此獨立,不應互相混用。
Fileset State
Fileset State 表示「整個 Fileset 的整體知識版本建立狀態」,也就是從整體角度觀察此 Fileset 是否已完成建庫、處理中、部分失敗或已取消。
Fileset State 會出現在 Fileset 物件中,例如 GET /v1/filesets 或 GET /v1/filesets/{fileset_id} 的回傳結果。其可能狀態包含:
-
draft -
queued -
processing -
completed -
cancelled -
partial_failed -
failed
範例如下(節錄):
{
"object": "fileset",
"id": "af8877f9-25ec-41db-8872-c872cd5c34b2",
"name": "test1",
"state": "partial_failed",
"file_counts": {
"draft": 0,
"queued": 0,
"processing": 0,
"completed": 4,
"failed": 2,
"total": 6
}
}
Fileset State 是針對整個 Fileset 的彙總結果,由 Commit 流程依內部所有檔案的處理結果決定:
-
所有檔案皆完成:
completed -
部分檔案成功、部分失敗:
partial_failed -
沒有任何檔案成功:
failed -
Commit 被取消:
cancelled
file_counts 則是以 Fileset File State 為基準的統計,詳見 檔案統計物件。
三種狀態的差異整理
| 狀態類型 | 代表意義 | 出現位置 | 是否可跨 Fileset 共用 |
|---|---|---|---|
| File Parse State | 檔案在特定解析模式下的文件解析進度 | file.metadata.parsed_results | 是 |
| Fileset File State | 某個檔案在特定 Fileset 內的 Commit / 建庫狀態 | GET /v1/filesets/{fileset_id}/files | 否 |
| Fileset State | 整個 Fileset 的整體知識版本建立狀態 | Fileset 物件 | 不適用 |