RapidOCR 原生 DLL 轉接器

HPDFRapidOCRRecognition 透過 HotPDFRapidOCR.dll 提供處理程序內的 IHPDFOCREngine，在 Delphi、C++Builder 與 Windows FPC/Lazarus 的 Win32 與 Win64 組建中公開相同的 API

DLL 直接對記憶體快照執行 CPU ONNX 推論，並保留已初始化的模型直到引擎介面被釋放；執行階段部署包含相符的原生 DLL 以及相容的本地模型與字典

既有的 Python 程序轉接器仍以原本的工廠多載提供

工廠與選項

function HPDFCreateRapidOCRDLLOCREngine(const LibraryPath,
  ModelDirectory: string): IHPDFOCREngine; overload;
function HPDFCreateRapidOCRDLLOCREngine(const LibraryPath,
  ModelDirectory: string; const Options: THPDFRapidOCRDLLOptions): IHPDFOCREngine; overload;

THPDFRapidOCRDLLOptions = record
  DetectionModel: string;
  RecognitionModel: string;
  ClassificationModel: string;
  CharacterDictionary: string;
  UseAngleClassifier: Boolean;
  RightToLeft: Boolean;
  Threads: Integer;
  MaxPixels: Integer;
  TimeoutMilliseconds: Cardinal;
  class function Default: THPDFRapidOCRDLLOptions; static;
  class function ForLanguage(const Language: string): THPDFRapidOCRDLLOptions; static;
end;

以 THPDFRapidOCRDLLOptions.Default 初始化選項；預設值使用下列本地檔案

相對檔名以 ModelDirectory 為基準解析；絕對路徑可選用另行備妥的檔案

工廠會在初始化模型前檢查檔案可用性、選項、必要匯出與 ABI 版本；組態無效丟出 EArgumentException，模型載入失敗則丟出 EInvalidOperation 並附原生診斷資訊

模型初始化在工廠內進行，不計入辨識期限；字典的類別數必須與辨識模型相符，且僅類別數相同並不代表字元順序或前處理相容

隨附的 pipeline 使用 DB 偵測，偵測邊長上限 1,024 像素並留 50 像素白色邊距；辨識器接受輸入高度固定為 32 或 48 的相容 NCHW 模型，動態高度時使用 48

動態寬度模型的辨識會保留長寬比，並以最小寬度 320 正規化含邊距的輸入；固定寬度模型會限制縮放後的裁切寬度，長文字行因此可能被壓縮

角度分類在模型輸入寬度內保留裁切影像的長寬比，未使用的像素以正規化後的零填滿；只有顛倒分數超過 0.9 時才將裁切旋轉 180 度，避免微弱的方向預測翻轉短文字

字典必須符合模型的字元順序與輸出類別數；字典可用 CRLF 換行，但會拒收 UTF-8 BOM

模型內嵌字元中繼資料時，工廠還會核對每個字典項目及其順序；只比對字典大小並不足夠

中文、俄文與常用語言

THPDFRapidOCRDLLOptions.ForLanguage 會在本地模型目錄下選擇辨識模型與對應字典，同時保留共享的偵測器、分類器、執行緒、像素與逾時預設值

此方法接受大小寫不分的語言別名、把底線換成連字號，並去除前後空白；空白或不支援的標籤會在載入模型前丟出 EArgumentException

每個設定檔都使用 <profile>/recognition.onnx 與 <profile>/dictionary.txt；設定檔名稱可直接使用，可辨識的區域別名都是明確定義的，並非從任意前綴推測

部署前先用固定 SHA256 的備妥輔助腳本安裝選定的模型組

& tools/Install-RapidOCRModels.ps1 `
  -Destination C:/OCR/models `
  -Language ch,chinese_cht,en,latin,japan,korean,cyrillic,arabic,devanagari

-Language All 安裝全部九個設定檔；-SkipClassifier 略過選用的分類器，此時建立引擎請設定 UseAngleClassifier := False

輔助腳本會驗證固定的 SHA256 雜湊，並以 Default 使用的根檔名安裝共享的多語言偵測器與分類器；辨識在離線執行，絕不自動下載缺少的模型

請為每個頁面或區域選擇引擎的語言；單一引擎不會自動偵測語言，也不會為不同文字系統組合多個辨識器

固定的套件使用相容的 PP-OCRv3 與 PP-OCRv4 模型；辨識準確度取決於模型、字型、解析度與裁切，即使輸入乾淨，拉丁模型仍可能混淆 ñ 這類附加符號

較新的 PP-OCRv5 模型可能需要比建置 DLL 所用靜態程式庫更新的 ONNX Runtime；不支援的模型格式會讓初始化失敗並附診斷資訊

偵測模型必須接受單一 float32 影像張量，並在縮放後的輸入解析度下產生形狀為 [1, 1, H, W] 的 float32 機率圖；型別、維度不相容、出現非有限值，或機率超出 [0, 1] 超過四個 float32 機器 epsilon，都會在偵測結果被採用前失敗並附診斷資訊

容差內的微小 sigmoid 捨入誤差會在閾值化與輪廓評分前被夾限到 [0, 1]，讓有效的模型維持正常的偵測行為

中文範例

uses SysUtils, HPDFDoc, HPDFRapidOCRRecognition;

procedure AddNativeRapidOCRText(PDF: THotPDF);
var
  Engine: IHPDFOCREngine;
  Models: THPDFRapidOCRDLLOptions;
  Layer: THPDFOCRTextLayerOptions;
  Info: THPDFOCRTextLayerInfo;
begin
  Models := THPDFRapidOCRDLLOptions.ForLanguage('zh-CN');
  Models.UseAngleClassifier := False;
  Engine := HPDFCreateRapidOCRDLLOCREngine(
    'C:\OCR\Win64\HotPDFRapidOCR.dll', 'C:\OCR\models', Models);
  Layer := THPDFOCRTextLayerOptions.Default;
  if not PDF.ApplyLoadedOCRTextLayer([0], Engine, Layer, Info) then
    raise Exception.Create('Native RapidOCR text layer was not added');
end;

跨請求保留引擎介面即可重用其模型；請使用與呼叫端應用程式架構相符的 DLL，並把其相依 DLL 放在同一目錄或標準 Windows 載入器目錄

俄文範例

procedure AddRussianRapidOCRText(PDF: THotPDF);
var
  Engine: IHPDFOCREngine;
  Models: THPDFRapidOCRDLLOptions;
  Layer: THPDFOCRTextLayerOptions;
  Info: THPDFOCRTextLayerInfo;
begin
  Models := THPDFRapidOCRDLLOptions.ForLanguage('ru-RU');
  Engine := HPDFCreateRapidOCRDLLOCREngine(
    'C:\OCR\Win64\HotPDFRapidOCR.dll', 'C:\OCR\models', Models);
  Layer := THPDFOCRTextLayerOptions.Default;
  if not PDF.ApplyLoadedOCRTextLayer([0], Engine, Layer, Info) then
    raise Exception.Create('Russian RapidOCR text layer was not added');
end;

ru、ru-RU 與 rus 選用的是同一個 cyrillic 辨識模型與字典

結果與生命週期

轉接器會把目前的點陣圖複製成獨立的由上而下 BGR 快照；配置前先檢查尺寸與像素預算，且不修改借用的點陣圖

原生 pipeline 對每個辨識出的文字行產出一筆結果，附原圖像素邊界與字元平均信賴度；每一行消耗一個 MaxWords 名額，且不提供原生基線

偵測框依水平行閱讀順序排列，預設由左至右，啟用 RightToLeft 時由右至左；阿拉伯文預設集會啟用此選項

角度分類校正的是個別文字裁切；它不判斷整頁方向，也不會把顛倒頁面上各自分開的偵測框重新排列成邏輯閱讀順序

辨識出的文字維持模型的邏輯 Unicode 順序；轉接器不會自動反轉阿拉伯文字串，也不套用雙向整形

轉接器會驗證 UTF-8、Unicode 控制字元、邊界、信賴度與請求的 MaxTextCodeUnits 上限，文字硬上限為 1,048,576 個 UTF-16 單元；補充字元消耗兩個單元

空白頁面以空結果陣列成功傳回；失敗會清除部分結果，可搜尋 PDF 的發布則保留既有的原子頁面交易行為

同一引擎的呼叫會逐一序列化執行；等待引擎鎖定期間每 25 毫秒檢查一次取消與辨識期限

原生 callback 在偵測、分類與每個辨識行前後都會檢查取消與期限；單次 ONNX 推論呼叫無法被強制中斷，因此取消可能要等目前階段結束後才回報

輸入與文字限制約束的是轉接器自身的配置與可接受的輸出，不會對模型、偵測、裁切或推論記憶體設下硬上限

建置與 ABI

Native/RapidOCR 包含 C++ 橋接層、相容的模型辨識器、版本化的 C 標頭、匯出定義與 CMake 專案；請備妥提供 DbNet、AngleNet 與 OcrUtils 的相容 CPU 網路原始碼，以及相符的 ONNX Runtime 與 OpenCV 程式庫

使用含 C++17 的 Windows MSVC、Windows SDK 與 CMake 3.20 以上版本；預設組建使用靜態 release CRT，必須與備妥的程式庫相符

& tools/Build-HotPDFRapidOCR.ps1 `
  -NativeSourceDirectory C:/OCR/native-sources `
  -OnnxRuntimeDirectory C:/OCR/onnxruntime/windows-x64 `
  -OpenCVDirectory C:/OCR/opencv/x64/vc16/staticlib `
  -Platform Win64

OnnxRuntimeDirectory 必須包含 OnnxRuntimeConfig.cmake，OpenCVDirectory 必須指向該架構專屬的程式庫組態；建置 32 位元 DLL 請選 Win32 與相符的 x86 程式庫

建置輔助腳本會寫出 Lib/Native/RapidOCR/<Platform>/HotPDFRapidOCR.dll；-BuildDirectory、-OutputDirectory 與 -Generator 可覆寫建置位置與 Visual Studio 產生器

橋接層會攔截 C++ 例外，並透過 HPDFRapidOCRAbiVersion、HPDFRapidOCRCreate、HPDFRapidOCRRecognize 與 HPDFRapidOCRDestroy 公開 ABI 版本 1；全部使用 cdecl、32 位元狀態值與明確的 UTF-8 位元組長度

ABI 版本 1 也定義了選用的 HPDFRapidOCRSetReadingDirection 匯出；只有啟用 RightToLeft 時轉接器才需要它，既有 DLL 仍可服務由左至右的請求

callback 只在呼叫期間借用文字；轉接器會在回傳前複製已驗證的文字，引擎解構子會先銷毀模型再卸載 DLL

驗證

有 Python onnx 套件與原生 BUILD_TESTING 組建時，可執行 python tools/test_rapidocr_detector.py <build>/Release/NativeDetectorTests.exe，透過 DLL ABI 檢查有效的空白輸出、無效的張量階數、通道與型別、不符的空間維度與無效機率；一次呼叫可傳入多個 runner 路徑，同時驗證兩種架構

在 Delphi 或 FPC 轉接器測試執行器加上 -RapidOCRLanguageModelDirectory 與一或兩個原生 DLL 程式庫參數，即可用中文、俄文、日文、韓文、常用拉丁語系、阿拉伯文與印地文樣本驗證全部已安裝預設集；俄文與繁體中文還會經過可搜尋 PDF 的儲存、重新載入、文字擷取與像素比對

Delphi 與 FPC 轉接器測試執行器會測試模型的持續生命週期、BGR 列布局、Unicode 與補充字元、ABI 檢查、無效結果、預算、合作式取消、序列化鎖定等待與清理

把 -RapidOCRNativeWin32Library、-RapidOCRNativeWin64Library 與 -RapidOCRNativeModelDirectory 傳給 Tests/Delphi/Run-TesseractRecognitionTests.ps1 或 Tests/Delphi/Run-TesseractFPCRecognitionTests.ps1，即可進行真實模型驗證、空白頁面、受損模型處理、英文與中文辨識，以及轉譯像素不變的可搜尋 PDF 往返測試

頁面轉譯、Unicode PDF 文字對應、可選內容分組與合規約束請見 可搜尋 OCR 文字層