docling-api: Scalable Document to Markdown Conversion Server

Introduction

docling-api is an advanced backend server that provides a highly efficient and scalable solution for converting diverse document formats into Markdown. Leveraging IBM's powerful Docling parser, alongside FastAPI, Celery, and Redis, this service excels at transforming PDFs, DOCX, PPTX, HTML, images, and more into structured Markdown. It supports both CPU and GPU processing modes, with GPU recommended for optimal performance in production, making it perfect for complex, large-scale document processing tasks. The project also highlights its superior parsing capabilities compared to other libraries through visual comparisons.

Installation

Setting up docling-api is straightforward, whether you prefer a local environment or a Dockerized deployment.

Local Setup (Prerequisites: Python 3.8+, Poetry, Redis server)

1. Install Poetry:

   curl -sSL https://install.python-poetry.org | python3 -
   

2. Clone and Setup Project:

   git clone https://github.com/drmingler/docling-api.git
   cd docling-api
   poetry install
   

3. Configure Environment:
   Create a .env file in the project root:

   REDIS_HOST=redis://localhost:6379/0
   ENV=development
   

4. Start Redis Server:

   • For MacOS:

     brew install redis
     brew services start redis
     

   • For Ubuntu/Debian:

     sudo apt-get install redis-server
     sudo service redis-server start
     

5. Start Application Components:

   • Start FastAPI server:

     poetry run uvicorn main:app --reload --port 8080
     

   • Start Celery worker (new terminal):

     poetry run celery -A worker.celery_config worker --pool=solo -n worker_primary --loglevel=info
     

   • Start Flower dashboard (optional, new terminal):

     poetry run celery -A worker.celery_config flower --port=5555
     

Docker Setup

1. Clone the repository:

   git clone https://github.com/drmingler/docling-api.git
   cd docling-api
   

2. Create a .env file:

   REDIS_HOST=redis://redis:6379/0
   ENV=production
   

3. CPU Mode:

   docker-compose -f docker-compose.cpu.yml up --build --scale celery_worker=1
   

4. GPU Mode (Recommended for production):

   docker-compose -f docker-compose.gpu.yml up --build --scale celery_worker=3
   

Examples

The docling-api provides flexible API endpoints for various conversion needs.

Synchronous Conversion (Single Document):

curl -X POST "http://localhost:8080/documents/convert" \
  -H "accept: application/json" \
  -H "Content-Type: multipart/form-data" \
  -F "document=@/path/to/document.pdf" \
  -F "extract_tables_as_images=true" \
  -F "image_resolution_scale=4"

Asynchronous Conversion (Single Document):

1. Submit document:

   curl -X POST "http://localhost:8080/conversion-jobs" \
     -H "accept: application/json" \
     -H "Content-Type: multipart/form-data" \
     -F "document=@/path/to/document.pdf"
   

2. Check status (replace {job_id}):

   curl -X GET "http://localhost:8080/conversion-jobs/{job_id}" \
     -H "accept: application/json"
   

Batch Processing (Asynchronous):

curl -X POST "http://localhost:8080/batch-conversion-jobs" \
  -H "accept: application/json" \
  -H "Content-Type: multipart/form-data" \
  -F "documents=@/path/to/document1.pdf" \
  -F "documents=@/path/to/document2.pdf"

Why Use It

docling-api stands out as a powerful solution for document-to-Markdown conversion due to several key advantages:

• Extensive Format Support: It handles a wide range of inputs, including PDFs, DOCX, PPTX, HTML, various image formats, and more, ensuring broad applicability.
• Advanced Conversion Capabilities: Beyond basic text extraction, it offers robust table detection and extraction, image processing, and multi-language OCR, providing comprehensive content conversion.
• Scalability and Performance: Designed for large-scale workflows, it leverages Celery for distributed task processing and supports both CPU and GPU modes, with GPU acceleration significantly boosting performance for demanding tasks.
• Flexible API: With synchronous, asynchronous, and batch processing endpoints, developers can integrate the service seamlessly into diverse applications, with job tracking for long-running tasks.
• Ease of Deployment: The project provides clear instructions for both local setup and Docker deployment, simplifying integration into existing infrastructures.
• Quality Output: Visual comparisons in the repository demonstrate its superior Markdown output quality compared to other parsing libraries.

Links

• GitHub Repository: https://github.com/drmingler/docling-api
• Docling (IBM's advanced document parser): https://github.com/DS4SD/docling