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:
- Ensure internet access for dependency downloads
- Disable security modules:
- Ubuntu: SELinux
- Windows: Windows Defender Real-Time Protection
Directory Setup:
# Ubuntumkdir -p ~/deepseek_projects && cd ~/deepseek_projects# Windows PowerShellNew-Item -ItemType Directory -Path C:\deepseek_projects | cd
Ubuntu 24.04 Deployment Process
Source Code Acquisition
git clone https://github.com/deepseek-ai/DeepSeek-OCR.gitcd DeepSeek-OCR
Python Environment Configuration
# Install uv environment managercurl -LsSf https://astral.sh/uv/install.sh | shsource ~/.bashrc# Create Python 3.12 environmentuv venv --python 3.12 .venvsource .venv/bin/activate
CUDA Toolkit Installation
sudo apt updatesudo apt install -y nvidia-cuda-toolkit nvidia-cuda-dev# Environment configurationecho 'export CUDA_HOME=/usr' >> ~/.bashrcsource ~/.bashrc# Verificationnvcc --version # Should show CUDA 11.8
Dependency Installation Sequence
# PyTorch installation (CUDA 11.8)pip install torch==2.6.0 torchvision==0.21.0 torchaudio==2.6.0 \--index-url https://download.pytorch.org/whl/cu118# vLLM installationpip install vllm-0.8.5+cu118-cp38-abi3-manylinux1_x86_64.whl# Additional dependenciespip install -r requirements.txtpip install flash-attn==2.7.3 --no-build-isolationpip install Pillow addict matplotlib opencv-python transformers accelerate
Model Deployment
Configure HuggingFace mirror:
echo 'export HF_ENDPOINT="https://hf-mirror.com"' >> ~/.bashrcsource ~/.bashrc
Launch service:
sed -i 's/os.environ\[.*\]/os.environ["HF_ENDPOINT"] = "https:\/\/hf-mirror.com"/' \DeepSeek-OCR-hf/run_dpsk_ocr.pyuv run DeepSeek-OCR-hf/run_dpsk_ocr.py
Windows 11 Deployment Guide
CUDA Toolkit Setup
- Download CUDA Toolkit 13.0 from NVIDIA official site
- Custom installation:
- Select CUDA Development components
- Deselect Driver components
- Verification:
nvidia-smi # Shows driver versionnvcc --version # Shows CUDA 13.0
Python Environment Configuration
# Install Python 3.13 with PATH optionpip install uvuv venv --python 3.13 .venv.\.venv\Scripts\activate
PyTorch Installation
# For CUDA 13.0pip install torch torchvision torchaudio --index-url https://download.pytorch.org/whl/cu130# Verificationpython -c "import torch; print(torch.cuda.is_available())" # Should return True
Dependency Management
pip install -r requirements.txtpip install flash-attn==2.7.3 --no-build-isolationpip install opencv-python transformers accelerate
Service Configuration
[System.Environment]::SetEnvironmentVariable('HF_ENDPOINT', 'https://hf-mirror.com', 'User')$env:HF_ENDPOINT = "https://hf-mirror.com"uv run .\DeepSeek-OCR-hf\run_dpsk_ocr.py
Troubleshooting Guide
CUDA Compatibility Issues
Symptom: torch.cuda.is_available() returns False
Solution:
- Verify CUDA version with
nvcc --version - Reinstall matching PyTorch version (cu118/cu130)
Dependency Conflicts
Symptom: ImportError for module components
Solution:
- Create clean virtual environment
- Follow recommended installation order:
- PyTorch framework
- Basic utilities (numpy, packaging)
- Project requirements
- Specialized libraries (flash-attn)
Model Download Failures
Symptom: HuggingFace loading timeouts
Solution:
- Configure mirror endpoint
- Use network proxy tools for acceleration
Performance Optimization
Memory Management
# In run_dpsk_ocr.py configurationmodel_config = {'batch_size': 32, # Adjust based on GPU memory'precision': 'fp16' # Enable mixed precision}
Monitoring Tools
- Ubuntu:
nvidia-smi dmonfor real-time GPU metrics - Windows: Task Manager GPU monitoring tab
Cache Optimization
# Terminal command for cache clearingtorch.cuda.empty_cache() # In Python environmentexport 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.
