WAIT — Slowing — last commit 4mo ago

• Last commit 4mo ago
• MIT licensed
• ⚠ Slowing — last commit 4mo ago
• ⚠ Solo or near-solo (1 contributor active in recent commits)
• ⚠ No CI workflows detected
• ⚠ No test directory detected
• ⚠ Scorecard: default branch unprotected (0/10)

_{Maintenance signals: commit recency, contributor breadth, bus factor, license, CI, tests + OpenSSF Scorecard}

DeepSeek-OCR is a vision-language model designed to compress visual information efficiently for LLM consumption via a specialized vision encoder. The core innovation is 'Contexts Optical Compression'—a technique that bridges high-resolution image understanding with LLM inference by encoding images into compact token sequences while preserving OCR-relevant details. It supports both HuggingFace Transformers and vLLM inference backends with specialized SDPA (Scaled Dot-Product Attention) implementations for CLIP and SAM encoders. Dual-backend monorepo: DeepSeek-OCR-vllm/ contains the vLLM-optimized path (deepseek_ocr.py orchestrates inference; deepencoder/ houses SDPA kernels; process/ handles image prep and n-gram generation), while DeepSeek-OCR-hf/ provides HuggingFace Transformers compatibility via run_dpsk_ocr.py. Both share image_process.py preprocessing logic. Three entry points: run_dpsk_ocr_image.py (single image), run_dpsk_ocr_pdf.py (PDF batch), run_dpsk_ocr_eval_batch.py (evaluation harness).

ML researchers and practitioners building OCR/document understanding systems who want to integrate vision capabilities into LLMs without excessive token overhead. Specifically targets vLLM deployment engineers evaluating multimodal inference optimization and researchers studying vision encoder design from an LLM-centric perspective.

Actively developed and recently production-hardened. The project released v1 in Oct 2025 and gained upstream vLLM support (v0.8.5+) with official documentation. DeepSeek-OCR2 released Jan 2026 signals active iteration. However, it remains a specialized research model rather than battle-tested enterprise software; the dual implementation (HF + vLLM) suggests refinement is ongoing.

Tight dependency pinning creates fragility: requires PyTorch 2.6.0, vLLM 0.8.5, CUDA 11.8, and flash-attn 2.7.3 with no upper bounds or flexibility documented. The vLLM dependency is particularly risky—v0.8.5 is now ~4 months old and the codebase uses internal SDPA APIs (clip_sdpa.py, sam_vary_sdpa.py) that could break on vLLM upgrades. Single GitHub org (deepseek-ai) maintains both this and successor (DeepSeek-OCR-2), suggesting potential deprecation without warning.

The project transitioned to upstream vLLM support (Oct 2025) and released a successor DeepSeek-OCR2 (Jan 2026). Current focus appears to be on stabilizing the v1 vLLM integration while innovating on encoder design in v2. The DeepSeek-OCR-hf branch suggests parallel maintenance of Transformers compatibility, but file timestamps and commit recency are not visible—unclear if HF branch is deprecated or actively maintained.

git clone https://github.com/deepseek-ai/DeepSeek-OCR.git && cd DeepSeek-OCR && conda create -n deepseek-ocr python=3.12.9 -y && conda activate deepseek-ocr && pip install torch==2.6.0 torchvision==0.21.0 torchaudio==2.6.0 --index-url https://download.pytorch.org/whl/cu118 && pip install vllm-0.8.5+cu118-cp38-abi3-manylinux1_x86_64.whl && pip install -r requirements.txt && pip install flash-attn==2.7.3 --no-build-isolation

Daily commands: For image inference: python run_dpsk_ocr_image.py --image-path <path> (HF) or python DeepSeek-OCR-vllm/run_dpsk_ocr_image.py (vLLM). For PDF batch: python run_dpsk_ocr_pdf.py --pdf-path <path>. For evaluation: python run_dpsk_ocr_eval_batch.py --dataset <config>. The vLLM path requires prior model download from HuggingFace (deepseek-ai/DeepSeek-OCR). Exact CLI flags are not visible in file listing—check run_dpsk_ocr_*.py files for argparse definitions.

• DeepSeek-OCR-master/DeepSeek-OCR-vllm/deepseek_ocr.py — Core OCR inference engine—orchestrates image processing, model loading, and text extraction; entry point for all OCR operations.
• DeepSeek-OCR-master/DeepSeek-OCR-vllm/process/image_process.py — Image preprocessing pipeline that handles input normalization, resizing, and tensor conversion—critical for model accuracy.
• DeepSeek-OCR-master/DeepSeek-OCR-vllm/deepencoder/__init__.py — Vision encoder initialization and registry—defines custom attention mechanisms (SDPA) for efficient image encoding.
• DeepSeek-OCR-master/DeepSeek-OCR-vllm/run_dpsk_ocr_image.py — Single-image OCR inference script demonstrating the primary user-facing API for standalone image processing.
• DeepSeek-OCR-master/DeepSeek-OCR-vllm/config.py — Configuration management for model paths, inference parameters, and environment setup across all scripts.
• DeepSeek-OCR-master/DeepSeek-OCR-vllm/run_dpsk_ocr_pdf.py — PDF-to-OCR pipeline demonstrating multi-page document processing with PyMuPDF integration.
• DeepSeek-OCR-master/requirements.txt — Dependency manifest pinning critical versions (transformers 4.46.3, tokenizers 0.20.3) required for model compatibility.

Add Support for a New Image Format

1. Extend image_process.py with a new preprocessing function that handles the format's color space and dimensions (DeepSeek-OCR-master/DeepSeek-OCR-vllm/process/image_process.py)
2. Update the image format validation in the preprocessing pipeline to accept the new extension (DeepSeek-OCR-master/DeepSeek-OCR-vllm/process/image_process.py)
3. Test the new format by creating a test script similar to run_dpsk_ocr_image.py with sample inputs (DeepSeek-OCR-master/DeepSeek-OCR-vllm/run_dpsk_ocr_image.py)

Implement a Custom Vision Encoder

1. Create a new encoder module in deepencoder/ (e.g., custom_encoder_sdpa.py) following the pattern of clip_sdpa.py (DeepSeek-OCR-master/DeepSeek-OCR-vllm/deepencoder/clip_sdpa.py)
2. Register the new encoder in deepencoder/__init__.py by adding it to the encoder registry (DeepSeek-OCR-master/DeepSeek-OCR-vllm/deepencoder/__init__.py)
3. Update config.py to include the new encoder name and its initialization parameters (DeepSeek-OCR-master/DeepSeek-OCR-vllm/config.py)
4. Modify deepseek_ocr.py to instantiate the new encoder when specified in config (DeepSeek-OCR-master/DeepSeek-OCR-vllm/deepseek_ocr.py)

Add Post-Processing Constraint Logic

1. Implement a new constraint function in ngram_norepeat.py or create a sibling module following its patterns (DeepSeek-OCR-master/DeepSeek-OCR-vllm/process/ngram_norepeat.py)
2. Integrate the constraint into the decoding pipeline in deepseek_ocr.py after model inference (DeepSeek-OCR-master/DeepSeek-OCR-vllm/deepseek_ocr.py)
3. Add configuration parameters to config.py to enable/disable the constraint (DeepSeek-OCR-master/DeepSeek-OCR-vllm/config.py)

Create a New Batch Processing Pipeline

1. Create a new script in the root directory (similar to run_dpsk_ocr_eval_batch.py) that loads multiple images (DeepSeek-OCR-master/DeepSeek-OCR-vllm/run_dpsk_ocr_eval_batch.py)
2. Import and instantiate DeepSeekOCR class from deepseek_ocr.py with batch-compatible parameters (DeepSeek-OCR-master/DeepSeek-OCR-vllm/deepseek_ocr.py)
3. Loop over input images, call the inference method, and aggregate results with appropriate error handling (DeepSeek-OCR-master/DeepSeek-OCR-vllm/run_dpsk_ocr_eval_batch.py)

• transformers==4.46.3 — Provides pre-built vision transformer encoders (CLIP, SAM) and LLM backbones for efficient OCR model loading and inference
• PyMuPDF (fitz) — Enables multi-page PDF document parsing and rasterization before feeding pages to the OCR engine
• einops — Simplifies flexible tensor reshaping and rearrangement operations required for image encoding pipeline
• vLLM integration — Accelerates LLM inference via optimized attention kernels and batching, reducing inference latency for text generation
• SDPA (Scaled Dot-Product Attention) — Custom attention implementations in clip_sdpa.py and sam_vary_sdpa.py optimize memory and compute for vision encoding

• Separate HF and vLLM implementations

  • Why: vLLM offers superior inference speed via optimized kernels and paging; HF provides broader compatibility
  • Consequence: Code duplication across DeepSeek-OCR-hf and DeepSeek-OCR-vllm directories; users must choose implementation at deploy time

• Custom vision encoders (CLIP, SAM) rather than generic ResNet

  • Why: Vision transformers provide better feature semantics for OCR tasks; already trained on document/visual data
  • Consequence: Requires large model checkpoint downloads (~2GB+); slower cold-start but superior accuracy

• N-gram no-repeat post-processing constraints

  • Why: Reduces hallucinated repetitions in OCR output without retraining
  • Consequence: Adds inference latency (~50-100ms per image); may truncate legitimate repeated text in tables/lists

• Real-time streaming OCR (batch-only processing)
• Multi-language fine-tuning (uses pre-trained multilingual encoders as-is

1. CUDA 11.8 is mandatory but rarely installed on modern systems—most users have CUDA 12.x; downgrading risks other projects. 2) vLLM 0.8.5 is pinned and outdated; installing from the WHL directly sidesteps pip dependency resolution, so unmet transitive deps (like werkzeug, click for vLLM CLI) may fail silently at runtime. 3) flash-attn 2.7.3 requires compilation; --no-build-isolation can mask compiler errors if CUDA headers are missing. 4) HuggingFace model ID 'deepseek-ai/DeepSeek-OCR' must be pre-downloaded or available via huggingface_hub; no fallback URL or mirror in code visible. 5) config.py likely contains hardcoded model paths or encoder names—check before running on custom hardware or model variants.

• Scaled Dot-Product Attention (SDPA) — Core optimization in this repo—custom SDPA kernels (clip_sdpa.py, sam_vary_sdpa.py) replace standard attention to reduce vision encoder memory/latency, directly enabling the 'optical compression' claimed in the name
• Vision-Language Model (VLM) Inference — DeepSeek-OCR is a VLM—understands how images are encoded into tokens for LLM consumption; the entire design optimizes this interface
• Token Budget & Compression — Central design principle—'Contexts Optical Compression' explicitly limits tokens per image to reduce LLM compute; understand how image_process.py tokenizes patches and how encoders compress spatial info
• Hierarchical Vision Features — SAM encoder (sam_vary_sdpa.py) outputs multi-scale features; the custom SDPA must handle variable-resolution tokens from different encoder layers, affecting how compression works
• n-gram Repetition Avoidance — ngram_norepeat.py enforces decoding constraints to prevent hallucination in OCR output; understanding how it penalizes repeated token sequences is critical for tuning generation quality
• vLLM Engine Optimization — vLLM's paged attention and batching mechanisms power the inference—deepseek_ocr.py orchestrates vLLM's API; understanding batching, KV caching, and async generation is needed to optimize throughput
• PDF Rasterization & Batch Processing — run_dpsk_ocr_pdf.py uses PyMuPDF to extract pages; understanding page-level parallelization, memory management for large PDFs, and how token budgets scale across pages is key for production OCR pipelines

• vllm-project/vllm — Official vLLM inference engine that DeepSeek-OCR is built on top of; now provides upstream support for DeepSeek-OCR as of v0.8.5
• deepseek-ai/DeepSeek-OCR-2 — Successor version (released Jan 2026) iterating on encoder design and compression technique; represents active research direction
• openai/CLIP — Vision encoder backbone integrated into DeepSeek-OCR; custom SDPA wrapper in clip_sdpa.py depends on understanding CLIP architecture
• facebookresearch/segment-anything — SAM encoder provides hierarchical vision features; DeepSeek-OCR's sam_vary_sdpa.py implements custom attention for SAM-extracted tokens
• huggingface/transformers — Alternative inference backend (HF path); deepseek-ocr-hf/ provides pure Transformers implementation without vLLM dependency

To work on one of these in Claude Code or Cursor, paste: Implement the "<title>" PR idea from CLAUDE.md, working through the checklist as the task list.

Add comprehensive unit tests for image_process.py and ngram_norepeat.py

The DeepSeek-OCR-vllm/process/ directory contains critical image preprocessing and token generation logic, but there are no test files visible in the repo. Adding unit tests for image_process.py (which handles image normalization, resizing, and encoding) and ngram_norepeat.py (which implements n-gram filtering for decoding) would catch regressions early and help contributors understand the expected behavior of these core modules.

• [ ] Create tests/test_image_process.py with test cases for various image formats (PNG, JPEG, PDF), edge cases (empty images, very large images), and expected output shapes
• [ ] Create tests/test_ngram_norepeat.py with test cases verifying n-gram filtering logic prevents repetitions correctly
• [ ] Add pytest configuration to root (pytest.ini or setup.cfg) and document how to run tests in README.md

Add GitHub Actions CI workflow for model validation on CPU

The repo has two entry points (run_dpsk_ocr_image.py and run_dpsk_ocr_pdf.py) and multiple processor modules, but no CI pipeline to validate that basic inference runs correctly. A lightweight CPU-based validation workflow would catch import errors, missing dependencies, and obvious model loading failures before users encounter them.

• [ ] Create .github/workflows/ci-test.yml that installs dependencies from requirements.txt and runs a simple inference test using run_dpsk_ocr_image.py with a minimal test image
• [ ] Add a small test image (e.g., 50x50px) to assets/ or tests/fixtures/ for CI to use without needing large model downloads
• [ ] Ensure the workflow validates both DeepSeek-OCR-hf and DeepSeek-OCR-vllm entry points with sensible timeouts and hardware constraints

Refactor deepencoder/ module with explicit component exports and integration tests

The deepencoder/ directory has specialized SDPA implementations (clip_sdpa.py, sam_vary_sdpa.py) and build utilities (build_linear.py) but the init.py is empty, making it unclear what the public API is. Additionally, there are no tests validating that these custom attention mechanisms integrate correctly with the main deepseek_ocr.py pipeline. Adding proper exports and integration tests would make the codebase more maintainable.

• [ ] Update DeepSeek-OCR-vllm/deepencoder/init.py to explicitly export CLIPSdpa, SAMVarySdpa, and build_linear_layer with docstrings describing when each should be used
• [ ] Create tests/test_deepencoder_integration.py that validates the attention mechanisms produce expected output shapes and gradients when integrated with sample encoder inputs
• [ ] Add comments to deepencoder/clip_sdpa.py and deepencoder/sam_vary_sdpa.py explaining the differences from standard attention (why SDPA variants are needed for OCR)

• Add type hints and docstrings to DeepSeek-OCR-vllm/deepseek_ocr.py's main inference functions (image_to_text, process_pdf, etc.)—currently undocumented, making API unclear for new users integrating this into their pipelines.
• Create unit tests for process/image_process.py covering edge cases (rotated PDFs, grayscale images, extreme resolutions, missing EXIF data)—no test directory visible and image handling is error-prone.
• Document the exact difference between DeepSeek-OCR-hf and DeepSeek-OCR-vllm inference paths in README with a decision tree (when to use which, performance comparison, feature parity matrix)—currently both exist without explanation of tradeoffs.

• High · Outdated Transformers Library with Known Vulnerabilities — requirements.txt. The codebase uses transformers==4.46.3, which may contain known security vulnerabilities. This package handles model loading and execution, making it a critical dependency. Newer versions contain security patches for potential code execution and data handling issues. Fix: Update to the latest stable version of transformers. Run 'pip install --upgrade transformers' and test compatibility. Monitor security advisories at huggingface.co/docs/transformers/security.
• High · Unvalidated File Input Processing — DeepSeek-OCR-vllm/process/image_process.py, run_dpsk_ocr_pdf.py. The codebase processes PDF and image files (PyMuPDF, img2pdf) without visible validation. Files located in 'process/image_process.py' and 'run_dpsk_ocr_pdf.py' likely handle user-supplied files. Malicious PDFs or images could trigger buffer overflows, zip bombs, or other file-based attacks. Fix: Implement strict file validation: verify file magic bytes, enforce file size limits, scan with antivirus/malware tools, and run file processing in isolated containers. Use PIL/Pillow safely with image format validation.
• High · Potential Path Traversal in File Processing — DeepSeek-OCR-vllm/process/image_process.py, run_dpsk_ocr_pdf.py. File processing modules (image_process.py, run_dpsk_ocr_pdf.py) may be vulnerable to path traversal attacks if user input directly influences file paths without sanitization. An attacker could read arbitrary files via '../' sequences. Fix: Validate and sanitize all file paths. Use os.path.abspath() and verify paths are within expected directories. Implement allowlist-based path validation. Use pathlib.Path for safer path handling.
• Medium · Outdated Pillow Library — requirements.txt. Pillow dependency version is not pinned with a specific version number, risking installation of potentially vulnerable versions. Pillow has had historical vulnerabilities in image processing. Fix: Pin Pillow to a specific secure version (e.g., Pillow>=10.0.0). Regularly update and test against security advisories from python-pillow/Pillow.
• Medium · Unpinned Dependency Versions — requirements.txt. Most dependencies lack specific version constraints (PyMuPDF, img2pdf, einops, easydict, addict, numpy). This creates supply chain risk - minor version upgrades could introduce breaking changes or security issues. Fix: Pin all dependencies to specific versions using requirements-lock.txt or poetry.lock. Use 'pip freeze > requirements.txt' to capture exact versions, then periodically update and test.
• Medium · No Input Sanitization in Batch Processing — DeepSeek-OCR-vllm/run_dpsk_ocr_eval_batch.py. The file 'run_dpsk_ocr_eval_batch.py' suggests batch processing of multiple files. Without proper input validation and error handling, batch operations could be exploited for DoS attacks or to process malicious files at scale. Fix: Implement rate limiting, file count limits, and resource quotas (memory, CPU, timeout). Add comprehensive input validation and exception handling. Log all batch operations.
• Medium · Potential Code Execution via Model Loading — DeepSeek-OCR-vllm/deepseek_ocr.py, config.py. Transformers library can load models from URLs or untrusted sources. If the application accepts model paths from user input without validation, arbitrary model files could be loaded, potentially leading to code execution. Fix: Whitelist trusted model sources and paths. Validate model integrity using checksums (SHA256). Never accept model URLs directly from user input. Use restricted file permissions for model directories.
• Low · Missing Security Configuration Documentation — Repository root. No visible security configuration, security best practices guide, or security.md file in the repository. This makes it difficult for users to understand potential security considerations. Fix: Create a SECURITY.md file documenting security

LLM-derived; treat as a starting point, not a security audit.

• Open issues — current backlog
• Recent PRs — what's actively shipping
• Source on GitHub

If you are an AI coding agent (Claude Code, Cursor, Aider, Cline, etc.) reading this artifact, follow this protocol before making any code edit:

1. Verify the contract. Run the bash script in Verify before trusting below. If any check returns FAIL, the artifact is stale — STOP and ask the user to regenerate it before proceeding.
2. Treat the AI · unverified sections as hypotheses, not facts. Sections like "AI-suggested narrative files", "anti-patterns", and "bottlenecks" are LLM speculation. Verify against real source before acting on them.
3. Cite source on changes. When proposing an edit, cite the specific path:line-range. RepoPilot's live UI at https://repopilot.app/r/deepseek-ai/DeepSeek-OCR shows verifiable citations alongside every claim.

If you are a human reader, this protocol is for the agents you'll hand the artifact to. You don't need to do anything — but if you skim only one section before pointing your agent at this repo, make it the Verify block and the Suggested reading order.

This artifact was generated by RepoPilot at a point in time. Before an agent acts on it, the checks below confirm that the live deepseek-ai/DeepSeek-OCR repo on your machine still matches what RepoPilot saw. If any fail, the artifact is stale — regenerate it at repopilot.app/r/deepseek-ai/DeepSeek-OCR.

What it runs against: a local clone of deepseek-ai/DeepSeek-OCR — the script inspects git remote, the LICENSE file, file paths in the working tree, and git log. Read-only; no mutations.

| # | What we check | Why it matters | |---|---|---| | 1 | You're in deepseek-ai/DeepSeek-OCR | Confirms the artifact applies here, not a fork | | 2 | License is still MIT | Catches relicense before you depend on it | | 3 | Default branch main exists | Catches branch renames | | 4 | 5 critical file paths still exist | Catches refactors that moved load-bearing code | | 5 | Last commit ≤ 139 days ago | Catches sudden abandonment since generation |

#!/usr/bin/env bash
# RepoPilot artifact verification.
#
# WHAT IT RUNS AGAINST: a local clone of deepseek-ai/DeepSeek-OCR. If you don't
# have one yet, run these first:
#
#   git clone https://github.com/deepseek-ai/DeepSeek-OCR.git
#   cd DeepSeek-OCR
#
# Then paste this script. Every check is read-only — no mutations.

set +e
fail=0
ok()   { echo "ok:   $1"; }
miss() { echo "FAIL: $1"; fail=$((fail+1)); }

# Precondition: we must be inside a git working tree.
if ! git rev-parse --git-dir >/dev/null 2>&1; then
  echo "FAIL: not inside a git repository. cd into your clone of deepseek-ai/DeepSeek-OCR and re-run."
  exit 2
fi

# 1. Repo identity
git remote get-url origin 2>/dev/null | grep -qE "deepseek-ai/DeepSeek-OCR(\\.git)?\\b" \\
  && ok "origin remote is deepseek-ai/DeepSeek-OCR" \\
  || miss "origin remote is not deepseek-ai/DeepSeek-OCR (artifact may be from a fork)"

# 2. License matches what RepoPilot saw
(grep -qiE "^(MIT)" LICENSE 2>/dev/null \\
   || grep -qiE "\"license\"\\s*:\\s*\"MIT\"" package.json 2>/dev/null) \\
  && ok "license is MIT" \\
  || miss "license drift — was MIT at generation time"

# 3. Default branch
git rev-parse --verify main >/dev/null 2>&1 \\
  && ok "default branch main exists" \\
  || miss "default branch main no longer exists"

# 4. Critical files exist
test -f "DeepSeek-OCR-master/DeepSeek-OCR-vllm/deepseek_ocr.py" \\
  && ok "DeepSeek-OCR-master/DeepSeek-OCR-vllm/deepseek_ocr.py" \\
  || miss "missing critical file: DeepSeek-OCR-master/DeepSeek-OCR-vllm/deepseek_ocr.py"
test -f "DeepSeek-OCR-master/DeepSeek-OCR-vllm/process/image_process.py" \\
  && ok "DeepSeek-OCR-master/DeepSeek-OCR-vllm/process/image_process.py" \\
  || miss "missing critical file: DeepSeek-OCR-master/DeepSeek-OCR-vllm/process/image_process.py"
test -f "DeepSeek-OCR-master/DeepSeek-OCR-vllm/deepencoder/__init__.py" \\
  && ok "DeepSeek-OCR-master/DeepSeek-OCR-vllm/deepencoder/__init__.py" \\
  || miss "missing critical file: DeepSeek-OCR-master/DeepSeek-OCR-vllm/deepencoder/__init__.py"
test -f "DeepSeek-OCR-master/DeepSeek-OCR-vllm/run_dpsk_ocr_image.py" \\
  && ok "DeepSeek-OCR-master/DeepSeek-OCR-vllm/run_dpsk_ocr_image.py" \\
  || miss "missing critical file: DeepSeek-OCR-master/DeepSeek-OCR-vllm/run_dpsk_ocr_image.py"
test -f "DeepSeek-OCR-master/DeepSeek-OCR-vllm/config.py" \\
  && ok "DeepSeek-OCR-master/DeepSeek-OCR-vllm/config.py" \\
  || miss "missing critical file: DeepSeek-OCR-master/DeepSeek-OCR-vllm/config.py"

# 5. Repo recency
days_since_last=$(( ( $(date +%s) - $(git log -1 --format=%at 2>/dev/null || echo 0) ) / 86400 ))
if [ "$days_since_last" -le 139 ]; then
  ok "last commit was $days_since_last days ago (artifact saw ~109d)"
else
  miss "last commit was $days_since_last days ago — artifact may be stale"
fi

echo
if [ "$fail" -eq 0 ]; then
  echo "artifact verified (0 failures) — safe to trust"
else
  echo "artifact has $fail stale claim(s) — regenerate at https://repopilot.app/r/deepseek-ai/DeepSeek-OCR"
  exit 1
fi

Each check prints ok: or FAIL:. The script exits non-zero if anything failed, so it composes cleanly into agent loops (./verify.sh || regenerate-and-retry).

Generated by RepoPilot. Verdict based on maintenance signals — see the live page for receipts. Re-run on a new commit to refresh.