Rukopys-OCR-4B

Rukopys-OCR-4B

Reads Ukrainian handwritten documents from images, finds each text region, labels its type and returns the transcriptions as structured JSON. An open 4B vision-language model for digitizing handwriting.

Made by ebinan92 on Hugging Face. These notes are Mindket's, written from its model page and model card; the model's own files and license are on Hugging Face.

About

What it is: Rukopys-OCR-4B reads images of Ukrainian handwritten documents. It finds each region on the page, labels its type and returns the transcribed text of every region as structured JSON. ebinan92 trained it by tuning all the weights of Qwen3.5-4B for a handwriting competition, and the card says it was part of an entry that finished third.

Who it suits: People who need Ukrainian handwriting turned into data, such as archivists, researchers and developers building document pipelines.

Industry | Who uses it | How they use it | Example
Archives | Digitization teams | Turn handwritten pages into searchable text | Transcribe a scanned notebook page
Education | Schools and researchers | Digitize handwritten student work | Read pages of a school notebook
Software | Document pipeline developers | Feed region boxes and text into other tools | Load the JSON output into a database
Research | OCR researchers | Study handwriting recognition for Cyrillic text | Compare results on formulas and tables

Anyone who works with other languages or only printed text can skip it, since it was tuned for Ukrainian handwriting.

Where to use it: It runs in Python through Transformers or vLLM, and the card gives a script for each.

• Python with Hugging Face Transformers 5.8.1 or newer
• vLLM, with the second sample script in the card
• Windows, macOS or Linux with Python, for downloading the files

Use case | Who | What they get back
Handwriting transcription | Archivists | The text of each handwritten region
Page layout detection | Developers | Region boxes on a normalized 0 to 1000 grid
Formulas and tables | Researchers | Formula text in LaTeX and table text split by pipe characters

How to set it up: You need Python, a recent Transformers and a document image.

• Python with pip
• Transformers 5.8.1 or newer
• The PIL and torch packages that the sample script imports
• Disk space for the weights, about 9.1 GB in BF16
• A photo or scan of a handwritten document

1. Install the Hugging Face hub tools with pip.
2. Download the model files with the hf command.
3. Check that your Transformers version is 5.8.1 or newer.
4. Save the Python script from the next section and point it at your image.

pip install -U huggingface_hub
hf download ebinan92/Rukopys-OCR-4B

How to use it: Run the card's Transformers script on your image. Keep its prompt exactly as written, because the card says the training prompt should stay unchanged. The script sends the image and prompt, generates up to 8192 new tokens without sampling and prints the JSON.

from PIL import Image
import torch
from transformers import AutoModelForMultimodalLM, AutoProcessor

MODEL_ID = "ebinan92/Rukopys-OCR-4B"
PROMPT = (
    "Detect every text region in this Ukrainian handwritten document and "
    "return a JSON array of regions. Each region has bbox (x1 y1 x2 y2 in "
    "0..1000 normalized image coordinates), type (handwritten | printed | "
    "formula | table | annotation | image | graph), and text (transcription; "
    "empty for image/graph; LaTeX for formula; pipe-separated for table)."
)

processor = AutoProcessor.from_pretrained(MODEL_ID)
model = AutoModelForMultimodalLM.from_pretrained(
    MODEL_ID, dtype=torch.bfloat16, device_map="auto"
)
image = Image.open("document.jpg").convert("RGB")
messages = [{
    "role": "user",
    "content": [{"type": "image"}, {"type": "text", "text": PROMPT}],
}]
text = processor.apply_chat_template(
    messages, tokenize=False, add_generation_prompt=True, enable_thinking=False
)
inputs = processor(text=[text], images=[image], return_tensors="pt").to(model.device)

with torch.inference_mode():
    output_ids = model.generate(**inputs, max_new_tokens=8192, do_sample=False)

new_tokens = output_ids[:, inputs["input_ids"].shape[1]:]
print(processor.batch_decode(new_tokens, skip_special_tokens=True)[0])

Tool | What it does
AutoProcessor | Turns the image and the prompt into model inputs
AutoModelForMultimodalLM | Loads the model weights in bfloat16 across the available devices
apply_chat_template | Builds the chat text with thinking switched off
generate | Produces the transcription, up to 8192 new tokens

The card also gives a vLLM script that does the same job with a maximum length of 16384 and one image per prompt.

Region type | What the text holds
handwritten, printed, annotation | The transcribed text
formula | The formula written in LaTeX
table | The table text, with cells split by pipe characters
image, graph | Empty text

Example: You give it a photo of a handwritten Ukrainian page together with the card's prompt. It answers with a JSON list, one item per region, each with a box, a type and the text, like this one for a handwritten line.

[
  {
    "bbox": [84, 107, 912, 168],
    "type": "handwritten",
    "text": "Приклад рукописного тексту"
  }
]

For newcomers and experts: This is a model that reads handwriting. You show it a picture of a handwritten page and it hands back the words and where they sit. The first small thing to try is running the sample script on one clear photo and reading the JSON it prints.

It answers one fixed prompt and places each region on a 0 to 1000 grid. Decoding is greedy with thinking switched off, and the vLLM sample limits image size through minimum and maximum pixel counts. Training mixed RUKOPYS gold and silver data, outside Cyrillic handwriting sets and pseudo-labels, some of which came from Gemini.

Give it a photo of a handwritten page
Send the fixed training prompt
The model finds the text regions
Each region gets a type
You receive JSON with boxes and text

Good to know: It targets Ukrainian handwriting, and the weights are lighter at lower precision.

Title: Approximate weight size
BF16: 9.1 GB
4-bit estimate: 2.3 GB

• Language: built for Ukrainian handwriting, and the record lists Ukrainian and Russian.
• Prompt: keep the training prompt unchanged.
• License: Apache 2.0 for the weights.
• Training data: the datasets are not redistributed and keep their own licenses, which include CC BY 4.0, CC BY-SA 4.0, MIT and Apache 2.0.
• Cost to run: none named.
• Data it reaches: the image you give it and the model files you download. The card names no web or account access.

On Hugging Face, 13 November 2026

• Task: image text to text
• Library: transformers
• Parameters: 4.5B
• Weights: about 9.1 GB in BF16; about 2.3 GB at 4-bit (estimate)
• Formats: Safetensors
• Downloads in the last 30 days: 86
• Likes: 7
• License: apache-2.0
• Languages: uk, ru
• Based on: Qwen/Qwen3.5-4B
• Quantized versions: 1
• Tags: transformers, safetensors, qwen3_5, image-text-to-text, handwritten-text-recognition, ukrainian, cyrillic, document-ai, layout-analysis, qwen3.5, conversational

Links

• Model: https://huggingface.co/ebinan92/Rukopys-OCR-4B
• Files: https://huggingface.co/ebinan92/Rukopys-OCR-4B/tree/main

Get the model

Download its files with Hugging Face's command line:

pip install -U huggingface_hub
hf download ebinan92/Rukopys-OCR-4B

Then follow the usage in its model card. Nothing in this kit runs by itself.