Surya Document Intelligence Toolkit

Surya 2 uses a unified vision-language model architecture (Qwen3.5-style, approximately 650M parameters) to handle Layout, OCR, and table recognition.

• Layout, OCR, and Table Recognition: These tasks share the single vision-language model. The model is trained to emit either a layout JSON or a full-page HTML output based on the provided prompt.
• Text-line Detection: This is handled by a separate, small PyTorch model. It is a modified EfficientViT segformer trained specifically on document line annotations.

If you require assistance fine-tuning Surya on custom data or wish to use the managed training stack, contact hi@datalab.to.

By default, every command spawns the VLM server on startup and shuts it down on exit. To avoid the startup/model-load cost when running multiple commands, use the --keep_server flag. This allows subsequent commands to attach to the already running server.

Alternatively, set the environment variable SURYA_INFERENCE_KEEP_ALIVE=1 to make keep-alive the default behavior.

To stop the server manually:

• For NVIDIA/vLLM: docker stop <container_id>
• For CPU/llama.cpp: Kill the llama-server process.

surya_ocr    DATA_PATH --keep_server   # spawns the server and leaves it up
surya_layout DATA_PATH                 # attaches to the running server
surya_table  DATA_PATH                 # attaches to the running server

Install the Surya OCR package using pip:

pip install surya-ocr

In v2, SuryaInferenceManager replaces FoundationPredictor. A single manager instance should be shared across LayoutPredictor, RecognitionPredictor, and TableRecPredictor.

Key Schema Changes:

• text_lines is now blocks (which includes html).
• Layout output: top_k is removed, count is added.
• Table recognition: is_header, colspan, and rowspan have been removed from cells.

# v2 migration example
from surya.inference import SuryaInferenceManager
from surya.recognition import RecognitionPredictor

manager = SuryaInferenceManager()              # auto-spawns vllm or llama-server
rec = RecognitionPredictor(manager)
predictions = rec([image])

You can interactively test Surya on images or PDFs using a Streamlit application.

pip install streamlit pdftext
surya_gui

To develop on Surya, install it manually using uv:

git clone https://github.com/datalab-to/surya.git
cd surya
uv sync --group dev      # installs runtime + dev deps
uv run surya_ocr ...     # or source .venv/bin/activate to enter the venv

Surya automatically spawns an inference server on first use. Depending on your hardware, you need one of the following:

• NVIDIA GPU: Requires Docker and the NVIDIA Container Toolkit.
• CPU / Apple Silicon: Requires the llama-server binary from llama.cpp. You can install it via Homebrew on macOS:

brew install llama.cpp

Or download a release from the llama.cpp releases page.

The surya_screenshot command launches a web-based viewer designed for creating clean screenshots of OCR results. The application displays a PDF or image page on the left and the full-page OCR output on the right side-by-side.

To use it:

1. Run the command surya_screenshot in your terminal.
2. Open your web browser and navigate to http://localhost:8504.

Features include:

• Page scrolling and previewing before running OCR.
• Exporting the side-by-side view as a PNG.
• Support for .pdf, .png, .jpg, .jpeg, .gif, and .webp files.

You can run the shared text-detection server, which uses a single EfficientViT instance with continuous batching, using the following command. The server batches forward passes across all clients and handles heatmap-to-box post-processing in a thread pool.

python -m surya.detection.server --port <PORT>

Arguments:

• --port: (Required) The port number to listen on.
• --host: The host address (defaults to settings.DETECTOR_SERVER_HOST).
• --checkpoint: Optional path to a specific model checkpoint.

python -m surya.detection.server --port P

If you are experiencing poor OCR or detection results, consider the following:

• Image Resolution: Try increasing the image resolution. If it is already very high, try decreasing it to a maximum width of 2048px.
• Preprocessing: Binarizing or deskewing images can help with old or blurry scans.
• Threshold Tuning: Adjust the following environment variables:
  • DETECTOR_BLANK_THRESHOLD: Controls space between lines. Predictions below this are considered blank. (Range: 0-1)
  • DETECTOR_TEXT_THRESHOLD: Controls how text is joined. Predictions above this are considered text. (Range: 0-1)
  • Note: DETECTOR_TEXT_THRESHOLD should always be higher than DETECTOR_BLANK_THRESHOLD.