# 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 檔案範例如下：

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

非 PDF ／ 圖片檔案範例如下：

```json
{
  "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`

範例如下（節錄）：

```json
{
  "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`

範例如下（節錄）：

```json
{
  "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 為基準的統計，詳見 [檔案統計物件](https://privstation-docs.apmic.ai/latest/privai-400/檔案統計物件.md)。

#### 三種狀態的差異整理

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