Instructions to use tardellirs/Escriba-OCR-1B with libraries, inference providers, notebooks, and local apps. Follow these links to get started.
- Libraries
- Transformers
How to use tardellirs/Escriba-OCR-1B with Transformers:
# Use a pipeline as a high-level helper from transformers import pipeline pipe = pipeline("image-text-to-text", model="tardellirs/Escriba-OCR-1B") messages = [ { "role": "user", "content": [ {"type": "image", "url": "https://huggingface.co/datasets/huggingface/documentation-images/resolve/main/p-blog/candy.JPG"}, {"type": "text", "text": "What animal is on the candy?"} ] }, ] pipe(text=messages)# pip install -U transformers accelerate # Load model directly from transformers import AutoProcessor, AutoModelForSeq2SeqLM processor = AutoProcessor.from_pretrained("tardellirs/Escriba-OCR-1B") model = AutoModelForSeq2SeqLM.from_pretrained("tardellirs/Escriba-OCR-1B", device_map="auto") messages = [ { "role": "user", "content": [ {"type": "image", "url": "https://huggingface.co/datasets/huggingface/documentation-images/resolve/main/p-blog/candy.JPG"}, {"type": "text", "text": "What animal is on the candy?"} ] }, ] inputs = processor.apply_chat_template( messages, add_generation_prompt=True, tokenize=True, return_dict=True, return_tensors="pt", ).to(model.device) outputs = model.generate(**inputs, max_new_tokens=256) print(processor.decode(outputs[0][inputs["input_ids"].shape[-1]:])) - Notebooks
- Google Colab
- Kaggle
- Local Apps Settings
- vLLM
How to use tardellirs/Escriba-OCR-1B with vLLM:
Install from pip and serve model
# Install vLLM from pip: pip install vllm # Start the vLLM server: vllm serve "tardellirs/Escriba-OCR-1B" # Call the server using curl (OpenAI-compatible API): curl -X POST "http://localhost:8000/v1/chat/completions" \ -H "Content-Type: application/json" \ --data '{ "model": "tardellirs/Escriba-OCR-1B", "messages": [ { "role": "user", "content": [ { "type": "text", "text": "Describe this image in one sentence." }, { "type": "image_url", "image_url": { "url": "https://cdn.britannica.com/61/93061-050-99147DCE/Statue-of-Liberty-Island-New-York-Bay.jpg" } } ] } ] }'Use Docker
docker model run hf.co/tardellirs/Escriba-OCR-1B
- SGLang
How to use tardellirs/Escriba-OCR-1B with SGLang:
Install from pip and serve model
# Install SGLang from pip: pip install sglang # Start the SGLang server: python3 -m sglang.launch_server \ --model-path "tardellirs/Escriba-OCR-1B" \ --host 0.0.0.0 \ --port 30000 # Call the server using curl (OpenAI-compatible API): curl -X POST "http://localhost:30000/v1/chat/completions" \ -H "Content-Type: application/json" \ --data '{ "model": "tardellirs/Escriba-OCR-1B", "messages": [ { "role": "user", "content": [ { "type": "text", "text": "Describe this image in one sentence." }, { "type": "image_url", "image_url": { "url": "https://cdn.britannica.com/61/93061-050-99147DCE/Statue-of-Liberty-Island-New-York-Bay.jpg" } } ] } ] }'Use Docker images
docker run --gpus all \ --shm-size 32g \ -p 30000:30000 \ -v ~/.cache/huggingface:/root/.cache/huggingface \ --env "HF_TOKEN=<secret>" \ --ipc=host \ lmsysorg/sglang:latest \ python3 -m sglang.launch_server \ --model-path "tardellirs/Escriba-OCR-1B" \ --host 0.0.0.0 \ --port 30000 # Call the server using curl (OpenAI-compatible API): curl -X POST "http://localhost:30000/v1/chat/completions" \ -H "Content-Type: application/json" \ --data '{ "model": "tardellirs/Escriba-OCR-1B", "messages": [ { "role": "user", "content": [ { "type": "text", "text": "Describe this image in one sentence." }, { "type": "image_url", "image_url": { "url": "https://cdn.britannica.com/61/93061-050-99147DCE/Statue-of-Liberty-Island-New-York-Bay.jpg" } } ] } ] }' - Docker Model Runner
How to use tardellirs/Escriba-OCR-1B with Docker Model Runner:
docker model run hf.co/tardellirs/Escriba-OCR-1B
Escriba-OCR-1B
A 1B-parameter OCR model for handwritten Portuguese essays that keeps the student's errors. Open weights; runs on a GPU or on a plain CPU (GGUF).
Escriba-OCR-1B reads a photo or scan of a handwritten redaΓ§Γ£o (ENEM-style student essay) and writes down exactly what the student wrote, line by line: spelling mistakes, end-of-line hyphenation, struck-through words and insertions included. General OCR models and large VLMs tend to return a "clean", corrected text. Escriba is trained to do the opposite.
| Task | Full-page handwritten text recognition (OCR) that preserves the writer's errors |
| Language | Brazilian Portuguese |
| Base model | lightonai/LightOnOCR-3-1B (Pixtral vision encoder + Qwen3 decoder, ~1B parameters) |
| Training data | BRESSAY: 1,000 handwritten essay pages by 1,000 writers (training split: 647 pages) |
| Output | Plain text, one line per handwritten line, BRESSAY markup for edits |
| License | CC BY-NC 4.0 (non-commercial, inherited from the training data) |
| Developed by | Tardelli Ronan Coelho Stekel, Federal Institute of SΓ£o Paulo (IFSP), Brazil |
| Try it | Online demo (Hugging Face Space) |
| CPU version | tardellirs/Escriba-OCR-1B-GGUF (llama.cpp) |
| Code, viewer and benchmark | github.com/tardellirs/escriba-ocr |
| Status | Research release, v1 (November 2026) |
Contents
- Intended use
- Output format
- Results
- How to use
- Training
- Evaluation protocol
- Limitations and risks
- License
- Citation
- Resumo em portuguΓͺs
Intended use
Use it for:
- digitising handwritten student essays for teachers, researchers and educational tools, keeping the student's own spelling and edits;
- building corpora of learner writing for research (orthography, writing development, automated feedback);
- a first transcription that a person then reviews.
Out of scope:
- grading or scoring essays, or any high-stakes decision without human review. Escriba transcribes; it does not assess;
- commercial use (see License);
- printed documents, forms, tables or math. Use the base LightOnOCR model for those;
- languages other than Portuguese, and historical manuscripts.
Output format
One output line per handwritten line, a blank line between paragraphs, and the student's spelling kept. Edits are written in the annotation scheme of BRESSAY, which the model learned. The definitions below are those of the dataset authors:
| Markup | Meaning |
|---|---|
--text-- |
Text that has been crossed out but remains readable |
--xxx-- |
Text that has been crossed out in a way that makes it unreadable |
##text## |
Text added as a superscript in the line, typically as a correction or additional note |
$$text$$ |
Text added as a subscript in the line, typically as a correction or additional note |
@@???@@ |
Text that cannot be read or identified due to its illegibility |
##--text--## |
Text added as a superscript and subsequently crossed out, but still legible |
$$--text--$$ |
Text added as a subscript and subsequently crossed out, but still legible |
##--xxx--## |
Text added as a superscript and subsequently crossed out, rendering it illegible |
$$--xxx--$$ |
Text added as a subscript and subsequently crossed out, rendering it illegible |
##@@???@@## |
Superscript text that has become unidentifiable and unreadable |
$$@@???@@$$ |
Subscript text that has become unidentifiable and unreadable |
The combined forms are rare in the data, so the model reproduces them less reliably than the basic ones (see Results).
Example in this style (BRESSAY ground truth, validation page 0212-004):
Os pensadores Adorno e Horkheimer, da Escola de Frankfurt, criaram o con-
ceito de IndΓΊstria Cultural, segundo o qual a ##arte e a## cultura sΓ£o padronizadas e massificada
principalmente, como uma ferramenta amicada ##para o## --no-- acΓΊmulo de capital. Hodiernamente, no Brasil,
The plural "padronizadas e massificada", the line-break hyphen in "con-ceito", the inserted words and the struck-through "no" are all part of the expected transcription.
Results
All numbers are on the BRESSAY test split (199 full pages, 1 writer each), which was used once, after model selection on the validation split. CER is the character error rate on the whole page (lower is better), case-insensitive unless noted, with each page capped at 100% so that a single runaway generation cannot dominate the average. Recall is the share of ground-truth struck-through (--text--) and inserted (##text##) spans reproduced exactly. "Lines" is the share of pages with the correct number of lines.
Escriba vs. the strongest open baselines
The comparison is restricted, by design, to open-weight systems that a school can run on its own hardware.
| System | Params | CER | CER, case-sensitive | CER, text only | WER | --t-- recall |
--xxx-- recall (precision) |
##t## recall |
Lines |
|---|---|---|---|---|---|---|---|---|---|
| Escriba-OCR-1B | 1B | 2.06% | 2.13% | 1.91% | 5.9% | 37% | 77% (68%) | 63% | 97% |
| Qwen3-VL 235B-A22B, zero-shot | 235B (22B active) | 5.60% | 6.44% | 4.62% | 11.2% | 1% | 1% | 3% | 79% |
| Qwen3.5 27B, zero-shot | 27B | 8.01% | 8.40% | 6.64% | 16.4% | 2% | 1% | 16% | 53% |
| LightOnOCR-3 4B, zero-shot | 4B | 8.44% | 8.52% | 7.14% | 18.2% | 0% | 0% | 0% | 0% |
| Qwen2.5-VL 72B, zero-shot | 72B | 8.51% | 9.12% | 7.58% | 21.5% | 0% | 0% | 0% | 42% |
| LightOnOCR-3 1B (base), zero-shot | 1B | 8.97% | 9.83% | 7.88% | 20.5% | 0% | 0% | 0% | 12% |
| HTR-Flor, trained on BRESSAY, ground-truth line crops | <1M | 10.33% | 10.43% | 9.48% | 30.6% | 0% | 0% | 0% | (100%) |
"Text only" removes struck-through and illegible spans and unwraps insertions, so it measures reading of the text itself. Against Qwen3-VL 235B-A22B, the best open baseline, Escriba's CER is 3.54 points lower (paired page bootstrap, 95% CI [β4.19, β2.94]), and 2.71 points lower on text only ([β3.37, β2.04]). The intervals reflect variation over test pages, not over training seeds. Training variation is small: two more runs of the same recipe with different seeds reach 2.05% and 2.03% CER, so over three seeds CER is 2.05 Β± 0.02, text-only CER 1.74 Β± 0.15 and error preservation 24.9 Β± 1.3% (mean Β± SD). The released model is seed 0.
Escriba vs. open vision-language models (zero-shot)
| Model | Params | Run via | CER | WER | Strike recall | Insert recall | Lines | Truncated pages |
|---|---|---|---|---|---|---|---|---|
| Escriba-OCR-1B (fine-tuned) | 1B | local | 2.06% | 5.9% | 37.3% | 63.3% | 97% | 0 |
| Qwen3-VL 235B-A22B | 235B (22B active) | OpenRouter | 5.60% | 11.2% | 1.0% | 2.9% | 79% | 0 |
| Qwen3.5 27B | 27B | OpenRouter | 8.01% | 16.4% | 1.5% | 15.6% | 53% | 4 |
| LightOnOCR-3 4B | 4B | local (vLLM) | 8.44% | 18.2% | 0.0% | 0.0% | 0% | 1 |
| Qwen2.5-VL 72B | 72B | OpenRouter | 8.51% | 21.5% | 0.0% | 0.0% | 42% | 1 |
| LightOnOCR-3 1B (base) | 1B | local (vLLM) | 8.97% | 20.5% | 0.0% | 0.0% | 12% | 0 |
| Qwen3.5 4B | 4B | local (vLLM) | 9.11% | 18.0% | 0.3% | 1.1% | 32% | 1 |
| Qwen3-VL 8B | 8B | OpenRouter | 9.18% | 19.8% | 0.0% | 0.0% | 19% | 2 |
| Qwen3-VL 30B-A3B | 30B (3B active) | OpenRouter | 10.01% | 23.7% | 0.0% | 0.3% | 42% | 4 |
| Qwen3.5 9B | 9B | OpenRouter | 10.82% | 24.1% | 0.2% | 1.1% | 20% | 9 |
| Gemma 4 31B | 31B | OpenRouter | 16.30% | 35.0% | 0.8% | 9.0% | 70% | 9 |
| Qwen3.5 2B | 2B | local (vLLM) | 17.01% | 32.0% | 0.0% | 0.0% | 6% | 8 |
| LightOnOCR-3 0.8B | 0.8B | local (vLLM) | 17.58% | 32.6% | 0.0% | 0.0% | 1% | 5 |
| Llama 4 Maverick | 400B (17B active) | OpenRouter | 18.47% | 34.8% | 0.2% | 0.0% | 22% | 0 |
| GLM-OCR | 0.9B | local (vLLM) | 18.84% | 43.7% | 0.0% | 0.0% | 20% | 6 |
| Mistral Small 3.2 | 24B | OpenRouter | 20.74% | 49.4% | 0.0% | 0.3% | 9% | 12 |
| PaddleOCR-VL 1.6 | 0.9B | local (vLLM) | 24.49% | 49.4% | 0.0% | 0.0% | 9% | 10 |
| Llama 4 Scout | 109B (17B active) | OpenRouter | 29.55% | 69.8% | 0.0% | 0.0% | 5% | 17 |
| Qwen3-VL 2B | 2B | local (vLLM) | 38.61% | 69.5% | 0.0% | 0.0% | 2% | 55 |
| Gemma 3 27B | 27B | OpenRouter | 40.48% | 65.3% | 1.0% | 0.0% | 17% | 6 |
| Gemma 3 12B | 12B | OpenRouter | 61.40% | 139.0% | 0.5% | 0.0% | 3% | 43 |
| Gemma 3 4B | 4B | OpenRouter | 85.23% | 223.5% | 0.0% | 0.0% | 1% | 125 |
Open models were prompted with the same Portuguese error-preserving instructions (local OCR-specialised models LightOnOCR, PaddleOCR-VL and GLM-OCR with their native prompt, as they do not follow instructions). OpenRouter models: page upscaled to 1540 px, temperature 0, reasoning disabled, 3,000 max tokens. Local models: vLLM 0.34 on an NVIDIA L4, page upscaled to 1600 px, greedy decoding, repetition penalty 1.05. "Truncated" counts pages where generation hit the token limit, usually a repetition loop.
Reading the tables.
- Accuracy. No open model we tried, from 0.8B to 400B parameters, comes close without fine-tuning. The best, Qwen3-VL 235B-A22B, makes 2.7 times more character errors than Escriba, and Escriba is better on 170 of the 199 test pages and worse on 5.
- Conventions. No zero-shot model reproduces the edit markup, and few reproduce the line structure. Fine-tuning teaches both.
- Robustness. On 50 validation pages with synthetic phone-photo degradation (blur, perspective, shadow, JPEG), Escriba's CER is 10.1%, against 30.9% for the base model. These degradations come from the same family as the training augmentation, so this is not a test on real photos.
Does it keep the student's mistakes?
Mostly, not always. Every model we tested, Escriba included, sometimes writes the dictionary form of a misspelled word. Two measurements:
- Automatic. Of the 496 test words that are absent from a pt-BR dictionary in the ground truth, Escriba copies 24% verbatim, against 13% for its base model and 21% for Qwen3-VL 235B-A22B. The 21 open VLMs we tested replace 39β78% of these words with dictionary words, even when told not to. Escriba turns a correctly spelled word into a non-word in 1.4% of cases.
- Human review. A teacher reviewed 96 random cases where Escriba wrote a dictionary word in place of such a non-dictionary word. 89 could be judged (the review was not blind):
| Verdict (n = 89) | Share (95% CI) |
|---|---|
| The student really misspelled the word and the model "fixed" it | 43% (33β53%) |
| The BRESSAY transcription itself was wrong; the student wrote the correct form | 45% (35β55%) |
| Ambiguous or illegible | 12% (7β21%) |
The automatic score therefore underestimates error preservation. Removing the estimated ground-truth errors from the 496 words raises Escriba's preservation from 24% to about 32%, or 36% if the ambiguous cases are removed as well. If every misspelling matters (spelling research, error annotation), have a person review the output.
How to use
vLLM (recommended)
# pip install "vllm>=0.34" pillow
import base64, io
from PIL import Image
from vllm import LLM, SamplingParams
def to_data_url(path, long_side=1200):
"""Resize so the longer side is 1200 px (up or down), as in training."""
im = Image.open(path).convert("RGB")
f = long_side / max(im.size)
im = im.resize((round(im.width * f), round(im.height * f)), Image.LANCZOS)
buf = io.BytesIO(); im.save(buf, format="PNG")
return "data:image/png;base64," + base64.b64encode(buf.getvalue()).decode()
llm = LLM(model="tardellirs/Escriba-OCR-1B", max_model_len=8192, limit_mm_per_prompt={"image": 1})
params = SamplingParams(temperature=0.0, repetition_penalty=1.05, max_tokens=2048)
# Image only, empty prompt: this is the transcription mode used in training.
messages = [{"role": "user", "content": [{"type": "image_url", "image_url": {"url": to_data_url("redacao.jpg")}}]}]
print(llm.chat([messages], params)[0].outputs[0].text)
A ready-to-run script for one or more pages is in inference_example.py.
Settings that matter
| Setting | Value | Why |
|---|---|---|
| Image size | 1200 px on the longer side | The processor only downscales. Small scans (BRESSAY pages are ~550 px wide) otherwise give too few visual tokens. Training and evaluation used 1200 px; 1540 px gave no reliable gain. |
| Prompt | empty (image only) | The training format |
| Decoding | greedy, repetition_penalty=1.05 |
Deterministic; prevents rare repetition loops |
max_tokens |
2048 | A full page is typically 600β1,100 tokens |
Throughput (vLLM, 1Γ A100 40 GB): 2.3 s per page one at a time (median); 1.6 pages/s in a batch.
CPU: llama.cpp (GGUF)
Quantized GGUF files for llama.cpp are in tardellirs/Escriba-OCR-1B-GGUF. The model runs on a CPU, with no GPU:
llama-server -hf tardellirs/Escriba-OCR-1B-GGUF:Q4_K_M --temp 0 --repeat-penalty 1.05 -c 8192 --cache-ram 0 --port 8010
llama-server exposes the same OpenAI-compatible API as vLLM, so the client, CLI and viewer in the GitHub repository work unchanged. Resize the page to 1200 px and send only the image, as above.
On a 4-vCPU cloud VM (AMD EPYC Turin), a page takes about 1 minute with Q4_K_M and under 4 GB of RAM. See the GGUF model card for all quantizations.
transformers
The checkpoint keeps the original LightOnOCR-3-1B weight layout, which vLLM loads directly. In transformers 5.22, LightOnOcrForConditionalGeneration.from_pretrained does not map this layout's decoder weights (language_model.model.*) and leaves them randomly initialised, without raising an error. The base model is affected the same way. Load the weights explicitly:
import torch
from huggingface_hub import hf_hub_download
from safetensors.torch import load_file
from transformers import LightOnOcrForConditionalGeneration, LightOnOcrProcessor
repo = "tardellirs/Escriba-OCR-1B"
model = LightOnOcrForConditionalGeneration.from_pretrained(repo, dtype=torch.bfloat16)
state = load_file(hf_hub_download(repo, "model.safetensors"))
prefix = "language_model.model."
remap = lambda k: "model.language_model." + k[len(prefix):] if k.startswith(prefix) else k
missing, unexpected = model.load_state_dict({remap(k): v for k, v in state.items()}, strict=False)
assert not [k for k in missing if k != "lm_head.weight"] and not unexpected
model.lm_head.weight = model.model.language_model.embed_tokens.weight # tied embeddings
model = model.eval().to("cuda")
processor = LightOnOcrProcessor.from_pretrained(repo)
Then build the input with processor.apply_chat_template([{"role": "user", "content": [{"type": "image"}]}], add_generation_prompt=True, tokenize=False) and the 1200 px image, and call model.generate(..., do_sample=False, repetition_penalty=1.05, max_new_tokens=2048).
Training
| Base model | lightonai/LightOnOCR-3-1B |
| Data | BRESSAY training split (647 pages) and the page, paragraph and line crops of those pages, sampled 40% / 30% / 30% |
| Target | the BRESSAY transcription verbatim (errors, hyphenation and markup) followed by <|im_end|>; loss on target tokens only, normalised per token |
| Input | 1200 px on the longer side; light phone-photo augmentation (rotation Β±1Β°, perspective, scale 0.95β1.05, blur, shadow, JPEG 60β95) |
| Trainable parameters | all; the vision encoder at 0.1Γ the learning rate |
| Optimiser | AdamW (Ξ²1 0.9, Ξ²2 0.95, no weight decay), lr 6e-5, cosine schedule, 3% warm-up, gradient clipping 1.0 |
| Batch / length | effective batch 8, 12,000 examples (1,500 steps) |
| Precision | bf16 weights with fp32 master copies |
| Hardware / time | 1Γ NVIDIA A100 40 GB, 85 minutes |
| Software | transformers 5.22.1, PyTorch 2.14, vLLM 0.34 (evaluation) |
What we tried (validation split, 154 pages)
Choices were made by screening short runs and comparing them with a paired page-level bootstrap. Seed-to-seed noise in these short decoder-only runs is about 0.7 pt CER; the final recipe, which also trains the vision encoder, varies by only Β±0.02 pt across three seeds.
| Change | Effect on validation CER | Kept |
|---|---|---|
| Train the vision encoder too (vs. decoder only) | β1.6 pt, significant | yes |
| Learning rate 3e-5 instead of 1e-5 (decoder only) | β1.4 pt, significant | yes (6e-5 final) |
| Add line crops to pages and paragraphs | β0.6 pt, within seed noise | yes |
| Phone-photo augmentation | β0 on clean scans; simulated-photo CER 15.7% β 11.2% at 8k examples (10.1% at 12k) | yes |
| Longer training | 2.46% (2.4k examples) β 2.25% (8k) β 2.03% (12k, with augmentation) | yes |
| 1540 px instead of 1200 px | β0.2 pt, within noise, 2Γ training cost | no |
| Contrastive decoding against the text-only prior | no gain in error preservation, more invented errors | no |
| Over-sampling crops that contain misspellings (4Γ) | +2 pt preservation, within noise | no |
| Repetition penalty 1.0 vs 1.05 | identical | 1.05 |
More data still helps. With a fixed budget of 8k examples and no augmentation, training on 25% of the pages gives 3.35% CER, 50% gives 2.70% and 100% gives 2.25%. The curve has not flattened.
Environmental impact
The final training run used about 1.4 GPU-hours on one A100. Including all screening runs and baselines, the project used about 28 GPU-hours (NVIDIA L4, T4, A6000 and A100) plus the API evaluations.
Evaluation protocol
- Data. Official BRESSAY splits: training 647 pages, validation 154, test 199. Development used the validation split only. The test split was evaluated once with the final model.
- Normalisation. Unicode NFC. Visually identical glyphs merged: curly quotes to straight quotes,
Β°toΒΊ, dashes to-. Whitespace collapsed for CER and WER. - Metrics. CER and WER are Levenshtein distance divided by reference length, micro-averaged over pages, with and without case.
- Markup: precision and recall over (type, content) spans.
- Error preservation: reference words absent from the Hunspell pt-BR dictionary (lowercase-initial, β₯3 letters) are aligned to the output and counted as preserved, corrected (output is a dictionary word), misread or deleted.
- Invented errors: reference dictionary words output as non-words.
- Baselines (open-weight only).
- General VLMs: a Portuguese error-preserving instruction (copy exactly, do not correct, keep line breaks and hyphens, use the BRESSAY markup). Thirteen models ran through OpenRouter with pages upscaled to 1540 px (JPEG q92), temperature 0, reasoning disabled and 3,000 max tokens; several were served by two to five providers with unknown quantisation. Three small ones ran locally.
- OCR-specialised VLMs (LightOnOCR-3, PaddleOCR-VL, GLM-OCR): their native prompt, since they do not follow instructions.
- Local runs: vLLM 0.34 on an NVIDIA L4, pages upscaled to 1600 px, greedy decoding, repetition penalty 1.05, 2,048 max tokens.
- HTR-Flor: trained on BRESSAY lines with the authors' code and evaluated on ground-truth line crops.
- Contamination: BRESSAY has been public since 2024, so the evaluated models may have seen its test images.
- Not comparable: results of the ICDAR 2024 competition use a different normalisation.
- Code. The benchmark, training code, all model outputs and a local viewer are at github.com/tardellirs/escriba-ocr.
Limitations and risks
- One source of data. BRESSAY pages come from online essay platforms, cropped to the text and at low resolution. Classroom photos (the official answer sheet, paper texture, perspective, lighting) are only simulated by augmentation and have not been validated on real photos.
- Casing convention. Following BRESSAY, ALL-CAPS handwriting is transcribed in sentence case.
- Corrections and hallucinations. The model sometimes replaces a misspelled or hard-to-read word with a plausible dictionary word, and in rare cases with an unrelated one (for example, "CATΓSTROFE" read as "amnistia").
- Edit markup is far from perfect: it finds about 37% of legible struck-through spans, 77% of illegible ones and 63% of insertions, and the
@@???@@illegible marker is rarely produced (12% recall). - Inputs. One page per call, Portuguese only. Text beyond about 2,000 output tokens is truncated.
- Ground-truth noise. BRESSAY transcriptions contain errors (see the human review above). Part of the reported error is in the reference, not in the model.
- Privacy. Student essays are personal data, protected in Brazil by the LGPD. Prefer running the model locally, and do not upload essays to third-party services without consent.
- Fairness. All 1,000 BRESSAY writers are different people, but the dataset has no demographic metadata. Performance on very different handwriting styles (for example, early literacy or motor impairments) is unknown.
License
- Weights: CC BY-NC 4.0. The BRESSAY terms of use say the dataset "may be used for non-commercial research and teaching purposes only", so this fine-tune is released for non-commercial use only. For other uses, contact the BRESSAY authors and the model author.
- Base model: LightOnOCR-3-1B, Β© LightOn, Apache License 2.0.
Citation
If you use Escriba-OCR-1B, please cite it together with the BRESSAY papers and LightOnOCR:
@misc{stekel2026escriba,
title = {Escriba-OCR: A 1B Vision-Language Model for Error-Preserving Transcription of Handwritten Portuguese Essays},
author = {Stekel, Tardelli Ronan Coelho},
year = {2026},
howpublished = {\url{https://huggingface.co/tardellirs/Escriba-OCR-1B}}
}
@inproceedings{neto2024bressay,
title = {{BRESSAY}: A Brazilian Portuguese Dataset for Offline Handwritten Text Recognition},
author = {Neto, Arthur F. S. and Bezerra, Byron L. D. and Araujo, S. S. and Souza, W. M. A. S. and Alves, K. F. and Oliveira, M. F. and Lins, S. V. S. and Hazin, H. J. F. and Rocha, P. H. V. and Toselli, Alejandro H.},
booktitle = {Document Analysis and Recognition -- ICDAR 2024},
publisher = {Springer},
doi = {10.1007/978-3-031-70536-6_19},
year = {2024}
}
@inproceedings{neto2024bressaycompetition,
title = {{ICDAR} 2024 Competition on Handwritten Text Recognition in Brazilian Essays -- {BRESSAY}},
author = {Neto, Arthur F. S. and Bezerra, Byron L. D. and Araujo, S. S. and Souza, W. M. A. S. and Alves, K. F. and Oliveira, M. F. and Lins, S. V. S. and Hazin, H. J. F. and Rocha, P. H. V. and Toselli, Alejandro H.},
booktitle = {Document Analysis and Recognition -- ICDAR 2024},
publisher = {Springer},
doi = {10.1007/978-3-031-70552-6_21},
year = {2024}
}
For LightOnOCR, use the citation given on the base model card.
Acknowledgements
We thank the BRESSAY authors for making the dataset available and LightOn for releasing LightOnOCR under an open license.
Resumo em portuguΓͺs
O Escriba-OCR-1B transcreve redaΓ§Γ΅es manuscritas em portuguΓͺs (estilo ENEM) preservando os erros: escreve exatamente o que o aluno escreveu, linha a linha, com os erros de grafia, a hifenizaΓ§Γ£o, os riscados (--texto--) e as inserΓ§Γ΅es (##texto##).
- Desempenho no teste do BRESSAY (199 pΓ‘ginas): CER de 2,06% (1,91% sΓ³ no texto). O melhor modelo aberto testado sem ajuste, o Qwen3-VL 235B, tem 5,60%, ou seja, 2,7 vezes mais erros. Nenhum dos 22 modelos abertos avaliados (de 0,8B a 400B parΓ’metros) reproduz as marcaΓ§Γ΅es de rasura e inserΓ§Γ£o.
- Roda localmente: com 1B de parΓ’metros, roda numa GPU comum ou sΓ³ em CPU (versΓ£o GGUF, com llama.cpp), entΓ£o as redaΓ§Γ΅es nΓ£o precisam sair da escola (LGPD).
- Como usar: amplie a pΓ‘gina para 1.200 px no lado maior, envie sΓ³ a imagem (prompt vazio) e use decodificaΓ§Γ£o gulosa com
repetition_penalty=1,05, de preferΓͺncia com vLLM. - Erros dos alunos: como todos os modelos testados, ele ainda "corrige" parte dos erros de grafia. Numa revisΓ£o humana, 45% das aparentes correΓ§Γ΅es eram, na verdade, erros do prΓ³prio gabarito do BRESSAY.
- Limites: treinado sΓ³ com o BRESSAY e ainda nΓ£o validado com fotos reais de sala de aula. NΓ£o serve para dar notas.
- LicenΓ§a: CC BY-NC 4.0, para uso nΓ£o comercial, por causa dos termos do BRESSAY.
- Downloads last month
- -
Model tree for tardellirs/Escriba-OCR-1B
Space using tardellirs/Escriba-OCR-1B 1
Collection including tardellirs/Escriba-OCR-1B
Evaluation results
- CER, case-insensitive (%) on BRESSAY (test split, 199 pages)test set self-reported2.060
- CER, case-sensitive (%) on BRESSAY (test split, 199 pages)test set self-reported2.130
- WER, case-insensitive (%) on BRESSAY (test split, 199 pages)test set self-reported5.880