Surya OCR

Surya OCR is a document-processing project for extracting text and page structure from images and PDFs. It is worth evaluating when your application needs more than a plain text string, such as reading order or table regions. The important qualification is version: this guide covers the current Surya 2 documentation, not the older interfaces still found in tutorials. A successful installation is only the beginning; your acceptance test must check whether the extracted document still means the same thing.

This is a source-based evaluation, checked on September 29, 2026. We have not run an OCR benchmark or processed customer documents. The workflow below is a proposed test you can adapt, with explicit rejection conditions rather than an invented accuracy score.

Reviewed code and document revision: a2363d33.

Decide what must survive the extraction

Start with the operation that will consume the result. Searching an archive needs different evidence from importing an invoice into an accounting system. A search index might tolerate a damaged decorative heading if users can still retrieve the right page. An invoice importer cannot treat a plausible but incorrect account number as a minor formatting issue.

Consider a hypothetical team receiving supplier PDFs. Some files contain clean digital text; others are scans, with a stamped note, a two-column address block or a table continuing onto the next page. The team's desired outcome is not simply “OCR completed.” It is a reviewable record in which supplier identity, item descriptions, quantities and totals remain associated with their source locations.

Write those requirements before choosing settings. Identify fields that must never be accepted without verification, structures that must remain linked, and cases that can be sent to a human queue. This prevents a readable paragraph from concealing an unusable table. It also gives you a fair basis for comparison: every candidate workflow must preserve the same information, not just produce an attractive preview.

The project's own documentation positions Surya for documents, rather than text in natural scenes. A storefront photograph or a moving street sign therefore needs a separate evaluation; broad language support does not establish suitability for every camera image. Surya scope and limitations.

Identify the installed version before copying examples

Surya's model-family name and Python package version are different identifiers. At this review, the repository's package configuration declares version 0.22.1 and Python support starting at 3.10. Record the actual installed package, checkpoint, backend and environment in your run notes. A copied command without those identifiers is not a reproducible integration. Package configuration.

The current migration notes replace the older foundation predictor with an inference manager, and describe changed OCR output fields. Treat an upgrade as an application-contract change. Before processing a collection, inspect one actual result and verify that your parser reads the fields returned by that version. Surya v1 migration notes.

The current recognition schema represents a page as blocks and an image boundary. Individual blocks include reading order, HTML content and explicit skipped/error flags. An empty block should not automatically become an empty database value. Preserve enough status information to distinguish a region intentionally skipped from a recognition failure or an extraction that genuinely found no text. Recognition schema.

For an existing integration, save a representative old result next to a new one and compare the structure before judging the text. Check renamed fields, changed nesting, page ordering and the downstream treatment of missing values. A schema test that passes while silently dropping every table is not an acceptable migration test.

Run OCR on one permitted document

Once Surya and the backend required by your platform are installed, the project's documented entry point is:

surya_ocr DATA_PATH

Replace DATA_PATH with the path to one image or PDF you are permitted to process. Use a small document whose text you can check yourself. The project also accepts a folder, but processing a batch before inspecting one result makes an integration mistake harder to isolate. Installing the Python package alone does not establish that the inference backend is ready.

Open the generated results.json before importing it elsewhere. The documented structure uses input filenames without extensions as keys, with a list of page records under each input. Compare the page count and block content with the source document, then use the acceptance sheet below to record any missing or incorrectly associated values. This command is documented by the project; we have not run it here. Official OCR usage.

Separate code permission from model-weight permission

The repository code uses Apache 2.0. The model weights have a separate modified OpenRAIL-M licence. Describing the complete system as simply GPL, or assuming that the code licence grants unrestricted use of the weights, would obscure the decision a commercial user actually needs to make. Code licence, model-weight licence.

Attachment A includes restrictions connected to prior-year gross revenue above five million US dollars, total equity or debt funding above that amount, and products or services competing with the licensor's offerings. The revenue and funding provisions contain personal-use or research exceptions; the competitive-use restriction is separate. Do not turn this into a blanket “small businesses qualify” statement. Read the complete terms for your organization and intended deployment, and obtain appropriate clarification when applicability is uncertain. This guide reports the licence, not a legal clearance.

Also account for the documents themselves. Permission to run a model does not establish permission to upload a supplier's records, retain extracted identifiers indefinitely or reuse those records to train another system. Record who owns the input, who may see the result, and which environment is authorized to process it. Those are project obligations, not capabilities that an OCR badge can confer.

Build a small sample that exposes costly errors

For the supplier scenario, choose a bounded sample that represents the problems your team really receives. Include a clean digital PDF, a scan with faint text, a rotated page, a multi-column document and a table with repeated headings. These are proposed sample categories, not a claim that every category will fail or succeed with Surya.

Have a person transcribe the critical fields and mark the expected reading sequence before inspecting model output. Otherwise the generated text can become its own answer key. Keep the original page beside this reference, and record any genuinely ambiguous mark as ambiguous instead of forcing a convenient ground-truth value.

Give each page a stable identifier. Save its input hash, source dimensions, processing settings and output path. Keep private documents out of public bug reports and shared screenshots. Where possible, reproduce a parsing problem with a nonsensitive substitute that preserves the relevant layout, then record that the substitute is a diagnostic fixture rather than a customer result.

Run the smallest sample first. Inspect the result from input through your own parser and destination application, not only in Surya's preview. The point is to locate a failure while you can still explain it. Sending the entire archive through an unvalidated parser creates a larger cleanup task without adding useful evidence about the first broken assumption.

Use an acceptance sheet instead of one accuracy number

The following worksheet is an editorial proposal for the supplier-document example. Set your actual tolerances with the people responsible for the destination system. We have not populated it with measured Surya results.

Separate critical errors from cosmetic ones. A line break change may be harmless for retrieval and unacceptable for a fixed-layout form. That difference belongs in the acceptance policy, not in an improvised decision after seeing a result. Record the reason for each classification so the next reviewer can apply the same rule.

Count review work as part of the result. If the output saves typing but requires repeated page hunting, the workflow may still be slower for your team. Measure the time to reach a corrected, accepted record, including the failures, rather than reporting only successful pages. This is how the sample becomes an operational decision instead of a model demonstration.

Measure startup and processing separately

Current Surya documentation describes inference backends using vLLM for NVIDIA GPUs and llama.cpp for CPU or Apple Silicon. An installation must therefore account for a serving process as well as the Python package. Backend choice should be explicit in your evaluation notes; “ran locally” is not a sufficiently precise hardware or software description. Backend documentation.

The settings file exposes model-cache, endpoint and server-lifecycle configuration. Those are separate concerns. A local command can use a configured remote endpoint, while first use may need model downloads. Confirm actual network behavior and document handling before calling a deployment offline or appropriate for confidential records. Inference settings.

For timing, record cold startup, warm page processing, output conversion and human correction separately. Compare runs on the same sample and report failures alongside elapsed time. A favorable warm run does not tell you how a scheduled job behaves when it starts a fresh environment for every document.

Change resolution or concurrency one at a time. Recheck small text and the most demanding table after each change, and watch the complete process for memory pressure or truncated output. Keep the previous settings until the replacement has passed the same acceptance sheet. A faster run that loses the supplier's decimal separator is not a useful optimization.

Diagnose the broken stage before retrying

Use the source page, raw result and imported record together. If text is already wrong in the raw result, debugging your database mapping will not repair recognition. If the raw result is correct but rows are mismatched after import, repeated model runs will not resolve the parser defect.

Do not repair an ambiguous source by silently inventing the likely text. Preserve an uncertainty marker or send the page for review. This matters particularly when a fluent result encourages someone to trust a value that was barely legible in the original.

Choose the next workflow from the evidence

If the original PDF already contains usable text and structure, compare direct extraction before adding OCR. If your problem is a small collection with difficult handwriting or highly irregular tables, a supervised transcription workflow may be easier to control than extensive integration work. These are alternative approaches, not claims that a named competing model is superior.

A managed document service is a different operational choice from self-hosting Surya. Evaluate its current terms, retention controls, output contract and total review burden independently. The fact that a provider uses a related model does not make the hosted service identical to the repository, nor does it transfer your local test results to that service.

The useful outcome is a documented boundary: which document classes can enter your pipeline, which fields require verification, and which failures stop automatic import. Keep rejected examples as a regression set, subject to your retention rules. When the package, checkpoint, backend or parser changes, run that set again before trusting the new combination.

This review does not establish universal language accuracy, production privacy compliance or an unattended invoice-processing guarantee. It gives you a way to test the particular job. For other model categories, use the model directory, but carry the same source-and-acceptance discipline into the next evaluation.