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

分頁策略 & 文件解析模式優化策略 (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​

ParameterTypeDefaultDescription
limitinteger10000每次回傳筆數,範圍 1–10000
orderstringdesc依建立時間(created_at)排序,asc 為由舊到新、desc 為由新到舊
afterstring (uuid)—分頁游標,傳入一筆資料的 ID,回傳排序上在該 ID 之後的資料;不可與 before 同時提供
beforestring (uuid)—分頁游標,傳入一筆資料的 ID,回傳排序上在該 ID 之前的資料;不可與 after 同時提供

回應中的分頁欄位​

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

使用方式​

  • 取得下一頁:將上一次回應的 last_id 帶入 after。

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

  • 同時提供 after 與 before 會回傳 VAL_001;游標所指定的 ID 不存在時會回傳 VAL_002,詳見 錯誤代碼說明-傳遞參數驗證類。

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 再新增一筆紀錄。