Docker 部署 DeepSeek-OCR 和WebUI

1 核心亮点

DeepSeek-OCR-WebUI介绍

• 🎯 7 种识别模式 - 文档、OCR、图表、查找、自定义等

• 🖼️ 边界框可视化 - Find 模式自动标注位置

• 📦 批量处理 - 支持多张图片逐一识别

• 📄 PDF 支持 - 上传 PDF 文件，自动转换为图片

• 🎨 现代化 UI - 炫酷的渐变背景和动画效果

• 🌐 多语言支持 - 简体中文、繁体中文、英语、日语

• 🍎 Apple Silicon 支持 - Mac M1/M2/M3/M4 原生 MPS 加速

• 🐳 Docker 部署 - 一键启动，开箱即用

• ⚡ GPU 加速 - 基于 NVIDIA GPU 的高性能推理

• 🌏 ModelScope 自动切换 - HuggingFace 不可用时自动切换

2 功能特性

7 种识别模式

模式	图标	说明	适用场景
文档转Markdown	📄	保留格式和布局	合同、论文、报告
通用OCR	📝	提取所有可见文字	图片文字提取
纯文本提取	📋	纯文本不保留格式	简单文本识别
图表解析	📊	识别图表和公式	数据图表、数学公式
图像描述	🖼️	生成详细描述	图片理解、无障碍
查找定位 ⭐	🔍	查找并标注位置	发票字段定位
自定义提示 ⭐	✨	自定义识别需求	灵活的识别任务

PDF 支持（v3.2 新功能）

DeepSeek-OCR-WebUI 现已支持 PDF 文件上传！上传 PDF 文件后，系统会自动将每一页转换为独立的图片，并保持后续的所有处理逻辑（OCR识别、批量处理等）。
技术架构

• 引擎: transformers（稳定可靠）

• 模型: deepseek-ai/DeepSeek-OCR

• GPU: NVIDIA L40S (自动检测)

• 推理模式: bfloat16

• 批处理: 逐一顺序处理

操作系统环境为环境为 ubuntu-24.04.4 Server 安装docker 自行处理

bash 复制代码

# 1. 更新软件包索引：
sudo apt-get update

# 2. 安装必要的软件包，以允许apt通过HTTPS使用仓库：
sudo apt-get install apt-transport-https ca-certificates curl software-properties-common

# 3. 添加Docker的官方GPG密钥：
curl -fsSL https://download.docker.com/linux/ubuntu/gpg | sudo apt-key add -

# 4. 添加Docker的稳定仓库
sudo add-apt-repository "deb [arch=amd64] https://download.docker.com/linux/ubuntu $(lsb_release -cs) stable"

# 5. 再次更新软件包索引
sudo apt-get update

# 6. 安装最新版本的Docker CE（社区版）
sudo apt-get install docker-ce

# 7. 验证Docker是否安装成功并运行：
sudo systemctl status docker
# 查看docker版本
sudo docker --version

# 8. 非root用户也能运行Docker
# *********这句代码执行后，请重新登录SSH 连接*********
sudo usermod -aG docker ${USER}

# 9. 镜像配置 下载的docker镜像将会被存放到 /data/docker 目录中
sudo tee /etc/docker/daemon.json <<-'EOF'
{
  "data-root": "/data/docker",
  "exec-opts":["native.cgroupdriver=systemd"],
  "log-driver":"json-file",
  "log-opts": {"max-size":"100m", "max-file":"3"}  
}
EOF

sudo systemctl daemon-reload 
sudo systemctl restart docker
sudo systemctl enable docker

源代码中已经为我们编写好了docker-compose.yml文件

bash 复制代码

git clone https://github.com/neosun100/DeepSeek-OCR-WebUI.git
cd DeepSeek-OCR-WebUI

该项目要求GPU驱动版本必须大于等于580.82

bash 复制代码

nvidia-smi

项目提供了 Dockerfile, 这样我们可以在本地服务器上构建docker 镜像，但是在构建docker镜像之前，我们需要修改一下Dockerfile,添加一些依赖和 pip 国内镜像加速

bash 复制代码

加这段代码:

RUN  apt-get update && apt-get install -y \
    libgl1 \
    libglib2.0-0 \
    pkg-config \
    python3-dev \
    build-essential \
    && rm -rf /var/lib/apt/lists/*
    
# 添加pip国内镜像加速
RUN pip config set global.index-url https://mirrors.huaweicloud.com/repository/pypi/simple/

安装 NVIDIA Container Toolkit[重要]

Docker 默认不支持直接访问 GPU。要让容器使用 NVIDIA GPU，必须安装并配置 NVIDIA Container Toolkit（以前叫 nvidia-docker2）。

如果没有正确安装或配置，当你在 docker run 命令中使用 --gpus all 或在 docker-compose.yml 中指定 deploy.resources.reservations.devices 等 GPU 相关选项时，Docker 就无法找到名为 "nvidia" 的设备驱动，从而报错。

bash 复制代码

官方文档： https://docs.nvidia.com/datacenter/cloud-native/container-toolkit/latest/install-guide.html#installing-with-apt

bash 复制代码

# 1：确认已安装 NVIDIA 驱动
# 如果命令成功输出 GPU 信息（驱动版本、GPU 型号等），说明驱动已装好。
# 如果提示命令未找到或驱动未加载，请先安装 NVIDIA 官方驱动。
nvidia-smi

# 2.安装 NVIDIA Container Toolkit
# 安装依赖工具
sudo apt-get update && sudo apt-get install -y --no-install-recommends curl gnupg2

# 添加 NVIDIA Container Toolkit 的 GPG 密钥和软件源
# 从 NVIDIA 官方地址下载 GPG 公钥, 下载 NVIDIA 提供的 APT 源列表文件
curl -fsSL https://nvidia.github.io/libnvidia-container/gpgkey | sudo gpg --dearmor -o /usr/share/keyrings/nvidia-container-toolkit-keyring.gpg \
  && curl -s -L https://nvidia.github.io/libnvidia-container/stable/deb/nvidia-container-toolkit.list | \
    sed 's#deb https://#deb [signed-by=/usr/share/keyrings/nvidia-container-toolkit-keyring.gpg] https://#g' | \
    sudo tee /etc/apt/sources.list.d/nvidia-container-toolkit.list
# 启用 experimental 软件源（可选）
sudo sed -i -e '/experimental/ s/^#//g' /etc/apt/sources.list.d/nvidia-container-toolkit.list

sudo apt-get update

# 设置环境变量 NVIDIA_CONTAINER_TOOLKIT_VERSION=1.18.0-1（方便统一指定版本）。
# libnvidia-container1：底层库，用于在容器内设置 NVIDIA 驱动环境。
# libnvidia-container-tools：配套工具（如 nvidia-container-cli）。
# nvidia-container-toolkit-base：基础运行时钩子（hook）配置。
# nvidia-container-toolkit：集成到 Docker 的 CLI 工具，提供 --gpus 支持。
export NVIDIA_CONTAINER_TOOLKIT_VERSION=1.18.0-1
  sudo apt-get install -y \
      nvidia-container-toolkit=${NVIDIA_CONTAINER_TOOLKIT_VERSION} \
      nvidia-container-toolkit-base=${NVIDIA_CONTAINER_TOOLKIT_VERSION} \
      libnvidia-container-tools=${NVIDIA_CONTAINER_TOOLKIT_VERSION} \
      libnvidia-container1=${NVIDIA_CONTAINER_TOOLKIT_VERSION}

NVIDIA 官方驱动安装请参考

bash 复制代码

检查是否存在开源驱动nouveau
lsmod | grep nouveau
有输出说明存在。 开源驱动会与NVIDA 驱动冲突。我的是有输出的

如果存在，则需要关闭 nouveau 驱动

bash 复制代码

sudo tee /etc/modprobe.d/blacklist-nouveau.conf <<EOF
blacklist nouveau
options nouveau modeset=0
EOF
# 更新initramfs
sudo update-initramfs -u
# 重启
sudo reboot 

# 重启后确认,如果没有输出则表示已经关闭了
sudo lsmod | grep nouveau

驱动下载

bash 复制代码

https://www.nvidia.cn/drivers/lookup/

将下载的文件存放到 /data/soft目录备用

bash 复制代码

cd /data/soft
# 添加可执行权限
 chmod +x NVIDIA-Linux-x86_64-580.105.08.run
# 执行安装
 sudo ./NVIDIA-Linux-x86_64-580.105.08.run

安装的时候，会让你选择许可证，我们直接选择 NVIDIA Proprietary即可

选项	许可证	特点	推荐选择
NVIDIA Proprietary	专有许可证	• 传统的NVIDIA专有驱动 • 经过长期测试，稳定性高 • 与各种NVIDIA功能完全兼容	大多数用户
MIT/GPL	开源许可证	• 较新的开源内核模块 • 更好的内核兼容性 • 遵循开源协议	特定场景用户
如果操作系统安装的是字符界面，则会出现一个警告:

WARNING: nvidia-installer was forced to guess the X library path '/usr/lib64' and X module path '/usr/lib64/xorg/modules';

这个警告信息表明NVIDIA安装程序无法自动检测到X Window系统的开发文件位置,解决这个警告你需要安装X.Org的开发包和pkg-config工具，

这个警告不会影响CUDA计算功能，只会影响图形显示，如果你只在字符界面使用Rocky Linux进行计算任务，可以暂时忽略这个警告

若输出显示显卡信息、驱动版本，则安装成功

bash 复制代码

nvidia-smi

CUDA Version: 13.0 表示支持的 cuda 版本最高到 13.0 版本

3.安装CUDA

bash 复制代码

UDA 是 Compute Unified Device Architecture 的缩写，是NVIDIA推出的并行计算平台和编程模型。

**本质：**让GPU不仅能处理图形，还能进行通用计算的平台

**作用：**允许开发者使用C/C++等语言直接在GPU上编写程序

**应用领域：**AI/深度学习、科学计算、数据分析、图形渲染等

前提条件，需要先安装 NVIDIA 驱动

nvidia-smi  # 有输出，则确认驱动正常工作

bash 复制代码

RTX 2080 Ti 的最优 CUDA 版本为 11.7 或 11.8，我们选择 11.8 版本下载，
下载地址：https://developer.nvidia.com/cuda-toolkit-archive ，
找到对应的版本，选择合适的环境下载。下载后，文件存放到 /data/soft
wget https://developer.download.nvidia.com/compute/cuda/11.8.0/local_installers/cuda_11.8.0_520.61.05_linux.run
sudo sh cuda_11.8.0_520.61.05_linux.run

安装的时候，会出现错误：unsupported compiler version: 14.2.1. Use --override to override this check. 此时使用下面命令跳过检查。原因是当前系统版本的gcc版本过高，cuda_11.8.0 不识别这个gcc版本。生产环境可以降低 gcc版本，比如gcc 10 版本。因为现在是测试，直接跳过检查

bash 复制代码

sudo sh cuda_11.8.0_520.61.05_linux.run --override

因为驱动已经安装了，所以这里需要将 "Driver" 选项去掉

安装完毕后，Toolkit 被安装在了 /usr/local/cuda-11.8, 同时有个链接文件 /usr/local/cuda指向了这个目录

环境变量配置

bash 复制代码

# 编辑bash配置文件
sudo vim ~/.bashrc

# 添加以下内容
export PATH=/usr/local/cuda/bin${PATH:+:${PATH}}
export LD_LIBRARY_PATH=/usr/local/cuda/lib64${LD_LIBRARY_PATH:+:${LD_LIBRARY_PATH}}
export CUDA_HOME=/usr/local/cuda

# 使配置生效
 source ~/.bashrc

查看是否安装成功

bash 复制代码

nvcc --version
nvcc: NVIDIA (R) Cuda compiler driver
Copyright (c) 2005-2022 NVIDIA Corporation
Built on Wed_Sep_21_10:33:58_PDT_2022
Cuda compilation tools, release 11.8, V11.8.89
Build cuda_11.8.r11.8/compiler.31833905_0

# 检查CUDA工具包版本
nvidia-smi  # 查看右上角的CUDA Version
nvidia-ctk --version
NVIDIA Container Toolkit CLI version 1.18.0
commit: f8daa5e26de9fd7eb79259040b6dd5a52060048c

nvidia-smi 显示的CUDA版本是驱动程序支持的最高 CUDA版本，不是实际安装的CUDA版本，使用 nvcc --version显示的才是实际安装的版本。
安装Conda

Conda 是一个开源的包管理和环境管理系统，最初由 Anaconda 公司开发，主要用于 Python 及其他语言（如 R、Ruby、Lua、Perl、Haskell、C/C++）的包管理和环境管理。它可以安装、更新、卸载软件包，并创建隔离的虚拟环境，使得不同项目之间的依赖不会相互干扰。

bash 复制代码

# 下载安装脚本
wget https://repo.anaconda.com/miniconda/Miniconda3-latest-Linux-x86_64.sh

 # 执行安装
sh Miniconda3-latest-Linux-x86_64.sh

# 手动激活 base环境
eval "$(/data/miniconda3/bin/conda shell.bash hook)"

# 接收许可
conda tos accept --override-channels --channel https://repo.anaconda.com/pkgs/main
conda tos accept --override-channels --channel https://repo.anaconda.com/pkgs/r

# 查看源
conda config --show-sources
==> /data/miniconda3/.condarc <==
channels:
  - defaults

conda config --set show_channel_urls yes

conda config --show channels

 # 自动激活base环境
conda config --set auto_activate_base true

设置docker默认使用nvidia-runtime

这个命令实际上是把配置写到 daemon.json文件中

bash 复制代码

sudo nvidia-ctk runtime configure --runtime=docker

sudo cat /etc/docker/daemon.json
{
   # 增加以下内容
    "runtimes": {
        "nvidia": {
            "args": [],
            "path": "nvidia-container-runtime"
        }
    }
}

• 重启docker

bash 复制代码

sudo systemctl restart docker

• 测试容器内是否可以使用GPU

bash 复制代码

docker run --rm --gpus all nvidia/cuda:13.0.1-runtime-ubuntu22.04 nvidia-smi

bash 复制代码

要用NVIDIA官方发布的镜像进行测试，因为内置了 **nvidia-smi** 工具

输出类似以下内容（显示 GPU 型号、驱动版本、CUDA 版本）：说明配置正确

启动服务

bash 复制代码

cd  DeepSeek-OCR-WebUI

此时会按照docker-comoose.yml 中的配置构建镜像

bash 复制代码

docker compose up -d

下面命令只显示了 NAME, STATUS , PORTS 字段

bash 复制代码

docker compose ps --format "table {{.Name}}\t{{.Status}}\t{{.Ports}}"
NAME                 STATUS                            PORTS
deepseek-ocr-webui   Up 2 minutes (health: starting)   6006/tcp, 8888/tcp, 0.0.0.0:8001->8001/tcp

查看docker日志

bash 复制代码

docker logs -f deepseek-ocr-webui

首次启动会很久，因为要下载各种依赖。服务启动的时候，会到 HUGGINGFACE 和 ModelScope 去加载模型。如果没有科学上网，可能 HUGGINGFACE 的模型无法加载到。

所以首次启动，要等待模型下载完毕。模型文件被下载到了**~/DeepSeek-OCR-WebUI/models/**** 文件夹中**

GPU监控

bash 复制代码

# 实时监控 GPU 使用
watch -n 1 nvidia-smi

# 查看当前 GPU 使用
nvidia-smi

重启服务（代码已更新后）

bash 复制代码

docker restart deepseek-ocr-webui

完全重启（重新加载模型）

bash 复制代码

docker compose restart

停止服务

bash 复制代码

docker compose down

重新构建并启动

bash 复制代码

docker compose up -d --build

查看资源使用

bash 复制代码

docker stats deepseek-ocr-webui

访问UI页面

UI界面: http://172.16.17.113:8001/
API文档: http://172.16.17.113:8001/docs
健康检查: http://172.16.17.113:8001/health

下载源码：

bash 复制代码

# 切换到用户目录
cd ~
# 克隆项目源码
git clone https://github.com/deepseek-ai/DeepSeek-OCR.git
cd ~/DeepSeek-OCR

安装依赖：

bash 复制代码

首先下载 vllm-0.8.5,
下载地址：https://github.com/vllm-project/vllm/releases/download/v0.8.5/vllm-0.8.5+cu118-cp38-abi3-manylinux1_x86_64.whl
下载后存放到 /data/soft目录中备用

bash 复制代码

# 1. 查看当前已经安装的环境，默认情况下，Conda会有一个base环境，即根环境
# 上一章已经创建了 DeepSeek-OCR环境，如果你没有可以创建
(base) conda env list

# 2. 创建 Conda 环境。 如果已有，测跳过
(base) conda create -n DeepSeek-OCR python=3.12 

# 3. 激活环境
(base) conda activate DeepSeek-OCR

# 4.添加国内加速
(DeepSeek-OCR) pip config set global.index-url https://mirrors.huaweicloud.com/repository/pypi/simple/

# 5. 安装 vllm , 确保文件vllm-0.8.5+cu118-cp38-abi3-manylinux1_x86_64.whl已经在 ~/soft目录中
cd ~/soft
pip install vllm-0.8.5+cu118-cp38-abi3-manylinux1_x86_64.whl

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


# 7. 安装项目依赖
cd ~/DeepSeek-OCR
pip install -r requirements.txt

# 安装加速组件（可选但推荐），因为我的显卡是 2080Ti，不支持flash-attn，所以就不再安装它
# pip install flash-attn==2.7.3 --no-build-isolation
安装过程中如果出现一下错误，这个错误可以忽略，不影响代码运行

• DeepSeek-OCR-master 主要代码目录

• assets资源文件

• requirements.txt依赖包列表

• README.md项目说明文档

DeepSeek-OCR-hf 与DeepSeek-OCR-vllm

DeepSeek-OCR-master目录下还有两个目录DeepSeek-OCR-hf与 DeepSeek-OCR-vllm

模型版本对比

对比维度	DeepSeek-OCR-hf (基于 Hugging Face Transformers)	DeepSeek-OCR-vllm (基于 vLLM)
核心框架	🤗 Hugging Face Transformers	⚡ vLLM (专为LLM服务优化的推理引擎)
主要目标	研究、实验与原型开发	高吞吐、低延迟的生产环境部署
性能特点	灵活性高，便于调试和实验	推理速度更快，尤其擅长批量处理，能显著提高吞吐量
适用场景	适合模型测试、微调 (fine-tuning) 和功能验证	适合API服务、云端部署及需要处理大量文档的企业级应用
使用便捷性	通常更贴近研究人员和开发者的实验习惯，易于上手	需要一些服务化的部署知识，但能提供更稳定、高效的服务
技术关联	利用 Transformers 库的通用接口加载和使用模型	与 vLLM 推理栈深度集成，优化计算资源使用

安装 modelscope依赖

bash 复制代码

pip install modelscope

创建模型存放目录

bash 复制代码

mkdir -p ~/models/modelscope/deepseek-ai/DeepSeek-OCR-Vllm

bash 复制代码

打开的项目中创建python文件download.py, 其完整路径为 /data/DeepSeek-OCR/DeepSeek-OCR-master/DeepSeek-OCR-vllm/download.py

bash 复制代码

# /data/DeepSeek-OCR/DeepSeek-OCR-master/DeepSeek-OCR-vllm/download.py
# 模型下载
from modelscope import snapshot_download

# 指定下载存放的路径 
model_dir = snapshot_download('deepseek-ai/DeepSeek-OCR',cache_dir='/data/models/modelscope/deepseek-ai/DeepSeek-OCR-Vllm')

执行命令行：

bash 复制代码

python download.py

注意，下载后模型完整路径是：

/data/models/modelscope/deepseek-ai/DeepSeek-OCR-Vllm/deepseek-ai/DeepSeek-OCR/,

因为下载的时候指定了 cache_dir为 /data/models/modelscope/deepseek-ai/DeepSeek-OCR-Vllm

修改模型路径

配置文件：/data/DeepSeek-OCR/DeepSeek-OCR-master/DeepSeek-OCR-vllm/config.py, 主要修改 MODEL_PATH指定为：/data/models/modelscope/deepseek-ai/DeepSeek-OCR-Vllm/deepseek-ai/DeepSeek-OCR/# /data/DeepSeek-OCR/DeepSeek-OCR-master/DeepSeek-OCR-vllm/config.py

注意必须是模型完整路径，这个路径下会有一个模型配置文件 config.json

MODEL_PATH = '/data/models/modelscope/deepseek-ai/DeepSeek-OCR-Vllm/deepseek-ai/DeepSeek-OCR/'
到这里就完成安装和编译了就可以使用啦

Docker 部署 DeepSeek-OCR 和WebUI

相关链接

1 核心亮点

2 功能特性

7 种识别模式

操作系统环境为环境为 ubuntu-24.04.4 Server 安装docker 自行处理

若输出显示显卡信息、驱动版本，则安装成功

这个命令实际上是把配置写到 daemon.json文件中

启动服务

此时会按照docker-comoose.yml 中的配置 构建镜像

下面命令只显示了 NAME, STATUS , PORTS 字段

查看docker日志

GPU监控

重启服务（代码已更新后）

完全重启（重新加载模型）

停止服务

重新构建并启动

查看资源使用

访问UI页面

下载源码：

DeepSeek-OCR-hf 与DeepSeek-OCR-vllm

模型版本对比

安装 modelscope依赖

创建模型存放目录

修改模型路径

注意必须是模型完整路径，这个路径下会有一个模型配置文件 config.json

此时会按照docker-comoose.yml 中的配置构建镜像