DeepSeek-OCR-WebUI 部署指南：支持 7 种识别模式与 GPU 加速

作者使用的是 transformers 而非 vLLM, 理由是：

作者结论：transformers 引擎更稳定，兼容性更好，非常适合生产环境。

2. 环境准备与下载代码

操作系统环境为 ubuntu-24.04.3 Server

2.1 安装 Docker

# 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}

2.2 下载代码

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

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

2.3 环境检查

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

2.4 VS Code 连接项目代码

下载到的源代码需要修改一下，我们用 vs code 进行连接。

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

添加这段代码:

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/

3. 安装 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" 的设备驱动，从而报错。

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

# 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 官方驱动 安装请参考 我前面的文章：《DeepSeek-OCR 实战 (01)：基础运行环境搭建-Ubuntu》

• 查看是否安装成功

nvidia-ctk --version
NVIDIA Container Toolkit CLI version 1.18.0
commit: f8daa5e26de9fd7eb79259040b6dd5a52060048c

• 设置 docker 默认使用 nvidia-runtime

# 这个命令实际上是把配置写到 daemon.json 文件中
sudo nvidia-ctk runtime configure --runtime=docker
sudo cat /etc/docker/daemon.json
{
  ...
  "runtimes": {
    "nvidia": {
      "args": [],
      "path": "nvidia-container-runtime"
    }
  }
}

• 重启 docker

sudo systemctl restart docker

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

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

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

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

4. 启动服务

cd ~/DeepSeek-OCR-WebUI
# 此时会按照 docker-comoose.yml 中的配置 构建镜像
docker compose up -d
# 下面命令只显示了 NAME, STATUS , PORTS 字段
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 日志
docker logs -f deepseek-ocr-webui

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

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

4.1 GPU 监控

# 实时监控 GPU 使用
watch -n 1 nvidia-smi
# 查看当前 GPU 使用
nvidia-smi

4.2 容器管理

# 重启服务（代码已更新后）
docker restart deepseek-ocr-webui
# 完全重启（重新加载模型）
docker compose restart
# 停止服务
docker compose down
# 重新构建并启动
docker compose up -d --build
# 查看资源使用
docker stats deepseek-ocr-webui

5. 访问 UI 页面

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

5.1 通用 OCR 测试

选中通用 OCR，然后上传一张图片。

识别结果：

============================================================
图片 1: fCOdj4aJI.png
============================================================
慢慢来，你又不差你所有的压力，都是因为你太想要了，你所有的痛苦，都是因为你太较真了。有些事，不能尽你心意，就是在提醒了该转变了。如果事事都如意，那就不叫生活了，所以睡前原谅一切，醒来不问过证，珍惜所有的不期而遇，看游所有的不详而别。人生一站有一站的风景，一岁有一岁的味道，你的年龄应该成为你生命的勋章，而不是你伤感的理由。生活嘛，慢慢来，你又不差。

5.2 图像描述测试

选中'图像描述'，上传一张从互联网上找到的图片：

识别结果，目前输出的是英文 (中文是我翻译过来的文字)：

An outdoor winter scene where snow is falling gently against a clear blue sky backdrop. In the foreground stands a young woman dressed warmly for cold weather; she wears a black coat adorned with white polka dots on her sleeves and gloves that match her coat's color scheme. Her long brown hair cascades down past her shoulders as she smiles broadly at the camera while extending both arms outward to catch or play with the swirling snowflakes around her hands. Behind her are several houses covered lightly by fresh snow, indicating recent snowfall. The closest house has light-colored siding and dark roofing, partially obscured behind utility poles running vertically across the frame from left to right. A fence made up of wooden posts connected by wire stretches horizontally nearer to the bottom edge of the photo, separating what appears to be someone's yard from another area beyond it. Power lines crisscross above everything else, adding depth to the composition through perspective lines leading towards distant structures barely visible due to the focus being primarily on the central figure amidst the serene wintry setting.
一幅冬日户外场景：雪花轻柔飘落，背景是清澈的蓝天。前景中站着一位年轻女子，她穿着保暖的冬装——一件黑色外套，袖子上点缀着白色波点；她的手套也与外套的配色相呼应。她留着长长的棕色秀发，披散至肩下，正对着镜头灿烂微笑，同时张开双臂，仿佛要接住或嬉戏于围绕双手飞舞的雪花之中。她身后是几栋覆盖着薄薄新雪的房屋，表明刚刚下过雪。最近处的房子外墙为浅色，屋顶为深色，部分被从画面左侧延伸至右侧的电线杆遮挡。靠近照片底部边缘处，一道由木桩和铁丝组成的围栏横向延伸，将一处庭院与远处区域分隔开来。上方纵横交错的电线进一步增强了画面的纵深感，其透视线条引向远方隐约可见的建筑，而整个画面的焦点则集中在雪景中这位神情愉悦的中心人物身上，营造出宁静祥和的冬日氛围。

5.3 定位查找