DeepSeek-OCR 部署、配置解析与测试完整指南

[一、DeepSeek-OCR 介绍](#一、DeepSeek-OCR 介绍)
[二、DeepSeek-OCR 部署](#二、DeepSeek-OCR 部署)
[三、DeepSeek-OCR 配置解析](#三、DeepSeek-OCR 配置解析)
- [1.DeepSeek-OCR 配置文件解析](#1.DeepSeek-OCR 配置文件解析)
- [2.DeepSeek-OCR 支持模式详解](#2.DeepSeek-OCR 支持模式详解)
[四、DeepSeek-OCR vLLM推理](#四、DeepSeek-OCR vLLM推理)
- 1.工作目录设置
- 2.图像流式输出
- [3.PDF 并发处理](#3.PDF 并发处理)
- 4.批量评估基准测试
[五、DeepSeek-OCR Transformers推理](#五、DeepSeek-OCR Transformers推理)

一、DeepSeek-OCR 介绍

DeepSeek-OCR 是 DeepSeek-AI 提出的用于探索视觉 2D 映射压缩长上下文可行性 的视觉语言模型（VLM），由DeepEncoder（核心编码器，~380M 参数） 和DeepSeek3B-MoE-A570M 解码器（激活 570M 参数） 构成；其核心优势在于 DeepEncoder 通过串联窗口注意力（SAM-base）、16× 卷积压缩器与全局注意力（CLIP-large），实现高分辨率输入下的低激活内存与高压缩比 ，实验显示在 Fox 基准上压缩比 < 10× 时 OCR 精度达 97% 、20× 时仍保持 60% 精度，在 OmniDocBench 上仅用 100 视觉 token 超越 GOT-OCR2.0（256token）、<800 视觉 token 超越 MinerU2.0（6000+token），同时具备深度解析（图表 / 化学式 / 几何）、近 100 种语言识别能力，生产级场景下单 A100-40G 日生成 200k + 页 LLM/VLM 训练数据，为 LLM 长上下文处理与记忆遗忘机制研究提供新方向。

二、DeepSeek-OCR 部署

1.准备文件

bash 复制代码

# 拉取CUDA 11.8的镜像
docker pull swr.cn-north-4.myhuaweicloud.com/ddn-k8s/docker.io/nvidia/cuda:11.8.0-devel-ubuntu22.04
# 克隆此存储库
git clone https://github.com/deepseek-ai/DeepSeek-OCR.git
# 下载vllm-0.8.5 [whl](https://github.com/vllm-project/vllm/releases/tag/v0.8.5)
vllm-0.8.5+cu118-cp38-abi3-manylinux1_x86_64.whl
# git下载模型
git lfs install
git clone https://www.modelscope.cn/deepseek-ai/DeepSeek-OCR.git

显卡环境（A100-40G）

2.创建Dockerfile

创建一个Dockerfile来构建包含CUDA 11.8和指定Python环境的镜像

dockerfile 复制代码

# 使用NVIDIA官方CUDA 11.8基础镜像
FROM swr.cn-north-4.myhuaweicloud.com/ddn-k8s/docker.io/nvidia/cuda:11.8.0-devel-ubuntu22.04

# 设置环境变量
ENV PYTHON_VERSION=3.12.9
ENV PYTHONUNBUFFERED=1
ENV DEBIAN_FRONTEND=noninteractive

# 设置工作目录
WORKDIR /workspace

COPY requirements.txt sources.list SimHei.ttf vllm-0.8.5+cu118-cp38-abi3-manylinux1_x86_64.whl /workspace/

# run mv /workspace/SimHei.ttf /usr/share/fonts/
# run mv /workspace/sources.list /etc/apt/sources.list

# 安装系统依赖
RUN apt-get update && apt-get install -y \
    wget \
    curl \
    git \
	vim \
    build-essential \
    zlib1g-dev \
    libncurses5-dev \
    libgdbm-dev \
    libnss3-dev \
    libssl-dev \
    libreadline-dev \
    libffi-dev \
    libsqlite3-dev \
    libbz2-dev \
    liblzma-dev \
    pkg-config \
    cmake \
    && rm -rf /var/lib/apt/lists/*

# 下载并编译安装Python 3.12.9
RUN cd /tmp && \
    wget https://www.python.org/ftp/python/${PYTHON_VERSION}/Python-${PYTHON_VERSION}.tgz && \
    tar -xzf Python-${PYTHON_VERSION}.tgz && \
    cd Python-${PYTHON_VERSION} && \
    ./configure --enable-optimizations --enable-shared && \
    make -j$(nproc) && \
    make altinstall && \
    ldconfig && \
    cd /tmp && rm -rf Python-*

# 创建符号链接并安装pip
RUN ln -sf /usr/local/bin/python3.12 /usr/local/bin/python3 && \
    ln -sf /usr/local/bin/python3.12 /usr/local/bin/python && \
    curl -sS https://bootstrap.pypa.io/get-pip.py | python3.12

# 设置CUDA环境变量
ENV PATH=/usr/local/cuda/bin:$PATH
ENV LD_LIBRARY_PATH=/usr/local/cuda/lib64:$LD_LIBRARY_PATH
ENV CUDA_HOME=/usr/local/cuda

# 安装Python包
RUN pip config set global.index-url https://pypi.tuna.tsinghua.edu.cn/simple && \
    pip install --upgrade pip

# 安装PyTorch
RUN pip install torch==2.6.0 torchvision==0.21.0 torchaudio==2.6.0 --index-url https://download.pytorch.org/whl/cu118

# 安装vllm
RUN pip install vllm-0.8.5+cu118-cp38-abi3-manylinux1_x86_64.whl

# 安装其他依赖
RUN pip install -r requirements.txt

# 安装flash-attn（如果需要从特定版本安装）
RUN pip install flash-attn==2.7.3 --no-build-isolation

# 验证安装
RUN python -c "import transformers; print('transformers导入成功')"
# RUN python -c "import torch; print(f'PyTorch版本: {torch.__version__}'); print(f'CUDA可用: {torch.cuda.is_available()}'); print(f'CUDA版本: {torch.version.cuda}')" && \
#    python -c "import vllm; print('vllm安装成功')" && \
#    nvcc --version

# 设置默认命令
CMD ["/bin/bash"]

3.构建镜像

bash 复制代码

docker build -t deepseek-ocr-cuda11.8-pytorch2.6:v1.0 .

# 清理缓存与中间层镜像：有时为了确保获取最新的基础镜像或依赖，可能需要放弃缓存，从头开始构建。可以使用 --no-cache 参数
docker build --no-cache -t deepseek-ocr-cuda11.8-pytorch2.6:v1.0 .

# 后台运行长时间构建任务：如果构建过程需要很长时间，可以使用`nohup`命令让构建在后台运行，避免因会话断开导致构建中止
nohup docker build -t deepseek-ocr-cuda11.8-pytorch2.6:v1.0 . &

构建时间：编译Python和安装包可能需要较长时间
磁盘空间：镜像会比较大，建议确保有足够的磁盘空间
内存：构建过程中可能需要较多内存，特别是在编译flash-attn时

4.运行容器

bash 复制代码

# 运行容器
docker run -it --gpus all -v $(pwd):/workspace deepseek-ocr-cuda11.8-pytorch2.6:v1.0

5.验证环境

bash 复制代码

# 验证环境，在容器中运行以下命令验证安装
python -c "import torch; print(f'PyTorch: {torch.__version__}, CUDA: {torch.version.cuda}')"
python -c "import torch; print(f'GPU可用: {torch.cuda.is_available()}, GPU数量: {torch.cuda.device_count()}')"
python -c "import flash_attn; print('flash_attn安装成功')"
python -c "from flash_attn import flash_attention; print('CUDA内核可用')"
nvidia-smi

三、DeepSeek-OCR 配置解析

1.DeepSeek-OCR 配置文件解析

打开配置文件

bash 复制代码

vim DeepSeek-OCR-master/DeepSeek-OCR-vllm/config.py

1.1模型模式配置

配置文件顶部有不同模型模式的参数说明：

python 复制代码

# TODO: change modes
# Tiny: base_size = 512, image_size = 512, crop_mode = False
# Small: base_size = 640, image_size = 640, crop_mode = False
# Base: base_size = 1024, image_size = 1024, crop_mode = False
# Large: base_size = 1280, image_size = 1280, crop_mode = False
# Gundam: base_size = 1024, image_size = 640, crop_mode = True

这些注释表明项目提供了5种预定义的模型模式，每种模式对应不同的参数组合。您可以根据自己的需求选择合适的模式。

1.2核心图像处理参数

python 复制代码

BASE_SIZE = 1024
IMAGE_SIZE = 640
CROP_MODE = True

BASE_SIZE: 图像的基础大小，决定了处理的最大分辨率。当前设置为1024，适合处理中等尺寸的文档。
- 修改建议：根据您的GPU内存和文档复杂度调整。更高的值能处理更复杂的文档，但会增加内存占用。
IMAGE_SIZE: 模型实际处理的图像尺寸。当前设置为640。
- 修改建议：与BASE_SIZE配合使用，通常设置为小于或等于BASE_SIZE的值。
CROP_MODE: 是否启用图像裁剪模式。当前设置为True，表明使用了Gundam模式。
- 修改建议：对于复杂或大尺寸文档，建议保持True；对于简单文档或内存不足的情况，可设为False。

1.3裁剪相关参数

python 复制代码

MIN_CROPS = 2
MAX_CROPS = 6  # max:9; If your GPU memory is small, it is recommended to set it to 6.

MIN_CROPS: 最少裁剪数量，当前为2。
- 修改建议：通常不需要修改，除非您有特定需求。
MAX_CROPS: 最大裁剪数量，当前为6。最大可设置为9，但对于GPU内存较小的情况，建议保持为6。
- 修改建议：根据GPU内存大小调整。内存充足可增大到9，内存紧张则保持在6或更小。

1.4性能优化参数

python 复制代码

MAX_CONCURRENCY = 100  # If you have limited GPU memory, lower the concurrency count.
NUM_WORKERS = 64  # image pre-process (resize/padding) workers

MAX_CONCURRENCY: 最大并发处理数，当前为100。
- 修改建议：GPU内存有限时，应降低此值；内存充足可适当提高以加快处理速度。
NUM_WORKERS: 图像预处理（调整大小/填充）的工作线程数，当前为64。
- 修改建议：根据CPU核心数调整，通常设置为CPU核心数的1-2倍。

1.5功能开关

python 复制代码

PRINT_NUM_VIS_TOKENS = False
SKIP_REPEAT = True

PRINT_NUM_VIS_TOKENS: 是否打印可见token数量，当前为False。
- 修改建议：调试时可设为True，生产环境建议保持False。
SKIP_REPEAT: 是否跳过重复内容，当前为True。
- 修改建议：处理重复内容较多的文档时可保持True，否则可设为False。

1.6模型和路径设置

python 复制代码

MODEL_PATH = 'deepseek-ai/DeepSeek-OCR'  # change to your model path

# TODO: change INPUT_PATH
# .pdf: run_dpsk_ocr_pdf.py;
# .jpg, .png, .jpeg: run_dpsk_ocr_image.py;
# Omnidocbench images path: run_dpsk_ocr_eval_batch.py

INPUT_PATH = ''
OUTPUT_PATH = ''

MODEL_PATH: OCR模型路径，当前使用Hugging Face上的预训练模型'deepseek-ai/DeepSeek-OCR'。
- 修改建议：如需使用本地模型或其他版本，可更改为相应路径。
INPUT_PATH: 输入文件或目录路径，当前为空。
- 修改建议：根据处理的文件类型填写相应路径。PDF文件使用run_dpsk_ocr_pdf.py，图片文件使用run_dpsk_ocr_image.py，批量评估使用run_dpsk_ocr_eval_batch.py。
OUTPUT_PATH: 输出结果保存路径，当前为空。
- 修改建议：设置为您希望保存OCR结果的目录路径。

1.7.提示词设置

python 复制代码

PROMPT = '<image>\n<|grounding|>Convert the document to markdown.'
# PROMPT = '<image>\nFree OCR.'
# TODO commonly used prompts
# document: <image>\n<|grounding|>Convert the document to markdown.
# other image: <image>\n<|grounding|>OCR this image.
# without layouts: <image>\nFree OCR.
# figures in document: <image>\nParse the figure.
# general: <image>\nDescribe this image in detail.
# rec: <image>\nLocate <|ref|>xxxx<|/ref|> in the image.

PROMPT : 模型提示词，当前设置为将文档转换为markdown格式。修改建议：根据需求选择合适的提示词。注释中提供了多种常见场景的提示词：
- 文档转换为markdown：<image>\n<|grounding|>Convert the document to markdown.
- 普通图像OCR：<image>\n<|grounding|>OCR this image.
- 无布局OCR：<image>\nFree OCR.
- 图表解析：<image>\nParse the figure.
- 图像详细描述：<image>\nDescribe this image in detail.
- 特定内容定位：<image>\nLocate <|ref|>xxxx<|/ref|> in the image.

1.8Tokenizer配置

python 复制代码

from transformers import AutoTokenizer

TOKENIZER = AutoTokenizer.from_pretrained(MODEL_PATH, trust_remote_code=True)

TOKENIZER : 用于文本处理的tokenizer，从MODEL_PATH加载，并启用了trust_remote_code以支持自定义代码。
- 修改建议：通常不需要修改，除非您使用了自定义tokenizer。

1.9修改建议总结

根据GPU内存调整:
- 内存有限：降低MAX_CROPS（建议6）、MAX_CONCURRENCY
- 内存充足：增加MAX_CROPS（最高9）、MAX_CONCURRENCY
根据文档类型选择模式:
- 简单文档：可以使用Tiny或Small模式
- 复杂文档：推荐使用Gundam模式（当前设置）或Large模式
根据需求设置提示词:
- 注重布局：使用带<|grounding|>的提示词
- 简单识别：使用Free OCR提示词
路径设置:
- 必须修改INPUT_PATH为实际文件路径
- 建议设置OUTPUT_PATH以便保存结果

2.DeepSeek-OCR 支持模式详解

2.1支持模式概览

DeepSeek-OCR 开源模型支持两大类分辨率处理模式：原生分辨率模式 （Native resolution）和动态分辨率模式（Dynamic resolution）。
原生分辨率模式 (Native resolution)，原生分辨率模式下，模型直接处理固定尺寸的图像，不需要裁剪。包括四种配置：

模式	分辨率	视觉token数量	GPU内存需求	适用场景
Tiny	512×512	64	最低	简单文档、资源受限环境
Small	640×640	100	较低	中等复杂度文档
Base	1024×1024	256	中等	标准文档处理
Large	1280×1280	400	较高	复杂文档、高精度需求

动态分辨率模式 (Dynamic resolution)，动态分辨率模式下，模型结合了全局视图和局部细节，提供了更好的复杂文档处理能力：

模式	配置	特点	内存需求	适用场景
Gundam	n×640×640 + 1×1024×1024	全局+局部，智能裁剪	较高	大尺寸、多列、复杂布局文档

2.2各模式对应的配置参数设置

这些模式在 config.py 中通过三个关键参数进行设置：

python 复制代码

BASE_SIZE = 1024      # 基础尺寸
IMAGE_SIZE = 640      # 模型处理的图像尺寸
CROP_MODE = True      # 是否启用裁剪模式

Tiny 模式：

python 复制代码

BASE_SIZE = 512
IMAGE_SIZE = 512
CROP_MODE = False

Small 模式：

python 复制代码

BASE_SIZE = 640
IMAGE_SIZE = 640
CROP_MODE = False

Base 模式：

python 复制代码

BASE_SIZE = 1024
IMAGE_SIZE = 1024
CROP_MODE = False

Large 模式：

python 复制代码

BASE_SIZE = 1280
IMAGE_SIZE = 1280
CROP_MODE = False

Gundam 模式（当前默认配置）：
python 复制代码
```
BASE_SIZE = 1024
IMAGE_SIZE = 640
CROP_MODE = True
```

2.3视觉token数量与处理能力

不同模式使用的视觉token数量不同：

Tiny：64 tokens
Small：100 tokens
Base：256 tokens
Large：400 tokens

视觉token数量直接影响：

细节捕捉能力：token数量越多，能够捕捉的细节越丰富
GPU内存占用：token数量与内存占用大致成正比
处理速度：token数量越多，处理时间通常越长

2.4模式选择建议

根据文档复杂度选择：
- 简单文档（如纯文本、单列）：Tiny或Small模式
- 标准文档：Base模式
- 复杂文档（多列、图表混合）：Large或Gundam模式
- 超大文档（A3及以上、复杂布局）：推荐Gundam模式
根据硬件条件选择：
- GPU内存 < 8GB：建议使用Tiny或Small模式
- GPU内存 8-16GB：可使用Base模式
- GPU内存 > 16GB：可使用Large或Gundam模式
根据速度需求选择：
- 对速度要求高：选择token数量少的模式（Tiny→Small→Base）
- 对精度要求高：选择token数量多的模式或Gundam模式

2.5Gundam模式的工作原理

Gundam模式是DeepSeek-OCR的特色功能，其工作原理为：

首先以1024×1024分辨率获取全局视图，把握文档整体布局
然后智能裁剪出n个640×640的局部区域，聚焦于关键内容
最后综合全局和局部信息，生成完整OCR结果

这种设计使得Gundam模式能够在保持全局布局感知的同时，对重要局部区域进行高精度识别，特别适合处理具有复杂布局的大尺寸文档。

2.6修改配置示例

要切换到不同模式，只需修改 config.py 中的三个参数。例如，若要使用Base模式处理标准文档：

python 复制代码

# 修改前（Gundam模式）
BASE_SIZE = 1024
IMAGE_SIZE = 640
CROP_MODE = True

# 修改后（Base模式）
BASE_SIZE = 1024
IMAGE_SIZE = 1024
CROP_MODE = False

根据具体需求和硬件条件，选择最适合的模式可以在性能和准确性之间取得最佳平衡。

四、DeepSeek-OCR vLLM推理

1.工作目录设置

bash 复制代码

cd DeepSeek-OCR-master/DeepSeek-OCR-vllm

2.图像流式输出

bash 复制代码

python run_dpsk_ocr_image.py

功能说明：

用于处理单张或多张图像文件（支持 jpg、png、jpeg 等格式）
采用流式输出方式，实时显示 OCR 识别结果
适合交互式使用场景和单图像处理

使用步骤：

首先修改 config.py 中的 INPUT_PATH 指向您的图像文件或包含图像的目录
设置 OUTPUT_PATH 为结果保存位置
选择合适的模型模式和参数
执行上述命令

输出特点：结果将实时显示在控制台，并保存到指定的输出路径。

3.PDF 并发处理

bash 复制代码

python run_dpsk_ocr_pdf.py

功能说明：

专门用于处理 PDF 文件的 OCR 识别
支持并发处理，提高处理效率
在 A100-40G GPU 上可达到约 2500 tokens/s 的处理速度

使用步骤：

修改 config.py 中的 INPUT_PATH 指向您的 PDF 文件或包含 PDF 的目录
根据您的 GPU 内存调整 MAX_CONCURRENCY 参数
对于内存较小的 GPU，建议降低并发数
执行上述命令

并发优化：

在高性能 GPU 上可以保持较高的 MAX_CONCURRENCY 值
在内存有限的情况下，降低此值以避免内存溢出

4.批量评估基准测试

bash 复制代码

python run_dpsk_ocr_eval_batch.py

功能说明：

主要用于在基准测试数据集上进行批量评估
适用于 Omnidocbench 等标准测试集
可以批量处理多个测试图像并生成评估报告

使用步骤：

修改 config.py 中的 INPUT_PATH 指向测试数据集的路径
确保测试数据集按照标准格式组织
执行命令进行批量评估

五、DeepSeek-OCR Transformers推理

python 复制代码

from transformers import AutoModel, AutoTokenizer
import torch
import os
os.environ["CUDA_VISIBLE_DEVICES"] = '0'
model_name = 'deepseek-ai/DeepSeek-OCR'

tokenizer = AutoTokenizer.from_pretrained(model_name, trust_remote_code=True)
model = AutoModel.from_pretrained(model_name, _attn_implementation='flash_attention_2', trust_remote_code=True, use_safetensors=True)
model = model.eval().cuda().to(torch.bfloat16)

# prompt = "<image>\nFree OCR. "
prompt = "<image>\n<|grounding|>Convert the document to markdown. "
image_file = 'your_image.jpg'
output_path = 'your/output/dir'

res = model.infer(tokenizer, prompt=prompt, image_file=image_file, output_path = output_path, base_size = 1024, image_size = 640, crop_mode=True, save_results = True, test_compress = True)

bash 复制代码

cd DeepSeek-OCR-master/DeepSeek-OCR-hf
python run_dpsk_ocr.py

使用 trust_remote_code=True 加载分词器，以执行模型中包含的自定义代码
加载模型时使用了多项优化：
- _attn_implementation='flash_attention_2' 用于更快的注意力计算
- use_safetensors=True 用于更安全的模型加载
配置模型用于推理：设置为 eval() 模式，移至GPU，并转换为bfloat16精度