Reza2kn's picture
Final Rizeh reader INT4 conversions; source 51b8c314b055; full-page qualification limits documented
b7a194b verified
|
Raw History Blame Contribute Delete
6.08 kB
---
language:
- fa
license: other
license_name: bina-0.4-rizeh
license_link: https://huggingface.co/Reza2kn/Bina-0.4-Rizeh/blob/51b8c314b0552b1884c1f0e28016cb12a143f637/README.md
base_model: Reza2kn/Bina-0.4-Rizeh
base_model_relation: quantized
pipeline_tag: image-to-text
tags:
- bina
- ocr
- int4
- onnx
---
# Bina0.4 Rizeh — ONNX-INT4
Quantized CTC reader components and experimental line-detector conversions of [the final release](https://huggingface.co/Reza2kn/Bina-0.4-Rizeh/tree/51b8c314b0552b1884c1f0e28016cb12a143f637), pinned at `51b8c314b0552b1884c1f0e28016cb12a143f637`. All five readers are included: body95k, short labels, printed, numeric/math and degraded scans. Original pipeline code and nonconverted dependencies remain in the source repository.
These are mixed-weight4-bit artifacts. They are not an all-INT4 document pipeline. The reference Python pipeline also uses Surya layout/order, native detector paths, table machinery and small admission/ordering models. No Sherpa-ONNX OCR support is claimed.
## Measured reader parity
Fresh uncompressed PyTorch2.10 CUDA baselines were generated for each published checkpoint. Each target uses the same300 frozen internal development crops (50 each: English, handwriting, mixed, newspaper, printed, synthetic). No text normalization is applied to parity. At least98% character parity is required in every bucket; exact-line agreement is reported separately in VALIDATION.json. These are development canaries, not held-out accuracy or full-page certification.
| Runtime | Reader components | Lowest bucket character parity |
|---|---:|---:|
| onnx-w4-block16 | 5/5 | 98.410% |
| onnx-hqq4-block32 | 5/5 | 98.583% |
| onnx-linux-cuda-w4-block16 | 5/5 | 98.642% |
| onnx-linux-cpu-hqq4-block32 | 5/5 | 98.583% |
| tract-cpu-w4-block16 | 5/5 | 98.672% |
| tract-metal-w4-block16 | 5/5 | 98.672% |
| tract-linux-cuda-w4-block16 | 5/5 | 98.672% |
| browser-webgpu | 5/5 | 98.672% |
| browser-wasm | 5/5 | 98.672% |
Mac timings were collected during concurrent conversion/browser work and are not controlled speed rankings. Linux CPU/CUDA results are host-specific; native Windows is untested. LiteRT was tested on Linux CPU, without an Android test device. Apple validation used an M2 Mac; iOS hardware was not tested.
## Page-pipeline limitation
The public release demo matched the original text in a small ONNX page test, and exact reader-cache reuse avoided recognition calls on its repeat. A broader public handwritten-table sample exposed a failure: the pure-W4 pipeline changed the output substantially even though line canaries passed. Therefore this bundle does **not** pass the full-page98% transcription gate and is not a drop-in fully qualified4-bit replacement for the production pipeline. Detector mask IoU is not transcription parity.
The experimental Python adapter preserves upstream crop geometry, routing and decoding. It also partitions an upstream geometry-reread cache by actual backend/weight hash, preventing cross-model cache reuse. Its optional image-only safety route uses original FP32 readers on color-separated handwritten pages, before OCR, avoiding a trial quantized pass. That route is mixed-precision and requires separate full-pipeline qualification. It does not make the pure-W4 model pass.
## Line-level use
Install requirements.txt, then run `python inference.py line.png --role body`. This expects one text line or an explicit line box through `Recognizer.read_line`; it does not detect or assemble a whole document. Persistent sessions and bounded exact-input caching are included. Widths are never squashed or truncated.
Inputs are64px-high float32 ink maps with aspect preserved, black=1/paper=0,20% vertical and30% horizontal margins measured in original line height. True widths retain masking semantics. CTC blank is0 and nonblank indices map to vocab.json. Persian visual-to-logical conversion follows the original rtl.py.
Use `recognizer-w4-block16.onnx` for ORT CUDA, browser WebGPU/WASM and tract. HQQ/block32 is an additional ORT CPU candidate; the tested tract importer cannot load its floating zero-point representation. Inputs: pixels float32 `[B,1,64,W]`, widths int64 `[B]`; outputs: tokens int32, confidence float32, lengths int32. The81 MatMulNBits layers use group16 symmetric W4; stem/depthwise operations and biases remain floating point. Their accuracy_level4 permits internal activation downcasting/quantization in runtime kernels; float32 graph inputs do not guarantee float32 internal GEMM.
Browser: `browser-reader.mjs` accepts an injected ONNX Runtime Web instance, a pinned baseURL, role and backend. It loads only the selected reader, reuses sessions, deduplicates pending requests and caches results by model/backend/input hash. It expects preprocessed ink maps; browser page segmentation/table assembly are not implemented by this loader. Use matching ORT1.31.1 JS/WASM assets and appropriate cross-origin isolation for threaded WASM.
## Experimental detectors
Three detector roles are included under experimental-detectors/: combined main detector1000, rule-C line guard500 and the printed detector/head. Their procedural-dev heatmaps were compared against their original FP32 models. Their full geometry/table/transcription impact is unqualified. Do not replace the production detectors based on mask IoU alone.
## Provenance and licensing
Quantization did not alter the source repository. The aggregate model.safetensors was verified tensor-for-tensor against the published native core checkpoints. Each component records its exact source checkpoint SHA256 in quantization_config.json. MANIFEST.json hashes the shipped artifacts. No private calibration images, benchmark fixtures, or private prediction texts are shipped.
Original recognizer weights/code remain under the source release CC BY-NC4.0 terms; Surya-derived detector/layout components retain their upstream Surya model terms. These conversions grant no additional rights. Retain the original Bina/Indra/Surya attribution. See the source release model card for details.