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

PrivAI 採用游標式分頁（Cursor-Based Pagination）機制，讓你能夠有效率地瀏覽大量資料，並保持查詢結果的一致性。

在請求中，你可以使用 after 或 before 參數來指定資料的查詢起點：

• 使用 after：傳入一筆資料的 ID，系統會回傳 在該 ID 之後的資料

• 使用 before：傳入一筆資料的 ID，系統會回傳 在該 ID 之前的資料

系統每次回傳資料時，會額外提供：

• has_more: 布林值，表示是否還有更多資料可讀取

這樣的設計簡化了狀態管理，也避免了傳統分頁中 offset 不穩定的問題。

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

PrivAI 提升知識庫版本建立的穩定性與效率，透過提供高解析模式（專業模式）、低解析模式（快速模式）和內建的穩健處理機制，確保文件內容能以最佳方式被抽取與納入知識庫。此舉有效解決了全數依賴高解析模式處理時間長、偶發處理無法順利完成的問題，優化了整體使用者體驗。

注意事項

• File 的解析狀態以 metadata.parsed_results 為準

• 各解析模式（HQ / LQ / STD 或新版支援模式）各自有獨立的 parsing_state

• parsing_state 可為：draft / queued / parsing / completed / failed

• parse 完成即視為 completed，不以 splitting / commit 是否完成判定

• 因不同解析模式可能同時存在不同結果，不再使用單一 file state 表達整體解析狀態

高解析模式

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

低解析模式

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

自動切換

為確保知識版本建立的最高成功率，系統內建了自動切換備援模式 (Fallback) 的機制。

當使用者選擇「高解析模式」處理文件時，若系統判斷無法順利完成（例如資源超限、結構異常複雜等），系統將自動、無縫地切換至「低解析模式」作為備援處理路徑。

當文件在原本預期的高解析模式下未能完成處理，而透過自動切換至低解析模式成功解析並納入知識庫時，其檔案處理狀態的 API 回覆將包含以下標記：

• fail_detail (Object)：紀錄具體高解析模式無法順利完成的原因。