Add VietOCR recognizer for high-accuracy Vietnamese OCR (lang='vi') - #5327
Open
nhducminh wants to merge 2 commits into
Open
Add VietOCR recognizer for high-accuracy Vietnamese OCR (lang='vi')#5327nhducminh wants to merge 2 commits into
nhducminh wants to merge 2 commits into
Conversation
Contributor
|
All contributors have signed the CLA ✍️ ✅ |
Author
|
I have read the CLA Document and I hereby sign the CLA |
Author
|
recheck |
nhducminh
force-pushed
the
add-vietocr-vietnamese-ocr
branch
from
July 25, 2026 02:47
5850ad0 to
5c367dc
Compare
PaddleOCR's shared "latin"/"ch" recognizer does not cover Vietnamese tone
marks, so pipeline OCR on Vietnamese documents frequently drops/misreads
diacritics ("QUYẾT ĐỊNH" -> "QUYT ĐNH"). This registers "vi" as a first-class
OCR language whose recognition is handled by VietOCR (vgg_transformer) while
detection stays PaddleOCR.
- ocr_language.py, models_config.yml: register "vi" as a public OCR language.
"vi" resolves through validate/normalize unchanged and maps its PaddleOCR
det/rec/dict to the "ch" models (detection is used; the rec model loads as a
valid fallback but is bypassed when VietOCR is available).
- pytorch_paddle.py: when lang='vi', load VietOCR and use it for the rec step
in ocr()/__call__(); confidence for drop_score filtering comes from VietOCR's
own softmax probs. Falls back to the PaddleOCR recognizer if VietOCR is
unavailable or errors (graceful degradation, no crash).
- vietocr_fast_batch.py: batched decoder for VietOCR with a KV-cache
(self-attn cache + one-time cross-attn projection) and per-sequence
early-exit, replacing vietocr's predict_batch()/translate() which recompute
self-attention over the full prefix every step and use an unbounded
torch.cat() that OOMs on large crop lists. Architecture-guarded: the
hand-rolled decode runs only on a post-norm nn.TransformerDecoderLayer stack,
else falls back to an architecture-agnostic decoder. ~26x faster than stock
predict_batch() in isolation, verified byte-identical to per-image predict().
- pyproject.toml: optional "vietocr" extra (install `mineru[pipeline,vietocr]`).
Tested end-to-end on a real Vietnamese PDF page: VietOCR path produces correct
diacritics; forcing VietOCR off exercises the PaddleOCR fallback without error.
Document the KV-cache/early-exit decoder rationale, the architecture guard, the correctness verification (0 mismatch vs stock predict_batch on 2000 crops), and the measured ~17x isolated speedup / ~3x in-pipeline speedup.
nhducminh
force-pushed
the
add-vietocr-vietnamese-ocr
branch
from
July 25, 2026 02:49
5c367dc to
6eeff10
Compare
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
Summary
Adds Vietnamese as a first-class OCR language (
lang='vi'). PaddleOCR's shared recognizer does not cover Vietnamese tone marks, so pipeline OCR on Vietnamese documents frequently drops/misreads diacritics — e.g. "QUYẾT ĐỊNH" → "QUYT ĐNH". This routes the recognition step to VietOCR (vgg_transformer) while detection stays PaddleOCR, and ships a custom batched decoder that is much faster than VietOCR's stockpredict_batch().Before / after (real Vietnamese PDF page)
Bng 2. Lưng phân hu co, hu co vi sinh cn cung cp theo kt qu phân tích đtBảng 2. Lượng phân hữu cơ, hữu cơ vi sinh cần cung cấp theo kết quả phân tích đấtChanges
ocr_language.py,models_config.yml— register"vi"as a public OCR language. It resolves throughvalidate/normalizeunchanged and maps its PaddleOCRdet/rec/dictto thechmodels (detection is used; the rec model still loads as a valid fallback but is bypassed when VietOCR is active).pytorch_paddle.py— forlang='vi', load VietOCR and use it for the rec step inocr()/__call__(); confidence fordrop_scorefiltering comes from VietOCR's own softmax probabilities. Falls back to the PaddleOCR recognizer if VietOCR is unavailable or errors (graceful degradation, no crash).vietocr_fast_batch.py(new) — batched VietOCR decoder with a KV-cache (self-attention cache + one-time cross-attention projection over the fixed encoder memory) and per-sequence early-exit. Replaces vietocr'spredict_batch()/translate(), which recompute self-attention over the full growing prefix every step and use an unboundedtorch.cat()that OOMs on large crop lists. Architecture-guarded: the hand-rolled decode runs only on a post-normnn.TransformerDecoderLayerstack, otherwise it falls back to an architecture-agnostic decoder — a differently-configured model can't produce silently-wrong output.pyproject.toml— optionalvietocrextra. Install withmineru[pipeline,vietocr].docs/en/reference/vietocr_benchmark.md— rationale, correctness, numbers.Correctness & performance
Predictor.predict()— 0 text mismatches across thousands of real crops, for both the KV-cache path and the fallback path.predict_batch()155 ms/crop → this decoder 9 ms/crop (~17×), 0/2000 mismatches. ~3× on the largest in-pipeline OCR batches.Notes
ch);viis opt-in via-l vi.vietocr+PyMuPDFare pulled only by the optionalvietocrextra, not by the core install.