# 分頁策略 ＆ 文件解析模式優化策略 (PDF)

### 分頁策略

PrivAI 採用游標式分頁（Cursor-Based Pagination）機制，讓你能夠有效率地瀏覽大量資料，並保持查詢結果的一致性。  
以下列表 API 皆採用相同的分頁規則：

- `GET /v1/api-keys`

- `GET /v1/files`

- `GET /v1/filesets`

- `GET /v1/filesets/{fileset_id}/files`

- `GET /v1/prompts`

#### Query Parameters

| Parameter | Type | Default | Description |
| --- | --- | --- | --- |
| limit | integer | 10000 | 每次回傳筆數，範圍 1–10000 |
| order | string | desc | 依建立時間（`created_at`）排序，`asc` 為由舊到新、`desc` 為由新到舊 |
| after | string (uuid) | — | 分頁游標，傳入一筆資料的 ID，回傳排序上**在該 ID 之後**的資料；不可與 `before` 同時提供 |
| before | string (uuid) | — | 分頁游標，傳入一筆資料的 ID，回傳排序上**在該 ID 之前**的資料；不可與 `after` 同時提供 |

#### 回應中的分頁欄位

| Field | Detail |
| --- | --- |
| first_id | 本頁第一筆資料的 ID；無資料時為 null |
| last_id | 本頁最後一筆資料的 ID；無資料時為 null |
| has_more | 布林值，表示依目前的查詢方向是否還有更多資料可讀取 |

#### 使用方式

- 取得下一頁：將上一次回應的 `last_id` 帶入 `after`。

- 取得上一頁：將目前回應的 `first_id` 帶入 `before`。回傳的資料順序仍與 `order` 一致。

- 同時提供 `after` 與 `before` 會回傳 `VAL_001`；游標所指定的 ID 不存在時會回傳 `VAL_002`，詳見 [錯誤代碼說明-傳遞參數驗證類](https://privstation-docs.apmic.ai/latest/privai-400/錯誤代碼說明-傳遞參數驗證類.md)。

```bash
curl -X 'GET' \
  'http://127.0.0.1:8000/v1/files?limit=100&order=desc&after=3f90f7e3-7ec5-4c68-8bd1-38f54e90d390' \
  -H 'accept: application/json' \
  -H 'Authorization: Bearer <your-api-key>'
```

這樣的設計簡化了狀態管理，也避免了傳統 offset 分頁在資料異動時結果不穩定的問題。

### 文件解析模式優化策略 (PDF)

PrivAI 透過提供高解析模式、快速（低解析）模式與內建的備援機制，提升知識版本建立的**穩定性與效率**，確保文件內容能以最佳方式被抽取與納入知識庫。  
解析模式的差異只適用於 **PDF 與圖片**檔案；其他格式（Word、文字、試算表、CSV 等）一律以標準解析（`STD`）處理。

#### 指定解析模式

呼叫「單一檔案轉換」、「上傳檔案」（`instant_parse`）或「Commit 知識版本」API 時，可透過 `parsing_mode` 指定解析模式：

| parsing_mode | 說明 | 解析結果記錄於 |
| --- | --- | --- |
| HQ | 高解析模式 | `metadata.parsed_results.HQ` |
| FAST | 快速（低解析）模式 | `metadata.parsed_results.LQ` |

非 PDF ／ 圖片檔案即使指定 `FAST`，也會以標準解析處理，結果記錄於 `metadata.parsed_results.STD`。

#### 注意事項

- 檔案的解析狀態以 `metadata.parsed_results` 為準。

- 各解析結果（`HQ` ／ `LQ` ／ `STD`）各自有獨立的 `parsing_state`。

- `parsing_state` 可為：`draft` ／ `queued` ／ `parsing` ／ `completed` ／ `failed`。

- **解析完成即視為** `completed`**，不以切段或 Commit 是否完成判定。**

- 因不同解析模式可能同時存在不同結果，**不使用單一的檔案狀態表達整體解析狀態**。

#### 高解析模式（HQ）

高解析模式提供最高品質與準確度的文件內容抽取，最大化還原文件的結構、排版與內容細節，適用於對知識庫內容準確性要求極高的場景。相對耗時較長，且對複雜或超大文件可能需要更多資源。

#### 快速模式（FAST）

快速模式提供高效率的文件內容基礎抽取，以最快速度抽取文件的核心**文字內容**本身，保障處理流程的連續性，適用於以文字為主的文件或對速度有較高要求的情境。

#### 自動切換

為確保知識版本建立的成功率，系統內建**自動切換備援（Fallback）** 機制：  
當 PDF 或圖片以高解析模式處理但**無法順利完成**時，系統會自動改以快速模式重新解析，作為備援處理路徑。  
發生自動切換時，檔案的 API 回應會呈現以下結果：

- `metadata.parsed_results.HQ.parsing_state` 為 `failed`。

- `metadata.parsed_results.LQ` 為快速模式的解析結果；若備援成功則為 `completed`。

- `metadata.fail_detail` 會新增一筆紀錄，說明高解析模式無法完成的原因。

- 在 Fileset 中，該檔案的 `used_quality` 會是 `LQ`。

若快速模式也失敗，`LQ` 的 `parsing_state` 同樣標示為 `failed`，並在 `fail_detail` 再新增一筆紀錄。
