DeepSeek-OCR Cross-Platform Deployment Guide: Detailed Configuration for Ubuntu and Windows

    This guide provides step-by-step instructions for deploying DeepSeek-OCR on Ubuntu 24.04 LTS and Windows 11 systems, covering system requirements, environment setup, dependency installation, and performance optimization techniques. Developers can follow these standardized procedures to implement OCR solutions in both Linux and Windows environments.

    System Requirements and Prerequisites

    Hardware and Software Specifications

    Supported Operating Systems:

    • Ubuntu 24.04 LTS (with root access)
    • Windows 11 Professional (with WSL2 or native CUDA support)

    Minimum Hardware:

    • NVIDIA GPU with Compute Capability ≥5.0 (16GB VRAM recommended)
    • Python 3.12-3.13 (version-specific to OS)
    • CUDA Toolkit 11.8 or 13.0

    Network Configuration:

    1. Ensure internet access for dependency downloads
    2. Disable security modules:
      • Ubuntu: SELinux
      • Windows: Windows Defender Real-Time Protection

    Directory Setup:

    1. # Ubuntu
    2. mkdir -p ~/deepseek_projects && cd ~/deepseek_projects
    3. # Windows PowerShell
    4. New-Item -ItemType Directory -Path C:\deepseek_projects | cd

    Ubuntu 24.04 Deployment Process

    Source Code Acquisition

    1. git clone https://github.com/deepseek-ai/DeepSeek-OCR.git
    2. cd DeepSeek-OCR

    Python Environment Configuration

    1. # Install uv environment manager
    2. curl -LsSf https://astral.sh/uv/install.sh | sh
    3. source ~/.bashrc
    4. # Create Python 3.12 environment
    5. uv venv --python 3.12 .venv
    6. source .venv/bin/activate

    CUDA Toolkit Installation

    1. sudo apt update
    2. sudo apt install -y nvidia-cuda-toolkit nvidia-cuda-dev
    3. # Environment configuration
    4. echo 'export CUDA_HOME=/usr' >> ~/.bashrc
    5. source ~/.bashrc
    6. # Verification
    7. nvcc --version # Should show CUDA 11.8

    Dependency Installation Sequence

    1. # PyTorch installation (CUDA 11.8)
    2. pip install torch==2.6.0 torchvision==0.21.0 torchaudio==2.6.0 \
    3. --index-url https://download.pytorch.org/whl/cu118
    4. # vLLM installation
    5. pip install vllm-0.8.5+cu118-cp38-abi3-manylinux1_x86_64.whl
    6. # Additional dependencies
    7. pip install -r requirements.txt
    8. pip install flash-attn==2.7.3 --no-build-isolation
    9. pip install Pillow addict matplotlib opencv-python transformers accelerate

    Model Deployment

    1. Configure HuggingFace mirror:

      1. echo 'export HF_ENDPOINT="https://hf-mirror.com"' >> ~/.bashrc
      2. source ~/.bashrc
    2. Launch service:

      1. sed -i 's/os.environ\[.*\]/os.environ["HF_ENDPOINT"] = "https:\/\/hf-mirror.com"/' \
      2. DeepSeek-OCR-hf/run_dpsk_ocr.py
      3. uv run DeepSeek-OCR-hf/run_dpsk_ocr.py

    Windows 11 Deployment Guide

    CUDA Toolkit Setup

    1. Download CUDA Toolkit 13.0 from NVIDIA official site
    2. Custom installation:
      • Select CUDA Development components
      • Deselect Driver components
    3. Verification:
      1. nvidia-smi # Shows driver version
      2. nvcc --version # Shows CUDA 13.0

    Python Environment Configuration

    1. # Install Python 3.13 with PATH option
    2. pip install uv
    3. uv venv --python 3.13 .venv
    4. .\.venv\Scripts\activate

    PyTorch Installation

    1. # For CUDA 13.0
    2. pip install torch torchvision torchaudio --index-url https://download.pytorch.org/whl/cu130
    3. # Verification
    4. python -c "import torch; print(torch.cuda.is_available())" # Should return True

    Dependency Management

    1. pip install -r requirements.txt
    2. pip install flash-attn==2.7.3 --no-build-isolation
    3. pip install opencv-python transformers accelerate

    Service Configuration

    1. [System.Environment]::SetEnvironmentVariable('HF_ENDPOINT', 'https://hf-mirror.com', 'User')
    2. $env:HF_ENDPOINT = "https://hf-mirror.com"
    3. uv run .\DeepSeek-OCR-hf\run_dpsk_ocr.py

    Troubleshooting Guide

    CUDA Compatibility Issues

    Symptom: torch.cuda.is_available() returns False
    Solution:

    1. Verify CUDA version with nvcc --version
    2. Reinstall matching PyTorch version (cu118/cu130)

    Dependency Conflicts

    Symptom: ImportError for module components
    Solution:

    1. Create clean virtual environment
    2. Follow recommended installation order:
      • PyTorch framework
      • Basic utilities (numpy, packaging)
      • Project requirements
      • Specialized libraries (flash-attn)

    Model Download Failures

    Symptom: HuggingFace loading timeouts
    Solution:

    1. Configure mirror endpoint
    2. Use network proxy tools for acceleration

    Performance Optimization

    Memory Management

    1. # In run_dpsk_ocr.py configuration
    2. model_config = {
    3. 'batch_size': 32, # Adjust based on GPU memory
    4. 'precision': 'fp16' # Enable mixed precision
    5. }

    Monitoring Tools

    • Ubuntu: nvidia-smi dmon for real-time GPU metrics
    • Windows: Task Manager GPU monitoring tab

    Cache Optimization

    1. # Terminal command for cache clearing
    2. torch.cuda.empty_cache() # In Python environment
    3. export CUDA_LAUNCH_BLOCKING=1 # For synchronization issues

    This deployment guide enables developers to implement DeepSeek-OCR across major operating systems with standardized procedures. Initial testing with smaller models is recommended before full-scale deployment. For production environments, consider containerization using Docker for consistent environment replication.