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

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 包paddleocr3.0的安装、命令行调用与 Python 脚本调用覆盖中英文模型、80 个语种的多语言模型、PDF 分页推理、滑动窗口切片识别等完整实操路径。读完本文你将能够在本机快速跑通检测 方向分类 识别全流程把结果以结构化 list 输出并可视化同时理解其底层参数与源码调用关系。1. 安装环境与 whl 包1.1 安装 PaddlePaddlePaddleOCR 依赖 PaddlePaddle 深度学习框架安装前请确保 Python 环境就绪。如果没有基础的 Python 运行环境可先参考运行环境准备。根据硬件情况选择对应安装命令机器安装的是 CUDA 11运行 GPU 版本pip install paddlepaddle-gpu2.6机器为纯 CPU 环境运行 CPU 版本pip install paddlepaddle2.6更多版本需求可参照飞桨官网安装文档中的说明操作。1.2 安装 PaddleOCR whl 包pip install paddleocr3.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表示不使用 GPUpaddleocr --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 22.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参数切换版本名称版本说明PP-OCRv4支持中、英文检测和识别方向分类器支持多语种识别PP-OCRv3支持中、英文检测和识别方向分类器支持多语种识别PP-OCRv2支持中英文的检测和识别方向分类器多语言暂未更新PP-OCR支持中、英文检测和识别方向分类器支持多语种识别从源码实现看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参数切换例如指定英文模型--langenpaddleocr --image_dir ./imgs_en/254.jpg --langen结果是一个 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)] ......常用的多语言简写如下语种缩写语种缩写语种缩写中文ch法文fr日文japan英文en德文german韩文korean繁体中文chinese_cht意大利文it俄罗斯文ru全部语种及其对应的缩写列表可查看多语言模型教程。该文档完整罗列了 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_clsTrue, langch) # 只需运行一次自动下载并加载模型到内存 img_path ./imgs/11.jpg result ocr.ocr(img_path, clsTrue) 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_orientationTrue) 等新接口。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_clsTrue, langch, page_numPAGE_NUM) # 只需运行一次自动下载并加载模型 # ocr PaddleOCR(use_angle_clsTrue, langch, page_numPAGE_NUM, use_gpu0) # 如需使用 GPU取消此行注释并注释上一行 result ocr.ocr(pdf_path, clsTrue) for idx in range(len(result)): res result[idx] if res is None: # 识别到空页就跳过防止程序报错 print(f[DEBUG] Empty page {idx1} 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(matrixmat, alphaFalse) # 如果宽或高超过 2000 像素则不再放大图片 if pm.width 2000 or pm.height 2000: pm page.get_pixmap(matrixfitz.Matrix(1, 1), alphaFalse) 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_pathdoc/fonts/simfang.ttf) im_show Image.fromarray(im_show) im_show.save(result_page_{}.jpg.format(idx))关键点说明使用page_num控制参与推理的 PDF 页数需保证其与后续打开 PDF 的页数一致用 PyMuPDFfitz将 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_clsTrue, langen) 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, clsTrue, sliceslice) # 加载图像 image Image.open(img_path).convert(RGB) draw ImageDraw.Draw(image) font ImageFont.truetype(./doc/fonts/simfang.ttf, size20) # 根据需要调整大小 # 处理并绘制结果 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, outlinered, width2) # 绘制矩形 draw.text((box[0][0], box[0][1] - 25), txt, fillblue, fontfont) # 在矩形上方绘制文本 # 保存结果 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 系列最常用的核心参数及其默认值便于在命令行或代码中精准调参字段说明默认值use_gpu是否使用 GPUTRUEgpu_mem初始化占用的 GPU 内存大小8000Mimage_dir命令行调用时执行的图片或文件夹路径-page_num输入为 PDF 时生效预测前 page_num 页默认预测所有页0det_algorithm使用的检测算法类型DBdet_model_dir检测模型目录None 时自动下载内置模型到~/.paddleocr/det或传自定义 inference 模型路径必须含 model 和 params 文件Nonedet_max_side_len检测前向时图片长边最大尺寸超出则等比缩放960det_db_threshDB 模型输出预测图的二值化阈值0.3det_db_box_threshDB 模型输出框阈值低于该值的框被丢弃0.5det_db_unclip_ratioDB 模型输出框扩大的比例2det_db_score_mode检测框 score 计算方式fast 或 slow文字弯曲场景建议 slow其 box score 偏大不易被过滤fastdet_east_score_threshEAST 模型输出预测图的二值化阈值0.8det_east_cover_threshEAST 模型输出框阈值0.1det_east_nms_threshEAST 模型输出框 NMS 阈值0.2rec_algorithm使用的识别算法类型CRNNrec_model_dir识别模型目录None 时自动下载内置模型到~/.paddleocr/recNonerec_image_shape识别算法的输入图片尺寸3,32,320rec_batch_num识别时同时前向的图片数30max_text_length识别算法能识别的最大文字长度25rec_char_dict_path识别模型字典路径使用自定义识别模型时需改为自己的字典./ppocr/utils/ppocr_keys_v1.txtuse_space_char是否识别空格TRUEdrop_score按识别分数过滤输出低于该分数的不返回0.5use_angle_cls是否加载方向分类模型FALSEcls_model_dir方向分类模型目录None 时自动下载内置模型到~/.paddleocr/clsNonecls_image_shape分类算法的输入图片尺寸3, 48, 192label_list分类算法的标签列表[0, 180]cls_batch_num分类时同时前向的图片数30enable_mkldnn是否启用 MKL-DNN 加速FALSEuse_zero_copy_run是否通过 zero_copy_run 方式进行前向FALSElang模型语言类型ch/en/french/german/korean/japan 等chdet前向时是否启动检测TRUErec前向时是否启动识别TRUEcls前向时是否启动分类命令行模式由 use_angle_cls 控制FALSEshow_log是否打印 logger 信息FALSEtype执行 OCR 或表格结构化可选 [ocr,structure]ocrocr_versionOCR 模型版本PP-OCRv3/PP-OCRv2/PP-OCR 等PP-OCRv32.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_clsTrue) img_path ./imgs/11.jpg result ocr.ocr(img_path, clsTrue) 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 与paddleocr3.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创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考