🚀 DeepSeek OCR - React + FastAPI

基于 DeepSeek-OCR 的现代 OCR 网页应用（光学字符识别），采用惊艳的 React 前端和 FastAPI 后端。现已支持 PDF 处理和多格式文档转换！

✨ v2.2.0 新增功能 - PDF 处理与文档转换

我们根据社区反馈新增了强大的 PDF 处理功能！现在您可以：

📄 处理完整 PDF 文档

• 上传最大 100MB 的 PDF 文件
• 自动多页 OCR 处理
• 大文件实时进度追踪
• 从扫描版 PDF 或图像文档中提取文本

🔄 转换为多种格式

将 OCR 结果导出为您需要的格式：

• Markdown (.md) - 清晰的结构化文本，适合文档编写
• HTML (.html) - 嵌入图像和表格的样式化文档
• Word (.docx) - 包含格式、表格和图像的专业文档
• JSON - 用于程序访问的结构化数据

🖼️ 自动图像提取

• 检测并提取 PDF 页面中的图像
• 在导出文档中嵌入图像
• 保留图像位置和上下文

📐 公式与格式保留

• 保留数学公式（LaTeX 语法）
• 保留表格、标题和文档结构
• 清理特殊字符的同时保持格式完整

🎯 应用场景

• 文档数字化 - 将扫描版 PDF 转换为可编辑格式
• 数据提取 - 从表单和发票中提取结构化数据
• 内容迁移 - 将 PDF 转换为 Markdown 用于维基/文档
• 学术论文 - 提取研究论文中的文本和公式
• 商业文档 - 将报告转换为 Word 以便编辑

---

最新更新 (v2.2.0) - 2025 年 11 月

• 🎉 新增：PDF 处理 - 上传 PDF 并提取所有页面文本
• 🎉 新增：多格式导出 - 转换为 Markdown、HTML、DOCX 或 JSON
• 🎉 新增：自动图像提取 - 提取并保留 PDF 中的图像
• 🎉 新增：进度追踪 - 多页文档的实时进度
• ✅ 双模式：图像 OCR + PDF 处理及格式转换
• ✅ 增强文档处理，保留公式和格式

历史更新 (v2.1.1)

• ✅ 修复图像移除按钮 - 现在可正确清除并重新上传
• ✅ 修复多个边界框解析 - 支持 [[x1,y1,x2,y2], [x1,y1,x2,y2]] 格式
• ✅ 简化为 4 个核心工作模式以提高稳定性
• ✅ 修复边界框坐标缩放（归一化 0-999 → 实际像素）
• ✅ 修复 HTML 渲染（模型输出 HTML，而非 Markdown）
• ✅ 增加文件上传限制至 100MB（可配置）
• ✅ 添加 .env 配置支持

快速开始

1. 克隆并配置：

   git clone <repository-url>
   cd deepseek_ocr_app
   
   # 复制并自定义环境变量
   cp .env.example .env
   # 编辑 .env 以配置端口、上传限制等
   

2. 启动应用：

   docker compose up --build
   

   首次运行将下载模型（约 5-10GB），可能需要一些时间。

3. 访问应用：

   • 前端: http://localhost:3000（或配置的 FRONTEND_PORT）
   • 后端 API: http://localhost:8000（或配置的 API_PORT）
   • API 文档: http://localhost:8000/docs

🎓 使用方法

处理图像（单图像 OCR）

1. 在切换器中选择 "Image OCR" 模式
2. 上传图像（PNG、JPG、WEBP 等）
3. 选择 OCR 模式：
   • Plain OCR - 提取所有文本
   • Describe - 获取图像描述
   • Find - 定位特定术语
   • Freeform - 使用自定义提示
4. 点击 "Analyze Image"
5. 查看结果（启用时显示边界框）
6. 复制或下载提取的文本

处理 PDF（多页文档）- 新增！

1. 在切换器中选择 "PDF Processing" 模式
2. 上传 PDF 文件（最大 100MB）
3. 选择 OCR 模式（同上）
4. 选择 输出格式：
   • 📝 Markdown - 用于文档、维基、GitHub
   • 🌐 HTML - 用于网页发布、样式化查看
   • 📄 DOCX - 用于 Word 编辑、专业文档
   • 📊 JSON - 用于程序访问、数据提取
5. 点击 "Process PDF"
6. 观察进度条处理各页面
7. 文件处理完成后自动下载！

最佳效果提示

• 扫描文档：在高级设置中使用更高 DPI（144-300）
• 表格：模型擅长提取结构化数据
• 公式：数学符号在输出中保留
• PDF 中的图像：启用 "Extract Images" 以包含在输出中
• 大型 PDF：JSON 格式最快，DOCX 因格式化耗时更长

输出格式对比

格式	最佳用途	特性	文件大小
Markdown	文档、GitHub、维基	清晰文本、表格、代码块	最小
HTML	网页查看、分享	样式化输出、嵌入图像、表格	中等
DOCX	编辑、专业文档	完整格式、图像、表格	最大
JSON	数据处理、API	结构化数据、元数据、页面信息	小

功能

双处理模式

📸 图像 OCR（4 核心模式）

• Plain OCR - 从任何图像中提取原始文本
• Describe - 生成智能图像描述
• Find - 通过视觉边界框定位特定术语
• Freeform - 自定义提示用于专业任务

📄 PDF 处理（新增！）

• 多页处理 - 逐页处理完整 PDF 文档
• 格式转换 - 导出为 Markdown、HTML、DOCX 或 JSON
• 图像提取 - 自动提取并保留嵌入图像
• 公式保留 - 保留数学公式和特殊格式
• 进度追踪 - 大型文档的实时进度更新

UI 功能

• 🎨 玻璃形态设计与动画渐变
• 🎯 拖放文件上传（图像最大 10MB，PDF 最大 100MB）
• 🔄 简单的文件移除和重新上传
• 📦 接地框可视化与正确坐标缩放
• ✨ 流畅动画（Framer Motion）
• 📋 多格式复制/下载结果
• 🎛️ 高级设置下拉菜单
• 📝 样式化输出的 HTML 和 Markdown 渲染
• 🔍 多边界框支持（处理找到术语的多个实例）
• 📊 多页 PDF 处理进度条
• 💾 转换文档直接下载（MD、HTML、DOCX）

配置

通过 .env 文件进行配置：

# API 配置
API_HOST=0.0.0.0
API_PORT=8000

# 前端配置
FRONTEND_PORT=3000

# 模型配置
MODEL_NAME=deepseek-ai/DeepSeek-OCR
HF_HOME=/models

# 上传配置
MAX_UPLOAD_SIZE_MB=100  # 最大文件上传大小

处理配置

BASE_SIZE=1024 # 基础处理分辨率 IMAGE_SIZE=640 # 图块处理分辨率 CROP_MODE=true # 启用大图像动态裁剪

### 环境变量

- `API_HOST`: 后端API主机 (默认: 0.0.0.0)
- `API_PORT`: 后端API端口 (默认: 8000)
- `FRONTEND_PORT`: 前端端口 (默认: 3000)
- `MODEL_NAME`: HuggingFace模型标识符
- `HF_HOME`: 模型缓存目录
- `MAX_UPLOAD_SIZE_MB`: 最大文件上传大小（单位：MB）
- `BASE_SIZE`: 基础图像处理尺寸（影响内存使用）
- `IMAGE_SIZE`: 动态裁剪图块尺寸
- `CROP_MODE`: 启用/禁用动态图像裁剪

## 技术栈

### 前端
- **框架**: React 18 + Vite 5
- **样式**: TailwindCSS 3 + 自定义玻璃磨砂效果
- **动画**: Framer Motion 11
- **HTTP客户端**: Axios
- **文件上传**: React Dropzone

### 后端
- **API框架**: FastAPI（异步Python Web框架）
- **ML/AI**: PyTorch + Transformers 4.46 + DeepSeek-OCR
- **PDF处理**: PyMuPDF (fitz) + img2pdf
- **文档转换**:
  - python-docx（Word文档）
  - markdown（Markdown处理）
  - 自定义HTML生成器
- **配置**: python-decouple 用于环境管理

### 基础设施
- **服务器**: Nginx（反向代理与静态文件服务）
- **容器**: Docker + Docker Compose 多阶段构建
- **GPU**: NVIDIA CUDA 支持（测试环境：RTX 3090, RTX 5090）

## 项目结构

deepseek-ocr/ ├── backend/ # FastAPI后端 │ ├── main.py # 包含OCR和PDF接口的主API │ ├── pdf_utils.py # PDF处理工具（新增） │ ├── format_converter.py # 文档格式转换（新增） │ ├── requirements.txt │ └── Dockerfile ├── frontend/ # React前端 │ ├── src/ │ │ ├── components/ │ │ │ ├── ImageUpload.jsx # 文件上传（图片 & PDF） │ │ │ ├── PDFProcessor.jsx # PDF处理UI（新增） │ │ │ ├── ModeSelector.jsx │ │ │ ├── ResultPanel.jsx │ │ │ └── AdvancedSettings.jsx │ │ ├── App.jsx # 支持双模式的主应用 │ │ └── main.jsx │ ├── package.json │ ├── nginx.conf │ └── Dockerfile ├── models/ # 模型缓存 └── docker-compose.yml

## 开发

Docker compose测试流程：
```bash
docker compose down
docker compose up --build

要求

硬件

• 支持CUDA的NVIDIA GPU
  • 推荐: RTX 3090, RTX 4090, RTX 5090 或更高
  • 最低: 8-12GB 显存
  • 显存越大越好！

软件

• Docker & Docker Compose（推荐最新版本）

• NVIDIA驱动 - 在Ubuntu上安装NVIDIA驱动（Blackwell/RTX 5090）

  注意: 在Blackwell GPU上安装NVIDIA驱动可能会遇到问题！以下是解决方案：

  RTX 5090在Ubuntu 24.04上的关键要求：

  • 使用开源驱动（nvidia-driver-570-open 或更新版本，如 nvidia-driver-580-open）
  • 升级到内核 6.11+（推荐 6.14+ 以获得最佳稳定性）
  • 在BIOS/UEFI中启用Resize Bar（关键！）

  分步指南:

  1. 安装NVIDIA开源驱动（580或更新）

     sudo add-apt-repository ppa:graphics-drivers/ppa
     sudo apt update
     sudo apt remove --purge nvidia*
     sudo nvidia-installer --uninstall  # 如果已安装
     sudo apt autoremove
     sudo apt install nvidia-driver-580-open
     

  2. 升级Linux内核到6.11+（Ubuntu 24.04 LTS）

     sudo apt install --install-recommends linux-generic-hwe-24.04 linux-headers-generic-hwe-24.04
     sudo update-initramfs -u
     sudo apt autoremove
     

  3. 重启

     sudo reboot
     

  4. 在UEFI/BIOS中启用Resize Bar

     • 重启并进入UEFI（通常在启动时按F2、Del或F12）
     • 找到并启用 "Resize Bar" 或 "Smart Access Memory"
     • 这也会启用 "Above 4G Decoding" 并禁用 "CSM"（兼容性支持模块）——这是预期行为！
     • 保存并退出

  5. 验证安装

     nvidia-smi
     

     你应该能看到RTX 5090被列出！

  💡 为什么使用开源驱动？不清楚，但开源驱动对Blackwell GPU的支持更好。如果没有启用Resize Bar，即使安装了正确驱动也会出现黑屏！

  致谢：解决方案改编自 这个Reddit帖子。

• NVIDIA容器工具包（Docker访问GPU所需）

  • 安装指南: https://docs.nvidia.com/datacenter/cloud-native/container-toolkit/latest/install-guide.html

系统要求

• ~20GB 可用磁盘空间（模型权重和Docker镜像）
• 推荐16GB+ 系统内存
• 快速网络连接（初始模型下载约5-10GB）

已知问题与修复

✅ 已修复: 图片移除和重新上传 (v2.1.1)

• 问题: 无法移除已上传图片并重新上传新图片
• 修复: 添加了显眼的 "移除" 按钮，清除图片状态并允许重新上传

✅ 已修复: 多个边界框 (v2.1.1)

• 问题: 仅单个边界框有效，多个框如 [[x1,y1,x2,y2], [x1,y1,x2,y2]] 失败
• 修复: 使用 ast.literal_eval 更新解析器以处理单个和坐标数组

✅ 已修复: 接地框坐标缩放 (v2.1)

• 问题: 边界框显示不正确
• 原因: 模型输出坐标归一化到0-999，而非实际像素尺寸
• 修复: 后端现在使用公式 实际坐标 = (归一化坐标 / 999) * 图像尺寸 正确缩放坐标

✅ 已修复: HTML vs Markdown 渲染 (v2.1)

• 问题: 模型输出HTML时却被渲染为Markdown
• 原因: 模型训练输出HTML（尤其是表格）
• 修复: 前端现在通过 dangerouslySetInnerHTML 正确检测并渲染HTML

✅ 已修复: 上传大小限制 (v2.1)

• 问题: 大图片无法上传
• 修复: 将nginx的 client_max_body_size 增加到100MB（可通过.env配置）

⚠️ 简化模式选择 (v2.1.1)

• 变更: 从12种模式减少到4种核心工作模式
• 原因: 高级模式（表格、布局、PII、多语言）需要额外测试
• 可用模式: 普通OCR、描述、查找、自由模式
• 未来: 所有模式将在充分测试后重新启用

模型工作原理

坐标系统

DeepSeek-OCR模型使用归一化坐标系统（0-999）进行边界框处理：

• 所有坐标输出范围 [0, 999]
• 后端缩放公式: 像素坐标 = (模型坐标 / 999) * 实际尺寸
• 这确保了不同图像尺寸的一致性

动态裁剪

对于大尺寸图像，模型使用动态裁剪：

• 图像 ≤640x640: 直接处理
• 更大图像: 根据宽高比分割为瓦片
• 全局视图 (BASE_SIZE) + 局部视图 (IMAGE_SIZE 瓦片)
• 实现细节请参见 process/image_process.py

输出格式

• 纯文本模式: 返回原始文本
• 表格模式: 返回 HTML 表格或 CSV
• JSON 模式: 返回结构化 JSON
• 接地模式: 返回带 <|ref|>label<|/ref|><|det|>[[coords]]<|/det|> 标签的文本

API 使用

POST /api/ocr

参数：

• image (文件, 必填) - 要处理的图像文件（最大100MB）
• mode (字符串) - OCR 模式: plain_ocr | describe | find_ref | freeform
• prompt (字符串) - 自定义提示（用于 freeform 模式）
• grounding (布尔值) - 启用边界框（find_ref 模式自动启用）
• find_term (字符串) - find_ref 模式中要查找的术语（支持多匹配）
• base_size (整数) - 基础处理尺寸（默认: 1024）
• image_size (整数) - 裁剪瓦片尺寸（默认: 640）
• crop_mode (布尔值) - 启用动态裁剪（默认: true）
• include_caption (布尔值) - 添加图像描述（默认: false）

响应：

{
  "success": true,
  "text": "Extracted text or HTML output...",
  "boxes": [{"label": "field", "box": [x1, y1, x2, y2]}],
  "image_dims": {"w": 1920, "h": 1080},
  "metadata": {
    "mode": "layout_map",
    "grounding": true,
    "base_size": 1024,
    "image_size": 640,
    "crop_mode": true
  }
}

关于边界框的说明：

• 模型输出的坐标已归一化到 0-999 范围
• 后端会自动将其缩放至实际图像尺寸
• 坐标格式为 [x1, y1, x2, y2]（左上角，右下角）
• 支持多个边界框：当查找多个实例时，格式为 [[x1,y1,x2,y2], [x1,y1,x2,y2], ...]
• 前端会自动将所有边界框以不同颜色叠加显示在图像上

POST /api/process-pdf (新增！)

使用 OCR 处理 PDF 文档并导出为多种格式。

参数：

• pdf_file (文件, 必填) - 要处理的 PDF 文件（最大100MB）
• mode (字符串) - OCR 模式: plain_ocr | describe | find_ref | freeform
• prompt (字符串) - 自定义提示（用于 freeform 模式）
• output_format (字符串) - 输出格式: markdown | html | docx | json
• grounding (布尔值) - 启用边界框（默认: false）
• include_caption (布尔值) - 添加图像描述（默认: false）
• extract_images (布尔值) - 从 PDF 提取嵌入图像（默认: true）
• dpi (整数) - PDF 渲染分辨率（默认: 144）
• base_size (整数) - 基础处理尺寸（默认: 1024）
• image_size (整数) - 裁剪瓦片尺寸（默认: 640）
• crop_mode (布尔值) - 启用动态裁剪（默认: true）

响应格式：

JSON 格式 (output_format=json)：

{
  "success": true,
  "total_pages": 5,
  "pages": [
    {
      "page_number": 1,
      "text": "Extracted and cleaned text...",
      "raw_text": "Raw model output with tags...",
      "boxes": [{"label": "field", "box": [x1, y1, x2, y2]}],
      "images": ["base64_encoded_image_data..."],
      "image_dims": {"w": 1920, "h": 1080}
    }
  ],
  "metadata": {
    "mode": "plain_ocr",
    "grounding": false,
    "extract_images": true,
    "dpi": 144
  }
}

文件下载 (output_format=markdown|html|docx)：

• 返回可下载的文档文件
• Markdown: .md 文件保留格式
• HTML: .html 文件包含内嵌样式和图像
• DOCX: .docx Word 文档包含表格和格式

功能特点：

• 📄 支持多页处理并跟踪进度
• 🖼️ 自动提取并嵌入图像
• 📐 公式和格式保留
• 🎨 带表格和代码块的样式化 HTML 输出
• 📝 结构清晰的 Markdown
• 📋 带标题和表格的专业 DOCX 文档

示例

以下示例展示了不同 OCR 功能的效果：

视觉理解

图表转表格

图像描述

故障排除

未检测到 GPU

nvidia-smi
docker run --rm --gpus all nvidia/cuda:11.8.0-base-ubuntu22.04 nvidia-smi

端口冲突

sudo lsof -i :3000
sudo lsof -i :8000

前端构建问题

cd frontend
rm -rf node_modules package-lock.json
docker-compose build frontend

许可证

本项目使用 DeepSeek-OCR 模型。请参考模型的许可条款。

Note: 遵循 MIT 许可证。查看完整许可证: LICENSE

DeepSeek OCR 快速上手指南

环境准备

系统要求

• GPU：NVIDIA 显卡（推荐 RTX 3090/4090/5090，最低 8-12GB 显存）
• CPU：16GB+ 内存
• 存储：20GB+ 可用空间（含模型文件和 Docker 镜像）
• 操作系统：Ubuntu 22.04+/24.04+（推荐）

前置依赖

1. Docker & Docker Compose（建议最新版本）
2. NVIDIA 驱动：
   • 安装开源驱动 nvidia-driver-580-open 或更高版本
   • 升级内核至 6.11+（Ubuntu 24.04 可用）
   • 启用 BIOS 中的 Resize Bar 功能
3. NVIDIA Container Toolkit（用于 Docker GPU 支持）
   • 安装指南：https://docs.nvidia.com/datacenter/cloud-native/container-toolkit/latest/install-guide.html

🚀 国内加速建议：

• 配置 Docker 国内镜像加速（如阿里云、DaoCloud）
• 使用 --build-arg HF_MIRROR=https://hf-mirror.com 参数加速模型下载

---

安装步骤

1. 克隆项目并配置环境

   git clone <repository-url>
   cd deepseek_ocr_app
   cp .env.example .env
   # 编辑 .env 修改端口或上传限制（可选）
   

2. 启动应用

   docker compose up --build
   

   ⏱️ 首次运行：需下载约 5-10GB 模型文件，建议使用高速网络

3. 访问服务

   • 前端界面：http://localhost:3000
   • API 文档：http://localhost:8000/docs

---

基本使用

示例 1：图像 OCR（单图识别）

1. 打开前端页面，选择 "Image OCR" 模式
2. 上传图片（支持 PNG/JPG/WEBP）
3. 选择识别模式：
   • Plain OCR：提取全部文字
   • Describe：生成图片描述
   • Find：定位特定关键词
   • Freeform：自定义提示词
4. 点击 "Analyze Image" 查看结果

示例 2：PDF 文档处理（多页识别）

1. 切换到 "PDF Processing" 模式
2. 上传 PDF 文件（最大 100MB）
3. 选择输出格式：
   • Markdown（文档/维基）
   • HTML（网页展示）
   • DOCX（Word 编辑）
   • JSON（数据接口）
4. 点击 "Process PDF"，下载处理后的文件

---

格式选择建议

格式	适用场景	特点
Markdown	文档编辑、GitHub	清晰结构，最小文件体积
HTML	网页展示	支持样式与嵌入图片
DOCX	专业文档编辑	保留格式与表格
JSON	数据分析、程序处理	结构化数据，便于解析

⚠️ 大文件处理提示：

• JSON 格式处理速度最快
• DOCX 格式因排版耗时较长
• 开启 "Extract Images" 选项可保留 PDF 中的图片