文本检测模块使用教程

一、概述

文本检测模块是OCR（光学字符识别）系统中的关键组成部分，负责在图像中定位和标记出包含文本的区域。该模块的性能直接影响到整个OCR系统的准确性和效率。文本检测模块通常会输出文本区域的边界框（Bounding Boxes），这些边界框将作为输入传递给文本识别模块进行后续处理。

二、支持模型列表

推理耗时仅包含模型推理耗时，不包含前后处理耗时。表格中的“常规模式”耗时对应本地 <code>paddle_static</code> 推理引擎。

<table> <thead> <tr> <th>模型</th><th>模型下载链接</th> <th>检测Hmean（%）</th> <th>GPU推理耗时（ms） [常规模式 / 高性能模式]</th> <th>CPU推理耗时（ms） [常规模式 / 高性能模式]</th> <th>模型存储大小（MB）</th> <th>介绍</th> </tr> </thead> <tbody> <tr> <td>PP-OCRv5_server_det</td> <td><a href="https://paddle-model-ecology.bj.bcebos.com/paddlex/official_inference_model/paddle3.0.0/PP-OCRv5_server_det_infer.tar">推理模型</a>/<a href="https://paddle-model-ecology.bj.bcebos.com/paddlex/official_pretrained_model/PP-OCRv5_server_det_pretrained.pdparams">训练模型</a></td> <td>83.8</td> <td>89.55 / 70.19</td> <td>383.15 / 383.15</td> <td>84.3</td> <td>PP-OCRv5 的服务端文本检测模型，精度更高，适合在性能较好的服务器上部署</td> </tr> <tr> <td>PP-OCRv5_mobile_det</td> <td><a href="https://paddle-model-ecology.bj.bcebos.com/paddlex/official_inference_model/paddle3.0.0/PP-OCRv5_mobile_det_infer.tar">推理模型</a>/<a href="https://paddle-model-ecology.bj.bcebos.com/paddlex/official_pretrained_model/PP-OCRv5_mobile_det_pretrained.pdparams">训练模型</a></td> <td>79.0</td> <td>10.67 / 6.36</td> <td>57.77 / 28.15</td> <td>4.7</td> <td>PP-OCRv5 的移动端文本检测模型，效率更高，适合在端侧设备部署</td> </tr> <tr> <td>PP-OCRv4_server_det</td> <td><a href="https://paddle-model-ecology.bj.bcebos.com/paddlex/official_inference_model/paddle3.0.0/PP-OCRv4_server_det_infer.tar">推理模型</a>/<a href="https://paddle-model-ecology.bj.bcebos.com/paddlex/official_pretrained_model/PP-OCRv4_server_det_pretrained.pdparams">训练模型</a></td> <td>69.2</td> <td>127.82 / 98.87</td> <td>585.95 / 489.77</td> <td>109</td> <td>PP-OCRv4 的服务端文本检测模型，精度更高，适合在性能较好的服务器上部署</td> </tr> <tr> <td>PP-OCRv4_mobile_det</td> <td><a href="https://paddle-model-ecology.bj.bcebos.com/paddlex/official_inference_model/paddle3.0.0/PP-OCRv4_mobile_det_infer.tar">推理模型</a>/<a href="https://paddle-model-ecology.bj.bcebos.com/paddlex/official_pretrained_model/PP-OCRv4_mobile_det_pretrained.pdparams">训练模型</a></td> <td>63.8</td> <td>9.87 / 4.17</td> <td>56.60 / 20.79</td> <td>4.7</td> <td>PP-OCRv4 的移动端文本检测模型，效率更高，适合在端侧设备部署</td> </tr> </tbody> </table>

<strong>测试环境说明:</strong>

<ul> <li><b>性能测试环境</b> <ul> <li><strong>测试数据集：</strong>PaddleOCR3.0 全新构建多语种（包含中、繁、英、日），覆盖街景、网图、文档、手写、模糊、旋转、扭曲等多个场景的文本检测数据集，包含2677 张图片。</li> <li><strong>硬件配置：</strong> <ul> <li>GPU：NVIDIA Tesla T4</li> <li>CPU：Intel Xeon Gold 6271C @ 2.60GHz</li> </ul> </li> <li><strong>软件环境：</strong> <ul> <li>Ubuntu 20.04 / CUDA 11.8 / cuDNN 8.9 / TensorRT 8.6.1.6</li> <li>paddlepaddle-gpu 3.0.0 / paddleocr 3.0.3</li> </ul> </li> </ul> </li> <li><b>推理模式说明</b></li> </ul> <table border="1"> <thead> <tr> <th>模式</th> <th>GPU配置</th> <th>CPU配置</th> <th>加速技术组合</th> </tr> </thead> <tbody> <tr> <td>常规模式</td> <td>FP32精度 / 无TRT加速</td> <td>FP32精度 / 8线程</td> <td>PaddleInference</td> </tr> <tr> <td>高性能模式</td> <td>选择先验精度类型和加速策略的最优组合</td> <td>FP32精度 / 8线程</td> <td>选择先验最优后端（Paddle/OpenVINO/TRT等）</td> </tr> </tbody> </table>

三、快速开始

❗ 在快速开始前，请先安装 PaddleOCR 的 wheel 包，详细请参考安装教程。

3.1 环境准备

3.1.1 基础安装

bash

# 安装基础版本（仅包含文本检测功能）
pip install paddleocr

# 安装完整版本（包含所有功能）
pip install "paddleocr[all]"

3.1.2 环境验证

python

# 验证安装是否成功
import paddleocr
print(f"PaddleOCR版本: {paddleocr.__version__}")

# 验证GPU是否可用
import paddle
print(f"Paddle版本: {paddle.__version__}")
print(f"GPU可用: {paddle.is_compiled_with_cuda()}")
print(f"GPU数量: {paddle.device.cuda.device_count()}")

3.2 命令行快速体验

使用一行命令即可快速体验：

bash

# 使用默认模型进行文本检测
paddleocr text_detection -i https://paddle-model-ecology.bj.bcebos.com/paddlex/imgs/demo_image/general_ocr_001.png

# 指定模型进行检测
paddleocr text_detection -i general_ocr_001.png --model_name PP-OCRv5_server_det

# 批量处理本地图片
paddleocr text_detection -i ./images/ --model_name PP-OCRv5_mobile_det

上述示例默认使用 <code>paddle_static</code> 推理引擎，请先按照飞桨框架安装完成 PaddlePaddle 安装。

如果选择 transformers 作为推理引擎，请确保已配置 Transformers 环境，然后执行如下命令：

bash

# 使用 transformers 引擎进行推理
paddleocr text_detection -i https://paddle-model-ecology.bj.bcebos.com/paddlex/imgs/demo_image/general_ocr_001.png \
    --engine transformers

在大多数场景下，默认的 paddle_static 推理引擎通常具备更好的推理性能，建议优先使用。

<b>注：</b>PaddleOCR 官方模型默认从 HuggingFace 获取，如运行环境访问 HuggingFace 不便，可通过环境变量修改模型源为 BOS：PADDLE_PDX_MODEL_SOURCE="BOS"，未来将支持更多主流模型源；

3.3 Python API 使用

您也可以将文本检测的模块中的模型推理集成到您的项目中。运行以下代码前，请您下载示例图片到本地。

python

from paddleocr import TextDetection
model = TextDetection(model_name="PP-OCRv5_server_det")
output = model.predict("general_ocr_001.png", batch_size=1)
for res in output:
    res.print()
    res.save_to_img(save_path="./output/")
    res.save_to_json(save_path="./output/res.json")

上述示例默认使用 <code>paddle_static</code> 推理引擎，请先按照飞桨框架安装完成 PaddlePaddle 安装。

如果选择 transformers 作为推理引擎，请确保已配置 Transformers 环境，然后执行如下代码：

python

from paddleocr import TextDetection
model = TextDetection(
    model_name="PP-OCRv5_server_det",
    engine="transformers",
)
output = model.predict("general_ocr_001.png", batch_size=1)
for res in output:
    res.print()
    res.save_to_img(save_path="./output/")
    res.save_to_json(save_path="./output/res.json")

在大多数场景下，默认的 paddle_static 推理引擎通常具备更好的推理性能，建议优先使用。

训练后的模型如果想使用 paddle_dynamic 或 transformers 引擎，请参考后文推理引擎中的权重转换部分将模型由 pdparams 格式通过 PaddleX 转换为 safetensors 格式。

运行后，得到的结果为：

bash

{'res': {'input_path': 'general_ocr_001.png', 'page_index': None, 'dt_polys': array([[[ 75, 549],
        ...,
        [ 77, 586]],

       ...,

       [[ 31, 406],
        ...,
        [ 34, 455]]], dtype=int16), 'dt_scores': [0.873949039891189, 0.8948166013613552, 0.8842595305917041, 0.876953790920377]}}

运行结果参数含义如下：

<ul> <li><code>input_path</code>：表示输入待预测图像的路径</li> <li><code>page_index</code>：如果输入是PDF文件，则表示当前是PDF的第几页，否则为 <code>None</code></li> <li><code>dt_polys</code>：表示预测的文本检测框，其中每个文本检测框包含一个四边形的四个顶点。其中每个顶点都是一个列表，分别表示该顶点的x坐标和y坐标</li> <li><code>dt_scores</code>：表示预测的文本检测框的置信度</li> </ul> 可视化图片如下：

相关方法、参数等说明如下：

<code>TextDetection</code>类实例化文本检测模型（此处以<code>PP-OCRv5_server_det</code>为例），具体说明如下：

<table> <thead> <tr> <th>参数</th> <th>参数说明</th> <th>参数类型</th> <th>默认值</th> </tr> </thead> <tbody> <tr> <td><code>model_name</code></td> <td><b>含义：</b>模型名称。

<b>说明：</b> 如果设置为<code>None</code>，则使用<code>PP-OCRv5_server_det</code>。</td>

<td><code>str|None</code></td> <td><code>None</code></td> </tr> <tr> <td><code>model_dir</code></td> <td><b>含义：</b>模型存储路径。</td> <td><code>str|None</code></td> <td><code>None</code></td> </tr> <tr> <td><code>device</code></td> <td><b>含义：</b>用于推理的设备。

<b>说明：</b> <b>例如：</b><code>"cpu"</code>、<code>"gpu"</code>、<code>"npu"</code>、<code>"gpu:0"</code>、<code>"gpu:0,1"</code>。

如指定多个设备，将进行并行推理。

默认情况下，优先使用 GPU 0；若不可用则使用 CPU。

</td> <td><code>str|None</code></td> <td><code>None</code></td> </tr> <tr> <td><code>engine</code></td> <td><b>含义：</b>推理引擎。 <b>说明：</b>支持 <code>None</code>（默认值）、<code>paddle</code>、<code>paddle_static</code>、<code>paddle_dynamic</code>、<code>transformers</code>。保持为默认值 <code>None</code> 时，本地推理默认使用 <code>paddle_static</code> 引擎。详细说明、取值、兼容性规则与示例请参见 <a href="../inference_engine.md">推理引擎与配置说明</a>。</td> <td><code>str|None</code></td> <td><code>None</code></td> </tr> <tr> <td><code>engine_config</code></td> <td><b>含义：</b>推理引擎配置。 <b>说明：</b>推荐与 <code>engine</code> 搭配使用。详细字段、兼容性规则与示例请参见 <a href="../inference_engine.md">推理引擎与配置说明</a>。</td> <td><code>dict|None</code></td> <td><code>None</code></td> </tr> <tr> <td><code>enable_hpi</code></td> <td><b>含义：</b>是否启用高性能推理。</td> <td><code>bool</code></td> <td><code>False</code></td> </tr> <tr> <td><code>use_tensorrt</code></td> <td><b>含义：</b>是否启用 Paddle Inference 的 TensorRT 子图引擎。

<b>说明：</b> 如果模型不支持通过 TensorRT 加速，即使设置了此标志，也不会使用加速。

对于 CUDA 11.8 版本的飞桨，兼容的 TensorRT 版本为 8.x（x>=6），建议安装 TensorRT 8.6.1.6。

</td> <td><code>bool</code></td> <td><code>False</code></td> </tr> <tr> <td><code>precision</code></td> <td><b>含义：</b>当使用 Paddle Inference 的 TensorRT 子图引擎时设置的计算精度。

<td><code>str</code></td> <td><code>"fp32"</code></td> </tr> <tr> <td><code>enable_mkldnn</code></td> <td> <b>含义：</b>是否启用 MKL-DNN 加速推理。

<b>说明：</b> 如果 MKL-DNN 不可用或模型不支持通过 MKL-DNN 加速，即使设置了此标志，也不会使用加速。

</td> <td><code>bool</code></td> <td><code>True</code></td> </tr> <tr> <td><code>mkldnn_cache_capacity</code></td> <td> <b>含义：</b>MKL-DNN 缓存容量。 </td> <td><code>int</code></td> <td><code>10</code></td> </tr> <tr> <td><code>cpu_threads</code></td> <td><b>含义：</b>在 CPU 上推理时使用的线程数量。</td> <td><code>int</code></td> <td><code>10</code></td> </tr> <tr> <td><code>limit_side_len</code></td> <td><b>含义：</b>检测的图像边长限制：<code>int</code> 表示边长限制数值。

<b>说明：</b> 如果设置为<code>None</code>，将使用模型默认配置。</td>

<td><code>int|None</code></td> <td><code>None</code></td> </tr> <tr> <td><code>limit_type</code></td> <td><b>含义：</b>检测的图像边长限制，检测的边长限制类型。

<b>说明：</b> <code>"min"</code> 表示保证图像最短边不小于det_limit_side_len，<code>"max"</code>表示保证图像最长边不大于limit_side_len。如果设置为<code>None</code>，将使用模型默认配置。</td>

<td><code>str|None</code></td> <td><code>None</code></td> </tr> <tr> <td><code>max_side_limit</code></td> <td><b>含义：</b>检测的图像边长最大值限制：<code>int</code> 限制输入检测模型的图片最长边。

<b>说明：</b> 如果设置为 <code>None</code>，将使用模型默认配置。</td>

<td><code>int|None</code></td> <td><code>None</code></td> </tr> <tr> <td><code>thresh</code></td> <td><b>含义：</b>像素得分阈值。输出概率图中得分大于该阈值的像素点被认为是文本像素。

<b>说明：</b> 如果设置为<code>None</code>，将使用模型默认配置。</td>

<td><code>float|None</code></td> <td><code>None</code></td> </tr> <tr> <td><code>box_thresh</code></td> <td><b>含义：</b>检测结果边框内，所有像素点的平均得分大于该阈值时，该结果会被认为是文字区域。

<b>说明：</b> 如果设置为<code>None</code>，将使用模型默认配置。</td>

<td><code>float|None</code></td> <td><code>None</code></td> </tr> <tr> <td><code>unclip_ratio</code></td> <td><b>含义：</b>Vatti clipping算法的扩张系数，使用该方法对文字区域进行扩张。

<b>说明：</b> 如果设置为<code>None</code>，将使用模型默认配置。</td>

<td><code>float|None</code></td> <td><code>None</code></td> </tr> <tr> <td><code>input_shape</code></td> <td><b>含义：</b>模型输入图像尺寸，格式为 <code>(C, H, W)</code>。</td> <td><code>tuple|None</code></td> <td><code>None</code></td> </tr> </tbody> </table>

调用文本检测模型的 <code>predict()</code> 方法进行推理预测，该方法会返回一个结果列表。另外，本模块还提供了 <code>predict_iter()</code> 方法。两者在参数接受和结果返回方面是完全一致的，区别在于 <code>predict_iter()</code> 返回的是一个 <code>generator</code>，能够逐步处理和获取预测结果，适合处理大型数据集或希望节省内存的场景。可以根据实际需求选择使用这两种方法中的任意一种。<code>predict()</code> 方法参数有 <code>input</code> 、<code>batch_size</code>、 <code>limit_side_len</code>、 <code>limit_type</code>、 <code>thresh</code>、 <code>box_thresh</code>、 <code>max_candidates</code>、<code>unclip_ratio</code>，具体说明如下：

<table> <thead> <tr> <th>参数</th> <th>参数说明</th> <th>参数类型</th> <th>默认值</th> </tr> </thead> <tr> <td><code>input</code></td> <td><b>含义：</b>待预测数据，支持多种输入类型，必填。

<ul> <li><b>Python Var</b>：如 <code>numpy.ndarray</code> 表示的图像数据</li> <li><b>str</b>：如图像文件或者PDF文件的本地路径：<code>/root/data/img.jpg</code>；<b>如URL链接</b>，如图像文件或PDF文件的网络URL：<a href="https://paddle-model-ecology.bj.bcebos.com/paddlex/imgs/demo_image/general_ocr_rec_001.png">示例</a>；<b>如本地目录</b>，该目录下需包含待预测图像，如本地路径：<code>/root/data/</code>(当前不支持目录中包含PDF文件的预测，PDF文件需要指定到具体文件路径)</li> <li><b>list</b>：列表元素需为上述类型数据，如<code>[numpy.ndarray, numpy.ndarray]</code>，<code>["/root/data/img1.jpg", "/root/data/img2.jpg"]</code>，<code>["/root/data1", "/root/data2"]</code></li> </ul> </td> <td><code>Python Var|str|list</code></td> <td></td> </tr> <tr> <td><code>batch_size</code></td> <td><b>含义：</b>批大小

<b>说明：</b> 可设置为任意正整数。</td>

<td><code>int</code></td> <td>1</td> </tr> <tr> <td><code>limit_side_len</code></td> <td><b>含义:</b>参数含义与实例化参数基本相同。