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

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 物件不適用