ARTICLE DETAIL

建站实战干货

来自一线的建站与推广经验沉淀，每一条都经过真实交付验证。

首页 / 资讯中心 / 正文

PaddleOCR 快速上手指南：whl 包安装、命令行与 Python API 全流程实战

2026/9/11 23:18:12 拓冰建站 浏览量
PaddleOCR 快速上手指南：whl 包安装、命令行与 Python API 全流程实战 PaddleOCR 快速上手指南whl 包安装、命令行与 Python API 全流程实战【免费下载链接】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/PaddleOCRPaddleOCR 是百度飞桨PaddlePaddle生态中面向 OCR 场景的开源工具库本文以其 2.x 版本的官方快速上手指南 docs/version2.x/ppocr/quick_start.en.md 为骨架结合仓库内配套文档与源码系统讲解 PP-OCR 系列模型的安装、命令行调用、Python API 集成、多语言切换、PDF 解析与大图滑窗切片等核心能力。读完本文你将掌握从零搭建 PaddleOCR 运行环境并在图片、PDF、网页图片、numpy 数组等多种输入上完成检测、方向分类与识别的完整实战方案。适用前提本文面向PaddleOCR 2.x 版本paddleocr3.0的 whl 包使用方式3.x 起仓库已演进为新的 API 客户端架构见 paddleocr/文中命令与参数以当前仓库 docs/version2.x 文档及配套源码为准。1. 环境安装1.1 安装 PaddlePaddle 基础框架PaddleOCR 依赖 PaddlePaddle 深度学习框架。若尚未配置 Python 环境请先参考 环境准备文档 完成 Conda/Python 与 CUDA 驱动的安装。有 CUDA 11 显卡环境安装 GPU 版本pip install paddlepaddle-gpu2.6无可用 GPU纯 CPU环境安装 CPU 版本python -m pip install paddlepaddle2.6版本说明锁定2.6是为了与 2.x 版 PaddleOCR 保持兼容。更详细的软硬件版本匹配关系请参考 PaddlePaddle 官方安装文档按实际环境核对。对于Windows 用户若安装 shapely 时出现OSError: [WinError 126] The specified module could not be found需要手动下载与 Python 版本匹配的 Shapely whl 文件后本地安装。1.2 安装 PaddleOCR whl 包pip install paddleocr2.0.1 # 推荐使用 2.0.1 版本安装完成后即可在任意目录通过paddleocr命令行或from paddleocr import PaddleOCR使用。whl 包会自动下载 PP-OCR 轻量级模型作为默认模型首次运行时下载到本地无需手动准备模型文件更完整的 whl 包能力说明见 whl 包文档。2. 命令行快速使用PaddleOCR 官方提供一系列测试图片可下载后切换到对应目录使用也可将下文--image_dir替换为你自己的图片路径cd /path/to/ppocr_img2.1 中英文模型检测 方向分类 识别全流程--use_gpu false表示禁用 GPU 设备--use_angle_cls true开启方向分类paddleocr --image_dir ./imgs_en/img_12.jpg --use_angle_cls true --lang en --use_gpu false输出为列表每项包含文本框四点坐标、识别文本与识别置信度[[[441.0, 174.0], [1166.0, 176.0], [1165.0, 222.0], [441.0, 221.0]], (ACKNOWLEDGEMENTS, 0.9971134662628174)] [[[403.0, 346.0], [1204.0, 348.0], [1204.0, 384.0], [402.0, 383.0]], (We would like to thank all the designers and, 0.9761400818824768)] [[[403.0, 396.0], [1204.0, 398.0], [1204.0, 434.0], [402.0, 433.0]], (contributors who have been involved in the, 0.9791957139968872)] ......PDF 输入命令行同样支持 PDF通过--page_num控制推理前几页默认值为 0 表示推理全部页paddleocr --image_dir ./xxx.pdf --use_angle_cls true --use_gpu false --page_num 2仅检测--rec false关闭识别输出每项仅含文本框坐标paddleocr --image_dir ./imgs_en/img_12.jpg --rec false[[397.0, 802.0], [1092.0, 802.0], [1092.0, 841.0], [397.0, 841.0]] [[397.0, 750.0], [1211.0, 750.0], [1211.0, 789.0], [397.0, 789.0]] ......仅识别--det false关闭检测输出每项含文本与置信度paddleocr --image_dir ./imgs_words_en/word_10.png --det false --lang en[PAIN, 0.9934559464454651]2.2 OCR 模型版本切换2.x 版paddleocr默认使用PP-OCRv4模型对应参数--ocr_version PP-OCRv4。可通过--ocr_version参数切换其他版本版本名能力说明PP-OCRv4支持中英文检测识别、方向分类器支持多语言识别PP-OCRv3支持中英文检测识别、方向分类器支持多语言识别PP-OCRv2仅支持中英文检测识别与方向分类器多语言模型未更新PP-OCR支持中英文检测识别、方向分类器支持多语言识别从仓库源码结构看PP-OCRv3/v4 的完整算法与训练配置分别维护在 configs/det/PP-OCRv3/、configs/det/PP-OCRv4/ 与 configs/rec/PP-OCRv3/、configs/rec/PP-OCRv4/ 下可作为深入研读算法细节的入口。若需接入自己训练的模型可在 paddleocr.py 对应位置注册模型链接与标识后重新编译安装 whl 包。2.3 多语言模型PaddleOCR 2.x 支持80 种语言通过修改--lang参数即可切换语言模型paddleocr --image_dir ./doc/imgs_en/254.jpg --langen输出同样为列表每项包含文本框、文本与识别置信度[[[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 语言缩写表见 多语言模型教程语言缩写语言缩写语言缩写中英文ch法语fr日语japan英语en德语german韩语korean繁体中文chinese_cht意大利语it俄语ru多语言模型覆盖拉丁语系、阿拉伯语系、繁体中文、韩语、日语等文字体系其中英文模型针对大小写字母与常见标点专门训练并优化了空格字符识别。仓库源码 paddleocr/_utils/langs.py 中将各语言代码按文字体系进行了分组如LATIN_LANGS、ARABIC_LANGS、CYRILLIC_LANGS、DEVANAGARI_LANGS等可佐证多语言按字符体系共享/复用模型的设计思路。3. Python API 集成使用3.1 中英文与多语言模型检测 方向分类 识别from paddleocr import PaddleOCR, draw_ocr # PaddleOCR 支持中文、英文、法语、德语、韩语、日语 # 可设置 lang 为 ch / en / fr / german / korean / japan 切换对应语言模型 ocr PaddleOCR(use_angle_clsTrue, langen) # 只需运行一次自动下载并加载模型到内存 img_path ./imgs_en/img_12.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)输出结构与命令行一致——列表内每项包含文本框、文本与置信度[[[441.0, 174.0], [1166.0, 176.0], [1165.0, 222.0], [441.0, 221.0]], (ACKNOWLEDGEMENTS, 0.9971134662628174)] [[[403.0, 346.0], [1204.0, 348.0], [1204.0, 384.0], [402.0, 383.0]], (We would like to thank all the designers and, 0.9761400818824768)] ......可视化效果可参考 识别结果示例图。模块自由组合调用ocr.ocr()时可通过det/cls/rec三个开关自由组合检测、方向分类与识别例如ocr.ocr(img_path, recFalse)仅检测输出每项只有文本框坐标ocr.ocr(img_path, detFalse, clsFalse)仅识别输出[文本, 置信度]ocr.ocr(img_path, detFalse, recFalse, clsTrue)仅方向分类输出[0, 置信度]0 表示正向180 表示倒置。3.2 PDF 文件识别与可视化PDF 输入时在构造PaddleOCR时传入page_num指定识别页数并用 PyMuPDFfitz将 PDF 渲染为图像后叠加识别框from paddleocr import PaddleOCR, draw_ocr PAGE_NUM 10 # 设置识别页数 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 None: # 跳过空页结果避免 NoneType 报错 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 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))3.3 超大图滑窗切片Slice识别对于尺寸极大的图片/文档直接整图推理会受检测模型det_max_side_len默认 960限制导致小字被裁剪丢失。此时可启用slice 滑窗切片在超大图上按固定步长滑动窗口生成切片对每个切片独立执行检测与识别再将切片级结果按合并阈值拼接回整图级结果from paddleocr import PaddleOCR from PIL import Image, ImageDraw, ImageFont 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)slice 参数字典含义详细机制见 slice 操作文档参数含义horizontal_stride水平方向滑动步长像素步长过小会产生大量切片、计算开销剧增vertical_stride垂直方向滑动步长像素merge_x_thres水平方向合并阈值文本框水平距离小于该值的切片级检测将被合并merge_y_thres垂直方向合并阈值文本框垂直距离小于该值的切片级检测将被合并官方建议对于 6616×14886 尺寸的图片推荐配置为slice {horizontal_stride: 300, vertical_stride: 500, merge_x_thres: 50, merge_y_thres: 35}。整体流程为滑窗切片 → 逐片检测识别 → 按阈值合并去重。4. 自定义模型接入当内置模型无法满足业务需求时可接入自己训练的模型。首先参照 检测模型训练与导出 将 det / rec 模型导出为推理模型目录中必须同时包含 model 与 params 文件再按如下方式使用Python 方式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_en/img_12.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 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 true多语言模型的微调训练可参考 configs/rec/multi_language/ 下的配置如法语rec_french_lite_train.yml修改训练数据路径与字典后按 文本识别训练教程 进行。5. 更多输入类型网页图片与 numpy 数组网页图片URL 输入from paddleocr import PaddleOCR, draw_ocr ocr PaddleOCR(use_angle_clsTrue, langch) # 只需运行一次 img_path http://example.com/path/to/image.jpg # 替换为真实图片 URL result ocr.ocr(img_path, clsTrue) for idx in range(len(result)): res result[idx] for line in res: print(line)对应命令行用法paddleocr --image_dir 图片URL --use_angle_clstrue。numpy 数组输入仅代码方式支持可直接接入 OpenCV 读取的帧import cv2 from paddleocr import PaddleOCR ocr PaddleOCR(use_angle_clsTrue, langch) # 只需运行一次 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)这一能力让 PaddleOCR 可以直接嵌入 OpenCV 摄像头流、视频帧处理等实时管线。6. 核心参数速查表下表汇总了 2.x whl 包的关键参数完整说明见 whl 包文档参数说明默认值use_gpu是否使用 GPUTRUEgpu_memGPU 初始化显存大小8000Mimage_dir命令行预测的图片路径或目录—page_numPDF 输入时指定推理前 N 页0 表示全部0det_algorithm检测算法类型DBdet_model_dir检测推理模型目录None 时自动下载内置模型到~/.paddleocr/detNonedet_max_side_len检测时图像长边最大值超长则等比缩放960det_db_threshDB 输出图二值化阈值0.3det_db_box_threshDB 输出框阈值低于该值的框被丢弃0.5det_db_unclip_ratioDB 输出框的扩张比例2det_db_score_mode检测框得分计算方式fast/slow弯曲文本建议slowfastrec_algorithm识别算法类型CRNNrec_model_dir识别推理模型目录None 时自动下载到~/.paddleocr/recNonerec_image_shape识别算法输入图像形状3,32,320rec_batch_num识别前向推理的 batch size30max_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分类前向推理的 batch size30enable_mkldnn是否启用 MKL-DNN 加速FALSElang语言缩写如 ch/en/fr/german/korean/japanchdet/rec/cls调用ocr()时是否启用对应模块TRUE / TRUE / FALSEshow_log是否打印日志FALSEtype执行 OCR 还是版面结构化取值ocr/structureocrocr_versionOCR 模型版本号PP-OCRv4/v3/v2/PP-OCRPP-OCRv4参数要点解读检测三阈值det_db_thresh/det_db_box_thresh/det_db_unclip_ratio直接控制 DB 算法的二值化、候选框筛选与框外扩密集小字场景可适当调低det_db_box_thresh以减少漏检det_max_side_len控制检测阶段输入图像长边上限超长图会被等比压缩这也是超大图需要配合 slice 切片的原因drop_score用于按置信度过滤识别结果低质量文本区域可通过调高该值清洗输出use_angle_cls开启后整图会先经方向分类器判断是否旋转 180°再进入检测识别对扫描件方向不确定的场景建议开启。7. 小结通过本文你已完整掌握 PaddleOCR 2.x whl 包的实战路径从 PaddlePaddle 与 PaddleOCR 安装、命令行三模块组合调用、PP-OCRv4/v3/v2/PP-OCR 版本切换、80 语言模型切换到 Python API 的检测/识别/分类自由组合、PDF 逐页推理可视化、超大图滑窗切片以及自定义模型、URL 与 numpy 数组输入等进阶用法。文档中提及的更多部署方式Python 推理、C 推理、Serving、移动端等可继续查阅 多语言模型教程 第 4 节及相关部署文档深入实践。【免费下载链接】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），仅供参考