pdf-inspector 选择性 OCR 运行时搭建指南PDFium、ONNX Runtime 与 PP-OCRv6 模型缓存实战【免费下载链接】pdf-inspectorFast Rust library for PDF inspection, classification, and text extraction. Intelligently detects scanned vs text-based PDFs to enable smart routing decisions.项目地址: https://gitcode.com/GitHub_Trending/pdf/pdf-inspectorpdf-inspector 是一款用 Rust 编写的 PDF 检测、分类与文本提取库其核心能力之一是选择性 OCR先通过原生提取器判断哪些页面真正需要 OCR再按需加载 PDFium 渲染、ONNX Runtime 推理与 PP-OCRv6 Small 模型从而让干净的文本型 PDF 全程不触碰任何 OCR 依赖。本文以 docs/ocr-runtime.md 为主体结合 src/vision 下的源码实现系统讲解 OCR 运行时的版本选择、共享库安装、模型缓存、离线部署与托管回退边界读完你可以在 Linux、macOS、Windows 上独立复现一条可验证的 OCR 链路并为生产环境设计出文本优先、按需 OCR、失败回退托管的智能路由方案。设计前提为什么 OCR 依赖是选择性加载的选择性 OCR 的总体契约非常明确干净的文本型文档永远不会加载 OCR 依赖也不会下载模型。只有auto模式路由出至少一页需要 OCR 时进程才会真正初始化 PDFium、ONNX Runtime并获取固定版本的 PP-OCRv6 Small 模型集。这一点在源码中有多重印证路由函数 route_ocr_pages 对OcrMode::Off直接返回空集Auto只保留被推荐且被用户选中的页面Force则处理全部选中页未指定时是全文档。空路由是零副作用的空操作no-oprun_ocr_pages 在页面列表为空时立即返回不触碰渲染器与 OCR 引擎。管道入口 process_pdf_with_ocr_mem 的文档注释明确指出Off模式即便完整编译了 OCR 功能也不会有渲染器、模型缓存、网络或推理副作用。auto模式下若没有路由出任何页面整个处理正常返回成功且不接触 PDFium、ONNX Runtime、模型缓存与网络对应 docs/ocr-runtime.md 的结尾说明。因此OCR 运行时本质上是按需就绪的外部运行时未用即零开销用到时才要求正确安装。下文所有安装步骤都是为被路由出页面这一条路径服务的。已验证版本可复现运行时的唯一基线官方文档给出了一条可复现的运行时路径三者必须配套使用组件固定版本说明Firecrawl PDFiumnative-v7988含 PDFium153.0.7988.0负责页面栅格化rasterization即把 PDF 页面渲染成位图ONNX Runtime1.27.0负责加载并执行 PP-OCRv6 的 ONNX 检测/识别图PP-OCRv6 Small工件修订号oar-ocr-v0.7.0检测模型 识别模型 字符字典三个工件文档明确提醒请以这些版本作为可复现基线。其他兼容的共享库构建或许能工作但不在发布冒烟测试smoke test覆盖范围内出了问题无法归因。从代码侧可以看到这条基线是如何被钉死的模型清单 PP_OCR_V6_SMALL 通过schema_version: 1、id: pp-ocrv6-small、revision: oar-ocr-v0.7.0唯一标识一套模型其中哈希与oar-ocr-core0.9.1 随附的注册表一致。每个工件都带固定文件名、HTTPS 下载地址、小写 SHA-256 摘要与精确字节数见 PP_OCR_V6_SMALL_ARTIFACTS任何大小或摘要不匹配都会被拒绝。ONNX Runtime 共享库名由 default_onnx_runtime_library 按平台给出Windows 为onnxruntime.dllLinux/Android/FreeBSD 为libonnxruntime.somacOS/iOS 为libonnxruntime.dylib。版本一致性是排障的第一依据如果模型下载失败或推理报错先核对这三个组件是否与上表完全一致。安装共享库按平台选择归档并解压PDFium 与 ONNX Runtime 都以共享库归档形式分发。官方推荐的资产如下平台PDFium 资产ONNX Runtime 资产Linux x64firecrawl-pdfium-linux-x64.tgzonnxruntime-linux-x64-1.27.0.tgzLinux ARM64firecrawl-pdfium-linux-arm64.tgzonnxruntime-linux-aarch64-1.27.0.tgzmacOS Apple Siliconfirecrawl-pdfium-mac-arm64.tgzonnxruntime-osx-arm64-1.27.0.tgzWindows x64firecrawl-pdfium-win-x64.tgzonnxruntime-win-x64-1.27.0.zip安全校验要点PDFium 发布页为每个平台归档同时提供SHA256SUMS、构建来源证明build provenance、许可证文件与 SPDX 文档ONNX Runtime 的每个资产也附带 GitHub 发布的 SHA-256 摘要。下载后应先做摘要校验再解压、放置到固定路径。用环境变量指向共享库当共享库不在平台默认库搜索路径上时通过两个环境变量显式指定这也是源码唯一认可的两个入口PDFIUM_LIB_PATHPDFium 共享库的绝对路径。加载失败的错误信息明确提示install a compatible PDFium shared library or set PDFIUM_LIB_PATH to its path见 pdfium.rs。ORT_DYLIB_PATHONNX Runtime 共享库的绝对路径。常量定义于 oar.rs加载失败同样提示设置该变量。Linux / macOSbashexport PDFIUM_LIB_PATH/absolute/path/to/libpdfium.so export ORT_DYLIB_PATH/absolute/path/to/libonnxruntime.so pdf2md scan.pdf --ocr auto --jsonmacOS 上文件名以.dylib结尾Windows 上使用 PowerShell 并把变量指向pdfium.dll与onnxruntime.dll$env:PDFIUM_LIB_PATH C:\absolute\path\to\pdfium.dll $env:ORT_DYLIB_PATH C:\absolute\path\to\onnxruntime.dll pdf2md scan.pdf --ocr auto --json关于变量读取顺序onnx_runtime_library_path 的逻辑是优先读取ORT_DYLIB_PATH非空即用否则回退到平台默认库名。PDFium 侧同理PdfiumRenderer::load 走平台搜索路径load_from_path则显式指定路径。平台覆盖面的诚实边界原生提取包还支持上述资产未覆盖的平台但不是所有平台都能跑通本地 OCRPython 包提供了 Intel macOS 的 wheel但 ONNX Runtime 1.27.0没有发布 Intel macOS 归档在该目标上做本地 OCR需要自行构建兼容的 ONNX Runtime。完整 OCR 链路目前只在 Linux x64 的 CI 上做端到端验证macOS 与 Windows 会编译并运行该功能的平台无关测试但其外部运行时路径应视为preview预览直到补齐等效冒烟任务。这段边界说明对生产选型非常关键若你的部署目标是 Intel macOS应优先走托管回退或自建 ONNX Runtime而不是默认期待本地 OCR 直接可用。模型缓存与离线模式SHA-256 验证的三件套首次路由触发下载与校验第一个被路由到 OCR 的页面会触发下载三个固定工件检测模型、识别模型、字符字典合计约 31 MB工件角色缓存文件名精确大小用途TextDetectionpp-ocrv6_small_det.onnx9,880,512 字节文本行检测ONNX 图TextRecognitionpp-ocrv6_small_rec.onnx21,159,378 字节文本行识别ONNX 图CharacterDictionaryppocrv6_dict.txt74,947 字节识别字符字典三个工件的固定摘要与大小定义在 PP_OCR_V6_SMALL_ARTIFACTS。每次使用时都会重新校验文件大小与 SHA-256任何不匹配都会被 ModelStoreError 的SizeMismatch/ChecksumMismatch拒绝——模型文件永远不会被信任存量跳过验证。模型存放在平台缓存目录之下具体布局为cache_root/manifest_id/revision/filename见 manifest_cache_root即pp-ocrv6-small/oar-ocr-v0.7.0/下放三个工件。可以通过环境变量PDF_INSPECTOR_MODEL_CACHE指定受管理的缓存根目录常量定义于 MODEL_CACHE_ENV未设置时回退到平台缓存目录下的pdf-inspector/models见 ModelStore::from_options。值得注意的工程细节模型下载与安装是跨进程加锁、原子替换的install_locked多个并发进程同时冷启动时只会产生一份验证过的文件.part临时文件会被清理sweep_stale_install_files损坏的旧缓存会被原子替换。此外缓存命中与否还决定 OCR 引擎是否复用管道层用模型根路径、运行时库路径、清单 schema/id/revision 与工件摘要构成缓存键cached_ocr_engine引擎会话在进程内按需构建一次。离线部署的四种写法对 hermetic密闭部署官方推荐提前填充模型目录 语言级离线开关的组合确保运行期零网络访问CLI--ocr-offline --ocr-model-dir /models/pp-ocrv6-smallRustModelDownloadPolicy::Offline配合OcrOptions::model_directoryPythonofflineTrue, model_directory/models/pp-ocrv6-smallNode.jsoffline: true, modelDirectory: /models/pp-ocrv6-small底层语义对应 ModelDownloadPolicy 的两个取值IfMissing默认仅在 OCR 实际被选中后获取缺失的固定工件Offline绝不访问网络要求显式模型目录或已有热缓存。实现上ModelStore::resolve_or_download 遵循严格的边界显式model_directory覆盖目录永远不会被网络补全或改写缺文件直接报ExplicitDirectoryIncompleteOffline策略下缓存不可用直接报DownloadsDisabled。对 Rust 侧可像 contracts.rs 测试 那样组合let options OcrOptions::new() .mode(OcrMode::Auto) .model_directory(/models/pp-ocr) .model_downloads(ModelDownloadPolicy::Offline);另外注意 validate_manifest 的防护清单 id、revision、工件文件名必须是单一普通路径组件杜绝路径逃逸下载 URL 必须为 HTTPS。离线包在交付前可用该清单自检避免部署后才发现目录不完整。模型来源与许可证模型工件来自GreatV/oar-ocr的v0.7.0发布其 OCR 实现与上游 PaddleOCR 项目均采用 Apache-2.0 许可。模型在运行时下载不嵌入任何 pdf-inspector 发布包。若你的分发物需要避免运行时外网依赖请务必用上面的离线模式 预填充目录方案。托管回退边界部署故障与页面质量问题必须分开这是运行时设计中容易被忽略、却最影响生产正确性的一环。何时产出pages_recommending_hosted本地管道完成后结果集中出现pages_recommending_hosted它标记那些OCR 结果为空、低置信度、或看起来仍不完整的页面。判定逻辑位于融合层融合选项 hosted_recommendation_confidence 默认 0.5即页面平均置信度低于该阈值时视为弱 OCRweak OCR融合时若markdown为空、或mean_confidence低于阈值、或自适应逻辑判定本地路径不适合则置位hosted_recommended见 fusion.rs最终汇总为 pages_recommending_hosted。也就是说pages_recommending_hosted是对本地 OCR 产出质量的结果级评价它只会在本地管道成功完成后才存在。何时直接返回错误与结果级评价相对的是设置/执行级失败这类问题发生在结果产生之前直接以错误形式返回PDFium / ONNX Runtime 库缺失或不兼容模型获取失败下载、校验、离线目录不完整OCR 执行错误推理失败。从错误枚举可以看得一清二楚OarOcrError::OnnxRuntimeLoad负责库加载ModelAcquireError的Download/DownloadsDisabled/ExplicitDirectoryIncomplete负责模型获取OcrRunError::Render/Ocr负责执行阶段。任何这类错误都应被下游视为部署问题而不是页面质量问题。正确的集成姿态是下游如果有托管解析器应捕获这些错误并把整份文档路由到托管路径。这样设计的好处是——部署问题库没装、模型拿不到与页面质量判断OCR 出来但不可信被严格分离不会因为环境故障而误判文档本身质量差。从源码契约看这一边界是刻意为之OcrMode::Auto下无路由页面时管道成功返回、零副作用见 docs/ocr-runtime.md 结尾意味着纯文本文档 未安装 OCR 运行时是一个完全合法的成功场景只有当确实需要 OCR 且环境不满足时才会以错误暴露运行时问题。运行时决策速查场景推荐做法纯文本 PDF 批量处理保持默认Off零外部依赖、零下载扫描件与文本混合的文档auto模式仅路由出问题页面走 OCR所有页面强制 OCRForce模式注意会包含有原生文本的页内网 / 密闭部署预填充模型目录 Offline策略 --ocr-offline共享库未装到系统路径设置PDFIUM_LIB_PATH与ORT_DYLIB_PATH本地 OCR 质量不可信检查pages_recommending_hosted回退托管解析运行时库 / 模型获取失败捕获错误整体路由到托管路径部署故障非质量问题延伸阅读docs/ocr-runtime.md本文对应的官方运行时文档src/vision/mod.rsOCR 相关 featurevision、render-pdfium、model-cache、model-download、ocr-oar等的模块门控与导出src/vision/pipeline.rsprocess_pdf_with_ocr(_mem)一键管道与引擎缓存src/vision/models.rs模型清单、SHA-256 缓存与离线边界src/vision/oar.rsPP-OCRv6 Small CPU 引擎、ONNX Runtime 加载与检测自适应src/vision/routing.rsOff/Auto/Force路由与页面校验src/vision/fusion.rs原生/OCR 融合与托管推荐阈值src/python.rs 与 napi/src/lib.rsPython 与 Node.js 侧process_pdf_with_ocr的参数映射offline/model_directory。【免费下载链接】pdf-inspectorFast Rust library for PDF inspection, classification, and text extraction. Intelligently detects scanned vs text-based PDFs to enable smart routing decisions.项目地址: https://gitcode.com/GitHub_Trending/pdf/pdf-inspector创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考
