DeepSeek-OCR-WEBUI实战解析｜从环境配置到网页端部署全流程

1. 章节概述与学习目标

随着文档数字化需求的不断增长，光学字符识别（OCR）技术在金融、教育、物流等领域的应用日益广泛。DeepSeek-OCR-WEBUI 是基于 DeepSeek 开源大模型构建的一套高性能 OCR 推理系统，支持图像与 PDF 文件的高精度文本提取，并通过 Web UI 提供直观易用的操作界面。

本文将围绕DeepSeek-OCR-WEBUI 镜像展开，详细介绍从环境准备、依赖安装、模型加载到 Web 服务部署的完整流程。文章定位为实践应用类教程指南，适合具备 Python 基础和 Linux 操作经验的开发者阅读。

读者学完本教程后将能够：

完成 DeepSeek-OCR 的本地环境搭建
成功运行图片与 PDF 的 OCR 识别任务
启动并访问基于 FastAPI 的 Web 用户界面
实现一键式文档上传与结构化结果导出

2. 环境准备与基础依赖安装

2.1 系统与硬件要求

DeepSeek-OCR-WEBUI 对计算资源有一定要求，推荐使用以下配置进行部署：

项目	推荐配置
GPU 显卡	NVIDIA RTX 4090D 或同等性能及以上
CUDA 版本	11.8（必须匹配 PyTorch 和 flash-attn）
显存容量	≥24GB
Python 版本	3.11（兼容性最佳）
操作系统	Ubuntu 20.04/22.04 LTS

注意：CUDA 版本必须为 11.8，否则在编译flash-attn时会出现 NVCC 编译错误。

2.2 创建虚拟环境

建议使用 Conda 管理 Python 虚拟环境以避免依赖冲突：

conda create -n deepseek-ocr python=3.11 -y conda activate deepseek-ocr

虽然官方文档提及可使用 Python 3.12.9，但实测中 Python 3.11 更稳定且兼容性更好。

2.3 安装核心依赖库

安装 PyTorch（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

安装 flash-attn（关键步骤）

由于flash-attn编译耗时极长（可能超过 30 分钟），建议直接下载预编译.whl包：

# 下载地址（需外网） https://github.com/Dao-AILab/flash-attention/releases/tag/v2.7.3

选择对应版本文件：

flash_attn-2.7.3+cu11torch2.6cxx11abiFALSE-cp311-cp311-linux_x86_64.whl

安装命令：

pip install flash_attn-2.7.3+cu11torch2.6cxx11abiFALSE-cp311-cp311-linux_x86_64.whl

若无法访问 GitHub，可通过国内镜像获取该文件。

2.4 安装 vLLM 推理框架

vLLM 是高效的大语言模型推理引擎，在本项目中用于加速 OCR 后处理阶段的语言理解能力。

下载 vLLM v0.8.5 的预编译包（CUDA 11.8）：

https://github.com/vllm-project/vllm/releases/tag/v0.8.5

目标文件名：

vllm-0.8.5+cu118-cp38-abi3-manylinux1_x86_64.whl

安装命令：

pip install vllm-0.8.5+cu118-cp38-abi3-manylinux1_x86_64.whl

2.5 克隆项目代码并安装其余依赖

git clone https://github.com/deepseek-ai/DeepSeek-OCR.git cd DeepSeek-OCR pip install -r requirements.txt

提示：安装过程中可能出现部分包缺失或报错（如modelscope相关警告），但不影响整体功能运行，可忽略。

3. 模型下载与配置修改

3.1 使用 ModelScope 下载模型权重

DeepSeek-OCR 模型托管于 ModelScope 平台，需先安装客户端工具：

pip install modelscope

然后执行模型拉取命令：

modelscope download --model deepseek-ai/DeepSeek-OCR --local_dir ./models

该命令会自动下载 OCR 主干网络及多语言识别头，存储至本地./models目录。

3.2 修改配置文件 config.py

进入项目主目录下的DeepSeek-OCR-vll子目录：

cd DeepSeek-OCR-master/DeepSeek-OCR-vll

编辑config.py文件，确保以下关键参数正确设置：

# config.py 示例片段 MODEL_PATH = "./models" # 指向上一步下载的模型路径 DEVICE = "cuda" # 使用 GPU 加速 USE_VLLM = True # 启用 vLLM 进行后处理 MAX_IMAGE_SIZE = 2048 # 最大输入图像边长 LANGUAGES = ["zh", "en"] # 支持中英文混合识别

根据实际部署路径调整MODEL_PATH。

4. 图像与 PDF 文档 OCR 实践

4.1 图像 OCR 识别流程

修改 run_dpsk_ocr_image.py

打开脚本文件run_dpsk_ocr_image.py，确认输入输出路径配置：

input_image_path = "test_images/example.jpg" output_json_path = "output/result.json" output_md_path = "output/result.md"

支持常见格式：JPG、PNG、BMP、TIFF 等。

执行图像识别

python run_dpsk_ocr_image.py

程序将依次完成：

文本区域检测（Text Detection）
单行文本识别（Text Recognition）
结构化信息组织（Markdown 输出）
可视化标注图生成

输出结果包含 JSON 结构数据和 Markdown 格式文本。

4.2 PDF 文档 OCR 处理

PDF 文件需先转换为图像序列再进行识别。

修改 run_dpsk_ocr_pdf.py

设置输入输出路径：

input_pdf_path = "documents/sample.pdf" output_dir = "output/pdf_results" dpi = 200 # 渲染精度，影响识别质量

提高 DPI 可提升小字号文字识别准确率，但增加计算开销。

执行 PDF 识别

python run_dpsk_ocr_pdf.py

处理流程包括：

PDF 页面转图像（使用pdf2image）
逐页调用 OCR 引擎
合并所有页面结果为统一 Markdown 文件
保留原始排版结构（标题、段落、列表）

5. Web UI 部署与交互式使用

5.1 启动 FastAPI Web 服务

项目内置基于 FastAPI 的 Web 接口服务，启动命令如下：

cd webui python app.py --host 0.0.0.0 --port 8080

默认监听端口为8080，可通过浏览器访问：

http://<your-server-ip>:8080

5.2 Web 界面功能说明

页面主要组件包括：

文件上传区（支持拖拽）
识别模式选择（图片 / PDF）
多语言选项（中文优先、英文辅助）
“开始识别”按钮
进度条与状态提示
结果展示区（Markdown 预览）
下载按钮（JSON / MD / TXT）

识别完成后，用户可点击“下载”获取结构化文本结果。

5.3 自定义端口与跨域配置

如需更改端口或启用 CORS（便于前端集成），可在app.py中修改：

import uvicorn from fastapi import FastAPI from fastapi.middleware.cors import CORSMiddleware app = FastAPI() app.add_middleware( CORSMiddleware, allow_origins=["*"], allow_methods=["POST", "GET"], allow_headers=["*"], ) if __name__ == "__main__": uvicorn.run(app, host="0.0.0.0", port=8080)

6. 常见问题与优化建议

6.1 常见问题排查

问题现象	原因分析	解决方案
flash-attn 编译超时	源码编译依赖复杂	使用预编译`.whl`包
vLLM 安装失败	CUDA 版本不匹配	确保使用`+cu118`版本
模型加载报错	路径错误或权限不足	检查`MODEL_PATH`是否绝对路径
Web 页面无法访问	防火墙限制	开放对应端口（如 8080）
PDF 识别乱码	字体嵌入缺失	提高渲染 DPI 至 300