import { Callout } from 'nextra/components'

Docling OCR for Sources and Attachments

DocsGPT uses Docling as the default parser layer for many document formats. OCR is optional and controlled by two settings:

DOCLING_OCR_ENABLED=false
DOCLING_OCR_ATTACHMENTS_ENABLED=false

• DOCLING_OCR_ENABLED: OCR behavior for Source Docs ingestion.
• DOCLING_OCR_ATTACHMENTS_ENABLED: OCR behavior for chat attachments uploaded from the message box.

Processing Flow

Source Docs flow (Upload and Train)

1. Files are uploaded through /api/upload.
2. Ingestion runs asynchronously in Celery (ingest_worker).
3. SimpleDirectoryReader parses files with get_default_file_extractor.
4. For PDFs and image formats, Docling parsers are used. OCR in this path is controlled by DOCLING_OCR_ENABLED.
5. Parsed text is chunked, embedded, and stored in the vector store.
6. Retrieval during chat uses this indexed text and returns source citations.

Attachment flow (Chat-only file context)

1. Files are uploaded through /api/store_attachment.
2. Celery task attachment_worker parses and stores the attachment in Postgres (attachments table).
3. OCR in this path is controlled by DOCLING_OCR_ATTACHMENTS_ENABLED.
4. Attachments are not vectorized and are not added to the source index.
5. During answer generation, selected attachment IDs are loaded and passed directly to the LLM pipeline.

How Docling OCR Works

Docling OCR behavior is different for PDFs vs images:

• PDF parser defaults to hybrid OCR:
  • text regions: extracted directly
  • bitmap/image regions: OCR only where needed
• Image parser defaults to full-page OCR (the whole image is visual content).

By default, Docling parser classes use RapidOCR options (language default: english).

Model compilation

Docling runs its layout, table, and OCR models through torch.compile by default. DocsGPT turns that off. On x86-64 Linux, compiling raised the first parse of a two-page PDF from 8.4s to 58.6s while steady-state parsing stayed at 1.5s either way, so the warmup is overhead a per-file parse never recovers. Compiling also fails outright on Apple Silicon, on install paths containing a space, on Windows without MSVC, and in slim images with no C compiler.

DOCLING_COMPILE_TORCH_MODELS=false

Set it to true only if you are parsing large batches on a machine where the warmup pays for itself.

Attachment Behavior by Model Support

When attachments are used in chat, behavior depends on the selected model/provider:

• If a MIME type is supported, DocsGPT sends files/images through provider-native attachment APIs.
• If unsupported, DocsGPT falls back to the parsed text content stored for the attachment.
• For providers that support images but not native PDF attachments, PDF files are converted to images (synthetic PDF support).

This means OCR quality is especially important for text fallback paths and for models without native attachment support.

Recommended Configuration

For most OCR-enabled use cases, enable both flags:

DOCLING_OCR_ENABLED=true
DOCLING_OCR_ATTACHMENTS_ENABLED=true

After changing these settings, restart the API and Celery worker.

Legacy Fallback Notes

• If Docling is unavailable, DocsGPT falls back to legacy parsers.
• With OCR disabled, text-based PDFs can still parse, but scanned/image-heavy content may produce little text.
• For image parsing without Docling OCR, the legacy image parser only extracts text when PARSE_IMAGE_REMOTE=true.