📚 课程目录第4章 PaddleOCR环境搭建与快速上手

4. PaddleOCR 环境搭建与快速上手

本章是进入 OCR 工程实战的第一步。我们将完成 PaddlePaddle 深度学习框架的安装、PaddleOCR 源码的获取，并通过命令行与 Python API 两种方式验证环境是否可用。掌握本节内容后，你就能在自己的机器上运行第一个 OCR 识别任务。

4.1 环境概览与版本对齐

PaddleOCR 对 Python、PaddlePaddle 以及 CUDA 版本有明确的依赖关系。在开始安装前，请确认你的硬件与系统满足下表要求：

组件	推荐版本	最低版本	备注
Python	3.10	3.8	建议使用 conda 虚拟环境
PaddlePaddle	2.6.0	2.4.0	GPU 版需 CUDA 11.7+
CUDA	11.8	11.2	仅 GPU 推理需要
cuDNN	8.6	8.2	与 CUDA 版本匹配
操作系统	Ubuntu 22.04	Ubuntu 18.04 / Windows 10	macOS 仅支持 CPU

💡 环境隔离建议： 使用 conda create -n paddleocr python=3.10 创建独立虚拟环境，避免与已有项目发生依赖冲突。

4.2 PaddlePaddle 安装

PaddlePaddle 是 PaddleOCR 的底层计算引擎。根据你的硬件条件选择 CPU 或 GPU 版本：

4.2.1 CPU 版本（通用兼容）

# 安装 CPU 版 PaddlePaddle
pip install paddlepaddle==2.6.0 -i https://mirror.baidu.com/pypi/simple

4.2.2 GPU 版本（推荐生产环境）

# CUDA 11.8 + cuDNN 8.6
pip install paddlepaddle-gpu==2.6.0 -i https://mirror.baidu.com/pypi/simple

⚠️ 版本验证： 安装完成后执行 python -c "import paddle; print(paddle.__version__); print('GPU available:', paddle.is_compiled_with_cuda())"，确认输出版本号且 GPU 可用性为 True（GPU 版）。

4.3 PaddleOCR 源码下载与结构

PaddleOCR 官方仓库托管在 GitHub 和 Gitee。推荐使用 Gitee 镜像加速国内下载：

# 从 Gitee 克隆（国内推荐）
git clone https://gitee.com/paddlepaddle/PaddleOCR.git

# 或从 GitHub 克隆
git clone https://github.com/PaddlePaddle/PaddleOCR.git

# 进入目录并安装依赖
cd PaddleOCR
pip install -r requirements.txt -i https://mirror.baidu.com/pypi/simple

下载后的目录结构关键部分如下：

目录/文件	说明
`ppocr/`	核心模型代码，包含检测、识别、分类模块
`tools/`	训练、评估、推理脚本
`deploy/`	部署方案（C++、Serving、移动端等）
`doc/`	文档与教程
`pretrain_models/`	预训练模型存放目录（需自行下载）

4.4 命令行快速体验

PaddleOCR 提供了开箱即用的命令行工具。以下演示使用内置的轻量模型对一张示例图片进行文字识别：

# 使用内置检测+识别模型，对图片进行端到端 OCR
python tools/infer/predict_system.py \
    --image_dir="doc/imgs/11.jpg" \
    --det_model_dir="inference/ch_PP-OCRv4_det_infer" \
    --rec_model_dir="inference/ch_PP-OCRv4_rec_infer" \
    --cls_model_dir="inference/ch_ppocr_mobile_v2.0_cls_infer" \
    --use_angle_cls=True \
    --use_gpu=True

命令执行后，终端会逐行输出识别结果，格式为 [[[x1,y1],[x2,y2],[x3,y3],[x4,y4]], (text, confidence)]，同时会在 inference_results/ 目录下生成带标注框的可视化图片。

🔑 关键参数说明：
--image_dir：支持单张图片路径或包含图片的目录。
--det_model_dir：文本检测模型路径。
--rec_model_dir：文本识别模型路径。
--use_angle_cls：是否启用文字方向分类，建议开启以处理旋转文本。
--use_gpu：是否使用 GPU 加速。

4.5 Python API 调用演示

在工程集成场景中，我们通常使用 Python API 而非命令行。以下代码展示了如何在 Python 脚本中加载模型并执行 OCR：

from paddleocr import PaddleOCR

# 初始化 OCR 引擎
ocr = PaddleOCR(
    use_angle_cls=True,   # 启用方向分类
    lang='ch',            # 中文模型
    use_gpu=True,         # 使用 GPU
    det_db_thresh=0.3,    # 检测阈值
    rec_batch_num=6       # 识别批大小
)

# 执行识别
img_path = 'doc/imgs/11.jpg'
result = ocr.ocr(img_path, cls=True)

# 解析结果
for line in result[0]:
    bbox = line[0]          # 文本框坐标
    text = line[1][0]       # 识别文字
    confidence = line[1][1] # 置信度
    print(f'文字: {text}, 置信度: {confidence:.4f}')
    print(f'坐标: {bbox}')

输出示例：

文字: 纯臻营养护发素, 置信度: 0.9921
坐标: [[107.0, 36.0], [304.0, 36.0], [304.0, 64.0], [107.0, 64.0]]
文字: 产品编号/条形码, 置信度: 0.9813
坐标: [[107.0, 80.0], [304.0, 80.0], [304.0, 104.0], [107.0, 104.0]]
...

4.6 环境验证与常见问题

完成上述步骤后，建议执行以下完整性检查：

框架可用性： python -c "import paddle; print(paddle.__version__)"
OCR 模块导入： python -c "from paddleocr import PaddleOCR; print('PaddleOCR imported successfully')"
模型下载： 首次调用 PaddleOCR() 时会自动下载预训练模型，请保持网络畅通。
推理速度： 对一张 640×480 图片，GPU 推理应在 0.5~2 秒内完成，CPU 推理在 3~8 秒内完成。

⚠️ 常见错误排查：

ImportError: No module named 'paddle' → 未安装 PaddlePaddle 或虚拟环境未激活。
Out of memory → 减小 rec_batch_num 或使用 CPU 模式。
模型下载超时 → 手动下载模型文件放入 inference/ 目录，或设置代理。
中文乱码 → 确保系统字体支持中文，或指定 lang='ch'。

4.7 PaddleOCR 推理流程架构

下图展示了 PaddleOCR 从输入图像到输出结构化文本的完整推理流水线：

4.8 本章小结

通过本章学习，你已经完成了 PaddleOCR 的完整环境搭建，并掌握了两种调用方式：

命令行方式：适合快速验证、批量测试和脚本集成。
Python API 方式：适合嵌入到业务系统、二次开发和自定义后处理。

下一阶段我们将深入模型选型与精度调优，为运费成本模型的数据采集环节提供高质量的 OCR 识别能力。