DeepSeek-OCR-WebUI 可视化 OCR 工作台部署与使用指南

DeepSeek-OCR-WebUI 的核心价值很直接：把 DeepSeek-OCR 这类 OCR（Optical Character Recognition，光学字符识别）模型包装成一个浏览器界面，让用户不用写推理代码，也能上传图片、识别文字、查看结果、复制 Markdown 或导出结构化内容。

传统 OCR 工具通常擅长“把图片里的字抠出来”，但面对复杂文档时会遇到几个麻烦：

• 截图里既有标题、正文，又有表格、公式、代码块；
• 扫描件存在倾斜、模糊、阴影、低分辨率等问题；
• PDF 页面需要先转图片，再逐页识别；
• 识别结果不只是纯文本，还要尽量保留段落、表格和版式结构；
• 非开发人员不想写 Python 脚本，只想拖拽上传并拿到结果。

DeepSeek-OCR-WebUI 解决的是“使用门槛”问题。模型负责识别，WebUI 负责交互、参数配置、结果展示和导出。

flowchart LR
    A[上传图片或PDF页面] --> B[图像预处理]
    B --> C[DeepSeek-OCR 推理]
    C --> D[文本与版式解析]
    D --> E[结果预览]
    E --> F[复制文本]
    E --> G[导出 Markdown / JSON / TXT]

它适合处理什么任务

DeepSeek-OCR-WebUI 更像一个文档识别工作台，而不只是简单的截图转文字工具。它适合下面这些场景：

不适合的场景也要说清楚：

WebUI 的整体结构

一个 OCR WebUI 通常分成四层：前端交互、文件处理、模型推理、结果整理。

flowchart TB
    subgraph UI[浏览器界面]
        U1[上传文件]
        U2[选择识别模式]
        U3[查看预览]
        U4[复制或下载结果]
    end

    subgraph Backend[后端服务]
        B1[接收文件]
        B2[图片格式转换]
        B3[PDF分页]
        B4[任务队列]
    end

    subgraph Model[OCR模型]
        M1[图像编码]
        M2[文本生成]
        M3[版式理解]
    end

    subgraph Output[结果层]
        O1[纯文本]
        O2[Markdown]
        O3[JSON]
        O4[日志与错误信息]
    end

    UI --> Backend
    Backend --> Model
    Model --> Output
    Output --> UI

这套结构的好处是职责比较清楚：

• 浏览器界面：负责上传、参数选择、预览和导出；
• 后端服务：负责保存临时文件、格式转换、调用模型；
• OCR 模型：负责从图像中识别文字和结构；
• 结果层：负责把模型输出整理成用户能直接使用的格式。

WebUI 本身并不替代模型能力。如果图片质量太差、内容过小、版面过于复杂，识别结果仍然可能出错。它提供的是更顺手的操作方式，以及更方便的人工校对入口。

一次识别请求是怎么跑完的

用户点击上传后，系统通常会经历这样的流程：

sequenceDiagram
    participant User as 用户
    participant Web as WebUI
    participant Pre as 预处理模块
    participant OCR as DeepSeek-OCR
    participant Out as 输出模块

    User->>Web: 上传图片或PDF
    Web->>Pre: 保存文件并检查格式
    Pre->>Pre: 转换图片、缩放、分页
    Pre->>OCR: 发送图像与识别参数
    OCR-->>Pre: 返回识别文本
    Pre->>Out: 整理为 Markdown / TXT / JSON
    Out-->>Web: 返回预览结果
    Web-->>User: 展示、复制、下载

这里有几个关键点。

1. 文件格式检查

WebUI 需要判断上传内容是图片还是 PDF。图片可以直接进入预处理，PDF 通常要先拆成页面图片。

常见输入格式包括：

2. 图像预处理

预处理不一定复杂，但很重要。常见动作包括：

• 统一图片格式，例如转成 RGB；
• 限制最大分辨率，避免显存占用过高；
• 对过小文字做适度放大；
• 对 PDF 页面逐页转图；
• 记录页面顺序，方便合并识别结果。

一个简化版预处理函数可以写成这样：

from PIL import Image

def load_image(path: str, max_side: int = 1600) -> Image.Image:
    image = Image.open(path).convert("RGB")

    width, height = image.size
    scale = max(width, height) / max_side

    if scale > 1:
        new_size = (int(width / scale), int(height / scale))
        image = image.resize(new_size)

    return image

这段代码只做了格式统一和尺寸限制。实际项目里还可能加入旋转纠正、去噪、增强对比度等处理，但预处理不是越多越好。过度锐化、过度二值化反而可能破坏模型需要的视觉信息。

3. 模型推理

DeepSeek-OCR 负责真正的识别。WebUI 通常会把图片和识别参数传给模型，再等待模型生成结果。

如果底层使用 Python 调用模型，伪代码大致是这样的：

def run_ocr(image, mode="markdown"):
    prompt_map = {
        "text": "识别图片中的文字，输出纯文本。",
        "markdown": "识别图片中的内容，尽量保留标题、段落、表格和列表结构。",
        "json": "识别图片中的内容，按结构化 JSON 输出。"
    }

    prompt = prompt_map.get(mode, prompt_map["markdown"])

    result = model.infer(
        image=image,
        prompt=prompt
    )

    return result

不同实现里的函数名会不一样，但思路基本一致：WebUI 收集输入，后端组织 prompt 和图像，模型返回文本，界面展示结果。

4. 输出整理

OCR 输出不能只看“有没有识别出字”，还要看结果是否能继续使用。常见输出格式有三种：

对于资料整理，Markdown 往往最实用。例如一张图片中包含标题、段落和表格，理想结果应该类似这样：

# 设备巡检记录

| 设备编号 | 状态 | 备注 |
|---|---|---|
| A-001 | 正常 | 无 |
| A-002 | 异常 | 温度过高 |

巡检时间：2026-06-07

纯文本只能保留内容，Markdown 可以保留一部分结构，这也是智能 OCR 比传统 OCR 更有用的地方。

部署方式

DeepSeek-OCR-WebUI 通常是 Python 项目，常见运行方式是创建虚拟环境、安装依赖、启动 Web 服务。

环境准备

建议使用独立虚拟环境，避免和系统 Python 或其他项目依赖冲突。

python -m venv .venv

Linux / macOS 激活环境：

source .venv/bin/activate

Windows PowerShell 激活环境：

.venv\Scripts\Activate.ps1

安装依赖：

pip install -r requirements.txt

如果项目依赖 PyTorch，并且需要 GPU 推理，要按 CUDA 版本安装对应的 PyTorch。可以先检查显卡是否能被识别：

python - <<'PY'
import torch
print("CUDA available:", torch.cuda.is_available())
if torch.cuda.is_available():
    print("GPU:", torch.cuda.get_device_name(0))
PY

输出 CUDA available: True 才表示当前 Python 环境可以使用 NVIDIA GPU。

启动 WebUI

不同项目的启动文件可能叫 app.py、webui.py 或 main.py。常见启动方式如下：

python app.py

或者：

python webui.py

启动成功后，终端通常会显示一个本地地址，例如：

Running on local URL: http://127.0.0.1:7860

浏览器打开这个地址，就可以进入上传和识别界面。

如果需要让局域网内其他机器访问，通常要把监听地址改成 0.0.0.0：

python app.py --host 0.0.0.0 --port 7860

部署在服务器上时，要注意防火墙和访问权限。OCR 服务可能处理合同、截图、报表等敏感内容，不建议直接暴露到公网。

一个典型的 WebUI 使用流程

实际使用时，可以按这个顺序操作：

flowchart TD
    A[打开 WebUI] --> B[上传图片或PDF]
    B --> C[选择输出格式]
    C --> D[设置识别参数]
    D --> E[开始识别]
    E --> F{结果是否可用}
    F -- 是 --> G[复制或下载]
    F -- 否 --> H[调整图片质量或参数]
    H --> E

关键参数一般包括：

对于 OCR 任务，稳定性通常比创造性更重要。如果模型或界面提供 temperature 一类生成参数，建议设置得低一些，避免模型输出额外解释或改写内容。

常见问题和处理办法

图片很清楚，但识别结果漏字

可能原因有三个：

1. 图片被压缩得太小，小字细节丢失；
2. 页面内容太密，模型在长文本中跳过了部分区域；
3. 表格、公式、边注混在一起，版面结构太复杂。

处理方式：

• 使用原图，不要使用聊天软件压缩后的图片；
• 把长页面裁成几块分别识别；
• 对密集表格单独截图；
• 提高输入分辨率，但要注意显存占用。

表格识别出来了，但行列错位

表格 OCR 的难点不只是识别文字，还要判断单元格关系。图片里如果没有明显边框，或者存在合并单元格，模型容易把相邻列混在一起。

可以尝试：

• 截图时保留完整表格边框；
• 不要裁掉表头；
• 对超宽表格分段识别；
• 使用 Markdown 输出后人工校对。

PDF 很大，识别速度很慢

PDF 通常要先转成图片，再逐页送入模型。页数越多，耗时越长，显存占用也越高。

更稳妥的处理方式是分批：

第 1 批：1-10 页
第 2 批：11-20 页
第 3 批：21-30 页

如果页面中大量是纯文本 PDF，而不是扫描件，用 PDF 文本提取工具会更快。OCR 更适合处理扫描 PDF、图片 PDF 或无法直接复制文字的页面。

CPU 能不能跑

能跑不代表适合日常使用。OCR 模型推理通常对计算资源要求较高，CPU 模式可能非常慢，尤其是高分辨率图片和多页 PDF。

识别结果出现多余解释

OCR 输出应该忠实于图片内容。如果结果里出现“这是一个表格”“图片展示了……”这类额外说明，通常是提示词或识别模式不够约束。

可以把提示词改得更明确：

只输出图片中真实存在的文字和结构。
不要解释图片。
不要补充图片中没有出现的内容。
表格请使用 Markdown 表格表示。

WebUI 和 API 服务的区别

WebUI 适合人工操作，API（Application Programming Interface，应用程序编程接口）适合系统集成。两者不是替代关系，而是面向不同使用方式。

如果只是偶尔识别截图，WebUI 最方便；如果要把 OCR 接到文档系统、知识库或审核平台，应该封装 API 或任务队列。

一个简单的 API 调用形式可能是这样：

import requests

files = {
    "file": open("sample.png", "rb")
}

data = {
    "format": "markdown"
}

response = requests.post(
    "http://127.0.0.1:7860/api/ocr",
    files=files,
    data=data,
    timeout=120
)

print(response.json()["result"])

真实接口路径要以项目实现为准。核心思路是把文件和参数发给服务端，再拿回识别结果。

部署时需要注意的安全问题

OCR 系统经常处理敏感内容，比如合同、内部截图、业务报表、客户资料。即使只是本地 WebUI，也要注意几个问题：

如果部署在服务器上，至少要加反向代理鉴权，或者只允许内网访问。OCR 输入本质上就是数据资产，不能只把它当普通图片处理。

什么时候应该选择 DeepSeek-OCR-WebUI

适合选择 WebUI 的情况：

• 不想写推理脚本，只想通过浏览器完成识别；
• 需要人工检查 OCR 结果；
• 经常处理截图、扫描件、图片表格；
• 想把识别结果整理成 Markdown；
• 本地或内网使用，数据不适合上传到第三方服务。

不适合直接使用 WebUI 的情况：

• 每天处理大量文件，需要自动化流水线；
• 多用户同时访问，并且要求稳定排队和权限控制；
• 识别结果要进入严肃业务系统，需要字段校验、人工审核和日志追踪；
• 对格式准确率要求极高，必须定制后处理规则。

DeepSeek-OCR-WebUI 的定位可以概括成一句话：它把模型能力变成了一个可操作、可预览、可校对的 OCR 工作台。对于个人资料整理、文档转写、截图识别和轻量批处理，这种形态比命令行脚本更容易使用；对于生产系统，它更适合作为原型验证工具，后续再拆成 API、队列和权限体系。