尧图网站建设 
PaddleOCR whl 包使用指南从安装、全流程推理到自定义模型部署【免费下载链接】PaddleOCR飞桨多语言OCR工具包实用超轻量OCR系统支持80种语言识别提供数据标注与合成工具支持服务器、移动端、嵌入式及IoT设备端的训练与部署 Awesome multilingual OCR toolkits based on PaddlePaddle (practical ultra lightweight OCR system, support 80 languages recognition, provide data annotation and synthesis tools, support training and deployment among server, mobile, embedded and IoT devices)项目地址: https://gitcode.com/paddlepaddle/PaddleOCRPaddleOCR 提供了开箱即用的 Python 安装包whl通过一条pip install即可获得完整的文本检测、方向分类与文字识别能力既支持 Python 代码调用也支持命令行直接推理还支持图片、网络图片、numpy 数组与 PDF 文件等多种输入形式。本文以 docs/version2.x/ppocr/blog/whl.md 为主线结合当前仓库的 paddleocr/_pipelines/ocr.py 源码实现系统讲解 whl 包的安装方式、五大使用场景、自定义模型加载方法以及全部核心参数的语义帮助你快速在真实项目中落地 PaddleOCR。说明本文面向 PaddleOCR 2.x 系列的 whl 包使用方式对应文档docs/version2.x/ppocr/blog/whl.md。当前仓库源码中PaddleOCR类位于 paddleocr/_pipelines/ocr.py其注释明确标注 Be comptable with PaddleOCR 2.x interfaces即 2.x 时代的接口约定仍在兼容范围内本文末尾将结合源码解析新老接口的对应关系。1 安装 whl 包1.1 pip 直接安装执行以下命令即可安装 PaddleOCR 的 Python 包pip install paddleocr3.0安装时注意3.0的版本约束表示安装 2.x 系列的最新版本与本文使用的 2.x 接口一致。安装完成后包内同时提供 Python 模块paddleocr和命令行入口paddleocr二者都将在后文使用。1.2 本地构建并安装如果希望从当前仓库源码构建 whl 包先进入仓库根目录然后执行python3 -m build pip3 install dist/paddleocr-x.x.x-py3-none-any.whl # x.x.x 是 paddleocr 的版本号其中python3 -m build会在dist/目录下生成 whl 文件x.x.x需替换为实际的版本号以dist/目录下生成的文件名为准。构建依赖build模块如未安装可先执行pip install build。2 使用paddleocr whl 包在首次使用时会自动下载 PP-OCR 轻量级模型作为默认模型并将模型缓存到本地之后可直接参考第 3 节「自定义模型」更换为自己训练的模型。模型自动下载与按lang/ocr_version选择模型名称的逻辑在源码中由 paddleocr/_pipelines/ocr.py 的_get_ocr_model_names实现——当未显式指定任何模型路径时它会根据语言与版本自动挑选对应的检测/识别模型例如默认情况下返回PP-OCRv6_medium_det与PP-OCRv6_medium_rec。2.1 代码使用统一导入方式后续所有代码示例均基于此from paddleocr import PaddleOCR, draw_ocr其中PaddleOCR负责推理draw_ocr负责将检测框、识别文本与置信度绘制到原图上。2.1.1 检测 方向分类器 识别全流程from paddleocr import PaddleOCR, draw_ocr # PaddleOCR 目前支持中英文、英文、法语、德语、韩语、日语可以通过修改 lang 参数进行切换 # 参数依次为 ch, en, french, german, korean, japan。 ocr PaddleOCR(use_angle_clsTrue, langch) # need to run only once to download and load model into memory img_path PaddleOCR/doc/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_pathdoc/fonts/simfang.ttf) im_show Image.fromarray(im_show) im_show.save(result.jpg)结果是一个 list每个 item 包含了文本框四角坐标、识别文字与识别置信度[[[24.0, 36.0], [304.0, 34.0], [304.0, 72.0], [24.0, 74.0]], [纯臻营养护发素, 0.964739]] [[[24.0, 80.0], [172.0, 80.0], [172.0, 104.0], [24.0, 104.0]], [产品信息/参数, 0.98069626]] [[[24.0, 109.0], [333.0, 109.0], [333.0, 136.0], [24.0, 136.0]], [45元/每公斤100公斤起订, 0.9676722]] ......结果可视化效果如下左图为带检测框的原文右图为识别文字及置信度列表几个关键点font_path用于指定绘制中文所需的字体文件仓库内置了多语言字体中文场景可直接使用 doc/fonts/simfang.ttf其他语言字体如japan.ttc、korean.ttf等也位于同一目录。代码中ocr.ocr(...)为 2.x 时代的标准调用方式。在最新源码中该方法已被标记为deprecated官方推荐改用predict见 paddleocr/_pipelines/ocr.py但ocr仍可用方便老项目平滑迁移。模型只需加载一次重复调用ocr.ocr()不会重复下载。2.1.2 检测 识别不启用方向分类器from paddleocr import PaddleOCR, draw_ocr ocr PaddleOCR() # need to run only once to download and load model into memory img_path PaddleOCR/doc/imgs/11.jpg result ocr.ocr(img_path, clsFalse) 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_pathdoc/fonts/simfang.ttf) im_show Image.fromarray(im_show) im_show.save(result.jpg)返回结构与全流程模式一致每个 item 仍为「文本框 文字 置信度」。区别在于构造PaddleOCR()时未传use_angle_clsTrue默认不加载方向分类模型且在调用时指定clsFalse从而跳过方向分类环节。2.1.3 方向分类器 识别不检测适用于已经裁切好的单行文字图片跳过检测直接分类纠偏并识别from paddleocr import PaddleOCR ocr PaddleOCR(use_angle_clsTrue) # need to run only once to download and load model into memory img_path PaddleOCR/doc/imgs_words/ch/word_1.jpg result ocr.ocr(img_path, detFalse, clsTrue) for idx in range(len(result)): res result[idx] for line in res: print(line)结果是一个 list每个 item 只包含识别结果和识别置信度[韩国小馆, 0.9907421]2.1.4 单独执行检测from paddleocr import PaddleOCR, draw_ocr ocr PaddleOCR() # need to run only once to download and load model into memory img_path PaddleOCR/doc/imgs/11.jpg result ocr.ocr(img_path, recFalse) 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) im_show draw_ocr(image, result, txtsNone, scoresNone, font_pathdoc/fonts/simfang.ttf) im_show Image.fromarray(im_show) im_show.save(result.jpg)结果是一个 list每个 item 只包含文本框四个角的坐标[[26.0, 457.0], [137.0, 457.0], [137.0, 477.0], [26.0, 477.0]] [[25.0, 425.0], [372.0, 425.0], [372.0, 448.0], [25.0, 448.0]] [[128.0, 397.0], [273.0, 397.0], [273.0, 414.0], [128.0, 414.0]] ......注意此时draw_ocr的txts与scores均传None只绘制检测框。可视化效果如下2.1.5 单独执行识别from paddleocr import PaddleOCR ocr PaddleOCR() # need to run only once to download and load model into memory img_path PaddleOCR/doc/imgs_words/ch/word_1.jpg result ocr.ocr(img_path, detFalse) for idx in range(len(result)): res result[idx] for line in res: print(line)结果是一个 list每个 item 只包含识别结果和识别置信度[韩国小馆, 0.9907421]2.1.6 单独执行方向分类器from paddleocr import PaddleOCR ocr PaddleOCR(use_angle_clsTrue) # need to run only once to download and load model into memory img_path PaddleOCR/doc/imgs_words/ch/word_1.jpg result ocr.ocr(img_path, detFalse, recFalse, clsTrue) for idx in range(len(result)): res result[idx] for line in res: print(line)结果是一个 list每个 item 只包含分类结果和分类置信度[0, 0.9999924]其中0表示文字方向正常180表示旋转了 180 度对应 ppocr/utils/dict 目录下方向分类模型使用的标签体系可在参数表label_list中查看默认值为[0, 180]。2.2 通过命令行使用whl 包安装后自带paddleocr命令行工具先查看帮助信息paddleocr -h命令行通过--image_dir指定输入图片或文件夹、PDF通过--det、--rec、--use_angle_cls等开关控制流水线组件与代码模式一一对应。检测 方向分类器 识别全流程paddleocr --image_dir PaddleOCR/doc/imgs/11.jpg --use_angle_cls true结果是一个 list每个 item 包含了文本框、文字和识别置信度[[[28.0, 37.0], [302.0, 39.0], [302.0, 72.0], [27.0, 70.0]], (纯臻营养护发素, 0.9658738374710083)] ......检测 识别paddleocr --image_dir PaddleOCR/doc/imgs/11.jpg结果是一个 list每个 item 包含了文本框、文字和识别置信度输出结构同上。方向分类器 识别paddleocr --image_dir PaddleOCR/doc/imgs_words/ch/word_1.jpg --use_angle_cls true --det false结果是一个 list每个 item 只包含识别结果和识别置信度[韩国小馆, 0.994467]单独执行检测paddleocr --image_dir PaddleOCR/doc/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]] ......单独执行识别paddleocr --image_dir PaddleOCR/doc/imgs_words/ch/word_1.jpg --det false结果是一个 list每个 item 只包含识别结果和识别置信度[韩国小馆, 0.994467]单独执行方向分类器paddleocr --image_dir PaddleOCR/doc/imgs_words/ch/word_1.jpg --use_angle_cls true --det false --rec false结果是一个 list每个 item 只包含分类结果和分类置信度[0, 0.9999924]此外paddleocr 命令行还支持输入 PDF 文件并通过--page_num控制推理前面几页默认为 0表示推理所有页paddleocr --image_dir ./xxx.pdf --use_angle_cls true --use_gpu false --page_num 23 自定义模型当内置模型无法满足需求例如特定场景、特定语言或自研算法时需要替换为自己训练的模型。首先参照 模型导出 将检测、分类和识别模型转换为 inference 模型然后按照如下方式使用。转换命令示例详见 docs/version2.x/ppocr/model_train/detection.mdpython3 tools/export_model.py -c configs/det/det_mv3_db.yml -o Global.pretrained_model./output/det_db/best_accuracy Global.save_inference_dir./output/det_db_inference/inference 模型由paddle.jit.save保存与训练 checkpoint 相比额外保存了模型结构信息预测部署与加速推理性能更优适合实际系统集成。3.1 代码使用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 PaddleOCR/doc/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_pathdoc/fonts/simfang.ttf) im_show Image.fromarray(im_show) im_show.save(result.jpg)关键约定det_model_dir、rec_model_dir、cls_model_dir指向的目录下必须同时包含model和params文件即导出的 inference 模型。rec_char_dict_path需要指向与你的识别模型配套的字典文件。仓库内置的默认字典为 ppocr/utils/ppocr_keys_v1.txt对应参数表中的默认值./ppocr/utils/ppocr_keys_v1.txt自定义模型时应改为自己的字典路径。3.2 通过命令行使用paddleocr --image_dir PaddleOCR/doc/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 true4 使用网络图片或者 numpy 数组作为输入4.1 网络图片代码使用from paddleocr import PaddleOCR, draw_ocr, download_with_progressbar # PaddleOCR 目前支持中英文、英文、法语、德语、韩语、日语可以通过修改 lang 参数进行切换 # 参数依次为 ch, en, french, german, korean, japan。 ocr PaddleOCR(use_angle_clsTrue, langch) # need to run only once to download and load model into memory img_path http://n.sinaimg.cn/ent/transform/w630h933/20171222/o111-fypvuqf1838418.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] download_with_progressbar(img_path, tmp.jpg) image Image.open(tmp.jpg).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_pathdoc/fonts/simfang.ttf) im_show Image.fromarray(im_show) im_show.save(result.jpg)ocr.ocr()直接传入 http 开头的 URL 即可完成推理download_with_progressbar用于把网络图片下载到本地供后续可视化绘制使用。命令行模式paddleocr --image_dir http://n.sinaimg.cn/ent/transform/w630h933/20171222/o111-fypvuqf1838418.jpg --use_angle_clstrue4.2 numpy 数组仅通过代码使用时支持 numpy 数组作为输入适合与 OpenCV 等图像处理库无缝衔接import cv2 from paddleocr import PaddleOCR, draw_ocr # PaddleOCR 目前支持中英文、英文、法语、德语、韩语、日语可以通过修改 lang 参数进行切换 # 参数依次为 ch, en, french, german, korean, japan。 ocr PaddleOCR(use_angle_clsTrue, langch) # need to run only once to download and load model into memory img_path PaddleOCR/doc/imgs/11.jpg img cv2.imread(img_path) # img cv2.cvtColor(img,cv2.COLOR_BGR2GRAY), 如果你自己训练的模型支持灰度图可以将这句话的注释取消 result ocr.ocr(img, 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_pathdoc/fonts/simfang.ttf) im_show Image.fromarray(im_show) im_show.save(result.jpg)从源码结构看PaddleOCR的预测入口对输入做了统一抽象因此无论是文件路径、URL 还是ndarray均可作为ocr.ocr()/predict()的输入具体预处理如灰度转换、归一化由流水线内部完成。5 PDF 文件作为输入PDF 输入既支持命令行也支持代码方式通过page_num参数控制推理页数。命令行模式paddleocr --image_dir ./xxx.pdf --use_angle_cls true --use_gpu false --page_num 2page_num默认为 0表示推理所有页指定为 N 时仅推理前 N 页。代码使用from paddleocr import PaddleOCR, draw_ocr # PaddleOCR 目前支持的多语言语种可以通过修改 lang 参数进行切换 # 例如 ch, en, fr, german, korean, japan ocr PaddleOCR(use_angle_clsTrue, langch, page_num2) # need to run only once to download and load model into memory img_path ./xxx.pdf result ocr.ocr(img_path, clsTrue) for idx in range(len(result)): res result[idx] for line in res: print(line) # 显示结果 import fitz from PIL import Image import cv2 import numpy as np imgs [] with fitz.open(img_path) as pdf: for pg in range(0, pdf.pageCount): page pdf[pg] mat fitz.Matrix(2, 2) pm page.getPixmap(matrixmat, alphaFalse) # if width or height 2000 pixels, dont enlarge the image if pm.width 2000 or pm.height 2000: pm page.getPixmap(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] 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))可视化阶段使用 PyMuPDFfitz将 PDF 每页渲染为图像默认放大 2 倍以保证清晰度若渲染后宽或高超过 2000 像素则回退为 1 倍缩放再逐页与result对齐绘制检测结果保存为result_page_0.jpg、result_page_1.jpg等文件。注意该示例依赖PyMuPDFfitz、opencv-python、Pillow、numpy使用前需自行安装。6 参数说明下表整理了 whl 包支持的完整参数清单包括字段、说明与默认值来源于原文档并保留原样字段说明默认值use_gpu是否使用GPUTRUEgpu_mem初始化占用的GPU内存大小8000Mimage_dir通过命令行调用时执行预测的图片或文件夹路径-page_num当输入类型为pdf文件时有效指定预测前面page_num页默认预测所有页0det_algorithm使用的检测算法类型DBdet_model_dir检测模型所在文件夹。传参方式有两种1. None: 自动下载内置模型到~/.paddleocr/det2.自己转换好的inference模型路径模型路径下必须包含model和params文件Nonedet_max_side_len检测算法前向时图片长边的最大尺寸当长边超出这个值时会将长边resize到这个大小短边等比例缩放960det_db_threshDB模型输出预测图的二值化阈值0.3det_db_box_threshDB模型输出框的阈值低于此值的预测框会被丢弃0.5det_db_unclip_ratioDB模型输出框扩大的比例2det_db_score_mode计算检测框score的方式有fast和slow如果要检测的文字有弯曲建议用slowslow模式计算的box的score偏大box不容易被过滤掉fastdet_east_score_threshEAST模型输出预测图的二值化阈值0.8det_east_cover_threshEAST模型输出框的阈值低于此值的预测框会被丢弃0.1det_east_nms_threshEAST模型输出框NMS的阈值0.2rec_algorithm使用的识别算法类型CRNNrec_model_dir识别模型所在文件夹。传参方式有两种1. None: 自动下载内置模型到~/.paddleocr/rec2.自己转换好的inference模型路径模型路径下必须包含model和params文件Nonerec_image_shape识别算法的输入图片尺寸3,32,320rec_batch_num进行识别时同时前向的图片数30max_text_length识别算法能识别的最大文字长度25rec_char_dict_path识别模型字典路径当rec_model_dir使用方式2传参时需要修改为自己的字典路径./ppocr/utils/ppocr_keys_v1.txtuse_space_char是否识别空格TRUEdrop_score对输出按照分数(来自于识别模型)进行过滤低于此分数的不返回0.5use_angle_cls是否加载分类模型FALSEcls_model_dir分类模型所在文件夹。传参方式有两种1. None: 自动下载内置模型到~/.paddleocr/cls2.自己转换好的inference模型路径模型路径下必须包含model和params文件Nonecls_image_shape分类算法的输入图片尺寸3, 48, 192label_list分类算法的标签列表[0, 180]cls_batch_num进行分类时同时前向的图片数30enable_mkldnn是否启用mkldnnFALSEuse_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-OCRv3 支持中、英文的检测、识别、多语种识别方向分类器等模型PP-OCRv2 目前仅支持中文的检测和识别模型PP-OCR支持中文的检测识别多语种识别方向分类器等模型PP-OCRv3参数使用要点det/rec/cls三个开关与第 2 节的代码示例一一对应detFalse跳过检测、recFalse跳过识别、clsTrue启用方向分类命令行模式下方向分类开关由--use_angle_cls控制。drop_score作用于识别结果的置信度过滤低于该分数的识别结果不返回默认 0.5可用于剔除低质量识别。det_max_side_len控制检测输入的长边上限默认 960长边超限时等比缩放是检测精度与速度之间的关键权衡参数。det_db_*系列仅对 DB 检测算法生效det_algorithmDB包括二值化阈值、框阈值、扩框比例与 score 计算模式det_east_*系列仅对 EAST 算法生效。若检测弯曲文字建议将det_db_score_mode设为slow其计算的 box score 偏大、不易被过滤。lang与ocr_version决定自动下载的默认模型文档中ocr_version默认值为 PP-OCRv32.x 时代当前仓库源码已扩展为支持PP-OCRv3 / PP-OCRv4 / PP-OCRv5 / PP-OCRv6见 paddleocr/_pipelines/ocr.py且_get_ocr_model_names会依据语言自动匹配合适版本的模型例如ch语言默认选用 PP-OCRv6 的检测与识别模型。7 源码视角2.x 接口的兼容与新老参数对应当前仓库的PaddleOCR类paddleocr/_pipelines/ocr.py为兼容 2.x 接口而保留了本文档中的核心用法同时提供了新命名参数。两者通过_DEPRECATED_PARAM_NAME_MAPPINGpaddleocr/_pipelines/ocr.py建立映射老参数传入时会给出弃用提示并自动转换2.x 参数本文档新参数det_model_dirtext_detection_model_dirdet_limit_side_lentext_det_limit_side_lendet_limit_typetext_det_limit_typedet_db_threshtext_det_threshdet_db_box_threshtext_det_box_threshdet_db_unclip_ratiotext_det_unclip_ratiorec_model_dirtext_recognition_model_dirrec_batch_numtext_recognition_batch_sizeuse_angle_clsuse_textline_orientationcls_model_dirtextline_orientation_model_dircls_batch_numtextline_orientation_batch_size同时在 3.x 中推荐使用predict()或predict_iter()流式返回替代 2.x 的ocr()方法见 paddleocr/_pipelines/ocr.pyCLI 也支持paddleocr ocr子命令与--text_detection_model_name等新式参数。这意味着本文档中的 2.x 代码与命令仍然可以运行而新项目则建议直接采用新接口以获取文档方向分类、文本矫正等更完整的流水线能力详见 paddleocr/_pipelines/ocr.py 的构造参数。8 延伸阅读模型导出与推理细节模型导出与预测推理超参数详解模型推理超参数解释教程多语言识别配置多语言模型教程快速上手总览快速开始【免费下载链接】PaddleOCR飞桨多语言OCR工具包实用超轻量OCR系统支持80种语言识别提供数据标注与合成工具支持服务器、移动端、嵌入式及IoT设备端的训练与部署 Awesome multilingual OCR toolkits based on PaddlePaddle (practical ultra lightweight OCR system, support 80 languages recognition, provide data annotation and synthesis tools, support training and deployment among server, mobile, embedded and IoT devices)项目地址: https://gitcode.com/paddlepaddle/PaddleOCR创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考 PaddleOCR whl 包使用指南：从安装、全流程推理到自定义模型部署
PaddleOCR whl 包使用指南从安装、全流程推理到自定义模型部署【免费下载链接】PaddleOCR飞桨多语言OCR工具包实用超轻量OCR系统支持80种语言识别提供数据标注与合成工具支持服务器、移动端、嵌入式及IoT设备端的训练与部署 Awesome multilingual OCR toolkits based on PaddlePaddle (practical ultra lightweight OCR system, support 80 languages recognition, provide data annotation and synthesis tools, support training and deployment among server, mobile, embedded and IoT devices)项目地址: https://gitcode.com/paddlepaddle/PaddleOCRPaddleOCR 提供了开箱即用的 Python 安装包whl通过一条pip install即可获得完整的文本检测、方向分类与文字识别能力既支持 Python 代码调用也支持命令行直接推理还支持图片、网络图片、numpy 数组与 PDF 文件等多种输入形式。本文以 docs/version2.x/ppocr/blog/whl.md 为主线结合当前仓库的 paddleocr/_pipelines/ocr.py 源码实现系统讲解 whl 包的安装方式、五大使用场景、自定义模型加载方法以及全部核心参数的语义帮助你快速在真实项目中落地 PaddleOCR。说明本文面向 PaddleOCR 2.x 系列的 whl 包使用方式对应文档docs/version2.x/ppocr/blog/whl.md。当前仓库源码中PaddleOCR类位于 paddleocr/_pipelines/ocr.py其注释明确标注 Be comptable with PaddleOCR 2.x interfaces即 2.x 时代的接口约定仍在兼容范围内本文末尾将结合源码解析新老接口的对应关系。1 安装 whl 包1.1 pip 直接安装执行以下命令即可安装 PaddleOCR 的 Python 包pip install paddleocr3.0安装时注意3.0的版本约束表示安装 2.x 系列的最新版本与本文使用的 2.x 接口一致。安装完成后包内同时提供 Python 模块paddleocr和命令行入口paddleocr二者都将在后文使用。1.2 本地构建并安装如果希望从当前仓库源码构建 whl 包先进入仓库根目录然后执行python3 -m build pip3 install dist/paddleocr-x.x.x-py3-none-any.whl # x.x.x 是 paddleocr 的版本号其中python3 -m build会在dist/目录下生成 whl 文件x.x.x需替换为实际的版本号以dist/目录下生成的文件名为准。构建依赖build模块如未安装可先执行pip install build。2 使用paddleocr whl 包在首次使用时会自动下载 PP-OCR 轻量级模型作为默认模型并将模型缓存到本地之后可直接参考第 3 节「自定义模型」更换为自己训练的模型。模型自动下载与按lang/ocr_version选择模型名称的逻辑在源码中由 paddleocr/_pipelines/ocr.py 的_get_ocr_model_names实现——当未显式指定任何模型路径时它会根据语言与版本自动挑选对应的检测/识别模型例如默认情况下返回PP-OCRv6_medium_det与PP-OCRv6_medium_rec。2.1 代码使用统一导入方式后续所有代码示例均基于此from paddleocr import PaddleOCR, draw_ocr其中PaddleOCR负责推理draw_ocr负责将检测框、识别文本与置信度绘制到原图上。2.1.1 检测 方向分类器 识别全流程from paddleocr import PaddleOCR, draw_ocr # PaddleOCR 目前支持中英文、英文、法语、德语、韩语、日语可以通过修改 lang 参数进行切换 # 参数依次为 ch, en, french, german, korean, japan。 ocr PaddleOCR(use_angle_clsTrue, langch) # need to run only once to download and load model into memory img_path PaddleOCR/doc/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_pathdoc/fonts/simfang.ttf) im_show Image.fromarray(im_show) im_show.save(result.jpg)结果是一个 list每个 item 包含了文本框四角坐标、识别文字与识别置信度[[[24.0, 36.0], [304.0, 34.0], [304.0, 72.0], [24.0, 74.0]], [纯臻营养护发素, 0.964739]] [[[24.0, 80.0], [172.0, 80.0], [172.0, 104.0], [24.0, 104.0]], [产品信息/参数, 0.98069626]] [[[24.0, 109.0], [333.0, 109.0], [333.0, 136.0], [24.0, 136.0]], [45元/每公斤100公斤起订, 0.9676722]] ......结果可视化效果如下左图为带检测框的原文右图为识别文字及置信度列表几个关键点font_path用于指定绘制中文所需的字体文件仓库内置了多语言字体中文场景可直接使用 doc/fonts/simfang.ttf其他语言字体如japan.ttc、korean.ttf等也位于同一目录。代码中ocr.ocr(...)为 2.x 时代的标准调用方式。在最新源码中该方法已被标记为deprecated官方推荐改用predict见 paddleocr/_pipelines/ocr.py但ocr仍可用方便老项目平滑迁移。模型只需加载一次重复调用ocr.ocr()不会重复下载。2.1.2 检测 识别不启用方向分类器from paddleocr import PaddleOCR, draw_ocr ocr PaddleOCR() # need to run only once to download and load model into memory img_path PaddleOCR/doc/imgs/11.jpg result ocr.ocr(img_path, clsFalse) 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_pathdoc/fonts/simfang.ttf) im_show Image.fromarray(im_show) im_show.save(result.jpg)返回结构与全流程模式一致每个 item 仍为「文本框 文字 置信度」。区别在于构造PaddleOCR()时未传use_angle_clsTrue默认不加载方向分类模型且在调用时指定clsFalse从而跳过方向分类环节。2.1.3 方向分类器 识别不检测适用于已经裁切好的单行文字图片跳过检测直接分类纠偏并识别from paddleocr import PaddleOCR ocr PaddleOCR(use_angle_clsTrue) # need to run only once to download and load model into memory img_path PaddleOCR/doc/imgs_words/ch/word_1.jpg result ocr.ocr(img_path, detFalse, clsTrue) for idx in range(len(result)): res result[idx] for line in res: print(line)结果是一个 list每个 item 只包含识别结果和识别置信度[韩国小馆, 0.9907421]2.1.4 单独执行检测from paddleocr import PaddleOCR, draw_ocr ocr PaddleOCR() # need to run only once to download and load model into memory img_path PaddleOCR/doc/imgs/11.jpg result ocr.ocr(img_path, recFalse) 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) im_show draw_ocr(image, result, txtsNone, scoresNone, font_pathdoc/fonts/simfang.ttf) im_show Image.fromarray(im_show) im_show.save(result.jpg)结果是一个 list每个 item 只包含文本框四个角的坐标[[26.0, 457.0], [137.0, 457.0], [137.0, 477.0], [26.0, 477.0]] [[25.0, 425.0], [372.0, 425.0], [372.0, 448.0], [25.0, 448.0]] [[128.0, 397.0], [273.0, 397.0], [273.0, 414.0], [128.0, 414.0]] ......注意此时draw_ocr的txts与scores均传None只绘制检测框。可视化效果如下2.1.5 单独执行识别from paddleocr import PaddleOCR ocr PaddleOCR() # need to run only once to download and load model into memory img_path PaddleOCR/doc/imgs_words/ch/word_1.jpg result ocr.ocr(img_path, detFalse) for idx in range(len(result)): res result[idx] for line in res: print(line)结果是一个 list每个 item 只包含识别结果和识别置信度[韩国小馆, 0.9907421]2.1.6 单独执行方向分类器from paddleocr import PaddleOCR ocr PaddleOCR(use_angle_clsTrue) # need to run only once to download and load model into memory img_path PaddleOCR/doc/imgs_words/ch/word_1.jpg result ocr.ocr(img_path, detFalse, recFalse, clsTrue) for idx in range(len(result)): res result[idx] for line in res: print(line)结果是一个 list每个 item 只包含分类结果和分类置信度[0, 0.9999924]其中0表示文字方向正常180表示旋转了 180 度对应 ppocr/utils/dict 目录下方向分类模型使用的标签体系可在参数表label_list中查看默认值为[0, 180]。2.2 通过命令行使用whl 包安装后自带paddleocr命令行工具先查看帮助信息paddleocr -h命令行通过--image_dir指定输入图片或文件夹、PDF通过--det、--rec、--use_angle_cls等开关控制流水线组件与代码模式一一对应。检测 方向分类器 识别全流程paddleocr --image_dir PaddleOCR/doc/imgs/11.jpg --use_angle_cls true结果是一个 list每个 item 包含了文本框、文字和识别置信度[[[28.0, 37.0], [302.0, 39.0], [302.0, 72.0], [27.0, 70.0]], (纯臻营养护发素, 0.9658738374710083)] ......检测 识别paddleocr --image_dir PaddleOCR/doc/imgs/11.jpg结果是一个 list每个 item 包含了文本框、文字和识别置信度输出结构同上。方向分类器 识别paddleocr --image_dir PaddleOCR/doc/imgs_words/ch/word_1.jpg --use_angle_cls true --det false结果是一个 list每个 item 只包含识别结果和识别置信度[韩国小馆, 0.994467]单独执行检测paddleocr --image_dir PaddleOCR/doc/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]] ......单独执行识别paddleocr --image_dir PaddleOCR/doc/imgs_words/ch/word_1.jpg --det false结果是一个 list每个 item 只包含识别结果和识别置信度[韩国小馆, 0.994467]单独执行方向分类器paddleocr --image_dir PaddleOCR/doc/imgs_words/ch/word_1.jpg --use_angle_cls true --det false --rec false结果是一个 list每个 item 只包含分类结果和分类置信度[0, 0.9999924]此外paddleocr 命令行还支持输入 PDF 文件并通过--page_num控制推理前面几页默认为 0表示推理所有页paddleocr --image_dir ./xxx.pdf --use_angle_cls true --use_gpu false --page_num 23 自定义模型当内置模型无法满足需求例如特定场景、特定语言或自研算法时需要替换为自己训练的模型。首先参照 模型导出 将检测、分类和识别模型转换为 inference 模型然后按照如下方式使用。转换命令示例详见 docs/version2.x/ppocr/model_train/detection.mdpython3 tools/export_model.py -c configs/det/det_mv3_db.yml -o Global.pretrained_model./output/det_db/best_accuracy Global.save_inference_dir./output/det_db_inference/inference 模型由paddle.jit.save保存与训练 checkpoint 相比额外保存了模型结构信息预测部署与加速推理性能更优适合实际系统集成。3.1 代码使用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 PaddleOCR/doc/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_pathdoc/fonts/simfang.ttf) im_show Image.fromarray(im_show) im_show.save(result.jpg)关键约定det_model_dir、rec_model_dir、cls_model_dir指向的目录下必须同时包含model和params文件即导出的 inference 模型。rec_char_dict_path需要指向与你的识别模型配套的字典文件。仓库内置的默认字典为 ppocr/utils/ppocr_keys_v1.txt对应参数表中的默认值./ppocr/utils/ppocr_keys_v1.txt自定义模型时应改为自己的字典路径。3.2 通过命令行使用paddleocr --image_dir PaddleOCR/doc/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 true4 使用网络图片或者 numpy 数组作为输入4.1 网络图片代码使用from paddleocr import PaddleOCR, draw_ocr, download_with_progressbar # PaddleOCR 目前支持中英文、英文、法语、德语、韩语、日语可以通过修改 lang 参数进行切换 # 参数依次为 ch, en, french, german, korean, japan。 ocr PaddleOCR(use_angle_clsTrue, langch) # need to run only once to download and load model into memory img_path http://n.sinaimg.cn/ent/transform/w630h933/20171222/o111-fypvuqf1838418.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] download_with_progressbar(img_path, tmp.jpg) image Image.open(tmp.jpg).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_pathdoc/fonts/simfang.ttf) im_show Image.fromarray(im_show) im_show.save(result.jpg)ocr.ocr()直接传入 http 开头的 URL 即可完成推理download_with_progressbar用于把网络图片下载到本地供后续可视化绘制使用。命令行模式paddleocr --image_dir http://n.sinaimg.cn/ent/transform/w630h933/20171222/o111-fypvuqf1838418.jpg --use_angle_clstrue4.2 numpy 数组仅通过代码使用时支持 numpy 数组作为输入适合与 OpenCV 等图像处理库无缝衔接import cv2 from paddleocr import PaddleOCR, draw_ocr # PaddleOCR 目前支持中英文、英文、法语、德语、韩语、日语可以通过修改 lang 参数进行切换 # 参数依次为 ch, en, french, german, korean, japan。 ocr PaddleOCR(use_angle_clsTrue, langch) # need to run only once to download and load model into memory img_path PaddleOCR/doc/imgs/11.jpg img cv2.imread(img_path) # img cv2.cvtColor(img,cv2.COLOR_BGR2GRAY), 如果你自己训练的模型支持灰度图可以将这句话的注释取消 result ocr.ocr(img, 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_pathdoc/fonts/simfang.ttf) im_show Image.fromarray(im_show) im_show.save(result.jpg)从源码结构看PaddleOCR的预测入口对输入做了统一抽象因此无论是文件路径、URL 还是ndarray均可作为ocr.ocr()/predict()的输入具体预处理如灰度转换、归一化由流水线内部完成。5 PDF 文件作为输入PDF 输入既支持命令行也支持代码方式通过page_num参数控制推理页数。命令行模式paddleocr --image_dir ./xxx.pdf --use_angle_cls true --use_gpu false --page_num 2page_num默认为 0表示推理所有页指定为 N 时仅推理前 N 页。代码使用from paddleocr import PaddleOCR, draw_ocr # PaddleOCR 目前支持的多语言语种可以通过修改 lang 参数进行切换 # 例如 ch, en, fr, german, korean, japan ocr PaddleOCR(use_angle_clsTrue, langch, page_num2) # need to run only once to download and load model into memory img_path ./xxx.pdf result ocr.ocr(img_path, clsTrue) for idx in range(len(result)): res result[idx] for line in res: print(line) # 显示结果 import fitz from PIL import Image import cv2 import numpy as np imgs [] with fitz.open(img_path) as pdf: for pg in range(0, pdf.pageCount): page pdf[pg] mat fitz.Matrix(2, 2) pm page.getPixmap(matrixmat, alphaFalse) # if width or height 2000 pixels, dont enlarge the image if pm.width 2000 or pm.height 2000: pm page.getPixmap(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] 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))可视化阶段使用 PyMuPDFfitz将 PDF 每页渲染为图像默认放大 2 倍以保证清晰度若渲染后宽或高超过 2000 像素则回退为 1 倍缩放再逐页与result对齐绘制检测结果保存为result_page_0.jpg、result_page_1.jpg等文件。注意该示例依赖PyMuPDFfitz、opencv-python、Pillow、numpy使用前需自行安装。6 参数说明下表整理了 whl 包支持的完整参数清单包括字段、说明与默认值来源于原文档并保留原样字段说明默认值use_gpu是否使用GPUTRUEgpu_mem初始化占用的GPU内存大小8000Mimage_dir通过命令行调用时执行预测的图片或文件夹路径-page_num当输入类型为pdf文件时有效指定预测前面page_num页默认预测所有页0det_algorithm使用的检测算法类型DBdet_model_dir检测模型所在文件夹。传参方式有两种1. None: 自动下载内置模型到~/.paddleocr/det2.自己转换好的inference模型路径模型路径下必须包含model和params文件Nonedet_max_side_len检测算法前向时图片长边的最大尺寸当长边超出这个值时会将长边resize到这个大小短边等比例缩放960det_db_threshDB模型输出预测图的二值化阈值0.3det_db_box_threshDB模型输出框的阈值低于此值的预测框会被丢弃0.5det_db_unclip_ratioDB模型输出框扩大的比例2det_db_score_mode计算检测框score的方式有fast和slow如果要检测的文字有弯曲建议用slowslow模式计算的box的score偏大box不容易被过滤掉fastdet_east_score_threshEAST模型输出预测图的二值化阈值0.8det_east_cover_threshEAST模型输出框的阈值低于此值的预测框会被丢弃0.1det_east_nms_threshEAST模型输出框NMS的阈值0.2rec_algorithm使用的识别算法类型CRNNrec_model_dir识别模型所在文件夹。传参方式有两种1. None: 自动下载内置模型到~/.paddleocr/rec2.自己转换好的inference模型路径模型路径下必须包含model和params文件Nonerec_image_shape识别算法的输入图片尺寸3,32,320rec_batch_num进行识别时同时前向的图片数30max_text_length识别算法能识别的最大文字长度25rec_char_dict_path识别模型字典路径当rec_model_dir使用方式2传参时需要修改为自己的字典路径./ppocr/utils/ppocr_keys_v1.txtuse_space_char是否识别空格TRUEdrop_score对输出按照分数(来自于识别模型)进行过滤低于此分数的不返回0.5use_angle_cls是否加载分类模型FALSEcls_model_dir分类模型所在文件夹。传参方式有两种1. None: 自动下载内置模型到~/.paddleocr/cls2.自己转换好的inference模型路径模型路径下必须包含model和params文件Nonecls_image_shape分类算法的输入图片尺寸3, 48, 192label_list分类算法的标签列表[0, 180]cls_batch_num进行分类时同时前向的图片数30enable_mkldnn是否启用mkldnnFALSEuse_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-OCRv3 支持中、英文的检测、识别、多语种识别方向分类器等模型PP-OCRv2 目前仅支持中文的检测和识别模型PP-OCR支持中文的检测识别多语种识别方向分类器等模型PP-OCRv3参数使用要点det/rec/cls三个开关与第 2 节的代码示例一一对应detFalse跳过检测、recFalse跳过识别、clsTrue启用方向分类命令行模式下方向分类开关由--use_angle_cls控制。drop_score作用于识别结果的置信度过滤低于该分数的识别结果不返回默认 0.5可用于剔除低质量识别。det_max_side_len控制检测输入的长边上限默认 960长边超限时等比缩放是检测精度与速度之间的关键权衡参数。det_db_*系列仅对 DB 检测算法生效det_algorithmDB包括二值化阈值、框阈值、扩框比例与 score 计算模式det_east_*系列仅对 EAST 算法生效。若检测弯曲文字建议将det_db_score_mode设为slow其计算的 box score 偏大、不易被过滤。lang与ocr_version决定自动下载的默认模型文档中ocr_version默认值为 PP-OCRv32.x 时代当前仓库源码已扩展为支持PP-OCRv3 / PP-OCRv4 / PP-OCRv5 / PP-OCRv6见 paddleocr/_pipelines/ocr.py且_get_ocr_model_names会依据语言自动匹配合适版本的模型例如ch语言默认选用 PP-OCRv6 的检测与识别模型。7 源码视角2.x 接口的兼容与新老参数对应当前仓库的PaddleOCR类paddleocr/_pipelines/ocr.py为兼容 2.x 接口而保留了本文档中的核心用法同时提供了新命名参数。两者通过_DEPRECATED_PARAM_NAME_MAPPINGpaddleocr/_pipelines/ocr.py建立映射老参数传入时会给出弃用提示并自动转换2.x 参数本文档新参数det_model_dirtext_detection_model_dirdet_limit_side_lentext_det_limit_side_lendet_limit_typetext_det_limit_typedet_db_threshtext_det_threshdet_db_box_threshtext_det_box_threshdet_db_unclip_ratiotext_det_unclip_ratiorec_model_dirtext_recognition_model_dirrec_batch_numtext_recognition_batch_sizeuse_angle_clsuse_textline_orientationcls_model_dirtextline_orientation_model_dircls_batch_numtextline_orientation_batch_size同时在 3.x 中推荐使用predict()或predict_iter()流式返回替代 2.x 的ocr()方法见 paddleocr/_pipelines/ocr.pyCLI 也支持paddleocr ocr子命令与--text_detection_model_name等新式参数。这意味着本文档中的 2.x 代码与命令仍然可以运行而新项目则建议直接采用新接口以获取文档方向分类、文本矫正等更完整的流水线能力详见 paddleocr/_pipelines/ocr.py 的构造参数。8 延伸阅读模型导出与推理细节模型导出与预测推理超参数详解模型推理超参数解释教程多语言识别配置多语言模型教程快速上手总览快速开始【免费下载链接】PaddleOCR飞桨多语言OCR工具包实用超轻量OCR系统支持80种语言识别提供数据标注与合成工具支持服务器、移动端、嵌入式及IoT设备端的训练与部署 Awesome multilingual OCR toolkits based on PaddlePaddle (practical ultra lightweight OCR system, support 80 languages recognition, provide data annotation and synthesis tools, support training and deployment among server, mobile, embedded and IoT devices)项目地址: https://gitcode.com/paddlepaddle/PaddleOCR创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考