# PDF OCR VL

**Repository Path**: ginkdu/pdf-ocr-vl

## Basic Information

- **Project Name**: PDF OCR VL
- **Description**: 基于 RapidOCR + PaddleOCR-VL 混合架构的高性能 PDF OCR 识别生成双层PDF的工具。
- **Primary Language**: Unknown
- **License**: MIT
- **Default Branch**: master
- **Homepage**: None
- **GVP Project**: No

## Statistics

- **Stars**: 1
- **Forks**: 0
- **Created**: 2026-06-06
- **Last Updated**: 2026-07-03

## Categories & Tags

**Categories**: Uncategorized

**Tags**: PaddleOCR-VL, pdf, ocr

## README

# PDF OCR VL

基于 **RapidOCR + PaddleOCR-VL** 混合架构的高性能 PDF OCR 识别工具。

## 项目简介

PDF OCR VL 是一个高效的 PDF 文字识别工具，采用创新的 **CPU/GPU 混合架构**：

- **CPU 侧**：使用 RapidOCR 进行文字检测、方向分类和图像裁剪
- **GPU 侧**：通过 llama.cpp HTTP 服务调用 PaddleOCR-VL 进行高精度文字识别

通过生产者-消费者模式协调 CPU 和 GPU 资源，实现高效的并行处理。

## 核心特性

- **混合架构**：CPU 负责 RapidOCR 检测，GPU 通过 llama.cpp HTTP 服务调用 PaddleOCR-VL 识别，充分利用硬件资源
- **高精度识别**：基于 PaddleOCR-VL 大模型，识别精度显著优于传统 OCR 方案
- **智能方向校正**：自动检测并校正页面旋转（0°/90°/180°/270°）
- **原生 DPI 支持**：自动识别 PDF 内嵌图像的原始分辨率，智能选择渲染参数
- **双层 PDF 输出**：生成可搜索的双层 PDF，保留原始图像层的同时添加文字层
- **异步并发处理**：支持多任务并发识别，显著提升处理速度
- **灵活配置**：支持 mobile/server 两种检测模型，Q4/Q8 两种识别精度

## 技术架构

```
PDF 文件
    ↓
[页面渲染] → [矢量页旋转校正]
    ↓
[方向分类] → [图像旋转校正]
    ↓
[RapidOCR 检测] → [文字区域裁剪]
    ↓
[Base64 编码] → [HTTP 请求] → [llama.cpp 服务] → PaddleOCR-VL (GPU)
    ↓
[结果聚合] → [双层 PDF 生成]
```

### 处理流程

1. **CPU 生产者**：逐页渲染 PDF → 矢量页旋转校正 → 页面方向分类+旋转 → RapidOCR 检测+分类+裁剪
2. **GPU 消费者**：从队列取页 → 逐框 base64 编码 → 通过 HTTP 调用 llama.cpp 服务进行异步并发识别
3. **聚合消费者**：组装结果 → 生成可搜索 PDF

## 安装

### 环境要求

- Python 3.13+
- llama.cpp 服务端（用于 PaddleOCR-VL 推理）

## 使用方法

### 命令行接口

```bash
# 基本用法（使用默认推荐配置）
pdf-ocr-vl input.pdf -o output_dir

# 使用 server 检测模型和 Q8 精度（高精度模式）
pdf-ocr-vl input.pdf --onnx-model server --vl-model Q8

# 调整并发数和 DPI
pdf-ocr-vl input.pdf --max-workers 16 --dpi 200

# 启用详细日志和调试输出
pdf-ocr-vl input.pdf --verbose --debug-json

# 指定 llama-server 地址
pdf-ocr-vl input.pdf --llama-url http://localhost:8080
```

### 参数说明

| 参数 | 说明 | 默认值 |
|------|------|--------|
| `input_path` | 输入 PDF 文件路径 | 必填 |
| `-o, --output` | 输出目录 | 输入文件同目录 |
| `-t, --output-type` | 输出格式 | pdf |
| `--onnx-model` | RapidOCR 检测模型 (mobile/server) | mobile |
| `--vl-model` | PaddleOCR-VL 精度 (Q4/Q8) | Q4 |
| `--dpi` | PDF 渲染 fallback 分辨率 | 150 |
| `-w, --max-workers` | GPU 侧最大并发请求数 | 8 |
| `--llama-url` | llama-server 地址 | localhost:8080 |
| `-v, --verbose` | 显示详细日志 | False |
| `--debug-json` | 输出调试 JSON | False |

## 模型配置

项目支持两种 RapidOCR 检测模型：

- **mobile**：轻量级模型，速度快，适合实时处理（推荐）
- **server**：服务端模型，精度高，适合批量处理

PaddleOCR-VL 支持两种量化精度：

- **Q4**：4-bit 量化，模型体积小，推理速度快（推荐）
- **Q8**：8-bit 量化，精度更高，适合对识别质量要求高的场景

**推荐配置**：RapidOCR 检测模型使用 `mobile`，llama.cpp 端的 PaddleOCR-VL 使用 `Q4`，可在速度和精度间取得良好平衡。

## 相关项目

- **[PDF OCR VL GUI](https://gitee.com/ginkdu/pdf_-ocr_-vl_-gui)** - PDF OCR VL 的图形用户界面版本，提供友好的可视化操作体验
- **[PaddleOCR VL Server GUI](https://gitee.com/ginkdu/paddle-ocr-vl-server_-gui)** - PaddleOCR-VL 推理服务的图形化管理工具，方便启动和管理 llama-server

## 性能优化

- **CPU/GPU 并行**：通过异步队列实现 CPU 检测和 GPU 识别的流水线并行
- **智能 DPI 选择**：自动识别 PDF 原图分辨率，避免不必要的重采样
- **并发控制**：可调整 `max_workers` 参数优化 GPU 利用率
- **内存优化**：流式处理，避免一次性加载所有页面图像

## 许可证

本项目采用 MIT 许可证。

## 致谢

- [PaddleOCR](https://github.com/PaddlePaddle/PaddleOCR) - 提供 PaddleOCR-VL 模型
- [RapidOCR](https://github.com/RapidAI/RapidOCR) - 提供高效的文字检测引擎
- [PyMuPDF](https://github.com/pymupdf/PyMuPDF) - 提供 PDF 处理能力
- [llama.cpp](https://github.com/ggerganov/llama.cpp) - 提供 GGUF 模型推理支持