JSON 與 C ABI 工作中的外部 OCR

ocr.layer 操作接受 builtin-ascii、tesseract-cli、tesseract-dll、rapidocr-cli 與 rapidocr-dll;省略 engine 時會沿用內建 ASCII 預設

能力探索會列出這些受支援的 adapter,但不會宣稱執行主機上已安裝外部程式、程式庫、語言資料或 ONNX 模型

Tesseract 範例

{"schemaVersion":1,"type":"ocr.layer","pages":[0],"dpi":300,
 "minimumConfidence":0.7,"skipPagesWithText":true,"replaceExisting":false,
 "engine":"tesseract-cli",
 "engineOptions":{"executablePath":"C:/OCR/tesseract.exe",
   "tessDataDirectory":"C:/OCR/tessdata","language":"eng",
   "pageSegMode":6,"engineMode":3,"timeoutMilliseconds":30000,
   "maxPixels":16777216}}

把這個物件放進 file job 的 operations 陣列並補上 input 與 output 路徑,或把它直接傳給 hpdf_document_execute_json_v1,並提供已載入的 handle 與 binary/result callback

引擎必填的 engineOptions選填的 engineOptions
builtin-ascii無engineOptions 必須省略或為空物件
tesseract-cliexecutablePath, tessDataDirectorylanguage, pageSegMode, engineMode, timeoutMilliseconds, maxPixels
tesseract-dlllibraryPath, tessDataDirectorylanguage, pageSegMode, engineMode, timeoutMilliseconds, maxPixels
rapidocr-clipythonExecutable, bridgeScript, modelDirectorydetectionModel, recognitionModel, classificationModel, characterDictionary, fontPath, useAngleClassifier, intraOpThreads, interOpThreads, timeoutMilliseconds, maxPixels
rapidocr-dlllibraryPath, modelDirectorylanguage, detectionModel, recognitionModel, classificationModel, characterDictionary, useAngleClassifier, rightToLeft, threads, timeoutMilliseconds, maxPixels

選項與本機資源

外部引擎必須提供明確的物件型 engineOptions;未知鍵、錯誤的 JSON 型別、含 NUL 的路徑或語言字串,以及空的必填值都會被拒絕

Tesseract 預設 language=eng、pageSegMode=3、engineMode=3;分割模式 0 與 2 無法辨識文字而遭拒絕,其餘模式到 13 為止都接受

engineMode 接受 0 到 3;trained-data 檔必須支援所選模式,而 eng+fra 這類多語言 Tesseract 語言運算式需要對應的本機模型

RapidOCR CLI 使用原生 THPDFRapidOCROptions.Default 的模型名稱,兩個執行緒上限都預設為 1;它接受明確提供的字典與字型路徑,且設定的 bridge 必須實作本機 TSV 合約

RapidOCR DLL 以 THPDFRapidOCRDLLOptions.ForLanguage(language) 起始,預設 ch;語言設定檔會挑選辨識模型、字典與閱讀方向,明確選項可以覆寫這些挑選結果

模型檔名由原生 adapter 決定,在 modelDirectory 底下解析;程式庫位元數必須與宿主 process 一致,而 CLI 引擎則以獨立的本機 process 執行

請事先佈建並明確選用這些資源;這個操作不會安裝引擎、下載模型、搜尋任意執行檔,也不會使用遠端 OCR 服務

預算與取消

timeoutMilliseconds 預設 60,000,接受 1 到 3,600,000 的整數;實際生效的 adapter 逾時會被 budget.timeMilliseconds 封頂

maxPixels 預設 16,777,216,接受 1 到 67,108,864 的整數;實際上限取請求值、budget.pixels 與 budget.memoryBytes / 16 三者的最小值

引擎實際的像素上限也會限制辨識前的 OCR 頁面 render;單字、內容與 UTF-16 文字預算受該操作的記憶體額度約束

這些限制約束已設定的緩衝區與操作資源;外部 DLL 的模型配置並不構成嚴格的 process RSS 配額

原生呼叫借用 Document.OperationCancellationToken 進行 render 與辨識;C callback 的取消會在合作式的操作、輸入與輸出檢查點輪詢,而正在執行的外部引擎可以繼續跑到逾時或下一個 callback 檢查點

本機 CLI 失敗、無效或不完整的 TSV 輸出,以及 adapter 逾時都會讓操作遭拒;已設定的操作時間與像素限制仍會歸入結構化預算失敗類別

輸出與交易行為

結果會回報 engine、recognizedPages、skippedPages、acceptedWords 與 droppedWords;engine 欄位存放原生 adapter 的描述名稱

minimumConfidence 必須是 0 到 1 的數字,skipPagesWithText 與 replaceExisting 必須是 JSON 布林值

通過的 Unicode 單字會變成帶 ToUnicode 對應與來源頁面幾何的隱形文字;掃描影像保留在輸出中,來源檔也維持不變,除非呼叫端刻意發布到同一個檔案路徑

file job 失敗時會保留既有目的地,並透過同目錄的暫存檔發布;C ABI 的變更在 PDF 位元組與 JSON 結果都成功送達後才提交,失敗時回復,已送達的位元組由呼叫端自行處置

驗收

Tests/Delphi/Run-JobOCRTests.ps1 在 Win32 與 Win64 上執行四種 adapter 分派設定,涵蓋格式錯誤的設定、像素與經過時間預算、部分單字拒絕、process 失敗、逾時,以及目的地/來源保留

提供實際的 Tesseract 執行檔與模型路徑可以測到真實辨識;獨立的 pypdf 與 MuPDF reader 驗證 Unicode 可搜尋文字與未改變的可見掃描像素,選做的真實 Win64 ABI DLL 檢查則驗證部分 callback 與失敗操作的回復

詳見文件操作、Tesseract adapter、本機 RapidOCR 模型、原生 RapidOCR 程式庫與可搜尋 OCR 文字層