企业官网建设流程全解析

• 人工智能
• 计算机视觉
• OCR
• 深度学习
• 大模型
• RAG

本文以 PaddleOCR 仓库 docs/version2.x/ppocr/quick_start.en.md 为核心骨架，系统讲解基于 PP-OCR 系列模型（PP-OCR / PP-OCRv2 / PP-OCRv3 / PP-OCRv4 及其后续版本）的快速使用方式：包括 PaddlePaddle 与paddleocrwhl 包的安装、命令行一键式 OCR、Python 代码调用、结果可视化、PDF 文档推理、滑动窗口切片以及 80+ 语言模型的切换。读者学完后，将能够在自己的机器上用三条命令完成「检测 + 方向分类 + 识别」的端到端 OCR 推理，并能够把识别结果绘制回原图、扩展到自定义模型与多语言场景。

提示：本文聚焦 PP-OCR 系列模型的快速使用。如需文档解析（版面分析、表格识别、公式识别等）相关功能，请参阅 PP-Structure 快速上手。

1. 环境安装

1.1 安装 PaddlePaddle 深度学习框架

paddleocr依赖飞桨（PaddlePaddle）作为底层推理引擎。如果本机尚无 Python 环境，请先参考 环境准备 完成 Python 与依赖的搭建。

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

• 有 NVIDIA GPU（CUDA 11）：安装 GPU 版本（注意版本约束<=2.6，与本文档对应的 PaddleOCR 2.x 系列兼容）：

  pip install "paddlepaddle-gpu<=2.6"

• 无可用 GPU（纯 CPU 环境）：安装 CPU 版本：

  python -m pip install "paddlepaddle<=2.6"

PaddlePaddle 对各操作系统、Python 版本与 CUDA 版本有具体的兼容矩阵，安装前建议对照官方安装指引核对软件版本要求。对于 Windows 用户，若安装shapely时出现OSError: [WinError 126] The specified module could not be found，可尝试下载预编译的 Shapely whl 文件进行安装。

1.2 安装 PaddleOCR whl 包

pip install "paddleocr>=2.0.1" # 推荐使用 2.0.1 及以上版本

安装完成后即获得paddleocr命令行工具与PaddleOCRPython 类。当前仓库中，paddleocr包在 paddleocr/init.py 中导出了PaddleOCR、TextDetection、TextRecognition、PPStructureV3等一系列推理入口，其中PaddleOCR类被特别注释为"与 PaddleOCR 2.x 接口保持兼容"，因此 2.x 时代的使用习惯可以平滑迁移。

2. 命令行一键使用（Easy-to-Use）

PaddleOCR 提供了系列测试图片，下载后解压，并在终端中切换到对应目录：

cd /path/to/ppocr_img

如果不使用官方测试图，把下面的--image_dir参数替换为本地图片路径即可。

2.1 中英文模型

① 检测 + 方向分类 + 识别（完整流水线）

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)] ......

其中--use_gpu false用于在无 GPU 设备时禁用 GPU 推理；--use_angle_cls true开启文本行方向分类器（处理旋转 180° 的文字）；--lang en指定语言为英文。

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]] [[397.0, 702.0], [1209.0, 698.0], [1209.0, 734.0], [397.0, 738.0]] ......

③ 仅识别：把--det设为false，关闭检测子模块（此时输入通常是已裁剪好的单词/文本行图片）：

paddleocr --image_dir ./imgs_words_en/word_10.png --det false --lang en

输出只包含文本与置信度：

['PAIN', 0.9934559464454651]

2.2 选择 PP-OCR 模型版本（--ocr_version）

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

从当前仓库源码看，3.x 兼容层的模型版本支持面进一步扩大：paddleocr/_pipelines/ocr.py 中定义_SUPPORTED_OCR_VERSIONS = ["PP-OCRv3", "PP-OCRv4", "PP-OCRv5", "PP-OCRv6"]，PaddleOCR(ocr_version=...)构造函数会校验传入版本并抛出ValueError；当lang与ocr_version均未指定时，_get_ocr_model_names()默认返回PP-OCRv6_medium_det与PP-OCRv6_medium_rec两个模型名。也就是说，文档层面的"默认 v4"是针对 2.x 指南的表述，当前仓库代码在未显式指定时已默认走 PP-OCRv6 系列模型，且会根据lang自动匹配最合适的版本与模型（例如ch、en、japan等语言落在 PP-OCRv6，拉丁语系小语种落在 PP-OCRv5，ka（格鲁吉亚语）回退到 PP-OCRv3），详见 paddleocr/_pipelines/ocr.py 的_get_ocr_model_names实现。

如果想接入自己训练的模型，可以在paddleocr.py中追加模型链接与键值后重新编译；更推荐的做法是使用 3.x 接口的text_detection_model_dir/text_recognition_model_dir参数直接指定推理模型目录（详见下文第 5 节）。

whl 包的更多用法可参阅 whl 包使用文档。

2.3 多语言模型（80+ 语言）

PaddleOCR 目前支持80 种语言，通过修改--lang参数即可切换，无需更换代码：

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

输出同样是「文本框 + 文本 + 置信度」的列表：

[[[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)] ......

常用语言的缩写对照如下：

全部语言及其对应缩写的完整列表可参阅 多语言模型教程。从源码结构看，语言映射在 paddleocr/_utils/langs.py 中被组织为若干字符集分组：LATIN_LANGS（拉丁语系，含fr、german、it、es、vi等 50 个左右代码）、ARABIC_LANGS（阿拉伯语系）、CYRILLIC_LANGS（西里尔语系）、ESLAV_LANGS（斯拉夫语系）、DEVANAGARI_LANGS（天城文语系）。PaddleOCR在解析lang时正是依据这些分组去匹配对应的识别模型，这也是"80+ 语言一条命令切换"得以实现的底层机制。

3. Python 代码调用

3.1 中英文 / 多语言模型：检测 + 方向分类 + 识别

from paddleocr import PaddleOCR, draw_ocr # Paddleocr 支持中文、英文、法语、德语、韩语、日语等。 # 可通过设置参数 `lang` 为 `ch`、`en`、`fr`、`german`、`korean`、`japan` 来切换对应语言模型。 ocr = PaddleOCR(use_angle_cls=True, lang='en') # 只需运行一次，自动下载并加载模型到内存 img_path = './imgs_en/img_12.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')

输出为列表，每项包含文本框、文本与识别置信度：

[[[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)] ......

可视化效果如下（红色边界框标出文字区域并叠加识别文本）：

字体文件simfang.ttf可在仓库 doc/fonts/simfang.ttf 中找到，用于保证中文等文字在可视化时正确渲染。从源码结构看，draw_ocr由paddleocr包导出（见 paddleocr/init.py），而PaddleOCR.ocr()方法在当前仓库中被标记为@deprecated("Please use \predict` instead.")，即 3.x 兼容层推荐改用predict/predict_iter` 接口（见 paddleocr/_pipelines/ocr.py），两者返回结构保持一致，旧代码仍可运行。

3.2 直接推理 PDF 并逐页可视化

若输入是 PDF 文件，PaddleOCR会按页返回结果（无内容的页返回None，需要跳过），配合fitz（PyMuPDF）把 PDF 渲染成图像后即可逐页绘制：

from paddleocr import PaddleOCR, draw_ocr # Paddleocr 支持中文、英文、法语、德语、韩语和日语。 # 通过设置 `lang` 为 `ch`、`en`、`fr`、`german`、`korean`、`japan` 切换语言模型。 PAGE_NUM = 10 # 设置识别的页数 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 == None: # 空结果时跳过，避免 TypeError:NoneType 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 == 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))

使用前需安装 PDF 渲染依赖：pip install PyMuPDF（即fitz）。命令行方式只需在--image_dir中传入 PDF 路径并配合--page_num即可，无需额外编写渲染代码。

3.3 大图的滑动窗口切片推理（slice）

对于超大尺寸图片，PaddleOCR 支持按滑动窗口切片推理，避免整图缩放导致的小字漏检。示例代码如下：

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")

slice字典中的四个键含义为：horizontal_stride/vertical_stride控制水平 / 垂直方向切片的步长（即相邻窗口的重叠程度），merge_x_thres/merge_y_thres控制相邻切片检测框在 x / y 方向上的合并阈值，阈值越大越倾向于把跨切片的文本框合并为一条。更完整的切片机制说明可参阅 slice 操作文档。

4. 核心参数详解

下表整理了paddleocr常用参数及其默认值，覆盖检测（DB 算法）、识别（CRNN 算法）、方向分类与运行环境四类配置：

参数与源码的对应关系：以 DB 检测为例，上表中的det_db_thresh、det_db_box_thresh、det_db_unclip_ratio、det_max_side_len对应 paddleocr/_pipelines/ocr.py 中PaddleOCR构造函数的text_det_thresh、text_det_box_thresh、text_det_unclip_ratio、text_det_limit_side_len参数；从 paddleocr/_pipelines/ocr.py 的 CLI 帮助文本可以确认它们的语义：text_det_thresh是概率图上判定文本像素的像素级阈值，text_det_box_thresh是判定文本框的边框平均得分阈值，text_det_unclip_ratio是文本框外扩系数（值越大外扩区域越大）。此外，2.x 时代的参数名（如det_model_dir、rec_model_dir、rec_batch_num、use_angle_cls、cls_model_dir等）在当前 3.x 兼容层中仍可使用，但会收到弃用告警并被映射到新名称（见 paddleocr/_pipelines/ocr.py 的_DEPRECATED_PARAM_NAME_MAPPING）；命令行模式下，--use_gpu也已由通用参数--device（取值如cpu、gpu、gpu:0、npu）取代，并新增了--engine（paddle / paddle_static / onnxruntime / transformers 等）、--precision、--enable_mkldnn、--cpu_threads等推理引擎配置项（见 paddleocr/_common_args.py）。本快速上手文档以 2.x 的--use_gpu写法为准，在新版本环境遇到参数不存在时，请优先改用上述新参数名。

5. 进阶：使用自定义模型、网络图片与 numpy 输入

当内置模型无法满足需求时，可加载自训练的推理模型。推理模型目录必须同时包含model与params两个文件（训练模型需先完成导出，导出方法可参考 model_train 训练与导出文档）。

• 代码方式：

  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 = 'PaddleOCR/doc/imgs_en/img_12.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='/path/to/PaddleOCR/doc/fonts/simfang.ttf') im_show = Image.fromarray(im_show) im_show.save('result.jpg')

• 命令行方式：

  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

此外，--image_dir也支持URL 形式的网络图片（代码与命令行均可直接传入 http 链接），而numpy 数组输入则仅限代码方式——直接把cv2.imread读取得到的 BGR 数组传给ocr.ocr(img)即可，无需保存为临时文件。

6. 总结

通过本文，你已经掌握了 PaddleOCR whl 包的完整使用链路：

1. 安装：pip install "paddlepaddle<=2.6"（或 GPU 版）+pip install "paddleocr>=2.0.1"；
2. 命令行三连：paddleocr --image_dir <img> --use_angle_cls true --lang <lang>一次完成检测、方向分类与识别；--rec false/--det false可单独关闭识别或检测；--page_num N支持 PDF 前 N 页推理；--ocr_version切换 PP-OCR 系列版本；--lang切换 80+ 语言；
3. Python 编程：实例化PaddleOCR(use_angle_cls=True, lang='en')后调用ocr.ocr(img_path, cls=True)，配合draw_ocr与doc/fonts/simfang.ttf字体即可输出带边界框的可视化结果；超大图用slice参数滑动切片；PDF 场景可叠加 PyMuPDF 完成逐页渲染与绘制；
4. 自定义扩展：传入det_model_dir/rec_model_dir/rec_char_dict_path即可无缝替换为自己训练的模型。

进一步深入学习可继续阅读 whl 包使用文档、推理参数说明、多语言模型教程 与 slice 切片操作文档；需要文档解析能力时，请转至 PP-Structure 快速上手。

• 人工智能
• 计算机视觉
• OCR
• 深度学习
• 大模型
• RAG