5.3.1. Docling Localhost Provider¶

Run IBM Docling document processing natively on your host machine (any platform with Python).

1. Quick Start¶

1.1. Install Dependencies¶

cd services/docling/provider/localhost
uv sync

This installs all required dependencies (docling, fastapi, uvicorn, pydantic, etc.)

For GPU acceleration (NVIDIA CUDA):

uv pip install torch torchvision --index-url https://download.pytorch.org/whl/cu124

For Apple Silicon (MPS):

uv pip install torch torchvision

1.2. Start the Server¶

uv run server.py

The server will start on http://0.0.0.0:18159 by default (reads DOCLING_LOCALHOST_PORT from environment).

First run: Downloads AI models (~500MB - DocLayNet + TableFormer). Please be patient (5-10 minutes). Subsequent runs: Instant startup.

1.3. Test the API¶

curl -X POST http://localhost:18159/v1/document/convert \
  -F "file=@document.pdf" \
  -F "output_format=markdown" \
  -F "table_mode=accurate"

2. Configuration¶

2.1. Environment Variables¶

Set before running server:

export DOCLING_LOCALHOST_PORT=18159      # Server port (default: 18159)
export DOCLING_DEVICE=cpu                # Device: cpu, cuda, mps
export DOCLING_OUTPUT_FORMAT=markdown    # Format: markdown, html, json, doctags
export DOCLING_USE_OCR=auto              # OCR: auto, always, never
export DOCLING_TABLE_MODE=accurate       # Table mode: accurate, fast
export DOCLING_ENABLE_FORMULAS=true      # Formula enrichment: true, false
export DOCLING_ENABLE_CODE_BLOCKS=true   # Code enrichment: true, false
export HF_TOKEN=your_token_here          # HuggingFace token (if needed)

The request's use_ocr and table_mode values override their environment defaults. Device, formula enrichment, and code enrichment are applied through Docling's pinned PdfPipelineOptions API. Unsupported output formats are rejected during request validation; they are never silently returned as Markdown.

2.2. Custom Port¶

export DOCLING_LOCALHOST_PORT=55021
uv run server.py

Or read from project .env:

# .env lives at the repo root, four levels up from this README
export DOCLING_LOCALHOST_PORT=$(grep '^DOCLING_LOCALHOST_PORT' ../../../../.env | cut -d'=' -f2)
uv run server.py

3. Supported Formats¶

3.1. Input Formats¶

Documents: PDF, DOCX, DOC, PPTX, PPT, XLSX, HTML
Images: PNG, JPG, JPEG, TIFF, TIF

3.2. Output Formats¶

markdown - Clean markdown (default)
html - Semantic HTML
json - Structured JSON with metadata
doctags - IBM Docling native format

4. API Examples¶

4.1. Basic Conversion¶

curl -X POST http://localhost:18159/v1/document/convert \
  -F "file=@report.pdf" \
  -F "output_format=markdown"

4.2. With OCR and Table Extraction¶

curl -X POST http://localhost:18159/v1/document/convert \
  -F "file=@scanned.pdf" \
  -F "use_ocr=always" \
  -F "table_mode=accurate"

4.3. RAG Chunking¶

curl -X POST http://localhost:18159/v1/document/convert \
  -F "file=@document.docx" \
  -F "enable_chunking=true" \
  -F "chunk_size=512" \
  -F "chunk_overlap=50"

5. Features¶

5.1. Table Extraction¶

Accurate Mode: Uses TableFormer AI model (slow, high quality)
Fast Mode: Rule-based extraction (10x faster, lower quality)

5.2. OCR Support¶

Auto: Only uses OCR when needed (scanned PDFs, images)
Always: Forces OCR on all documents
Never: Disables OCR completely

5.3. Advanced Extraction¶

Mathematical formulas (LaTeX format)
Code blocks with syntax preservation
Images and figures
Document structure (headings, paragraphs, lists)

6. Integration with Atlas¶

6.1. Method 1: Localhost Mode (Recommended)¶

# Terminal 1: Start doc processor
cd services/docling/provider/localhost
uv run server.py

# Terminal 2: Start stack
./start.sh --doc-processor-source docling-localhost

6.2. Method 2: With Custom Base Port¶

# Terminal 1: Export port from .env (repo root is four levels up)
export DOCLING_LOCALHOST_PORT=$(grep '^DOCLING_LOCALHOST_PORT' ../../../../.env | cut -d'=' -f2)
uv run server.py

# Terminal 2: Start stack with custom port
./start.sh --base-port 55000 --doc-processor-source docling-localhost

6.3. Method 3: Permanent Configuration¶

Edit .env file:

DOC_PROCESSOR_SOURCE=docling-localhost

Then start stack:

./start.sh

7. Performance¶

7.1. CPU (Any Platform)¶

Simple PDFs: ~2-5 seconds/page
PDFs with tables: ~10-30 seconds/page
Memory: ~2GB RAM

7.2. GPU (NVIDIA CUDA)¶

Simple PDFs: ~1-2 seconds/page
PDFs with tables: ~2-7 seconds/page (4.3x faster than CPU)
Memory: ~2GB VRAM

7.3. Apple Silicon (MPS)¶

Simple PDFs: ~1-3 seconds/page
PDFs with tables: ~5-15 seconds/page
Memory: ~2GB RAM

Performance varies based on document complexity and table count

8. Troubleshooting¶

8.1. Port Already in Use¶

# Use different port
export DOCLING_LOCALHOST_PORT=63090
uv run server.py

8.2. GPU Not Detected (NVIDIA)¶

# Install CUDA-enabled PyTorch
pip install torch torchvision --index-url https://download.pytorch.org/whl/cu124

# Verify CUDA
python -c "import torch; print(torch.cuda.is_available())"

8.3. Model Download Fails¶

# Set HuggingFace token if accessing gated models
export HF_TOKEN=your_token_here
uv run server.py

# Check disk space (need ~1GB free)
df -h

8.4. Import Errors¶

# Reinstall dependencies
uv sync --reinstall

# Or use fresh environment
rm -rf .venv
uv sync

8.5. Slow Processing¶

Problem: Document processing takes too long

Solutions: - Use table_mode=fast for faster (less accurate) table extraction - Reduce file size (compress images in PDF) - Use GPU if available (4.3x speedup for tables) - Disable OCR if not needed: use_ocr=never

9. Technical Details¶

9.1. Model Downloads¶

Models are downloaded on first run and cached in: - Linux/Mac: ~/.cache/huggingface/ - Windows: %USERPROFILE%\.cache\huggingface\

Downloaded models: - DocLayNet: ~200MB (layout analysis) - TableFormer: ~300MB (table structure recognition)

9.2. Device Selection¶

# Auto-detected based on availability:
# 1. CUDA (NVIDIA GPU) if available
# 2. MPS (Apple Silicon) if available
# 3. CPU as fallback

Override with DOCLING_DEVICE environment variable.

9.3. Memory Requirements¶

Minimum: 2GB RAM
Recommended: 4GB RAM
GPU: 2GB VRAM (for table extraction acceleration)

10. Advanced Usage¶

10.1. Python Integration¶

import requests

with open("document.pdf", "rb") as f:
    response = requests.post(
        "http://localhost:18159/v1/document/convert",
        files={"file": f},
        data={
            "output_format": "markdown",
            "table_mode": "accurate",
            "enable_chunking": True,
            "chunk_size": 512
        }
    )

result = response.json()
print(result["content"])
print(f"Processed {result['metadata']['pages']} pages")
print(f"Found {result['metadata']['tables']} tables")

10.2. Batch Processing¶

# Process multiple files
for file in *.pdf; do
  curl -X POST http://localhost:18159/v1/document/convert \
    -F "file=@$file" \
    -F "output_format=markdown" \
    > "${file%.pdf}.md"
done