Dosu LogoDosu Logo
Ask
Join our Discord
DoclingPublic
IBM Docling
DocumentsDocling
Redis Integration
Redis Integration
Type
Topic
Status
Published
Created
Jul 13, 2026
Updated
Jul 13, 2026

Redis Integration in docling-serve (Ray Backend)#

Redis is a mandatory external dependency when using the Ray orchestration backend in docling-serve. It is not optional or replaceable — startup validation raises an error if DOCLING_SERVE_ENG_RAY_REDIS_URL is not set when DOCLING_SERVE_ENG_KIND=ray . Redis serves four distinct roles in this backend: durable task state storage, pub/sub messaging, conversion result storage, and per-tenant fairness controls.

The rq backend also requires Redis (DOCLING_SERVE_ENG_RQ_REDIS_URL), but uses a separate key space. This article covers only the Ray backend, which uses Redis more extensively .

What Redis is Used For#

Task State Management#

The Ray orchestrator stores all durable task lifecycle state in Redis — not in actor memory. This means the full queue and in-flight task state survives process restarts. Key data structures (all implemented in docling_jobkit/orchestrators/ray/redis_helper.py):

  • Task queues: tenant:{tenant_id}:tasks — Redis Lists (RPUSH/LPOP for FIFO dispatch)
  • Active task tracking: tenant:{tenant_id}:active_tasks — Redis Sets (SADD on dispatch, SREM on completion)
  • Task metadata & counters: task:{task_id} hash, tenant:{tenant_id}:limits hash, tenant:{tenant_id}:stats hash
  • Execution lease: task:{task_id}:execution hash — written when a Ray actor claims a task; used to detect stale/crashed workers
  • Dispatch state: task:{task_id}:dispatch — tracks dispatcher ownership with a TTL for lease expiry

Atomic dispatch uses Redis transactions (WATCH/MULTI/EXEC) to prevent race conditions when multiple dispatchers compete for the same task.

Pub/Sub Notifications#

When a task completes (success or failure), the coordinator actor PUBLISHes to the docling:ray:updates channel (configurable via DOCLING_SERVE_ENG_RAY_SUB_CHANNEL) . The docling-serve API process subscribes on a dedicated Redis connection (separate from the command connection pool) with TCP keepalive and health-check interval of 15 seconds. This subscription drives the WebSocket streaming and polling endpoints that clients use to receive results.

Result Storage#

Completed conversion results are stored under the key pattern {results_prefix}:task:{task_id}:result using SETEX with a TTL . Defaults:

SettingEnv VarDefault
Results prefixDOCLING_SERVE_ENG_RAY_RESULTS_PREFIXdocling:ray:results
Initial TTLDOCLING_SERVE_ENG_RAY_RESULTS_TTL4 hours
After-fetch expiryDOCLING_SERVE_RESULT_REMOVAL_DELAY300 s

Results are msgpack-encoded StoredSuccessOutcome or StoredFailureOutcome objects. The two-phase expiry (initial TTL → crash-safe EXPIRE after fetch) means results are available for up to 4 hours if never retrieved, or for 5 minutes after first retrieval .

Per-Tenant Fairness Controls#

Redis stores per-tenant concurrency state that the dispatcher uses to enforce fair round-robin scheduling. The Ray RayTaskDispatcher actor maintains an in-memory deque of tenant IDs for round-robin ordering, but reads/writes the authoritative limits and counters from Redis :

  • max_concurrent_tasks per tenant (default: 5, DOCLING_SERVE_ENG_RAY_MAX_CONCURRENT_TASKS)
  • max_queued_tasks — optional queue depth cap with rejection (DOCLING_SERVE_ENG_RAY_MAX_QUEUED_TASKS, DOCLING_SERVE_ENG_RAY_ENABLE_QUEUE_LIMIT_REJECTION)
  • max_documents — optional per-tenant document count limit (DOCLING_SERVE_ENG_RAY_MAX_DOCUMENTS)
  • active_tasks and queued_tasks counters checked atomically before dispatch

The tenant ID is extracted from the X-Tenant-Id request header (configurable via DOCLING_SERVE_ENG_RAY_TENANT_ID_HEADER) . Child page slices (when PDF fan-out is enabled) do not increment the tenant's active_tasks counter — only the parent task counts .

Configuration Reference#

All Ray-backend Redis settings are defined in docling_serve/settings.py and wired into RayOrchestratorConfig in orchestrator_factory.py.

Connection#

Env VarDefaultDescription
DOCLING_SERVE_ENG_RAY_REDIS_URL(required)Redis connection URL (standard, Sentinel, or Cluster)
DOCLING_SERVE_ENG_RAY_REDIS_MAX_CONNECTIONS50Command connection pool size
DOCLING_SERVE_ENG_RAY_REDIS_SOCKET_TIMEOUTNoneSocket read/write timeout
DOCLING_SERVE_ENG_RAY_REDIS_SOCKET_CONNECT_TIMEOUTNoneSocket connect timeout
DOCLING_SERVE_ENG_RAY_REDIS_OPERATION_TIMEOUT30.0 sPer-operation timeout applied at the application layer

Connection Pool Gate (Concurrency Throttle)#

A "gate" limits the number of concurrent callers accessing Redis to prevent connection exhaustion :

Env VarDefaultDescription
DOCLING_SERVE_ENG_RAY_REDIS_GATE_CONCURRENCYmax_connections - reservedMax concurrent Redis callers
DOCLING_SERVE_ENG_RAY_REDIS_GATE_RESERVED_CONNECTIONS10Connections held back for internal use
DOCLING_SERVE_ENG_RAY_REDIS_GATE_WAIT_TIMEOUT0.25 sMax wait to acquire a gate slot
DOCLING_SERVE_ENG_RAY_REDIS_GATE_STATUS_POLL_WAIT_TIMEOUT5.0 sPoll timeout for status checks

Per-Tenant Limits#

Env VarDefaultDescription
DOCLING_SERVE_ENG_RAY_MAX_CONCURRENT_TASKS5Max in-flight tasks per tenant
DOCLING_SERVE_ENG_RAY_MAX_QUEUED_TASKSNoneMax queued tasks per tenant (none = unlimited)
DOCLING_SERVE_ENG_RAY_ENABLE_QUEUE_LIMIT_REJECTIONfalseReject (HTTP 429) when queue is full
DOCLING_SERVE_ENG_RAY_MAX_DOCUMENTSNoneMax concurrent document pages per tenant
DOCLING_SERVE_ENG_RAY_TENANT_ID_HEADERX-Tenant-IdHTTP header used to identify the tenant

See .env.example for annotated examples.

Key Source Files#

FileRole
docling_serve/settings.pyAll DOCLING_SERVE_ENG_RAY_REDIS_* env vars and validation
docling_serve/orchestrator_factory.pyWires settings into RayOrchestratorConfig
docling_jobkit/orchestrators/ray/redis_helper.pyAll Redis operations: key patterns, TTLs, pub/sub, atomic transactions
docling_jobkit/orchestrators/ray/orchestrator.pyon_result_fetched(), task lifecycle
docling_jobkit/orchestrators/ray/dispatcher.pyFair round-robin scheduling; reads/writes per-tenant Redis counters
docling_jobkit/orchestrators/ray/config.pyRayOrchestratorConfig — all Redis-related config fields
docs/ray-orchestrator-architecture-page-slicing-delta.mdArchitecture doc showing Redis's role in the coordinator/converter split
Documents
Agentic Document Processing
API Authentication
Apple Silicon Support
How can I set up and run docling-serve on a MacBook Pro using Docker, and what performance and stability considerations should I be aware of?
ASR Language Configuration
Async Task Result Management
Audio and Video Processing
Bibliography Extraction and Parsing
Bounding Box Visualization
Caption-Figure Linking
Chart Extraction
What are the differences between `vlm_pipeline_model_local` and `picture_description_local` in Docling, and how do image descriptions, OCR, and table extraction work together? Also, how do the `include_annotations` and `mark_annotations` properties affect exported output?
Chemical Notation OCR
Citation Data Modeling
CLI File Staging and Collision Handling
CLI Image Export Modes
How can I improve the resolution or quality of images extracted from a PDF using docling?
CLI Logging and Console Output
Code Chunking
Container Image Variants
How can I set up and run docling-serve on a MacBook Pro using Docker, and what performance and stability considerations should I be aware of?
What is the recommended Azure deployment option for a Docling-based Python SDK application using a custom Dockerfile with PyTorch and OCR, and why?
Cross-Platform Support
Custom Enrichment Models
Custom Layout Plugin Architecture
DocItemLabel Type System
DocLang Format
Docling Image Extraction
How can I improve the resolution or quality of images extracted from a PDF using docling?
What are the differences between `vlm_pipeline_model_local` and `picture_description_local` in Docling, and how do image descriptions, OCR, and table extraction work together? Also, how do the `include_annotations` and `mark_annotations` properties affect exported output?
Docling Model Management
How can I set up and run docling-serve on a MacBook Pro using Docker, and what performance and stability considerations should I be aware of?
What is the recommended Azure deployment option for a Docling-based Python SDK application using a custom Dockerfile with PyTorch and OCR, and why?
Docling Pipeline Configuration
What are the differences between `vlm_pipeline_model_local` and `picture_description_local` in Docling, and how do image descriptions, OCR, and table extraction work together? Also, how do the `include_annotations` and `mark_annotations` properties affect exported output?
Docling Resource Requirements
How can I set up and run docling-serve on a MacBook Pro using Docker, and what performance and stability considerations should I be aware of?
What is the recommended Azure deployment option for a Docling-based Python SDK application using a custom Dockerfile with PyTorch and OCR, and why?
Docling Rust SDK
Docling Serve API Client
How can I use Docling's REST API to convert a PDF from a URL to Markdown with OpenAI-generated image descriptions, and is base64 encoding required for URL sources?
Docling Serve Configuration
How can I set up and run docling-serve on a MacBook Pro using Docker, and what performance and stability considerations should I be aware of?
How can you mount a PersistentVolumeClaim (PVC) in docling-serve on OpenShift to store EasyOCR models, and what steps are required to ensure docling-serve can access these models?
What are the differences between `vlm_pipeline_model_local` and `picture_description_local` in Docling, and how do image descriptions, OCR, and table extraction work together? Also, how do the `include_annotations` and `mark_annotations` properties affect exported output?
Docling Serve Deployment
How can I set up and run docling-serve on a MacBook Pro using Docker, and what performance and stability considerations should I be aware of?
How can you mount a PersistentVolumeClaim (PVC) in docling-serve on OpenShift to store EasyOCR models, and what steps are required to ensure docling-serve can access these models?
Models handling in Docling Serve
skill.md
What is the recommended Azure deployment option for a Docling-based Python SDK application using a custom Dockerfile with PyTorch and OCR, and why?
Docling Serve Worker Architecture
DoclingDocument Builder API
Building a Modular IDP Pipeline with Docling Components
DoclingDocument Data Model
Building a Modular IDP Pipeline with Docling Components
DoclingDocument Hierarchization
DoclingDocument Java Serialization
DoclingDocument Serialization
DoclingDocument Text Formatting
Document Backends
Building a Modular IDP Pipeline with Docling Components
Document Chunk Metadata and Provenance
Document Chunking
Document Content Classification
Document Extraction Strategies
Document Figure Classification
Document Input Methods
How can I use Docling's REST API to convert a PDF from a URL to Markdown with OpenAI-generated image descriptions, and is base64 encoding required for URL sources?
Document Layout and Reading Order
How does Docling reconstruct reading order without using a large language model (LLM) call in an unsupervised manner?
Document Layout Detection Models
Building a Modular IDP Pipeline with Docling Components
Document Merging and Concatenation
Document Metadata
Document Pagination
Document Rotation and Orientation
Document Serialization Architecture
Document Token and Heading Schema
Document Tree Traversal
Document Type Classification and Routing
Document-to-Graph Pipeline
DocumentConverter Configuration
How can I use granite-docling to process all PDFs in a directory and output doctags?
DOCX Header/Footer Processing
DOCX Image Extraction
DOCX List Processing
DOCX Numbered Heading Processing
DOCX Reference and Citation Extraction
DOCX SDT Handling
DOCX Table Extraction
DOCX Text Formatting
Email Format Support
Enrichment Pipeline
What are the differences between `vlm_pipeline_model_local` and `picture_description_local` in Docling, and how do image descriptions, OCR, and table extraction work together? Also, how do the `include_annotations` and `mark_annotations` properties affect exported output?
Entity Cardinality and Ranking
Excel Backend Processing
Models handling in Docling Serve
Extraction Pipeline Prompting
GPU Accelerator Support
GPU Memory Management
Heading Hierarchy Configuration
HTML Export Format
HuggingFace Transformers Integration
IBM Watsonx and Granite Integration
How can I use granite-docling to process all PDFs in a directory and output doctags?
Image Reference Handling
How can I use Docling's REST API to convert a PDF from a URL to Markdown with OpenAI-generated image descriptions, and is base64 encoding required for URL sources?
skill.md
Input Format and Image Support
Knowledge Graph Extraction
Large PDF Memory Management
Layout Detection Configuration
Layout Postprocessor
Layout Prediction Data Structures
Building a Modular IDP Pipeline with Docling Components
LibreOffice Integration
List Marker Normalization
Markdown Export Configuration
How can I use Docling's REST API to convert a PDF from a URL to Markdown with OpenAI-generated image descriptions, and is base64 encoding required for URL sources?
Markdown Processing
MCP Server Integration
Docling MCP in Docling Serve
Multi-Language API Integration
Native Library Compatibility
NuExtract Transformers Compatibility
OCR Engine Configuration
OCR Engine Integration
OCR Language Support
ODF Backend Processing
ODF Chart Extraction
Open WebUI Integration
Optional Dependency Management
Package Architecture
skill.md
Page Assembly Pipeline
Parsed Page Access and Segmentation
PDF Document Pipeline
Building a Modular IDP Pipeline with Docling Components
PDF Page Range Selection
PDF Parse Lifecycle Management
PDF Pipeline Configuration
How can I improve the resolution or quality of images extracted from a PDF using docling?
PDF Rendering and OCR Pipeline
How can I improve the resolution or quality of images extracted from a PDF using docling?
PDF Spatial Filtering
PDF Text Extraction
PDF-to-RAG Pipeline
skill.md
Picture Classification Filtering
Picture Detection and Segmentation
Pipeline and Model Caching
skill.md
Pipeline Batch Size Configuration
Pipeline Error Logging
Pipeline Initialization and Dependency Loading
Pipeline Stage Architecture
PPTX Content Extraction
Pydantic-Based Extraction Templates
RAG Framework Connectors
RapidOCR Model Management
Redis Integration
Remote Inference Services
Resource Cleanup and Lifecycle Management
RTL and Bidirectional Text Support
Security Hardening
Spatial Predicates and R-tree Indexing
Structured Information Extraction
How can I use granite-docling to process all PDFs in a directory and output doctags?
skill.md
Table Cell Formatting
Table Cell Text Matching
Table Chunking
Table Export and Serialization
What are the differences between `vlm_pipeline_model_local` and `picture_description_local` in Docling, and how do image descriptions, OCR, and table extraction work together? Also, how do the `include_annotations` and `mark_annotations` properties affect exported output?
Table Structure Recognition
Building a Modular IDP Pipeline with Docling Components
Models handling in Docling Serve
TableFormer Confidence Scoring
Text Element Merging and Dehyphenation
Threaded PDF Backend
Tokenizer Backends
Torch Compile Optimization
VLM Coordinate System and Image Scaling
VLM Extraction Pipeline
VLM Formula and Code Extraction
VLM Image Cropping
VLM Inference Configuration
VLM Inference Engine
Building a Modular IDP Pipeline with Docling Components
VLM Picture Description
How can I use Docling's REST API to convert a PDF from a URL to Markdown with OpenAI-generated image descriptions, and is base64 encoding required for URL sources?
What are the differences between `vlm_pipeline_model_local` and `picture_description_local` in Docling, and how do image descriptions, OCR, and table extraction work together? Also, how do the `include_annotations` and `mark_annotations` properties affect exported output?
VLM Pipeline
VLM Token Limits and Truncation
XML Backend Architecture
Can I use a custom OCR model in Docling, and how do I set its path in the pipeline options?
Can docling-serve fetch documents from object storage (e.g., S3)?
Comment corriger la phrase : "Je suis allé à l'école en pied et mains je parte par quotidien des beaucoup de kilomètres cela est importante" ?
Content Layers
Does Docling automatically detect the language of a document when sending images to Tesseract OCR, and how can it be configured?
How can I enable and use GPU acceleration with Docling?
How can I find page numbers and bounding box information for content in a chunk produced by the hybrid chunker, and what is the structure of the doc_items list within a chunk?
How can a student build a local, open-source LLM-based system to extract and analyze technical PDF documents (PMS/IDC) and generate instrumentation datasheets, using Python on a PC with limited resources?
How can a student build a local, open-source, privacy-preserving AI system to extract and query technical PDF documents (PMS/IDC) on a PC with limited resources?
How can you make Docling read/understand images embedded in a DOCX file, and what is the correct code to use the VlmPipeline for this purpose?
How can you use Docling's REST API to convert a PDF to Markdown and generate image descriptions using an OpenAI model?
How do I set up a complete multi-format document processing pipeline using Docling that handles technical PDFs, HTML files, images, videos, audio, codebases, and schematics, and exports everything to organized agent-friendly markdown files?
How do you install and use Docling in Python on WSL2, including integration with an AI agent?
How do you use HybridChunker in Docling, including saving and reloading the converted document?
How does Docling support parallel/multiprocessing for document conversion, and what do the key performance parameters (`page_chunk_size`, `doc_batch_concurrency`, `doc_batch_size`) do?
How to properly enable `enable_remote_services` in Docling Serve (CPU image) to use an external OpenAI-compatible API for picture description and formula enrichment, and what is the correct config format?
No Docling, o uso de CUDA é obrigatório para processar PDFs com extração de texto e descrição de imagens, ou é opcional?
Quais são as melhores opções de OCR para extração de tabelas financeiras complexas em PDFs usando Docling, incluindo alternativas externas e integração com plugins?
Quelle est l'origine et le statut des êtres mathématiques selon Platon et John Stuart Mill ?
What are all the parameters of HybridChunker in Docling, and how do you use it with a custom tokenizer?
What are all the pipelines that exist in Docling, including their purposes, selection criteria, and how they handle scanned documents?
What are the detailed pipeline options and processing behaviors for PDF, DOCX, PPTX, and XLSX files in the Python SDK?
What are the steps to convert a complex payment advice PDF to Excel using Docling?
What does 'RFLP' stand for or refer to?
What is the best practice for extracting text from a mixed PDF (digital + scanned pages) for enterprise financial document processing without a GPU and with limited costs?
What is the best practice for processing a mixed PDF (digital + scanned pages) containing sensitive financial data in Docling, given no GPU and limited cost?
What is the general sentiment expressed about the messy nature of documents and content in the Docling project?
What is the recommended architecture and implementation for processing a mixed PDF bundle (digital + scanned pages) for an enterprise financial payment verification system (like MRT Jakarta's AI-Augmented Payment Flow), with constraints of no GPU and limited cost?
When processing large PDFs (700+ pages) with Docling's StandardPdfPipeline, what causes the `std::bad_alloc` errors and what are the recommended workarounds?
Which is the better option for running Docling: using 'docling serve' in Azure Container Apps or code-based deployment in Azure Function App (Windows Premium plan)?
Why are bounding boxes not available for items (such as images, tables, text) when using VlmPipeline with certain VLM presets (like Qwen/Markdown)?
Zoom on Layer 1 (L1): Layout Detection & Routing in a Modular IDP Pipeline
คู่มือการดึงรูปภาพจาก PDF และสร้าง Markdown พร้อม Alternative Text ด้วย Docling