Adapter DLL native RapidOCR

HPDFRapidOCRRecognition cung cấp IHPDFOCREngine chạy in-process dựa trên HotPDFRapidOCR.dll, với cùng bộ API công khai trên các build Delphi, C++Builder, và Windows FPC/Lazarus Win32 lẫn Win64

DLL chạy inference ONNX trên CPU trực tiếp từ các snapshot bộ nhớ và giữ các mô hình đã khởi tạo cho tới khi engine interface được giải phóng; triển khai runtime gồm DLL native tương ứng cùng mô hình và từ điển cục bộ tương thích

Adapter tiến trình Python hiện có vẫn khả dụng với các overload factory gốc như cũ

Factory và options

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;

Khởi tạo options bằng THPDFRapidOCRDLLOptions.Default; các giá trị mặc định dùng những file cục bộ sau

Tên file tương đối được phân giải theo ModelDirectory; đường dẫn tuyệt đối có thể chọn các file được cấp phát riêng

Factory kiểm tra tính khả dụng của file, options, các export bắt buộc, và phiên bản ABI trước khi khởi tạo mô hình; cấu hình không hợp lệ raise EArgumentException, còn lỗi nạp mô hình raise EInvalidOperation kèm chẩn đoán từ phía native

Khởi tạo mô hình diễn ra trong factory và nằm ngoài deadline nhận dạng; số lớp của từ điển phải khớp mô hình nhận dạng, và chỉ riêng số lớp bằng nhau chưa đủ kết luận thứ tự ký tự hay tiền xử lý đã tương thích

Pipeline đi kèm dùng phát hiện DB với cạnh phát hiện tối đa 1,024 pixel và 50 pixel đệm trắng; recognizer chấp nhận các mô hình NCHW tương thích với chiều cao đầu vào cố định 32 hoặc 48, và dùng 48 cho chiều cao động

Nhận dạng giữ nguyên tỉ lệ khung hình cho các mô hình có chiều rộng động và chuẩn hóa đầu vào đã đệm với chiều rộng tối thiểu 320; mô hình chiều rộng cố định chặn trên chiều rộng crop sau resize, có thể nén một dòng văn bản dài

Phân loại góc nghiêng giữ tỉ lệ khung hình của crop trong bề rộng đầu vào của mô hình và lấp các pixel chưa dùng bằng số 0 đã chuẩn hóa; một crop chỉ bị xoay 180 độ khi điểm upside-down vượt 0.9, để các dự đoán hướng yếu không lật nhầm những dòng văn bản ngắn

Từ điển phải khớp thứ tự ký tự và số lớp đầu ra của mô hình; từ điển có line ending CRLF vẫn được chấp nhận, nhưng UTF-8 BOM bị từ chối

Khi mô hình nhúng metadata ký tự, factory còn xác thực từng mục từ điển và thứ tự của chúng; chỉ khớp kích thước từ điển là chưa đủ

Tiếng Trung, tiếng Nga, và các ngôn ngữ thông dụng

THPDFRapidOCRDLLOptions.ForLanguage chọn một mô hình nhận dạng cùng từ điển tương ứng bên dưới thư mục mô hình cục bộ, đồng thời giữ các giá trị mặc định dùng chung cho detector, classifier, thread, pixel, và timeout

Phương thức chấp nhận alias ngôn ngữ không phân biệt hoa thường, đổi gạch dưới thành gạch ngang, và cắt khoảng trắng hai đầu; tag rỗng hoặc không được hỗ trợ sẽ raise EArgumentException trước khi nạp mô hình

Mọi profile đều dùng <profile>/recognition.onnx và <profile>/dictionary.txt; tên profile được chấp nhận trực tiếp, còn các alias vùng miền được nhận diện đều được định nghĩa tường minh thay vì suy từ một tiền tố tùy ý

Cài các bộ mô hình đã chọn trước khi triển khai bằng helper cấp phát ghim SHA256

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

-Language All cài cả chín profile; -SkipClassifier bỏ qua classifier tùy chọn, khi đó hãy đặt UseAngleClassifier := False khi tạo engine

Helper xác thực các hash SHA256 đã ghim và cài một detector cùng classifier đa ngôn ngữ dùng chung dưới các tên file gốc mà Default dùng; nhận dạng chạy ngoại tuyến và không bao giờ tự tải mô hình còn thiếu

Hãy chọn ngôn ngữ cho engine theo từng trang hoặc từng vùng; một engine không tự phát hiện ngôn ngữ và cũng không ghép nhiều recognizer riêng biệt cho các hệ chữ khác nhau

Các package được ghim dùng các mô hình PP-OCRv3 và PP-OCRv4 tương thích; độ chính xác nhận dạng phụ thuộc mô hình, font, độ phân giải, và vùng crop, và mô hình Latin có thể nhầm các dấu như ñ ngay cả trên đầu vào sạch

Các mô hình PP-OCRv5 mới hơn có thể đòi hỏi ONNX Runtime mới hơn các static library dùng để build DLL; định dạng mô hình không được hỗ trợ sẽ fail khởi tạo kèm chẩn đoán

Mô hình phát hiện phải nhận một tensor ảnh float32 duy nhất và cho ra một map xác suất float32 với shape [1, 1, H, W] ở độ phân giải đầu vào đã resize; kiểu hoặc kích thước không tương thích, giá trị non-finite, hay xác suất lệch ngoài [0, 1] quá bốn epsilon máy của float32 sẽ thất bại kèm chẩn đoán trước khi kết quả phát hiện được dùng

Sai số làm tròn sigmoid nhỏ trong dung sai đó bị kẹp về [0, 1] trước khi ngưỡng hóa và chấm điểm contour để các mô hình hợp lệ giữ được hành vi phát hiện bình thường

Ví dụ tiếng Trung

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;

Hãy giữ interface engine qua nhiều yêu cầu để tái sử dụng mô hình của nó; dùng DLL khớp kiến trúc ứng dụng gọi và đặt các dependency của nó cạnh DLL hoặc trong các thư mục loader chuẩn của Windows

Ví dụ tiếng Nga

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, và rus chọn cùng mô hình nhận dạng lẫn từ điển cyrillic

Kết quả và vòng đời

Adapter sao chép bitmap hiện tại thành một snapshot BGR top-down độc lập; nó kiểm tra kích thước và ngân sách pixel trước khi cấp phát, và không sửa bitmap mượn

Pipeline native phát ra một kết quả cho mỗi dòng văn bản nhận dạng được, với biên theo pixel ảnh gốc và độ tin cậy trung bình của ký tự; mỗi dòng dùng một slot MaxWords, và không có baseline native nào được cung cấp

Các box phát hiện được theo thứ tự đọc theo hàng ngang, từ trái sang phải theo mặc định và từ phải sang trái khi bật RightToLeft; preset Arabic bật tùy chọn này

Phân loại góc nghiêng chỉ sửa từng crop văn bản riêng lẻ; nó không xác định hướng của cả trang và cũng không sắp xếp lại các box phát hiện riêng biệt của một trang bị lật ngược thành thứ tự đọc hợp lý

Văn bản nhận dạng được giữ theo thứ tự Unicode logic của mô hình; adapter không tự đảo chuỗi Ả Rập cũng như không áp dụng shaping hai chiều

Adapter xác thực UTF-8, ký tự điều khiển Unicode, biên, độ tin cậy, và giới hạn MaxTextCodeUnits của yêu cầu, với trần văn bản cứng 1,048,576 đơn vị UTF-16; ký tự bổ sung dùng hai đơn vị

Trang rỗng vẫn thành công với mảng kết quả rỗng; thất bại sẽ xóa kết quả làm dở, và việc công bố PDF tìm được vẫn giữ hành vi giao dịch trang nguyên tử hiện có

Các lời gọi trên cùng một engine được tuần tự hóa; việc chờ khóa engine kiểm tra hủy và deadline nhận dạng mỗi 25 milli-giây

Callback native kiểm tra hủy và deadline trước và sau các bước phát hiện, phân loại, và từng dòng nhận dạng được; một lời gọi inference ONNX đơn lẻ không thể bị ngắt ép, nên lệnh hủy có thể chỉ có hiệu lực sau khi giai đoạn hiện tại chạy xong

Các giới hạn đầu vào và văn bản chặn cấp phát của adapter cùng đầu ra được chấp nhận, nhưng không phải trần cứng cho bộ nhớ mô hình, phát hiện, crop, hay inference

Build và ABI

Native/RapidOCR chứa bridge C++, recognizer mô hình tương thích, header C có phiên bản, định nghĩa export, và project CMake; hãy cấp phát các mã nguồn mạng CPU tương thích có DbNet, AngleNet, và OcrUtils, cùng các thư viện ONNX Runtime và OpenCV tương ứng

Dùng Windows MSVC với C++17, một Windows SDK, và CMake 3.20 trở lên; build mặc định dùng static release CRT, phải khớp với các thư viện được cấp phát

& 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 phải chứa OnnxRuntimeConfig.cmake, và OpenCVDirectory phải trỏ tới cấu hình thư viện theo kiến trúc; chọn Win32 cùng các thư viện x86 tương ứng cho DLL 32-bit

Helper build ghi ra Lib/Native/RapidOCR/<Platform>/HotPDFRapidOCR.dll; -BuildDirectory, -OutputDirectory, và -Generator có thể ghi đè vị trí build và generator Visual Studio

Bridge bắt giữ các exception C++ và cung cấp ABI phiên bản 1 qua HPDFRapidOCRAbiVersion, HPDFRapidOCRCreate, HPDFRapidOCRRecognize, và HPDFRapidOCRDestroy; tất cả đều dùng cdecl, giá trị trạng thái 32-bit, và độ dài byte UTF-8 tường minh

ABI phiên bản 1 còn định nghĩa export tùy chọn HPDFRapidOCRSetReadingDirection; adapter chỉ đòi hỏi export này khi bật RightToLeft, nên các DLL hiện có vẫn phục vụ được yêu cầu trái-sang-phải

Callback chỉ mượn văn bản trong thời gian lời gọi; adapter sao chép văn bản đã xác thực trước khi trả về, và destructor của engine phá hủy mô hình trước khi unload DLL

Kiểm chứng

Với package onnx của Python và bản build native BUILD_TESTING, chạy python tools/test_rapidocr_detector.py <build>/Release/NativeDetectorTests.exe để kiểm tra đầu ra trắng hợp lệ, hạng tensor không hợp lệ, kênh và kiểu, kích thước không gian lệch nhau, và xác suất không hợp lệ qua ABI của DLL; nhiều đường dẫn runner có thể xác thực cả hai kiến trúc trong một lần chạy

Thêm -RapidOCRLanguageModelDirectory và một hoặc cả hai tham số thư viện DLL native vào runner adapter Delphi hoặc FPC để xác thực mọi preset đã cài với các mẫu tiếng Trung, Nga, Nhật, Hàn, các ngôn ngữ Latin thông dụng, Ả Rập, và Hindi; tiếng Nga và tiếng Trung phồn thể còn được chạy thêm lưu PDF tìm được, nạp lại, trích xuất văn bản, và so sánh pixel

Các runner adapter Delphi và FPC kiểm thử vòng đời mô hình bền vững, bố cục hàng BGR, ký tự Unicode và bổ sung, kiểm tra ABI, kết quả không hợp lệ, ngân sách, hủy hợp tác, chờ khóa tuần tự hóa, và dọn dẹp

Cung cấp -RapidOCRNativeWin32Library, -RapidOCRNativeWin64Library, và -RapidOCRNativeModelDirectory cho Tests/Delphi/Run-TesseractRecognitionTests.ps1 hoặc Tests/Delphi/Run-TesseractFPCRecognitionTests.ps1 để xác thực mô hình thật, trang rỗng, xử lý mô hình hỏng, nhận dạng tiếng Anh và tiếng Trung, và các round-trip PDF tìm được với pixel dựng ảnh không đổi

Xem Các lớp văn bản OCR có thể tìm kiếm để biết dựng trang, ánh xạ văn bản PDF Unicode, nhóm optional content, và các ràng buộc tuân thủ