File Parse State、Fileset File State 與 Fileset State 的差異¶

在 PrivAI 中，File 是最基本的知識單位，代表一份上傳的文件，例如 PDF、Word 或文字檔案。在 PrivAI 中，檔案解析、知識版本建立，以及知識版本內單一檔案的處理進度，分別屬於不同層次的狀態資訊。

為避免狀態語意混淆，PrivAI 將狀態區分為以下三種類型：在 PrivAI 中，檔案解析、知識版本建立，以及知識版本內單一檔案的處理進度，分別屬於不同層次的狀態資訊。為避免狀態語意混淆，PrivAI 將狀態區分為以下三種類型：File Parse State 、Fileset File State

Fileset State。這三者彼此相關，但代表的意義不同，應分別理解與使用。

File Parse State¶

File Parse State 表示「單一檔案在某一種解析模式下的文件解析進度」，例如檔案是否已完成高解析（HQ）或低解析（LQ）的內容抽取。

此狀態記錄於 File 物件的 metadata.parsed_results 中，各解析模式會各自擁有獨立的 parsing_state，例如：此狀態記錄於 File 物件的 metadata.parsed_results 中，各解析模式會各自擁有獨立的 parsing_state，例如：

draft
queued
parsing
completed
failed

範例如下：

{
  "metadata": {
    "parsed_results": {
      "HQ": {
        "parsing_state": "completed",
        "character_count": 2639,
        "page_count": 5,
        "failed_page_numbers": []
      },
      "LQ": {
        "parsing_state": "draft"
      }
    }
  }
}

File Parse State 僅表示檔案本身在特定解析模式下的處理結果，不代表該檔案是否已被某個 Fileset 成功建立為可問答的知識版本內容。

換言之，即使某個檔案的 HQ 解析已完成，也不代表它已能在某個 Fileset 中被檢索與使用。

Fileset File State¶

Fileset File State 表示「某個檔案在某個 Fileset 內的 commit / 建庫狀態」。

此狀態會出現在 GET /v1/filesets/{fileset_id}/files 的回傳結果中，用來表示該檔案在指定 Fileset 內，是否已完成知識版本建立流程。其可能狀態包含：

draft
queued
processing
completed
failed

範例如下：

{
  "object": "fileset.file",
  "id": "18b8b0f0-83c1-41a0-ba58-40774c8dfb99",
  "filename": "2024清明.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 的彙總結果，通常可理解為由內部所有 Fileset File State 綜合判斷後所得出的整體狀態。例如：

若所有檔案皆完成，Fileset State 可能為 completed
若部分檔案成功、部分失敗，Fileset State 可能為 partial_failed
若整體處理失敗，Fileset State 可能為 failed

三種狀態的差異整理¶

狀態類型	代表意義	出現位置	是否可跨 Fileset 共用
File Parse State	檔案在特定解析模式下的文件解析進度	file.metadata.parsed_results	是
Fileset File State	某個檔案在特定 Fileset 內的 commit / 建庫狀態	GET /v1/filesets/{fileset_id}/files	否
Fileset State	整個 Fileset 的整體知識版本建立狀態	Fileset 物件	不適用