Skip to content

okf-rapidocr

Evaluate RapidOCR (PaddleOCR PP-OCR models on onnxruntime) as a native-ARM64 offline OCR path for OKF matters - A/B against the okf-ocr paddle path, identical sidecar conventions and confidence flags, resume-safe batches. Use when asked to benchmark or evaluate a native ARM64 OCR option, run fully offline batch OCR, or when paddle under x64 emulation crashes on a Snapdragon X / Windows-on-ARM laptop. Writes only sidecars next to sources - never touches matter folders or OCR_Log.

Source: .opencode/skills/okf-rapidocr/SKILL.md — site rebuilt 2026-09-05.

okf-rapidocr

OKF RapidOCR — native-ARM64 PaddleOCR engine

What this is

RapidOCR runs the PaddleOCR (PP-OCR, Baidu) models on onnxruntime instead of the paddle framework. It is the only fully-native ARM64 OCR path for the PP-OCR family: paddlepaddle ships no win_arm64 wheels, so the okf-ocr paddle path on a Snapdragon X / Windows-on-ARM laptop runs x64-emulated (verified 2026-08-09: PE machine 0x8664, PROCESSOR_ARCHITECTURE=AMD64) with emulation overhead and the known oneDNN/AVX512 crash — which is exactly why okf-ocr's pipeline sets enable_mkldnn=False.

Free, unlimited, 100% offline after first run (models download once, ~20 MB, and cache locally). No accounts, no API keys, no data leaves the machine.

Standalone evaluation skill — deliberately NOT wired into okf-ocr yet. It writes the same sidecar conventions (<base>_V1_OCR.txt, --- PAGE n --- sections, [LOW CONFIDENCE]/[FIGURE UNVERIFIED] flags) so results can drop into the OKF matter structure if adopted — but it writes NO OCR_Log rows, NO matter folders, NO README changes. Evaluate first, integrate later.

When to run

  • User asks to evaluate/benchmark a native-ARM64 OCR option for OKF matters (Snapdragon X / Windows-on-ARM laptops).
  • A/B testing RapidOCR against the okf-ocr paddle path on the same scan pages (identical flag thresholds so verdicts compare 1:1).
  • Fully-offline batch OCR of scans without touching the vision API chain.
  • Any time paddle under x64 emulation is slow or crashes on this laptop.

Tooling

tools/rapidocr_pipeline.py — single entry point:

python <skill>/tools/rapidocr_pipeline.py <file_or_folder> [--dpi 200] [--force]
                              [--pages 1-7] [--version v4|v5|v6] [--model small|mobile|server|tiny|medium]
                              [--json out.json]
  • Engine: unified rapidocr package (v3.x, requires Python <4,>=3.8 — works on 3.13), PP-OCR models on onnxruntime, per-line confidence scores. Defaults = package config (PP-OCRv6 small / ch) unless --version/--model given; overrides are passed as section-prefixed enum params (Det.ocr_version, Rec.model_type, ...) and fall back to package defaults if rejected.
  • Runtime architecture detection: reports native ARM64 / x64-emulated / x64-native automatically. Windows-on-ARM gotcha (verified): platform.machine() reports ARM64 even for an x64-emulated Python (Microsoft Store x64 build on Snapdragon X Elite) — the tool uses PROCESSOR_IDENTIFIER (ARMv8 prefix = ARM64 host) + PROCESSOR_ARCHITECTURE instead. When emulated, it prints a note: native speed requires a native ARM64 Python (python.org ARM64 or conda) with rapidocr/onnxruntime reinstalled there.
  • PDFs: pages rendered via PyMuPDF at --dpi; images (PNG/JPG/TIF/BMP) OCR'd directly.
  • Flags (identical to okf-ocr's paddle path):
  • score < 0.80 → [LOW CONFIDENCE n.nnn]
  • line contains a digit and score < 0.95 → [FIGURE UNVERIFIED n.nnn]
  • Resume-safe: existing sidecar sections are kept unless --force; --pages N-M merges into existing sections.
  • Outputs: <base>_V1_OCR.txt next to the source + per-file console summary (pages, lines, flagged, mean score, ms, arch) + optional --json combined summary.

Workflow

  1. Architecture check — the tool prints the runtime architecture first. On an ARM64 laptop, prefer running this under a native ARM64 Python; the venv/skills that run under the Store x64 build will report x64-emulated.
  2. Install (once, per Python): pip install rapidocr onnxruntime (+ pymupdf). First run downloads the models.
  3. Run the file/folder; review the console summary: mean score, flagged lines.
  4. QA the output — same bar as okf-ocr:
  5. flagged lines ([LOW CONFIDENCE] / [FIGURE UNVERIFIED]) stay flagged for human/agent decision; never auto-clear, never guess figures.
  6. tables/figures double-checked against the source even with zero flags.
  7. Evaluate vs the okf-ocr paddle path — run the same page through ocr_pipeline.py --engine paddle and compare: verbatim fidelity, line pairing on dense tables (RapidOCR is box-based, so row pairing on tabular scans is the known risk), speed under emulation vs native.

Rules

  • Never edit, redact or "fix" document content; never guess figures. Flagged lines remain for human decision.
  • Fully offline after first model download; no API keys, no accounts.
  • This skill writes only sidecars next to sources — it never touches OCR_Log, matter folders, or the okf-ocr skill. Do not "helpfully" wire it into ocr_pipeline.py during the evaluation phase.
  • The rapidocr API varies across major versions (rapidocr unified v3 vs rapidocr_onnxruntime legacy) — the tool probes defensively; if a future version breaks it, fix the probe, not the caller.

Self-learning

learnings.md sits next to this SKILL.md. Read before each run; append dated lessons after each evaluation run. Never delete entries.