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

模型初始化发生在工厂内，不占用识别时限；字典的类别数必须与识别模型匹配，而且仅仅类别数相同并不能说明字符顺序或预处理兼容

随附管线使用 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，并把它的依赖放在旁边或标准 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 快照；分配之前检查尺寸与像素预算，且不修改借用的位图

原生管线为每条识别出的文本行输出一个结果，带原始图像像素边界框和平均字符置信度；每行占用一个 MaxWords 名额，且不提供原生基线

检测框按水平行阅读顺序排列，默认从左到右，启用 RightToLeft 时从右到左；阿拉伯语预设会启用该选项

角度分类校正的是单个文本裁剪区域；它不判断整页方向，也不会把倒置页面上彼此分开的检测框重排成逻辑阅读顺序

识别出的文本保持模型的逻辑 Unicode 顺序；适配器不会自动反转阿拉伯语字符串，也不做双向塑形

适配器校验 UTF-8、Unicode 控制字符、边界框、置信度以及请求的 MaxTextCodeUnits 限制，文本硬上限为 1,048,576 个 UTF-16 单元；补充字符占用两个单元

空页面以空结果数组成功返回；失败会清除部分结果，可搜索 PDF 发布保持既有的原子页面事务行为

同一引擎上的调用会被串行化；等待引擎锁时每 25 毫秒检查一次取消状态与识别时限

原生回调在检测、分类以及每条识别行之前和之后检查取消与时限；单个 ONNX 推理调用无法被强制中断，因此取消可能在当前阶段完成后才返回

输入与文本限制约束的是适配器自身的分配和所接受的输出，不会对模型、检测、裁剪或推理内存施加硬性上限

构建与 ABI

Native/RapidOCR 包含 C++ 桥接、兼容的模型识别器、带版本号的 C 头文件、导出定义和 CMake 工程；请准备暴露 DbNet、AngleNet 和 OcrUtils 的兼容 CPU 网络源码，以及匹配的 ONNX Runtime 与 OpenCV 库

使用带 C++17 的 Windows MSVC、Windows SDK 以及 CMake 3.20 或更高版本；默认构建使用静态发布 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 库

构建辅助脚本把 DLL 写到 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 仍可服务从左到右的请求

回调中的文本只在调用期间借用；适配器在返回之前复制已校验的文本，引擎析构函数会先销毁模型再卸载 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 文本层