企业官网建设流程全解析

PaddleOCR 快速开始：用 whl 包一行命令完成图片与 PDF 的检测、方向分类与识别

【免费下载链接】PaddleOCRTurn any PDF or image document into structured data for your AI. A powerful, lightweight OCR toolkit that bridges the gap between images/PDFs and LLMs. Supports 100+ languages.项目地址: https://gitcode.com/GitHub_Trending/pa/PaddleOCR

导读：本文以 PaddleOCR 仓库 2.x 版本文档为主线，系统讲解 PaddleOCR whl 包（paddleocr<3.0）的安装、命令行调用与 Python 脚本调用，覆盖中英文模型、80 个语种的多语言模型、PDF 分页推理、滑动窗口切片识别等完整实操路径。读完本文，你将能够在本机快速跑通"检测 + 方向分类 + 识别"全流程，把结果以结构化 list 输出并可视化，同时理解其底层参数与源码调用关系。

1. 安装环境与 whl 包

1.1 安装 PaddlePaddle

PaddleOCR 依赖 PaddlePaddle 深度学习框架，安装前请确保 Python 环境就绪。如果没有基础的 Python 运行环境，可先参考运行环境准备。

根据硬件情况选择对应安装命令：

• 机器安装的是 CUDA 11，运行 GPU 版本：

  pip install "paddlepaddle-gpu<=2.6"

• 机器为纯 CPU 环境，运行 CPU 版本：

  pip install "paddlepaddle<=2.6"

更多版本需求可参照飞桨官网安装文档中的说明操作。

1.2 安装 PaddleOCR whl 包

pip install "paddleocr<3.0"

注意：<3.0版本约束是为了安装 2.x 系列接口（即本文描述的PaddleOCR(...).ocr(...)快速调用方式）；仓库主目录中的 paddleocr/init.py 表明新版 3.x 已演进为PaddleOCR、PaddleOCRVL、PPStructureV3、PPChatOCRv4Doc等多条产线与PaddleOCRClientAPI 客户端并存的结构。若你的项目依赖 2.x 接口，请务必锁定该版本范围。

Windows 用户注意事项：直接通过 pip 安装的 shapely 库可能出现[winError 126] 找不到指定模块的问题，建议从官方预编译站点下载 shapely 安装包完成安装。

安装完成后，可通过paddleocr -h查看全部命令行帮助信息。

2. 命令行便捷使用

PaddleOCR 提供了一系列测试图片，下载并解压后在终端切换到相应目录即可开始体验：

cd /path/to/ppocr_img

如果不使用提供的测试图片，可以将下方--image_dir参数替换为任意测试图片路径。

2.1 中英文模型

2.1.1 检测 + 方向分类器 + 识别全流程

--use_angle_cls true表示启用方向分类器以识别 180 度旋转文字，--use_gpu false表示不使用 GPU：

paddleocr --image_dir ./imgs/11.jpg --use_angle_cls true --use_gpu false

返回结果是一个 list，每个 item 包含文本框坐标、识别文字与识别置信度：

[[[28.0, 37.0], [302.0, 39.0], [302.0, 72.0], [27.0, 70.0]], ('纯臻营养护发素', 0.9658738374710083)] ......

2.1.2 支持 PDF 文件输入与分页推理

paddleocr 同样支持输入 PDF 文件，并通过参数page_num控制推理前面几页，默认为 0，表示推理所有页：

paddleocr --image_dir ./xxx.pdf --use_angle_cls true --use_gpu false --page_num 2

2.1.3 单独使用检测模块

设置--rec false关闭识别，只输出文本框：

paddleocr --image_dir ./imgs/11.jpg --rec false

结果是一个 list，每个 item 只包含文本框四点坐标：

[[27.0, 459.0], [136.0, 459.0], [136.0, 479.0], [27.0, 479.0]] [[28.0, 429.0], [372.0, 429.0], [372.0, 445.0], [28.0, 445.0]] ......

2.1.4 单独使用识别模块

设置--det false关闭检测，直接对整图/裁剪文字区域识别：

paddleocr --image_dir ./imgs_words/ch/word_1.jpg --det false

结果是一个 list，每个 item 只包含识别结果和识别置信度：

['韩国小馆', 0.994467]

2.1.5 模型版本说明

paddleocr 默认使用 PP-OCRv4 模型（--ocr_version PP-OCRv4），如需其他版本可通过--ocr_version参数切换：

从源码实现看，2.x 兼容类 paddleocr/_pipelines/ocr.py 中定义了_SUPPORTED_OCR_VERSIONS = ["PP-OCRv3", "PP-OCRv4", "PP-OCRv5", "PP-OCRv6"]，并在构造函数中对非法版本直接抛出ValueError，同时通过_get_ocr_model_names(lang, ocr_version)自动匹配对应版本的检测/识别模型名。该文件还维护了_DEPRECATED_PARAM_NAME_MAPPING（如use_angle_cls→use_textline_orientation、det_model_dir→text_detection_model_dir），用于兼容 2.x 旧参数名并给出弃用告警。

如需新增自己训练的模型，可以在 paddleocr 的模型注册处增加模型链接和字段后重新编译即可（详见下文"自定义模型"小节）。

更多 whl 包使用细节可参考 whl 包使用文档。

2.2 多语言模型

PaddleOCR 目前支持 80 个语种，可通过修改--lang参数切换，例如指定英文模型--lang=en：

paddleocr --image_dir ./imgs_en/254.jpg --lang=en

结果是一个 list，每个 item 包含文本框、文字和识别置信度：

[[[67.0, 51.0], [327.0, 46.0], [327.0, 74.0], [68.0, 80.0]], ('PHOCAPITAL', 0.9944712519645691)] [[[72.0, 92.0], [453.0, 84.0], [454.0, 114.0], [73.0, 122.0]], ('107 State Street', 0.9744491577148438)] [[[69.0, 135.0], [501.0, 125.0], [501.0, 156.0], [70.0, 165.0]], ('Montpelier Vermont', 0.9357033967971802)] ......

常用的多语言简写如下：

全部语种及其对应的缩写列表可查看多语言模型教程。该文档完整罗列了 80 个语种的缩写（如es西班牙文、ar阿拉伯文、hi印地文、vi越南文、tr土耳其文等），并给出了对应字典文件与微调示例（如rec_french_lite_train.yml对应的 french_dict.txt）。

3. Python 脚本使用

3.1 中英文与多语言全流程

通过 Python 脚本使用 whl 包时，包会自动下载 PP-OCR 轻量级模型作为默认模型：

from paddleocr import PaddleOCR, draw_ocr # Paddleocr 目前支持的多语言语种可以通过修改 lang 参数进行切换 # 例如 `ch`, `en`, `fr`, `german`, `korean`, `japan` ocr = PaddleOCR(use_angle_cls=True, lang="ch") # 只需运行一次，自动下载并加载模型到内存 img_path = './imgs/11.jpg' result = ocr.ocr(img_path, cls=True) for idx in range(len(result)): res = result[idx] for line in res: print(line) # 显示结果 from PIL import Image result = result[0] image = Image.open(img_path).convert('RGB') boxes = [line[0] for line in result] txts = [line[1][0] for line in result] scores = [line[1][1] for line in result] im_show = draw_ocr(image, boxes, txts, scores, font_path='./fonts/simfang.ttf') im_show = Image.fromarray(im_show) im_show.save('result.jpg')

结果是一个 list，每个 item 包含了文本框、文字和识别置信度：

[[[28.0, 37.0], [302.0, 39.0], [302.0, 72.0], [27.0, 70.0]], ('纯臻营养护发素', 0.9658738374710083)] ......

结果可视化效果如下图所示：

说明：在仓库 2.x 兼容类 paddleocr/_pipelines/ocr.py 中，ocr()方法被标记为@deprecated("Please use \predict` instead.")，即推荐的新式调用为ocr.predict(img)；ocr.ocr()仍然可用，但会提示改用predict。因此新代码建议直接使用ocr.predict(img_path, use_textline_orientation=True)` 等新接口。

3.2 处理 PDF 文件并逐页可视化

如果输入是 PDF 文件，可以参考下面的代码进行识别与逐页可视化：

from paddleocr import PaddleOCR, draw_ocr # Paddleocr 目前支持的多语言语种可以通过修改 lang 参数进行切换 # 例如 `ch`, `en`, `fr`, `german`, `korean`, `japan` PAGE_NUM = 10 # 将识别页码前置作为全局，防止后续打开 pdf 的参数和前文识别参数不一致 pdf_path = 'default.pdf' ocr = PaddleOCR(use_angle_cls=True, lang="ch", page_num=PAGE_NUM) # 只需运行一次，自动下载并加载模型 # ocr = PaddleOCR(use_angle_cls=True, lang="ch", page_num=PAGE_NUM, use_gpu=0) # 如需使用 GPU，取消此行注释并注释上一行 result = ocr.ocr(pdf_path, cls=True) for idx in range(len(result)): res = result[idx] if res is None: # 识别到空页就跳过，防止程序报错 print(f"[DEBUG] Empty page {idx+1} detected, skip it.") continue for line in res: print(line) # 显示结果 import fitz from PIL import Image import cv2 import numpy as np imgs = [] with fitz.open(pdf_path) as pdf: for pg in range(0, PAGE_NUM): page = pdf[pg] mat = fitz.Matrix(2, 2) pm = page.get_pixmap(matrix=mat, alpha=False) # 如果宽或高超过 2000 像素，则不再放大图片 if pm.width > 2000 or pm.height > 2000: pm = page.get_pixmap(matrix=fitz.Matrix(1, 1), alpha=False) img = Image.frombytes("RGB", [pm.width, pm.height], pm.samples) img = cv2.cvtColor(np.array(img), cv2.COLOR_RGB2BGR) imgs.append(img) for idx in range(len(result)): res = result[idx] if res is None: continue image = imgs[idx] boxes = [line[0] for line in res] txts = [line[1][0] for line in res] scores = [line[1][1] for line in res] im_show = draw_ocr(image, boxes, txts, scores, font_path='doc/fonts/simfang.ttf') im_show = Image.fromarray(im_show) im_show.save('result_page_{}.jpg'.format(idx))

关键点说明：

• 使用page_num控制参与推理的 PDF 页数，需保证其与后续打开 PDF 的页数一致；
• 用 PyMuPDF（fitz）将 PDF 页面渲染为图像，2 倍矩阵放大以保证小字清晰，超过 2000 像素则回到 1 倍防止内存膨胀；
• 空页检测结果可能为None，务必做跳过处理，避免TypeError: NoneType。

3.3 使用滑动窗口切片处理超大图

对超大图像或长文档执行检测识别时，可启用滑动窗口切片（slicing）模式。核心代码片段：

from paddleocr import PaddleOCR from PIL import Image, ImageDraw, ImageFont # 初始化 OCR 引擎 ocr = PaddleOCR(use_angle_cls=True, lang="en") img_path = "./very_large_image.jpg" slice = {'horizontal_stride': 300, 'vertical_stride': 500, 'merge_x_thres': 50, 'merge_y_thres': 35} results = ocr.ocr(img_path, cls=True, slice=slice) # 加载图像 image = Image.open(img_path).convert("RGB") draw = ImageDraw.Draw(image) font = ImageFont.truetype("./doc/fonts/simfang.ttf", size=20) # 根据需要调整大小 # 处理并绘制结果 for res in results: for line in res: box = [tuple(point) for point in line[0]] # 找出边界框 box = [(min(point[0] for point in box), min(point[1] for point in box)), (max(point[0] for point in box), max(point[1] for point in box))] txt = line[1][0] draw.rectangle(box, outline="red", width=2) # 绘制矩形 draw.text((box[0][0], box[0][1] - 25), txt, fill="blue", font=font) # 在矩形上方绘制文本 # 保存结果 image.save("result.jpg")

此示例初始化了启用角度分类的 PaddleOCR 实例并将语言设置为英语，然后调用ocr方法，通过slice参数自定义切片过程。切片的工作原理是：在大图上运行一个滑动窗口，创建图像切片并逐一执行 OCR，再将切片级零散结果按邻近阈值合并，生成整图级别的检测和识别结果。

参数语义如下：

• horizontal_stride/vertical_stride：水平/垂直方向的窗口滑动步幅。步幅不宜过低，否则切片数量爆炸，计算耗时显著上升；文档给出的 6616×14886 大图推荐配置为{'horizontal_stride': 300, 'vertical_stride': 500, 'merge_x_thres': 50, 'merge_y_thres': 35}；
• merge_x_thres/merge_y_thres：切片间检测框在 x/y 方向上的合并阈值，所有边界框间距接近这两个阈值的切片级检测结果会被合并为一个目标。

更全面的切片操作说明可参考切片操作文档。

4. 常用参数速查

下表汇总了 whl 包（2.x 系列）最常用的核心参数及其默认值，便于在命令行或代码中精准调参：

值得注意的是，上述部分 2.x 参数在 paddleocr/_pipelines/ocr.py 中被声明为弃用并映射到新参数：use_angle_cls→use_textline_orientation、det_db_thresh→text_det_thresh、det_db_box_thresh→text_det_box_thresh、det_db_unclip_ratio→text_det_unclip_ratio、rec_batch_num→text_recognition_batch_size等，同时新版PaddleOCR构造函数新增了use_doc_orientation_classify（文档方向分类）与use_doc_unwarping（文档图像矫正）两个预处理开关，对应内部DocPreprocessor子管线。

5. 自定义模型接入

当内置模型无法满足需求时，可接入自己训练并导出的模型。首先参照模型导出教程将检测、分类、识别模型转换为 inference 模型（目录下必须包含 model 和 params 文件），然后：

代码方式：

from paddleocr import PaddleOCR, draw_ocr # 模型路径下必须含有 model 和 params 文件 ocr = PaddleOCR(det_model_dir='{your_det_model_dir}', rec_model_dir='{your_rec_model_dir}', rec_char_dict_path='{your_rec_char_dict_path}', cls_model_dir='{your_cls_model_dir}', use_angle_cls=True) img_path = './imgs/11.jpg' result = ocr.ocr(img_path, cls=True) for idx in range(len(result)): res = result[idx] for line in res: print(line)

命令行方式：

paddleocr --image_dir ./imgs/11.jpg --det_model_dir {your_det_model_dir} --rec_model_dir {your_rec_model_dir} --rec_char_dict_path {your_rec_char_dict_path} --cls_model_dir {your_cls_model_dir} --use_angle_cls true

自定义模型时务必同步指定rec_char_dict_path指向训练时使用的字典文件（仓库内置字典位于 ppocr/utils/dict 目录）。多语言模型的训练微调流程可参考多语言模型教程中的法文模型示例，其对应的训练配置为 rec_french_lite_train.yml。

6. 小结

通过本文，你已掌握 PaddleOCR whl 包的完整使用链路：从 PaddlePaddle 与paddleocr<3.0的安装，到命令行一行完成"检测 + 方向分类 + 识别"全流程与 PDF 分页推理，再到 Python 脚本中实现多语言识别、结果可视化、超大图滑动窗口切片，以及核心参数的调参与自定义模型接入。基于 paddleocr/_pipelines/ocr.py 的源码可以看到，2.x 接口在新版本中仍然保持兼容并映射到 PaddleX 产线体系，可平滑迁移到predict新接口。后续如需进一步体验文档分析（版面解析、表格识别、公式识别、印章识别等），可参考 PP-Structure 快速使用教程。

【免费下载链接】PaddleOCRTurn any PDF or image document into structured data for your AI. A powerful, lightweight OCR toolkit that bridges the gap between images/PDFs and LLMs. Supports 100+ languages.项目地址: https://gitcode.com/GitHub_Trending/pa/PaddleOCR