Surya 2.5 GGUF

Surya 2.5 GGUF

Reads text, tables and layout from document images and returns it as text. GGUF builds of the Surya 2.5 OCR model for llama.cpp, for people who run document OCR on their own machine.

Made by datalab-to 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: This repository holds GGUF builds of Surya 2.5, an OCR model from Datalab, made to run under llama.cpp. Surya reads page images and returns text, with layout labels, reading order and tables as HTML. There are bf16 and 8-bit files, and a vision projector file that you need with either one.

Who it suits: People who need to turn scanned pages and document images into text on their own hardware, and who are comfortable running a local server.

Industry | Who uses it | How they use it | Example
Document processing | Teams that digitize paper records | Serve the model locally and send page scans to it | Converting a stack of scanned forms into text
Legal and finance | Staff who work from PDFs and scans | Extract text and tables from document images | Pulling a table from a scanned statement as HTML
Research | Developers who build document pipelines | Use the GGUF build as the OCR step in their own tools | Comparing the 8-bit and bf16 files on their own pages

Skip it if you want a hosted OCR service, or if you do not want to run llama.cpp.

Where to use it: It runs under llama.cpp, and the files download on Windows, macOS or Linux. The card names Apple Silicon and CPU for the automatic setup.

• llama.cpp: serves the GGUF files through llama-server
• The surya-ocr Python package: can start the server for you
• Apple Silicon or CPU: where the package sets things up automatically

Use case | Who | What they get back
Full page OCR | Document teams | The text of a page image
Layout analysis | Pipeline developers | Block labels and reading order
Table extraction | Analysts | Tables returned as HTML

How to set it up: You need Python and llama.cpp, plus the three files.

• Python with pip
• llama.cpp with llama-server
• The vision projector file, which you need with either model file

1. Install the Hugging Face hub library and download the files.
2. Or install the surya-ocr package, which fetches the bf16 file and launches the server on its own where it runs on Apple Silicon or CPU.
3. To serve it yourself, run llama-server with both files.
4. Set the two Surya environment variables, SURYA_INFERENCE_BACKEND and SURYA_INFERENCE_URL, so Surya talks to your server.

pip install -U huggingface_hub
hf download datalab-to/surya-ocr-2.5-gguf

The quicker route:

pip install surya-ocr

To serve it yourself:

llama-server -m surya-2.5.gguf --mmproj surya-2.5-mmproj.gguf --jinja --special \
  --parallel 8 --ctx-size 98304 -ngl 99 --port 8080

How to use it: Start the server, point Surya at it, then run OCR on page images. The special flag is required, because block labels and coordinates come back only with it.

Tool | What it does
llama-server | Serves the GGUF model over a local port
--mmproj | Loads the vision projector file
--special | Required, returns block labels and coordinates
--parallel 8 | Handles eight requests at once

Example: You start llama-server with the Surya files and send it a full page scan. You get back the text of the page together with block labels, coordinates and reading order, and tables come back as HTML.

For newcomers and experts: If you are new to this, install surya-ocr and let it start the server for you. Feed it one clean page scan first, and check the text against the page.

If you know the field, the card reports a speed test on an M4 Max with 8 parallel requests. Surya 2.5 finished all 32 pages, and Surya 2 finished 28 before the token cap. The 8-bit file used less memory than bf16 at a similar speed.

Title: Card speed test, 32 full page requests
Model | Pages per second | Peak memory
Surya 2 in bf16 | 0.061 | 5,875 MB
Surya 2.5 in bf16 | 0.190 | 4,764 MB
Surya 2.5 in Q8_0 | 0.198 | 4,278 MB

Page image goes to llama-server
Surya 2.5 reads text and layout
Block labels and coordinates return
You use the text and HTML tables

Good to know: The authors report 85.9 on OmniParseBench and 83.7% on olmOCR-bench for Surya, and these are their own figures.

• License: OpenRAIL on Hugging Face's record, with the card's badges showing Apache 2.0 for code and OpenRAIL-M for the model
• Cost to run: none named for local use, though Datalab also offers an optional managed platform
• Data it reaches: the page images you send to your local server
• Not for: row and column geometry in tables, which needs a Surya 2 checkpoint

On Hugging Face, 13 November 2026

• Task: image text to text
• Library: transformers
• Parameters: 589M
• Weights: about 294 MB at 4-bit (estimate)
• Formats: GGUF
• Downloads in the last 30 days: 126,232
• Likes: 8
• License: openrail
• Based on: datalab-to/surya-ocr-2.5
• Tags: transformers, gguf, qwen3_5, image-text-to-text, markdown, layout, conversational

Links

• Model: https://huggingface.co/datalab-to/surya-ocr-2.5-gguf
• Files: https://huggingface.co/datalab-to/surya-ocr-2.5-gguf/tree/main

Get the model

Download its files with Hugging Face's command line:

pip install -U huggingface_hub
hf download datalab-to/surya-ocr-2.5-gguf

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