一、开发环境准备与依赖安装
在开始编写代码之前，必须先配置好基础的 Python 运行环境。本指南基于 Python 3.8 或 3.9 版本进行演示，兼容性最佳。请确保你的系统已经安装了 Python，并配置好了环境变量。
我们需要创建一个独立的虚拟环境来隔离项目依赖，避免与其他项目产生冲突。打开终端（Windows 下为 CMD 或 PowerShell，Linux/Mac 下为 Terminal），执行以下命令：
```bash
创建名为 ocr_archive 的虚拟环境
python -m venv ocr_archive
激活虚拟环境
Windows 下执行：
ocr_archive\Scripts\activate
Linux/Mac 下执行：
source ocr_archive/bin/activate
```
环境激活后，接下来安装核心依赖库。PaddleOCR 是百度开源的超轻量级 OCR 模型，识别准确率高且对中文支持极好，非常适合处理文书档案。同时，我们需要安装 PaddlePaddle 作为底层深度学习框架，以及处理 PDF 和 Excel 的辅助库。
执行以下安装命令。请注意，这里默认安装 CPU 版本，确保所有电脑都能直接运行，无需配置显卡驱动：
```bash
安装 PaddlePaddle CPU 版本
pip install paddlepaddle==2.5.1 -i https://mirror.baidu.com/pypi/simple
安装 PaddleOCR 及其模型自动下载工具
pip install paddleocr==2.7.0.3
安装图像处理、PDF转换及表格处理库
pip install Pillow pdf2image pandas openpyxl
```
关键注意点：处理 PDF 文件需要系统安装 Poppler 工具，这是将 PDF 页面转换为图片的必要组件，很多初学者容易在此处卡壳。
- Windows 用户：访问
https://github.com/oschwartz10612/poppler-windows/releases/ 下载最新版 Release，解压后将 bin 文件夹路径（如 C:\poppler-xx\bin）添加到系统的 Path 环境变量中。
- Linux 用户：执行
sudo apt-get install poppler-utils。
- Mac 用户：执行
brew install poppler。
二、单张文书档案识别核心代码实现
在处理批量档案之前，我们先通过一个简单的脚本验证单张图片的识别效果。PaddleOCR 的使用非常简洁，初始化模型后，直接调用 ocr 方法即可返回结果。
创建一个名为 single_test.py 的文件，输入以下代码：
```python
from paddleocr import PaddleOCR
import cv2
初始化 PaddleOCR
use_angle_cls=True: 启用文字方向分类，识别倒置或侧放的文字
lang="ch": 指定中英文识别模型
ocr = PaddleOCR(use_angle_cls=True, lang="ch", show_log=False)
指定图片路径
img_path = './demo.jpg'
执行识别
result = ocr.ocr(img_path, cls=True)
解析并打印结果
result 是一个三维列表，结构为 [ [ [坐标], (文本, 置信度) ], ... ]
if result[0]:
for idx in range(len(result[0])):
res = result[0][idx]
提取文本内容和置信度
text_content = res[1][0]
confidence = res[1][1]
只打印置信度大于 0.5 的结果，过滤噪点
if confidence > 0.5:
print(f"识别内容: {text_content} | 置信度: {confidence:.4f}")
else:
print("未识别到文字")
```
运行此脚本前，请将一张名为 demo.jpg 的文书档案图片放在同级目录下。第一次运行时，程序会自动从官网下载约 4MB 的轻量级模型文件，请保持网络通畅。识别结果会包含文本内容及其在图片中的坐标信息。
三、PDF 文书档案批量转换与处理
实际的文书档案多以 PDF 格式存在，且往往是多页文档。为了提高识别率，我们需要将 PDF 每一页转换为高清晰度的图片，然后再送入 OCR 引擎。
创建一个工具类文件 pdf_utils.py，专门处理 PDF 转图片的逻辑：
```python
from pdf2image import convert_from_path
import os
def pdf_to_images(pdf_path, output_folder, dpi=300):
"""
将 PDF 文件转换为图片列表
:param pdf_path: PDF 文件路径
:param output_folder: 图片临时保存目录
:param dpi: 分辨率，越高越清晰但速度越慢，建议 200-300
:return: 图片路径列表
"""
if not os.path.exists(output_folder):
os.makedirs(output_folder)
print(f"正在转换 PDF: {pdf_path} ...")
try:
使用 pdf2image 进行转换
thread_count=3 启用多线程加速转换
pages = convert_from_path(pdf_path, dpi=dpi, thread_count=3)
image_paths = []
pdf_name = os.path.splitext(os.path.basename(pdf_path))[0]
for i, page in enumerate(pages):
保存为 JPG 格式
image_path = os.path.join(output_folder, f"{pdf_name}_page_{i+1}.jpg")
page.save(image_path, 'JPEG')
image_paths.append(image_path)
return image_paths
except Exception as e:
print(f"PDF 转换失败: {e}")
return []
```
四、完整批量识别与结果导出实战
下面我们将所有逻辑整合，编写一个完整的自动化脚本。该脚本会遍历指定文件夹下的所有 PDF 文件，将其转换为图片，进行 OCR 识别，并将结果结构化地保存到 Excel 表格中。Excel 将包含四列：文件名、页码、识别文本内容、置信度。
创建主程序文件 archive_ocr_main.py：
```python
import os
import pandas as pd
from paddleocr import PaddleOCR
from pdf_utils import pdf_to_images
import time
class ArchiveOCR:
def __init__(self, input_folder, output_excel):
self.input_folder = input_folder
self.output_excel = output_excel
初始化 OCR 模型，全局只初始化一次，提高效率
self.ocr = PaddleOCR(use_angle_cls=True, lang="ch", show_log=False)
self.temp_img_folder = "./temp_images"
self.all_results = []
def process_single_image(self, img_path, pdf_name, page_num):
"""处理单张图片并提取文本"""
try:
result = self.ocr.ocr(img_path, cls=True)
if not result or not result[0]:
return
for line in result[0]:
text = line[1][0]
conf = float(line[1][1])
过滤低置信度和非文本字符
if conf > 0.6 and text.strip():
row_data = {
"文件名": pdf_name,
"页码": page_num,
"识别内容": text.strip(),
"置信度": conf
}
self.all_results.append(row_data)
print(f"[{pdf_name}-P{page_num}] {text}")
except Exception as e:
print(f"识别图片出错 {img_path}: {e}")
def run(self):
start_time = time.time()
遍历输入文件夹
files = os.listdir(self.input_folder)
pdf_files = [f for f in files if f.lower().endswith('.pdf')]
if not pdf_files:
print("未在文件夹中找到 PDF 文件")
return
print(f"共发现 {len(pdf_files)} 个 PDF 文件，开始处理...")
for pdf_file in pdf_files:
pdf_path = os.path.join(self.input_folder, pdf_file)
pdf_name = os.path.splitext(pdf_file)[0]
1. PDF 转图片
image_paths = pdf_to_images(pdf_path, self.temp_img_folder)
2. 逐页识别
for idx, img_path in enumerate(image_paths):
self.process_single_image(img_path, pdf_name, idx + 1)
清理临时图片文件，节省磁盘空间
if os.path.exists(img_path):
os.remove(img_path)
3. 保存结果到 Excel
if self.all_results:
df = pd.DataFrame(self.all_results)
按文件名和页码排序
df.sort_values(by=['文件名', '页码'], inplace=True)
df.to_excel(self.output_excel, index=False, engine='openpyxl')
print(f"\n处理完成！结果已保存至: {self.output_excel}")
else:
print("\n未识别到任何有效文本内容")
end_time = time.time()
print(f"总耗时: {end_time - start_time:.2f} 秒")
if __name__ == "__main__":
配置输入输出路径
INPUT_DIR = "./archives" 请在此处放置你的 PDF 文件
OUTPUT_FILE = "./ocr_result.xlsx"
if not os.path.exists(INPUT_DIR):
os.makedirs(INPUT_DIR)
print(f"已创建输入文件夹 {INPUT_DIR}，请将 PDF 文件放入其中后重新运行。")
else:
app = ArchiveOCR(INPUT_DIR, OUTPUT_FILE)
app.run()
```
五、实操步骤与验证
为了确保你能零门槛运行上述代码，请严格按照以下步骤操作：
1. 准备目录结构：
在代码同级目录下创建一个名为 archives 的文件夹，将你需要识别的文书档案 PDF 文件复制进去。
2. 运行脚本：
在终端中执行：
```bash
python archive_ocr_main.py
```
3. 观察输出：
终端会实时打印正在处理的文件名和识别出的关键文本片段。如果第一次运行，你会看到提示下载模型文件的进度条。模型文件会自动缓存到 ~/.paddleocr/ 目录下，后续运行无需重新下载。
4. 检查结果：
程序运行结束后，打开目录下生成的 ocr_result.xlsx。你应该能看到所有档案中的文字已被提取出来。如果识别结果有乱码或漏字，通常是因为 PDF 分辨率过低或扫描件有噪点，可以在 pdf_utils.py 中将 dpi 参数调整为 400 或更高。
六、常见报错与参数调优
在实操过程中，你可能会遇到以下特定问题，这里给出直接的解决方案：
1. 报错：FileNotFoundError: 'poppler' not found
这完全是因为没有按照第二章节的说明安装 Poppler 或者环境变量未生效。请检查 Poppler 的 bin 目录是否已添加到 Path 中，并在安装后重启 IDE 或终端。
2. 识别速度慢
默认使用 CPU 运行，处理大量高分辨率 PDF 会较慢。如果电脑有 NVIDIA 显卡且安装了 CUDA，可以卸载 CPU 版 PaddlePaddle 并安装 GPU 版：
```bash
pip uninstall paddlepaddle
pip install paddlepaddle-gpu==2.5.1
```
3. 识别率不高（如手写字体、繁体）
修改初始化代码中的 lang 参数。PaddleOCR 支持多种语言模型：
lang="ch": 简体中文（默认）lang="chinese_cht": 繁体中文lang="en": 英文
如果是表格类的文书档案，可以使用 PaddleOCR 的 Structure 模式，但需要加载更大的模型，参数改为 use_angle_cls=True, lang="ch", table=True，此时返回结果会包含 HTML 格式的表格结构。
