DeepSeek-OCR-2在Ubuntu20.04上的保姆级安装教程

1. 引言

如果你正在寻找一个强大的OCR工具来处理文档、图片或者PDF，DeepSeek-OCR-2绝对值得一试。这个模型不仅能识别文字，还能理解文档结构，甚至能把复杂的PDF转换成整洁的Markdown格式。

不过，在Ubuntu上安装这类AI工具可能会遇到各种环境问题。别担心，这篇教程会手把手带你完成整个安装过程，从驱动安装到环境配置，再到常见问题的解决。即使你是Linux新手，跟着步骤走也能轻松搞定。

2. 环境准备

在开始安装之前，我们需要先确保系统环境符合要求。DeepSeek-OCR-2需要CUDA 11.8和Python 3.12.9，所以先来检查一下你的系统配置。

2.1 系统要求确认

首先打开终端，检查你的Ubuntu版本：

lsb_release -a

你应该看到类似这样的输出：

Distributor ID: Ubuntu
Description:    Ubuntu 20.04.6 LTS
Release:        20.04
Codename:       focal

确认是Ubuntu 20.04后，检查显卡驱动是否安装：

nvidia-smi

如果看到显卡信息，说明驱动已经安装。如果提示命令未找到，需要先安装NVIDIA驱动。

2.2 NVIDIA驱动安装

如果你的系统还没有安装NVIDIA驱动，可以这样安装：

# 添加官方PPA源
sudo add-apt-repository ppa:graphics-drivers/ppa
sudo apt update

# 查看推荐的驱动版本
ubuntu-drivers devices

# 安装推荐的驱动（这里以nvidia-driver-535为例）
sudo apt install nvidia-driver-535

# 安装完成后重启
sudo reboot

重启后再次运行nvidia-smi确认驱动安装成功。

3. CUDA和cuDNN安装

DeepSeek-OCR-2需要CUDA 11.8环境，下面是详细的安装步骤。

3.1 安装CUDA 11.8

# 下载CUDA 11.8安装包
wget https://developer.download.nvidia.com/compute/cuda/11.8.0/local_installers/cuda_11.8.0_520.61.05_linux.run

# 给安装文件添加执行权限
chmod +x cuda_11.8.0_520.61.05_linux.run

# 运行安装程序
sudo ./cuda_11.8.0_520.61.05_linux.run

安装过程中，记得取消勾选Driver选项（因为我们已经安装了驱动），只选择CUDA Toolkit。

安装完成后，配置环境变量：

# 编辑bashrc文件
nano ~/.bashrc

# 在文件末尾添加以下内容
export PATH=/usr/local/cuda-11.8/bin${PATH:+:${PATH}}
export LD_LIBRARY_PATH=/usr/local/cuda-11.8/lib64${LD_LIBRARY_PATH:+:${LD_LIBRARY_PATH}}

# 使配置生效
source ~/.bashrc

验证CUDA安装：

nvcc --version

3.2 安装cuDNN

cuDNN是NVIDIA的深度学习加速库，需要注册NVIDIA开发者账号后下载。

# 下载cuDNN（需要先在官网下载）
# 假设下载的文件是cudnn-linux-x86_64-8.9.7.29_cuda11-archive.tar.xz

# 解压文件
tar -xvf cudnn-linux-x86_64-8.9.7.29_cuda11-archive.tar.xz

# 复制文件到CUDA目录
sudo cp cudnn-*-archive/include/cudnn*.h /usr/local/cuda/include 
sudo cp -P cudnn-*-archive/lib/libcudnn* /usr/local/cuda/lib64 
sudo chmod a+r /usr/local/cuda/include/cudnn*.h /usr/local/cuda/lib64/libcudnn*

4. 创建Python虚拟环境

为了避免包冲突，我们使用conda创建独立的Python环境。

4.1 安装Miniconda

如果还没有安装conda，先安装Miniconda：

wget https://repo.anaconda.com/miniconda/Miniconda3-latest-Linux-x86_64.sh
bash Miniconda3-latest-Linux-x86_64.sh

按照提示完成安装，然后重启终端。

4.2 创建专用环境

# 创建名为deepseek-ocr2的环境，指定Python版本为3.12.9
conda create -n deepseek-ocr2 python=3.12.9 -y

# 激活环境
conda activate deepseek-ocr2

5. 安装DeepSeek-OCR-2

现在开始安装DeepSeek-OCR-2及其依赖。

5.1 克隆项目仓库

# 克隆项目代码
git clone https://github.com/deepseek-ai/DeepSeek-OCR-2.git
cd DeepSeek-OCR-2

5.2 安装PyTorch和相关依赖

# 安装PyTorch 2.6.0（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（需要先下载whl文件）
# 从https://github.com/vllm-project/vllm/releases下载vllm-0.8.5+cu118-cp312-cp312-manylinux1_x86_64.whl
pip install vllm-0.8.5+cu118-cp312-cp312-manylinux1_x86_64.whl

# 安装项目依赖
pip install -r requirements.txt

# 安装flash-attention
pip install flash-attn==2.7.3 --no-build-isolation

5.3 安装其他必要依赖

# 安装一些可能需要的系统依赖
sudo apt update
sudo apt install -y libgl1-mesa-glx libglib2.0-0

# 安装Python依赖
pip install opencv-python-headless pillow transformers

6. 验证安装

安装完成后，我们来验证一下是否一切正常。

6.1 基本环境检查

# 检查Python版本
python --version

# 检查CUDA是否可用
python -c "import torch; print(torch.cuda.is_available())"

# 检查显卡内存
python -c "import torch; print(torch.cuda.get_device_name(0)); print(torch.cuda.get_device_properties(0).total_memory / 1024**3, 'GB')"

6.2 简单测试代码

创建一个简单的测试脚本test_install.py：

import torch
from transformers import AutoModel, AutoTokenizer
import os

# 设置使用的GPU
os.environ["CUDA_VISIBLE_DEVICES"] = '0'

# 检查环境
print("CUDA available:", torch.cuda.is_available())
print("GPU name:", torch.cuda.get_device_name(0))
print("PyTorch version:", torch.__version__)

# 尝试加载tokenizer（不加载完整模型以节省时间）
try:
    tokenizer = AutoTokenizer.from_pretrained('deepseek-ai/DeepSeek-OCR-2', trust_remote_code=True)
    print("Tokenizer加载成功！")
except Exception as e:
    print("Tokenizer加载失败:", e)

运行测试脚本：

python test_install.py

如果一切正常，你应该看到CUDA可用、GPU信息正确，并且tokenizer加载成功。

7. 常见问题解决

在安装过程中可能会遇到一些问题，这里提供一些常见问题的解决方法。

7.1 CUDA版本不匹配

如果遇到CUDA版本错误，检查CUDA版本：

nvcc --version

确保显示的是11.8版本。如果不是，检查环境变量设置是否正确。

7.2 内存不足问题

如果显卡内存不足（小于8GB），可以尝试使用更小的模型或者启用梯度检查点：

model = AutoModel.from_pretrained(
    'deepseek-ai/DeepSeek-OCR-2',
    use_gradient_checkpointing=True,  # 减少内存使用
    torch_dtype=torch.float16,        # 使用半精度
    device_map='auto'                 # 自动分配设备
)

7.3 依赖冲突

如果遇到包冲突，可以尝试重新创建环境：

# 删除旧环境
conda deactivate
conda env remove -n deepseek-ocr2

# 重新创建环境
conda create -n deepseek-ocr2 python=3.12.9 -y
conda activate deepseek-ocr2

# 按顺序安装
pip install torch==2.6.0 torchvision==0.21.0 torchaudio==2.6.0 --index-url https://download.pytorch.org/whl/cu118
pip install -r requirements.txt

7.4 网络问题

如果从Hugging Face下载模型时遇到网络问题，可以设置镜像：

# 设置Hugging Face镜像
export HF_ENDPOINT=https://hf-mirror.com

# 或者使用国内镜像源下载
git clone https://mirror.ghproxy.com/https://github.com/deepseek-ai/DeepSeek-OCR-2.git

8. 第一次运行

现在让我们来运行一个简单的例子，验证安装是否完全成功。

创建测试图片和脚本：

# create_test_image.py
from PIL import Image, ImageDraw, ImageFont
import os

# 创建一个简单的测试图片
img = Image.new('RGB', (400, 200), color='white')
d = ImageDraw.Draw(img)

# 尝试使用系统字体
try:
    font = ImageFont.truetype("Arial", 24)
except:
    font = ImageFont.load_default()

d.text((50, 80), "Hello DeepSeek-OCR-2!", fill='black', font=font)
img.save('test_image.jpg')
print("测试图片已创建：test_image.jpg")

运行创建测试图片：

python create_test_image.py

然后创建运行脚本：

# first_run.py
from transformers import AutoModel, AutoTokenizer
import torch
import os

os.environ["CUDA_VISIBLE_DEVICES"] = '0'

def first_test():
    print("正在加载模型，这可能需要一些时间...")
    
    try:
        # 加载tokenizer和模型
        tokenizer = AutoTokenizer.from_pretrained(
            'deepseek-ai/DeepSeek-OCR-2', 
            trust_remote_code=True
        )
        
        model = AutoModel.from_pretrained(
            'deepseek-ai/DeepSeek-OCR-2',
            _attn_implementation='flash_attention_2',
            trust_remote_code=True,
            use_safetensors=True
        )
        
        model = model.eval().cuda().to(torch.bfloat16)
        print("模型加载成功！")
        
        # 简单测试
        prompt = "<image>\nFree OCR. "
        image_file = 'test_image.jpg'
        
        print("正在进行OCR识别...")
        result = model.infer(
            tokenizer,
            prompt=prompt,
            image_file=image_file,
            output_path='./output',
            base_size=1024,
            image_size=768,
            crop_mode=True,
            save_results=True
        )
        
        print("识别完成！结果保存在output目录")
        return True
        
    except Exception as e:
        print(f"运行出错: {e}")
        return False

if __name__ == "__main__":
    first_test()

运行测试：

python first_run.py

第一次运行会下载模型权重，可能需要较长时间。如果一切顺利，你应该看到模型成功加载并完成了OCR识别。

9. 总结

通过这篇教程，我们完整地在Ubuntu 20.04上配置了DeepSeek-OCR-2的运行环境。从驱动安装、CUDA配置到Python环境搭建，每一步都进行了详细的说明。虽然过程看起来有些复杂，但只要按照步骤操作，基本上都能成功安装。

实际使用下来，DeepSeek-OCR-2的安装过程相对 straightforward，主要的时间会花在模型下载上。如果在任何步骤遇到问题，可以参考常见问题解决部分，或者到项目的GitHub页面查看issue讨论。

现在你已经有了一个功能强大的OCR环境，可以开始尝试处理各种文档和图片了。建议先从简单的图片开始测试，熟悉后再处理更复杂的文档。

---

获取更多AI镜像

想探索更多AI镜像和应用场景？访问 CSDN星图镜像广场，提供丰富的预置镜像，覆盖大模型推理、图像生成、视频生成、模型微调等多个领域，支持一键部署。