paddle_static 推理引擎。
| 模型 | 模型下载链接 | mAP(%) | GPU推理耗时（ms） [常规模式 / 高性能模式] |
CPU推理耗时（ms） [常规模式 / 高性能模式] |
模型存储大小（MB） | 介绍 |
|---|---|---|---|---|---|---|
| RT-DETR-L_wired_table_cell_det | 推理模型/训练模型 | 82.7 | 33.47 / 27.02 | 402.55 / 256.56 | 124 | RT-DETR 是一个实时的端到端目标检测模型。百度飞桨视觉团队基于 RT-DETR-L 作为基础模型，在自建表格单元格检测数据集上完成预训练，实现了对有线表格、无线表格均有较好性能的表格单元格检测。 |
| RT-DETR-L_wireless_table_cell_det | 推理模型/训练模型 |
| 模式 | GPU配置 | CPU配置 | 加速技术组合 |
|---|---|---|---|
| 常规模式 | FP32精度 / 无TRT加速 | FP32精度 / 8线程 | PaddleInference |
| 高性能模式 | 选择先验精度类型和加速策略的最优组合 | FP32精度 / 8线程 | 选择先验最优后端（Paddle/OpenVINO/TRT等） |
paddle_static 推理引擎，请先按照[飞桨框架安装](../paddlepaddle_installation.md)完成 PaddlePaddle 安装。
如果选择 `transformers` 作为推理引擎，请确保已配置 Transformers 环境，然后执行如下命令：
```bash
# 使用 transformers 引擎进行推理
paddleocr table_cells_detection -i https://paddle-model-ecology.bj.bcebos.com/paddlex/imgs/demo_image/table_recognition.jpg \
--engine transformers
```
如果选择 `onnxruntime` 作为推理引擎，请确保已配置 ONNX Runtime 环境，然后执行如下命令：
```bash
# 使用 onnxruntime 引擎进行推理
paddleocr table_cells_detection -i https://paddle-model-ecology.bj.bcebos.com/paddlex/imgs/demo_image/table_recognition.jpg \
--engine onnxruntime
```
在大多数场景下，默认的 `paddle_static` 推理引擎通常具备更好的推理性能，建议优先使用。
注：PaddleOCR 官方模型默认从 HuggingFace 获取，如运行环境访问 HuggingFace 不便，可通过环境变量修改模型源为 BOS：`PADDLE_PDX_MODEL_SOURCE="BOS"`，未来将支持更多主流模型源；
您也可以将表格单元格检测的模块中的模型推理集成到您的项目中。运行以下代码前，请您下载[示例图片](https://paddle-model-ecology.bj.bcebos.com/paddlex/imgs/demo_image/table_recognition.jpg)到本地。
```python
from paddleocr import TableCellsDetection
model = TableCellsDetection(model_name="RT-DETR-L_wired_table_cell_det")
output = model.predict("table_recognition.jpg", threshold=0.3, batch_size=1)
for res in output:
res.print(json_format=False)
res.save_to_img("./output/")
res.save_to_json("./output/res.json")
```
上述示例默认使用 paddle_static 推理引擎，请先按照[飞桨框架安装](../paddlepaddle_installation.md)完成 PaddlePaddle 安装。
如果选择 `transformers` 作为推理引擎，请确保已配置 Transformers 环境，然后执行如下代码：
```python
from paddleocr import TableCellsDetection
model = TableCellsDetection(
model_name="RT-DETR-L_wired_table_cell_det",
engine="transformers",
)
output = model.predict("table_recognition.jpg", threshold=0.3, batch_size=1)
for res in output:
res.print(json_format=False)
res.save_to_img("./output/")
res.save_to_json("./output/res.json")
```
如果选择 `onnxruntime` 作为推理引擎，请确保已配置 ONNX Runtime 环境，然后执行如下代码：
```python
from paddleocr import TableCellsDetection
model = TableCellsDetection(
model_name="RT-DETR-L_wired_table_cell_det",
engine="onnxruntime",
)
output = model.predict("table_recognition.jpg", threshold=0.3, batch_size=1)
for res in output:
res.print(json_format=False)
res.save_to_img("./output/")
res.save_to_json("./output/res.json")
```
在大多数场景下，默认的 `paddle_static` 推理引擎通常具备更好的推理性能，建议优先使用。
训练后的模型如果想使用 `paddle_dynamic` 或 `transformers` 引擎，请参考后文 [推理引擎](#五推理引擎) 中的 [权重转换](#52-权重转换) 部分将模型由 `pdparams` 格式通过 PaddleX 转换为 `safetensors` 格式。
运行后，得到的结果为：
```
{'res': {'input_path': 'table_recognition.jpg', 'page_index': None, 'boxes': [{'cls_id': 0, 'label': 'cell', 'score': 0.9698355197906494, 'coordinate': [2.3011515, 0, 546.29926, 30.530712]}, {'cls_id': 0, 'label': 'cell', 'score': 0.9690820574760437, 'coordinate': [212.37508, 64.62493, 403.58868, 95.61413]}, {'cls_id': 0, 'label': 'cell', 'score': 0.9668057560920715, 'coordinate': [212.46791, 30.311079, 403.7182, 64.62613]}, {'cls_id': 0, 'label': 'cell', 'score': 0.966505229473114, 'coordinate': [403.56082, 64.62544, 546.83215, 95.66117]}, {'cls_id': 0, 'label': 'cell', 'score': 0.9662341475486755, 'coordinate': [109.48873, 64.66485, 212.5177, 95.631294]}, {'cls_id': 0, 'label': 'cell', 'score': 0.9654079079627991, 'coordinate': [212.39197, 95.63037, 403.60852, 126.78792]}, {'cls_id': 0, 'label': 'cell', 'score': 0.9653300642967224, 'coordinate': [2.2320926, 64.62229, 109.600494, 95.59732]}, {'cls_id': 0, 'label': 'cell', 'score': 0.9639787673950195, 'coordinate': [403.5752, 30.562355, 546.98975, 64.61531]}, {'cls_id': 0, 'label': 'cell', 'score': 0.9636150002479553, 'coordinate': [2.1537683, 30.410172, 109.568306, 64.62762]}, {'cls_id': 0, 'label': 'cell', 'score': 0.9631900191307068, 'coordinate': [2.0534437, 95.57448, 109.57601, 126.71458]}, {'cls_id': 0, 'label': 'cell', 'score': 0.9631181359291077, 'coordinate': [403.65976, 95.68139, 546.84766, 126.713394]}, {'cls_id': 0, 'label': 'cell', 'score': 0.9614537358283997, 'coordinate': [109.56504, 30.391184, 212.65425, 64.6444]}, {'cls_id': 0, 'label': 'cell', 'score': 0.9607433080673218, 'coordinate': [109.525795, 95.62622, 212.44917, 126.8258]}]}}
```
参数含义如下：
input_path：输入的待预测图像的路径page_index：如果输入是PDF文件，则表示当前是PDF的第几页，否则为 Noneboxes：预测的目标框信息，一个字典列表。每个字典代表一个检出的目标，包含以下信息：
cls_id：类别ID，一个整数label：类别标签，一个字符串score：目标框置信度，一个浮点数coordinate：目标框坐标，一个浮点数列表，格式为[xmin, ymin, xmax, ymax]
相关方法、参数等说明如下：
* TableCellsDetection实例化表格单元格检测模型（此处以RT-DETR-L_wired_table_cell_det为例），具体说明如下：
| 参数 | 参数说明 | 参数类型 | 默认值 |
|---|---|---|---|
model_name |
含义：模型名称。 说明： 如果设置为 None，则使用RT-DETR-L_wired_table_cell_det。 |
str|None |
None |
model_dir |
含义：模型存储路径。 | str|None |
None |
device |
含义：用于推理的设备。 说明： 例如： "cpu"、"gpu"、"npu"、"gpu:0"、"gpu:0,1"。如指定多个设备，将进行并行推理。 默认情况下，优先使用 GPU 0；若不可用则使用 CPU。 |
str|None |
None |
engine |
含义：推理引擎。 说明：支持 None（默认值）、paddle、paddle_static、paddle_dynamic、transformers、onnxruntime。保持为默认值 None 时，本地推理默认使用 paddle_static 引擎。详细说明、取值、兼容性规则与示例请参见 推理引擎与配置说明。 |
str|None |
None |
engine_config |
含义：推理引擎配置。 说明：推荐与 engine 搭配使用。详细字段、兼容性规则与示例请参见 推理引擎与配置说明。 |
dict|None |
None |
enable_hpi |
含义：是否启用高性能推理。 | bool |
False |
use_tensorrt |
含义：是否启用 Paddle Inference 的 TensorRT 子图引擎。 说明： 如果模型不支持通过 TensorRT 加速，即使设置了此标志，也不会使用加速。 对于 CUDA 11.8 版本的飞桨，兼容的 TensorRT 版本为 8.x（x>=6），建议安装 TensorRT 8.6.1.6。 |
bool |
False |
precision |
含义：当使用 Paddle Inference 的 TensorRT 子图引擎时设置的计算精度。 说明： 可选项： "fp32"、"fp16"。 |
str |
"fp32" |
enable_mkldnn |
含义：是否启用 MKL-DNN 加速推理。 说明： 如果 MKL-DNN 不可用或模型不支持通过 MKL-DNN 加速，即使设置了此标志，也不会使用加速。 |
bool |
True |
mkldnn_cache_capacity |
含义：MKL-DNN 缓存容量。 | int |
10 |
cpu_threads |
含义：在 CPU 上推理时使用的线程数量。 | int |
10 |
img_size |
含义：输入图像大小。 说明：
|
int|list|None |
None |
threshold |
含义：用于过滤掉低置信度预测结果的阈值。 说明：
|
float|dict|None |
None |
predict() 方法进行推理预测，该方法会返回一个结果列表。另外，本模块还提供了 predict_iter() 方法。两者在参数接受和结果返回方面是完全一致的，区别在于 predict_iter() 返回的是一个 generator，能够逐步处理和获取预测结果，适合处理大型数据集或希望节省内存的场景。可以根据实际需求选择使用这两种方法中的任意一种。predict() 方法参数有 input、batch_size和threshold，具体说明如下：
| 参数 | 参数说明 | 参数类型 | 默认值 |
|---|---|---|---|
input |
含义：待预测数据，支持多种输入类型，必填。 说明：
|
Python Var|str|list |
|
batch_size |
含义：批大小。 说明： 可设置为任意正整数。 |
int |
1 |
threshold |
含义：参数含义与实例化参数基本相同。 说明： 设置为 None表示使用实例化参数，否则该参数优先级更高。 |
float|dict|None |
None |
json文件的操作:
| 方法 | 方法说明 | 参数 | 参数类型 | 参数说明 | 默认值 |
|---|---|---|---|---|---|
print() |
打印结果到终端 | format_json |
bool |
是否对输出内容进行使用 JSON 缩进格式化 |
True |
indent |
int |
指定缩进级别，以美化输出的 JSON 数据，使其更具可读性，仅当 format_json 为 True 时有效 |
4 | ||
ensure_ascii |
bool |
控制是否将非 ASCII 字符转义为 Unicode。设置为 True 时，所有非 ASCII 字符将被转义；False 则保留原始字符，仅当format_json为True时有效 |
False |
||
save_to_json() |
将结果保存为json格式的文件 | save_path |
str |
保存的文件路径，当为目录时，保存文件命名与输入文件类型命名一致 | 无 |
indent |
int |
指定缩进级别，以美化输出的 JSON 数据，使其更具可读性，仅当 format_json 为 True 时有效 |
4 | ||
ensure_ascii |
bool |
控制是否将非 ASCII 字符转义为 Unicode。设置为 True 时，所有非 ASCII 字符将被转义；False 则保留原始字符，仅当format_json为True时有效 |
False |
||
save_to_img() |
将结果保存为图像格式的文件 | save_path |
str |
保存的文件路径，当为目录时，保存文件命名与输入文件类型命名一致 | 无 |
| 属性 | 属性说明 |
|---|---|
json |
获取预测的json格式的结果 |
img |
获取可视化图像 |
| model | engine | Preprocessing (ms) | Inference (ms) | PostProcessing (ms) | End-to-End (ms) |
|---|---|---|---|---|---|
| RT-DETR-L_wired_table_cell_det | paddle_static | 3.59 | 23.11 | 0.14 | 27.02 |
| paddle_dynamic | 4.04 | 70.38 | 0.15 | 75.49 | |
| transformers | 3.69 | 37.30 | 0.71 | 42.10 | |
| onnxruntime | 2.70 | 9.10 | 0.12 | 12.07 | |
| RT-DETR-L_wireless_table_cell_det | paddle_static | 3.77 | 23.44 | 0.14 | 27.52 |
| paddle_dynamic | 4.01 | 69.97 | 0.15 | 75.10 | |
| transformers | 3.69 | 37.11 | 0.71 | 41.91 | |
| onnxruntime | 2.77 | 9.11 | 0.12 | 12.14 |
