Skip to main content
The Document Parser service handles document and image processing for AI workflows. It provides multiple parsing engines, OCR capabilities, table extraction, document classification, and signature detection.

​
Dependencies

The Document Parser connects to standard FlowX infrastructure services that should already be configured in your environment:
  • Kafka — async document processing and inter-service communication
  • Identity provider (Keycloak or Azure AD) — authentication
  • CMS Core — file retrieval from FlowX content management
  • AI provider (OpenAI, Azure OpenAI, Ollama, Anthropic, or GCP) — required for LLM and VLM parsing engines
  • Vector database (Qdrant) — optional, for RAG use cases
The Document Parser retrieves files through CMS Core — it does not require its own S3/MinIO storage configuration.
The Document Parser is a Python 3.13 service that loads ML models at startup. Plan for longer startup times (5–20 minutes) compared to Java-based FlowX services.

​
Capabilities

​
What it can do

  • Multi-format parsing: PDF, DOCX, XLSX/XLS/XLSM, PPTX, JPG, PNG, TIFF
  • Three parsing engine families: Classic, LLM, and Docling (with Auto/Simple/OCR/VLM modes)
  • OCR text extraction: Tesseract, RapidOCR, EasyOCR
  • Table structure extraction: Detect and extract tabular data
  • Document classification: Keyword-based or LLM-based
  • Signature detection: Locate signatures within documents
  • Page rotation detection: Detect and correct rotated pages
  • Semantic chunking: Smart chunking for Retrieval-Augmented Generation (RAG) workflows
  • Vector store integration: Store embeddings in Qdrant

​
What it cannot do

  • Cannot process encrypted or password-protected PDFs
  • Cannot process audio or video files
  • Cannot edit or modify source documents
  • Does not perform language translation

​
Supported formats

​
Parsing engines

The Document Parser supports six parsing modes organized into three engine families:
Docling Auto analyzes each page using text density, gibberish ratio, image area coverage, and layout metrics. It then routes each page to the cheapest engine that can handle it: Standard (simple extraction), OCR (text-poor/garbled pages), or VLM (complex visual layouts).

​
Engine selection guide

Uses PyMuPDF for direct text extraction from the PDF file structure, with Tesseract OCR as a fallback for empty pages.
  • Zero cost (no external API calls)
  • Fastest processing
  • Only works with digital PDFs that have selectable text
  • Falls back to Tesseract OCR when pages have no text layer

​
LiteParse engine

Available starting with FlowX.AI 5.9.2
LiteParse (parser_engine value: LiteParse) adds a seventh parsing mode that runs fully locally, built on PDFium with bundled Tesseract OCR. It makes no AI calls and requires no GPU, so it offers fast, zero-cost parsing of PDFs and images, including scanned pages that the Classic engine cannot read, without the cost of the LLM or VLM engines. In the same release, OCR language support across all engines expands to English, Romanian, Hungarian, and Bulgarian.

​
API endpoints

All endpoints are prefixed with the URL_PREFIX value (default: /doc-parser).

​
Configuration

​
Server configuration

Keep GUNICORN_WORKERS at 1 per pod. The Document Parser loads large ML models into memory — multiple workers per pod will cause out-of-memory (OOM) errors. Scale horizontally by adding more pods instead.
Set USE_DOCLING to 1 if you use Docling parsing engines. This pre-downloads models at startup rather than on first request, avoiding timeout issues on the first document.

​
AI model configuration

The Document Parser uses three types of AI models, each independently configurable:
All three model types support the same providers: OPENAI, AZUREOPENAI, OLLAMA, ANTHROPIC, GCP, GCP_VERTEX, CUSTOM_OPENAI, OPENAI_COMPATIBLE. Embedding models additionally support HUGGINGFACE and AWS.

​
Provider-specific variables

​
OCR configuration

The OCR engine is selected per-request via the API ocr_engine parameter. Available engines: tesseract-cli (default), tesseract-ocr, rapidocr, easyocr.

​
Vector database configuration (optional)

Required only if using semantic chunking and RAG workflows. The Document Parser stores embeddings in Qdrant.

​
Observability (optional)

​
Langfuse

​
Deployment and sizing

The Document Parser ships as a single image that auto-detects an NVIDIA GPU. If a GPU is scheduled to the pod, the service uses it to accelerate the local Docling OCR and VLM engines; with no GPU, it runs CPU-only. A GPU is optional — the Classic engine and the LLM (AI-vision) engine don’t benefit from it, since LLM parsing offloads to an external AI provider.
GPU acceleration applies only to the local Docling engines — the document layout model, OCR, and VLM. Classic parsing and LLM/AI-vision parsing see no speedup from a GPU.

​
Kubernetes configuration (15,000 pages/day)

The following profiles size a CPU-only deployment. For GPU sizing, see GPU acceleration below.
For predictable, consistent workloads:

​
GPU acceleration

To speed up the local Docling OCR and VLM engines on scanned or complex documents, schedule the Document Parser on GPU nodes. The image detects the GPU automatically — no configuration flag is required. FlowX Cloud production environments run this profile.
FlowX Cloud runs the Document Parser on NVIDIA T4 GPUs (AWS g4dn.xlarge). Self-hosted deployments can use any CUDA 12.x-compatible NVIDIA GPU.
GPU nodes must have the NVIDIA device plugin installed. Add a matching nodeSelector and toleration so the Document Parser pod lands on the GPU pool, and request exactly one GPU per pod.

​
Important deployment notes

Pod startup time: 5–20 minutes. The service loads ML models (OCR, Docling) into memory at startup. Configure your readiness probes and deployment strategy accordingly.
  • Set GUNICORN_TIMEOUT to at least 600 (10 minutes) — increase for very large documents
  • Use 1 Gunicorn worker per pod — scale horizontally with more pods
  • Configure liveness probes with a generous initial delay (at least 300 seconds)
  • Consider using a RollingUpdate strategy with maxUnavailable: 0 to avoid downtime during deploys
  • The service listens on port 8080

​
Cost considerations

Estimated monthly costs for a 15,000 pages/day workload using LLM-based parsing:

​
Cost reduction tips

Use keyword-only classification

Set use_llm_to_classify to false in API calls instead of LLM-based classification. Saves ~$450/month.

Use Docling Auto

Let Docling Auto route pages to the cheapest engine that works. Saves ~$240/month compared to forcing OCR on all pages.

Turn off signature detection

Set detect_signature to false in API calls when not needed. Saves ~$90/month.

Use Classic for clean PDFs

Route clean digital PDFs to the Classic engine (free, no API calls). Reserve LLM/Docling for scanned or complex documents.

​
Verify your setup

The Document Parser pod is running: kubectl get pods -l app=document-parser
The health endpoint returns HTTP 200: curl http://document-parser:8080/api/v1/doc-parser/info/health
ML models loaded successfully — check pod logs for model initialization messages (this can take 5–20 minutes)
Test a document parse request against the /api/v1/doc-parser/extract/parse_file endpoint and verify the response contains extracted text

​
Troubleshooting

Symptoms: Pods restart with OOMKilled status.Solutions:
  • Increase memory limits (try 8 Gi)
  • Ensure GUNICORN_WORKERS is set to 1
  • Reduce OMP_NUM_THREADS to 2
  • Check for concurrent large document processing
Symptoms: Documents take much longer than expected to process.Solutions:
  • For the local Docling OCR/VLM engines, deploy on GPU nodes (see GPU acceleration) — on CPU these engines work but are significantly slower
  • Verify network latency to the AI provider
  • Use Docling Auto instead of forcing VLM on all documents
  • Check pod CPU utilization — may need more replicas
Symptoms: Extracted text is incomplete or garbled.Solutions:
  • Try VLM or LLM mode for complex documents
  • Check source document quality (low resolution images reduce OCR accuracy)
  • Ensure the correct OCR engine is configured for your document language
  • Use apply_rotation: true for scanned documents that may be rotated
Symptoms: Pod stays in CrashLoopBackOff or never becomes ready.Solutions:
  • Increase readiness probe initial delay to 600 seconds
  • Check that ML model files are accessible (network or storage issues)
  • Verify memory limits are sufficient for model loading (minimum 4 Gi)
  • Review pod logs for specific error messages
The Document Converter (doc-converter) is a separate, CPU-only service that converts Office documents, images, and text into PDF before parsing. See the Document Converter setup guide.

Extract Data from File

Configure the Extract Data from File AI node in Agent Builder

AI Platform setup

Configure AI Platform services and service discovery

Agent Builder overview

Get started with Agent Builder workflows
Last modified on July 9, 2026

Related topics

AI Platform setupDocument Converter setupDocuments plugin setupDeployment guidelines v5.9.0Deployment guidelines v5.10