rizkybs70/openwebui-vision-extractor repository overview

⁠OpenWebUI Vision Extractor

A lightweight external document loader for OpenWebUI that extracts text from native PDFs locally and uses an OpenAI-compatible vision model only when OCR is needed.

Designed for self-hosted deployments where scanned PDFs, mixed PDFs, and normal text PDFs need to be ingested into OpenWebUI reliably without sending every page through a vision model.

⁠How It Works

OpenWebUI
    |
    v
Vision Extractor
    |
    +-- Native text page --> PyMuPDF
    |
    +-- Scanned/image page --> Render PNG --> Vision API
    |
    +-- Plain text --> Direct passthrough
    |
    v
Extracted text --> OpenWebUI RAG

PDF pages are evaluated individually, so a single document can contain both native-text and scanned pages.

Vision pages can be processed concurrently while the final output remains in the original page order.

⁠Features

• Native PDF text extraction with PyMuPDF
• Vision OCR for scanned PDF pages
• Hybrid per-page PDF processing
• Plain-text passthrough
• OpenAI-compatible vision API support
• Configurable model and upstream endpoint
• Bounded parallel vision processing
• Automatic PDF rendering and DPI control
• Retry handling for temporary upstream failures and rate limits
• File-size, page-count, and processing-time limits
• Bearer-token authentication
• Separate liveness and readiness endpoints
• In-memory processing with no persistent document storage
• Compatible with hardened read-only Docker deployments

⁠Supported Inputs

⁠OpenWebUI Configuration

In Admin Settings -> Documents:

Content Extraction Engine:
External

External Document Loader URL:
http://openwebui-vision-extractor:8080

External Document Loader API Key:
<EXTRACTOR_API_KEY>

The extractor and OpenWebUI should normally share the same Docker network.

⁠Quick Start

services:
  openwebui-vision-extractor:
    image: rizkybs70/openwebui-vision-extractor:latest
    container_name: openwebui-vision-extractor
    restart: unless-stopped

    environment:
      EXTRACTOR_API_KEY: "change-this-token"

      UPSTREAM_BASE_URL: "http://your-vision-api:port/v1"
      UPSTREAM_API_KEY: "your-api-key"
      UPSTREAM_MODEL: "your-vision-model"

      TEXT_MIN_CHARS: "20"
      VISION_CONCURRENCY: "2"

    networks:
      - ai

    read_only: true

    tmpfs:
      - /tmp:size=64m

    security_opt:
      - no-new-privileges:true

    cap_drop:
      - ALL

networks:
  ai:
    external: true

For production deployments, pinning a specific version is recommended instead of relying on latest.

Example:

rizkybs70/openwebui-vision-extractor:1.1.1

⁠Main Configuration

⁠Health

⁠Liveness

GET /health

Checks whether the extractor application is running.

It does not contact the upstream vision provider.

⁠Readiness

GET /ready

Checks required configuration and performs a lightweight upstream connectivity check without running vision inference.

⁠API

Main document processing endpoint:

PUT /process
Authorization: Bearer <EXTRACTOR_API_KEY>

The request contains the raw document bytes and returns extracted text for OpenWebUI.

⁠Security

Recommended deployment:

• internal Docker network
• no public port exposure
• bearer authentication
• read-only root filesystem
• tmpfs for temporary runtime data
• cap_drop: ALL
• no-new-privileges
• no persistent document storage

⁠Current Release

Latest: 1.1.1

Image:

rizkybs70/openwebui-vision-extractor:latest
rizkybs70/openwebui-vision-extractor:1.1.1

See the versioned Docker Hub tags for previous releases.