jmn319/deepseek-ocr

DeepSeek-OCR：PDF转Markdown转换器

一个强大的OCR解决方案，使用DeepSeek-OCR配合FastAPI后端将PDF文档转换为Markdown格式。本项目提供批处理脚本和REST API，实现灵活的文档转换功能。

🚀 快速开始

选项1：使用pdf_to_markdown_processor.py进行批处理

1. 将PDF文件放入data/目录
2. 确保DeepSeek-OCR API已运行（见下文Docker设置）
3. 运行处理器：

bash
python pdf_to_markdown_processor.py

选项2：使用Docker后端的REST API

1. 构建并启动Docker容器
2. 使用API端点处理文档
3. 与您的应用程序集成

---

📋 先决条件

硬件要求

• 支持CUDA 11.8+的NVIDIA GPU
• GPU内存：最低12GB显存（模型占用约9GB）
• 系统内存：最低32GB（推荐64GB+）
• 存储空间：50GB+可用空间（用于模型和容器）

软件要求

• Python 3.8+（用于本地处理）
• Docker 20.10+（带GPU支持）
• Docker Compose 2.0+
• 已安装NVIDIA Container Toolkit
• 兼容CUDA 11.8的驱动程序

---

🐳 Docker后端设置

1. 下载模型权重

创建模型权重目录并下载DeepSeek-OCR模型：

bash
# 创建模型目录
mkdir -p models

# 使用Hugging Face CLI下载
pip install huggingface_hub
huggingface-cli download deepseek-ai/DeepSeek-OCR --local-dir models/deepseek-ai/DeepSeek-OCR

# 或使用git
git clone https://huggingface.co/deepseek-ai/DeepSeek-OCR models/deepseek-ai/DeepSeek-OCR

2. 构建并运行Docker容器

Windows用户

cmd
REM 构建Docker镜像
build.bat

REM 启动服务
docker-compose up -d

REM 查看日志
docker-compose logs -f deepseek-ocr

Linux/macOS用户

bash
# 构建Docker镜像
docker-compose build

# 启动服务
docker-compose up -d

# 查看日志
docker-compose logs -f deepseek-ocr

3. 验证安装

bash
# 健康检查
curl http://localhost:8000/health

# 预期响应：
{
  "status": "healthy",
  "model_loaded": true,
  "model_path": "/app/models/deepseek-ai/DeepSeek-OCR",
  "cuda_available": true,
  "cuda_device_count": 1
}

---

📄 PDF处理脚本

本项目提供多个PDF处理脚本，适用于不同使用场景。所有脚本扫描data/目录中的PDF文件，并使用不同的提示和后处理选项将其转换为Markdown格式。

输出命名规则

所有处理器在输出文件名后添加后缀，指示所使用的处理方法：

• -MD.md：Markdown转换（保留文档结构）
• -OCR.md：纯OCR提取（无格式原始文本）
• -CUSTOM.md：自定义提示处理（使用YAML文件中的提示）

例如，处理document.pdf将创建：

• document-MD.md（markdown处理器）
• document-OCR.md（OCR处理器）
• document-CUSTOM.md（自定义提示处理器）

---

1. pdf_to_markdown_processor.py

用途：使用标准markdown提示进行基本PDF转Markdown转换

特点：

• 使用提示：'<image>\n<|grounding|>Convert the document to markdown.'
• 将PDF转换为结构化Markdown格式
• 简单处理，不提取图像
• 输出文件带有-MD.md后缀

使用方法：

bash
# 将PDF文件放入data目录
cp your_document.pdf data/

# 运行处理器
python pdf_to_markdown_processor.py

# 查看结果
ls data/*-MD.md

---

2. pdf_to_markdown_processor_enhanced.py

用途：带后处理的增强型PDF转Markdown转换

特点：

• 使用与基础版本相同的markdown提示
• 后处理功能：
  • 图像提取并保存到data/images/文件夹
  • 特殊令牌清理
  • 布局信息引用处理
  • 内容清理和格式化
• 输出文件带有-MD.md后缀

使用方法：

bash
# 将PDF文件放入data目录
cp your_document.pdf data/

# 运行增强型处理器
python pdf_to_markdown_processor_enhanced.py

# 查看结果（包括提取的图像）
ls data/*-MD.md
ls data/images/

---

3. pdf_to_ocr_enhanced.py

用途：无markdown格式的纯OCR文本提取

特点：

• 使用OCR提示：'<image>\nFree OCR.'
• 提取无markdown结构的原始文本
• 包含与增强型markdown处理器相同的后处理功能
• 输出文件带有-OCR.md后缀

使用方法：

bash
# 将PDF文件放入data目录
cp your_document.pdf data/

# 运行OCR处理器
python pdf_to_ocr_enhanced.py

# 查看结果
ls data/*-OCR.md

---

4. pdf_to_custom_prompt.py

用途：使用自定义提示处理PDF（原始输出）

特点：

• 使用从custom_prompt.yaml加载的自定义提示
• 返回未经后处理的原始模型响应
• 适用于测试和调试不同提示
• 输出文件带有-CUSTOM.md后缀

配置： 编辑custom_prompt.yaml自定义提示：

yaml
# PDF处理的自定义提示
prompt: '<image>\n<|grounding|>Convert the document to markdown.'

使用方法：

bash
# 编辑custom_prompt.yaml中的提示
nano custom_prompt.yaml

# 将PDF文件放入data目录
cp your_document.pdf data/

# 运行自定义提示处理器
python pdf_to_custom_prompt.py

# 查看结果
ls data/*-CUSTOM.md

---

5. pdf_to_custom_prompt_enhanced.py

用途：使用自定义提示和完整后处理的PDF处理

特点：

• 使用从custom_prompt.yaml加载的自定义提示
• 包含所有后处理功能（图像提取、内容清理等）
• 结合自定义提示与增强型输出处理
• 输出文件带有-CUSTOM.md后缀

配置： 与pdf_to_custom_prompt.py相同 - 编辑custom_prompt.yaml自定义提示。

使用方法：

bash
# 编辑custom_prompt.yaml中的提示
nano custom_prompt.yaml

# 将PDF文件放入data目录
cp your_document.pdf data/

# 运行增强型自定义提示处理器
python pdf_to_custom_prompt_enhanced.py

# 查看结果（包括提取的图像）
ls data/*-CUSTOM.md
ls data/images/

---

📊 处理器比较

---

📋 常见使用模式

比较不同处理方法

要比较不同处理器处理同一文档的效果：

bash
# 将PDF放入data目录
cp test_document.pdf data/

# 运行所有处理器
python pdf_to_markdown_processor.py
python pdf_to_markdown_processor_enhanced.py
python pdf_to_ocr_enhanced.py
python pdf_to_custom_prompt.py

# 比较输出
ls data/test_document-*.md

使用自定义提示处理

1. 编辑custom_prompt.yaml设置所需提示：

yaml
prompt: '<image>\nExtract all tables and format as CSV.'

2. 运行自定义处理器：

bash
python pdf_to_custom_prompt_enhanced.py

3. 查看专门输出：

bash
cat data/your_document-CUSTOM.md

---

🔌 REST API使用

FastAPI后端提供多个文档处理端点。

API端点

健康检查

bash
GET http://localhost:8000/health

处理单张图像

bash
curl -X POST "http://localhost:8000/ocr/image" \
  -H "accept: application/json" \
  -H "Content-Type: multipart/form-data" \
  -F "file=@your_image.jpg"

处理PDF

bash
curl -X POST "http://localhost:8000/ocr/pdf" \
  -H "accept: application/json" \
  -H "Content-Type: multipart/form-data" \
  -F "file=@your_document.pdf"

批处理

bash
curl -X POST "http://localhost:8000/ocr/batch" \
  -H "accept: application/json" \
  -H "Content-Type: multipart/form-data" \
  -F "files=@image1.jpg" \
  -F "files=@document.pdf" \
  -F "files=@image2.png"

响应格式

单图像响应

json
{
  "success": true,
  "result": "# 文档标题\n\n这是Markdown格式的OCR结果...",
  "page_count": 1
}

PDF响应

json
{
  "success": true,
  "results": [
    {
      "success": true,
      "result": "# 第1页内容\n...",
      "page_count": 1
    },
    {
      "success": true,
      "result": "# 第2页内容\n...",
      "page_count": 2
    }
  ],
  "total_pages": 2,
  "filename": "document.pdf"
}

---

💻 客户端集成示例

Python客户端

python
import requests

class DeepSeekOCRClient:
    def __init__(self, base_url="http://localhost:8000"):
        self.base_url = base_url
    
    def process_image(self, image_path):
        with open(image_path, 'rb') as f:
            response = requests.post(
                f"{self.base_url}/ocr/image",
                files={"file": f}
            )
        return response.json()
    
    def process_pdf(self, pdf_path):
        with open(pdf_path, 'rb') as f:
            response = requests.post(
                f"{self.base_url}/ocr/pdf",
                files={"file": f}
            )
        return response.json()

# 使用示例
client = DeepSeekOCRClient()
result = client.process_pdf("document.pdf")

if result["success"]:
    for page_result in result["results"]:
        print(f"第{page_result['page_count']}页:")
        print(page_result["result"])
        print("---")

JavaScript客户端

javascript
class DeepSeekOCR {
    constructor(baseUrl = 'http://localhost:8000') {
        this.baseUrl = baseUrl;
    }
    
    async processImage(file) {
        const formData = new FormData();
        formData.append('file', file);
        
        const response = await fetch(`${this.baseUrl}/ocr/image`, {
            method: 'POST',
            body: formData
        });
        
        return await response.json();
    }
    
    async processPDF(file) {
        const formData = new FormData();
        formData.append('file', file);
        
        const response = await fetch(`${this.baseUrl}/ocr/pdf`, {
            method: 'POST',
            body: formData
        });
        
        return await response.json();
    }
}

// 浏览器中使用示例
const ocr = new DeepSeekOCR();
document.getElementById('fileInput').addEventListener('change', async (e) => {
    const file = e.target.files[0];
    const result = await ocr.processPDF(file);
    
    if (result.success) {
        result.results.forEach(page => {
            console.log(`第${page.page_count}页:`, page.result);
        });
    }
});

---

⚙️ 配置

自定义配置和关键修复

本项目包含自定义文件，替换原始DeepSeek-OCR库代码以修复关键问题并提供增强功能。这些替换在Docker构建过程中自动应用。

🚨 关键提示参数修复

问题：原始DeepSeek-OCR库在模型初始化期间调用tokenize_with_images()方法时缺少必需的prompt参数，导致服务器启动失败。

解决方案：已创建自定义运行脚本来正确处理prompt参数，防止启动错误。

自定义文件及其用途

项目根目录中的以下自定义文件在Docker构建期间替换其对应文件：

• custom_config.py：带有可自定义默认提示和设置的自定义配置
• custom_image_process.py：修复版图像处理模块，正确处理prompt参数
• custom_run_dpsk_ocr_pdf.py：增强型PDF脚本，接受--prompt参数并修复初始化问题
• custom_run_dpsk_ocr_image.py：增强型图像脚本，接受--prompt参数并修复初始化问题
• custom_run_dpsk_ocr_eval_batch.py：增强型批处理脚本，接受--prompt参数并修复初始化问题

这些自定义文件在Docker构建过程中自动复制到原始库文件上，确保无需手动干预即可应用修复。

使用自定义配置

1. 编辑默认提示：

   python
   # 编辑custom_config.py
   PROMPT = '<image>\n<|grounding|>此处为您的自定义默认提示。'
   

2. 通过直接脚本使用自定义提示：

   bash
   # 使用custom_config.py中的默认提示
   python custom_run_dpsk_ocr_pdf.py --input your_file.pdf --output output_dir
   
   # 通过命令行使用自定义提示
   python custom_run_dpsk_ocr_pdf.py --prompt "<image>\n<|grounding|>将表格提取为CSV格式。" --input your_file.pdf
   

3. 通过API使用自定义提示：

   bash
   # 使用默认提示
   curl -X POST "http://localhost:8000/ocr/pdf" -F "file=@your_file.pdf"
   
   # 使用自定义提示
   curl -X POST "http://localhost:8000/ocr/pdf" -F "file=@your_file.pdf" -F "prompt=<image>\n<|grounding|>此处为您的自定义提示。"
   

4. 构建并运行：

   bash
   # 使用自定义配置和修复重建
   docker-compose build
   
   # 启动容器
   docker-compose up -d
   

Docker构建过程

Dockerfile在构建过程中自动应用自定义文件：

dockerfile
# 复制自定义文件替换原始文件（透明替换方法）
COPY custom_config.py ./DeepSeek-OCR-vllm/config.py
COPY custom_image_process.py ./DeepSeek-OCR-vllm/process/image_process.py

# 复制自定义运行脚本替换原始文件
COPY custom_run_dpsk_ocr_pdf.py ./DeepSeek-OCR-vllm/run_dpsk_ocr_pdf.py
COPY custom_run_dpsk_ocr_image.py ./DeepSeek-OCR-vllm/run_dpsk_ocr_image.py
COPY custom_run_dpsk_ocr_eval_batch.py ./DeepSeek-OCR-vllm/run_dpsk_ocr_eval_batch.py

这种透明替换方法确保：

• 应用关键提示参数修复
• 提供自定义配置选项
• 无需手动修改原始库代码
• 修复在容器重建中保持有效

详细文档请参见**CUSTOM_CONFIG_README.md**。

环境变量

编辑docker-compose.yml调整以下设置：

yaml
environment:
  - CUDA_VISIBLE_DEVICES=0                    # 要使用的GPU设备
  - MODEL_PATH=/app/models/deepseek-ai/DeepSeek-OCR  # 模型路径
  - MAX_CONCURRENCY=50                         # 最大并发请求数
  - GPU_MEMORY_UTIL