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
  • PostgreSQL β€” job store for parse jobs from Integration Designer (see Job store)
The Document Parser retrieves CMS files through CMS Core, but it also connects to the documents object storage directly. It offloads Kafka job payloads larger than 512,000 bytes there, and it reads files passed as a bucket/key reference. Set the connection with APPLICATION_FILE_STORAGE_S3_DOCUMENTS_SERVER_URL (include the scheme: an https:// URL turns on TLS), APPLICATION_FILE_STORAGE_S3_DOCUMENTS_ACCESS_KEY and APPLICATION_FILE_STORAGE_S3_DOCUMENTS_SECRET_KEY, or the equivalent MINIO_DOCUMENTS_URL, MINIO_DOCUMENTS_ACCESS_KEY and MINIO_DOCUMENTS_SECRET_KEY. Offloaded payloads go to KAFKA_OFFLOAD_BUCKET, then to the documents bucket (APPLICATION_FILE_STORAGE_S3_DOCUMENTS_BUCKET_NAME or MINIO_DOCUMENTS_BUCKET), and to workflows-bucket when neither is set.
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, EasyOCR, and RapidOCR (RapidOCR up to 5.9.5 only)
  • 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 without the cost of the LLM or VLM engines. On FlowX.AI 6.0.0, LiteParse runs with OCR turned off by default and reads only the document’s native text layer, so scanned pages and images return no text. Use the OCR or VLM engine for scanned content. 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.
Starting with FlowX.AI 5.9.6, the layout, table, and OCR models are part of the Document Parser image, so nothing is downloaded at startup or on the first document, and the parser runs without internet access or on a read-only filesystem. USE_DOCLING has no effect.On 5.9.5 and earlier, 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. Starting with FlowX.AI 5.9.6, a request for rapidocr runs tesseract-cli instead.

Vector database configuration (optional)

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

Job store (PostgreSQL)

The Document Parser runs parse jobs from Integration Designer through a durable job queue that keeps each job’s state in PostgreSQL. The queue is on by default. With the flowx-ai Helm chart, the connection variables point at the doc_parser database.
If POSTGRES_PASSWORD is not set (and POSTGRES_DSN is not used), the service fails at startup with a postgres_dsn is required error.
The job queue uses these Kafka topics:

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 November 16, 2026