vlmparse 0.1.7

No project description provided

vlmparse

A unified wrapper for Vision Language Models (VLM) and OCR solutions to parse PDF documents into Markdown.

Features:

• ⚡ Async/concurrent processing for high throughput
• 🐳 Automatic Docker server management for local models
• 🔄 Unified interface across all VLM/OCR providers
• 📊 Built-in result visualization with Streamlit

Supported Converters:

• Open Source Small VLMs: lightonocr, mineru2.5, hunyuanocr, paddleocrvl, granite-docling, olmocr2-fp8, dotsocr, chandra, deepseekocr, nanonets/Nanonets-OCR2-3B
• Open Source Generalist VLMs: such as the Qwen family.
• Pipelines: docling
• Proprietary LLMs: gemini, gpt

Installation

Simplest solution with only the cli:

uv tool install vlmparse

If you want to run the granite-docling model or use the streamlit viewing app:

uv tool install vlmparse[docling_core,st_app]

If you prefer cloning the repository and using the local version:

uv sync

With optional dependencies:

uv sync --all-extras

Activate the virtual environment:

source .venv/bin/activate

CLI Usage

Note that you can bypass the previous installation step and just add uvx before each of the commands below.

Convert PDFs

With a general VLM (requires setting your api key as an environment variable):

vlmparse convert --input "*.pdf" --out_folder ./output --model gemini-2.5-flash-lite

Convert with auto deployment of a small vlm (or any huggingface VLM model, requires a gpu + docker installation):

vlmparse convert --input "*.pdf" --out_folder ./output --model nanonets/Nanonets-OCR2-3B

Deploy a local model server

Deployment (requires a gpu + docker installation):

• You need a gpu dedicated for this.
• Check that the port is not used by another service.

vlmparse serve --model lightonocr --port 8000 --gpus 1

then convert:

vlmparse convert --input "*.pdf" --out_folder ./output --model lightonocr --uri http://localhost:8000/v1

You can also list all running servers:

vlmparse list

Show logs of a server (if only one server is running, the container name is not needed):

vlmparse log <container_name>

Stop a server (if only one server is running, the container name is not needed):

vlmparse stop <container_name>

View conversion results with Streamlit

vlmparse view ./output

Configuration

Set API keys as environment variables:

export GOOGLE_API_KEY="your-key"
export OPENAI_API_KEY="your-key"

Python API

Client interface:

from vlmparse.registries import converter_config_registry

# Get a converter configuration
config = converter_config_registry.get("gemini-2.5-flash-lite")
client = config.get_client()

# Convert a single PDF
document = client("path/to/document.pdf")
print(document.to_markdown())

# Batch convert multiple PDFs
documents = client.batch(["file1.pdf", "file2.pdf"])

Docker server interface:

from vlmparse.registries import docker_config_registry

config = docker_config_registry.get("lightonocr")
server = config.get_server()
server.start()

# Client calls...

server.stop()

Converter with automatic server management:

from vlmparse.converter_with_server import ConverterWithServer

with ConverterWithServer(model="mineru2.5") as converter_with_server:
    documents = converter_with_server.parse(inputs=["file1.pdf", "file2.pdf"], out_folder="./output")

Note that if you pass an uri of a vllm server to ConverterWithServer, the model name is inferred automatically and no server is started.