🎯 目标读者: 技术小白
📖 阅读后你能: 理解 OCR 原理，并独立搭建一个相同的系统
# 1. 克隆仓库
git clone https://github.com/caixingorg/ocr_engine.git
cd ocr_engine
# 2. 创建虚拟环境
python -m venv venv
source venv/bin/activate # Windows: venv\Scripts\activate
# 3. 安装依赖
pip install -r requirements.txt# 处理图片
python main.py your_image.jpg
# 处理 PDF
python main.py your_document.pdf
# 指定语言 (ch=中英混合, en=纯英文)
python main.py document.pdf --lang en
⚠️ 首次运行会下载约 1.3GB 的 AI 模型，请耐心等待。下载完成后会缓存到本地。
OCR = Optical Character Recognition（光学字符识别）
简单说：让电脑"看懂"图片里的文字。
想象你拍了一张书页的照片，照片对电脑来说只是一堆像素点（颜色格子）。OCR 就是教电脑：
- 找到哪里有文字（检测）
- 认出每个字是什么（识别）
- 按正确顺序输出文字（排序）
┌─────────────────┐ ┌─────────────────┐
│ 📷 图片输入 │ → │ 📝 文字输出 │
│ (像素点阵列) │ │ (可编辑文本) │
└─────────────────┘ └─────────────────┘
↑ ↑
你的照片 电脑识别出的文字
OCR 不是写几行代码就能实现的。电脑需要"学习"才能认字，就像小孩子需要先认识字卡才能阅读一样。
模型就是电脑学习后的"记忆"，里面存储了：
- 什么形状是"A"，什么形状是"B"
- 文字通常长什么样
- 如何区分表格和段落
我们使用的是 PP-StructureV3，它不只认字，还能：
| 能力 | 对应模型 | 大小 |
|---|---|---|
| 识别文字 | 通用 OCR 模型 | ~200MB |
| 识别表格 | 表格结构模型 | ~300MB |
| 识别公式 | 公式识别模型 | ~700MB |
| 识别版面 | 版面分析模型 | ~100MB |
这些模型是百度用数百万张图片训练出来的，所以很大。
- 太大了 — 代码几 KB，模型几 GB
- 更新频繁 — 模型会不断优化，分开更新更方便
- 按需下载 — 你只用中文就不需要下载日文模型
我们没有自己训练模型（那需要几百万张图片和几十块 GPU），而是使用百度开源的 PaddleOCR。
┌─────────────────────────────────────────────────┐
│ 我们写的代码 │
│ ┌─────────┐ ┌─────────┐ ┌─────────┐ │
│ │ main.py │ │ engine │ │handlers │ │
│ └────┬────┘ └────┬────┘ └────┬────┘ │
│ │ │ │ │
│ ▼ ▼ ▼ │
├─────────────────────────────────────────────────┤
│ PaddleOCR (百度开源) │
│ ┌──────────────────────────┐ │
│ │ PP-StructureV3 模型 │ │
│ │ (文字+表格+公式+版面) │ │
│ └──────────────────────────┘ │
├─────────────────────────────────────────────────┤
│ PaddlePaddle (深度学习框架) │
└─────────────────────────────────────────────────┘
- 封装调用 — 让复杂的 AI 模型变成简单的一行调用
- 处理 PDF — PaddleOCR 只认图片，我们把 PDF 转成图片再识别
- 格式化输出 — 把识别结果整理成好看的 Markdown 文档
- 命令行工具 — 让你能在终端直接使用
用户输入 处理流水线 最终输出
────────────────────────────────────────────────────────────────
图片.jpg ──┐
│ ┌─────────┐ ┌─────────┐
├────▶│ 图像 │────▶│ PP- │
│ │ 加载 │ │Structure│
文档.pdf ──┤ └─────────┘ │ V3 引擎 │────▶ 结果.md
│ ▲ └─────────┘
│ │ │
│ ┌────┴────┐ │
└────▶│ PDF转图 │ │
│ (逐页) │ │
└─────────┘ ▼
┌─────────┐
│ Markdown│
│ 格式化 │
└─────────┘
# main.py
python main.py 你的文件.pdf程序判断输入是图片还是 PDF：
- 图片 → 直接送去识别
- PDF → 先转成图片，再逐页识别
# PDFHandler 干的事
page = pdf文档.load_page(页码)
图片 = page.get_pixmap(zoom=2.0) # 放大2倍提高清晰度为什么要放大 2 倍？
原始 PDF 分辨率可能太低，放大后文字更清晰，识别更准确。
这是核心步骤，由 PP-StructureV3 完成：
# OCREngine 干的事
结果 = PP-StructureV3.predict(图片)它会返回类似这样的数据：
[
{'type': 'title', 'bbox': [100, 50, 500, 80], 'text': '第一章 引言'},
{'type': 'text', 'bbox': [100, 100, 500, 300], 'text': '正文内容...'},
{'type': 'table', 'bbox': [100, 350, 500, 500], 'html': '<table>...</table>'},
]每个区域包含：
type: 类型（标题/正文/表格/图片）bbox: 位置坐标 [左, 上, 右, 下]text或html: 识别出的内容
# 根据类型生成不同格式
if 类型 == 'title':
输出 "## 标题文字"
elif 类型 == 'table':
输出 HTML表格
else:
输出 普通段落with open('结果.md', 'w') as f:
f.write(markdown内容)ocr_engine/
├── main.py # 入口：解析命令行，调度各模块
├── requirements.txt # 依赖清单
└── src/
├── __init__.py # 包入口：导出公共接口
├── core/
│ ├── __init__.py
│ └── engine.py # 核心：封装 PP-StructureV3
├── handlers/
│ ├── __init__.py
│ ├── pdf.py # PDF 处理：转图片
│ └── image.py # 图片处理：加载图片
└── utils/
├── __init__.py
└── logger.py # 工具：日志记录
| 模块 | 文件 | 职责 |
|---|---|---|
| 入口 | main.py |
解析命令行参数，组织处理流程 |
| 引擎 | engine.py |
调用 AI 模型，转换输出格式 |
| PDF 处理 | pdf.py |
把 PDF 拆成一张张图片 |
| 图片处理 | image.py |
加载图片文件 |
| 日志 | logger.py |
打印进度信息 |
- Python 3.9+（推荐 3.11）
- macOS / Windows / Linux
- 约 3GB 磁盘空间（存模型）
mkdir my_ocr_engine
cd my_ocr_engine
python -m venv venv
source venv/bin/activate # Windows: venv\Scripts\activatepip install paddlepaddle paddleocr "paddlex[ocr]" pymupdf opencv-python
pip install beautifulsoup4 scikit-learn scipy创建 simple_ocr.py：
from paddleocr import PPStructureV3
import fitz # PyMuPDF
# 初始化引擎（首次会下载模型，约1.3GB）
engine = PPStructureV3(lang='ch')
# 处理图片
def ocr_image(image_path):
for result in engine.predict(image_path):
print(result) # 打印识别结果
# 处理 PDF
def ocr_pdf(pdf_path):
doc = fitz.open(pdf_path)
for page_num, page in enumerate(doc):
pix = page.get_pixmap(matrix=fitz.Matrix(2, 2))
img = pix.samples # 获取图片数据
# ... 调用 engine.predict 处理
doc.close()
# 运行
ocr_image("test.jpg")python simple_ocr.py第一次运行会下载模型，请耐心等待。
A: 首次运行需要从服务器下载 AI 模型（约 1.3GB）。下载完成后会缓存到本地，以后就快了。
A: 默认在 ~/.paddleocr/ 目录下。
A: 模型下载完成后，可以完全离线使用。
A: 尝试以下方法：
- 提高图片清晰度
- 确保光线均匀，无阴影
- 调整 PDF 转图片时的 zoom 参数
A:
ch: 中英混合（默认）en: 纯英文- 其他语言需单独安装对应模型
| 术语 | 解释 |
|---|---|
| OCR | 光学字符识别，让电脑识别图片中的文字 |
| 模型 | AI 学习后的"记忆"，存储了识别规则 |
| PaddleOCR | 百度开源的 OCR 工具包 |
| PP-StructureV3 | PaddleOCR 的版面分析模型 |
| PyMuPDF (fitz) | 处理 PDF 文件的库 |
| OpenCV (cv2) | 处理图片的库 |
| Markdown | 一种轻量级文本格式 |
文档版本: v1.0 | 更新日期: 2026-02-06