DeepSeek-OCR-WebUI
Self-hosted DeepSeek-OCR-2 for documents and images — vLLM or transformers on NVIDIA, native Apple Silicon, and CPU, with per-page quality checks.
🌐 English · 简体中文 · 繁體中文 · 日本語
What's new · Screenshots · Quick start · API · Architecture · Performance · Development
✨ What's new in v5.0
v5 is a ground-up renovation of the backend and a hardening of the Vue 3 frontend. Every number below was measured; see CHANGELOG for the full list.
| v4.1 | v5.0 |
|---|
| Apple Silicon / CPU | loads, then fails on first page (upstream code hard-codes .cuda()) | works — device-agnostic inference, M5 Max 8.1 pages/min |
| NVIDIA engines | transformers only, one page at a time | vLLM (continuous batching, 132 pages/min on an A10G) or transformers |
| Old GPUs (T4 / V100, no bf16) | BFloat16 vs float crash (#30 #40) | fp16 + eager, verified on T4 |
| Driver requirement | CUDA 13 image ⇒ driver ≥ 580 (#46) | CUDA 12 builds |
| Docker image | 13 GB with weights inside (#38) | weights in a volume; hf image ≈ 4.0 GB unpacked |
| Output quality | HTTP 200 = "success" | per-page ok + warnings (repetition, truncation, coordinate loops, empty) |
| Readiness | /health 200 before the model can read | 503 until a warm-up page is read back correctly |
| Large PDFs | 200 pages ⇒ 662 MB in IndexedDB, freezes (#31 #50) | 78 MB, parsed once in a worker; 500 MB upload limit (#51) |
| Markdown export | dropped multi-box blocks (#49) | 100 % character recall on all samples |
| Security | binds 0.0.0.0, CORS * with credentials, XSS via v-html | 127.0.0.1 by default, CORS allow-list, DOMPurify |
| Tests | 0 backend tests; 123 frontend tests failing on Node 26 | backend, frontend, e2e and mutation suites — live counts in the badges above |
📸 Screenshots
All screenshots are generated by frontend/scripts/screenshots.mjs against a real backend (DeepSeek-OCR-2 on an Apple M5 Max). The demo document is generated by scripts/make_demo_docs.py.
Document → Markdown with layout boxes and a rendered table
| Batch queue | Second PDF page |
|---|
| |
| Recognition modes | Service status (engine · device · precision) |
| |
| Swagger UI | Mobile (简体中文) |
| |
🚀 Quick start
🔒 The service has no login. Every command below listens on 127.0.0.1 only. To use it from another machine, use an SSH tunnel (ssh -L 8001:127.0.0.1:8001 you@gpu-host) or put it behind a reverse proxy that authenticates users — do not publish the port on all interfaces.
Option 1 — Docker, NVIDIA GPU (vLLM engine, recommended)
git clone https://github.com/neosun100/DeepSeek-OCR-WebUI.git && cd DeepSeek-OCR-WebUI
docker compose up -d # builds the image; first start downloads ~6.8 GB of weights
open http://127.0.0.1:8001 # UI · API docs: http://127.0.0.1:8001/docs
Prebuilt images (published by CI on each release):
docker run -d --gpus all --shm-size 8g -p 127.0.0.1:8001:8001 -v dsocr-models:/models \
ghcr.io/neosun100/deepseek-ocr-webui:5.0.0 # vLLM engine
docker run -d --gpus all --shm-size 8g -p 127.0.0.1:8001:8001 -v dsocr-models:/models \
ghcr.io/neosun100/deepseek-ocr-webui:5.0.0-hf # transformers engine (smaller, also for T4/V100)
/health returns 503 while the model is loading (first start: download + load + warm-up) and 200 once a warm-up page has been read back correctly. docker ps shows healthy at that point.
Option 2 — macOS (Apple Silicon) or Linux without Docker
Requires uv and Node.js ≥ 20.
git clone https://github.com/neosun100/DeepSeek-OCR-WebUI.git && cd DeepSeek-OCR-WebUI
(cd frontend && npm ci && npm run build) # the backend serves the built UI
uv sync --extra hf # transformers + torch (MPS on macOS, CUDA 12.6 wheels on Linux)
uv run deepseek-ocr-webui serve # http://127.0.0.1:8001
On Linux with vLLM instead: uv sync --extra vllm && uv run deepseek-ocr-webui serve --engine vllm.
Offline / air-gapped
Download once (huggingface-cli download deepseek-ai/DeepSeek-OCR-2 --revision aaa02f3811945a91062062994c5c4a3f4c0af2b0 --local-dir /models/ocr2), then start with DSOCR_MODEL_PATH=/models/ocr2.
Configuration
All settings are environment variables with the DSOCR_ prefix (config.py is the single source). The most useful ones:
This is the beginning of the README. Read the rest at the original. Read the full README ↗
