使用 NextPDF Connect（Pro）擷取文字內容

概覽

從既有 PDF 擷取文字，可供索引、分析或後續處理使用。此工具為 extract_text。它會重新驗證 Pro 工具提供者；該提供者會以協定名稱 extract_text 註冊 new ExtractTextTool()。extract_text 是 Pro 級工具。 伺服器啟動時會以 class_exists() 探測它，且僅在安裝 Pro 套件時才註冊。它支援純文字輸出、頁碼範圍，以及依頁分段的結構化輸出。

安裝

composer require nextpdf/server
composer require nextpdf/pro

綁定一個傳輸層。在仰賴此工具之前，請先以 diagnostic.capabilities 確認它可用。

概念總覽

擷取流程會依串流順序讀取內容串流中的文字顯示運算子（ISO 32000-2 §9.4）。輸出反映的是編碼後的閱讀順序（ISO 32000-2 §9.10）。沒有文字層的掃描式 PDF 只會產生極少文字，甚至完全沒有文字。這是來源本身的性質，並非工具缺陷。format: "plain" 會回傳單一字串。format: "structured" 會回傳每頁的物件，並包含字元計數。page_range 會限制處理的頁面。

API 介面

工具	級別	角色	風險等級
`extract_text`	Pro	擷取文字（純文字/結構化/範圍）	安全
`parse_pdf`	Core（受環境變數控管）	低階結構（頁數、中繼資料）	安全

工具名稱就是註冊表中的協定名稱。工具目錄是權威目錄。可用工具取決於已安裝的級別。

程式碼範例 — 快速上手

extract_text，搭配 source（伺服器可讀取的路徑）與 format: "plain"。
extract_text，搭配 page_range: "1-3" 取得部分頁面。
extract_text，搭配 format: "structured" 取得依頁分段的輸出。

程式碼範例 — 生產環境

在請求頁碼範圍之前，先以 parse_pdf（或先前一次未設限的 extract_text）取得頁數。若用於 RAG/索引，建議採用 format: "structured"，讓每一頁都能獨立分塊。若來源已加密，請提供密碼參數。字元計數採 UTF-8 碼位計數，而非位元組。

邊界情況與陷阱

來源遺失。 錯誤路徑會回傳找不到檔案的錯誤。請使用伺服器可讀取的絕對路徑。
掃描式 PDF。 沒有文字層表示文字會是空的或近乎為空。請先對來源進行 OCR。
頁碼超出範圍。 超出文件頁數的範圍會被拒絕，並回傳實際頁數。
來源已加密。 請提供密碼參數。
未安裝 Pro。 只有 Core 時，extract_text 並不會註冊。請以 diagnostic.capabilities 探測。

效能

擷取工作量會隨文件大小增加，且預算允許大型輸入。對任何產出的成品，其設定檔為 structural，因為此工具回傳的是文字，而非 PDF。

安全須知

擷取出的文字可能含有敏感內容。請將結果視為機密，且僅透過可信通道回傳。此工具不會寫入檔案系統。它只會以伺服器權限讀取來源路徑，因此請限制呼叫方可傳入的路徑。

符合性

陳述	規範	條款	reference_id
文字由文字運算子依串流順序顯示。	ISO 32000-2	§9.4
擷取反映的是編碼後的閱讀順序。	ISO 32000-2	§9.10

本範例並不主張：對未加標籤的文件而言，擷取出的文字就是忠實的邏輯閱讀順序。其順序是編碼後的順序。

商業脈絡

extract_text 是 Pro 級工具；只有在伺服器啟動時可解析 Pro 套件，才會註冊。

傳輸層支援度

傳輸層	是否支援	備註
MCP（stdio）	是（Pro）	大量文字會讓 stdio 訊框膨脹。
REST	是（Pro）	在支援的情況下，請以串流方式回傳大型結果。
gRPC	是（Pro）	大量文字會受到訊息大小上限限制。

HITL 風險等級

extract_text 屬於安全（唯讀、無副作用），且永遠不會設下確認關卡。

確認關卡 JSON 封套

唯讀擷取永遠不會設下確認關卡：

{ "allowed": true }