PaddleOCR 表格单元格检测模块实战指南从模型选型、推理引擎配置到结果解析【免费下载链接】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导读表格单元格检测是表格识别链路中的关键前置环节负责在表格图像中精确定位每个单元格的边界框Bounding Box为后续的单元格内容识别与 HTML/Excel 结构还原提供坐标基础。本文以 PaddleOCR 仓库中的官方文档为核心结合仓库源码如 paddleocr/_models/table_cells_detection.py、paddleocr/_models/_object_detection.py与单元测试tests/models/test_table_cells_detection.py系统讲解表格单元格检测模块的模型选型、CLI 与 Python 双入口快速上手、paddle_static/transformers/onnxruntime三种推理引擎的切换、预测结果的字段含义与保存方式以及基于 PaddleX 的二次开发与权重转换流程。读完本文你将能独立完成表格单元格检测的部署、调参与结果消费并将其无缝接入自己的 OCR 业务系统。一、模块定位表格识别产线的坐标提供者表格单元格检测模块是表格识别任务的关键组成部分负责在表格图像中定位和标记每个单元格区域该模块的性能直接影响到整个表格识别过程的准确性和效率。表格单元格检测模块通常会输出各个单元格区域的边界框Bounding Boxes这些边界框将作为输入传递给表格识别相关产线进行后续处理。从仓库源码可以看出该模块在 PaddleOCR 中具有明确的工程化落点模型封装层paddleocr/_models/table_cells_detection.py 中定义了TableCellsDetection类它继承自ObjectDetection目标检测基类默认模型名为RT-DETR-L_wired_table_cell_det并注册了名为table_cells_detection的 CLI 子命令CLI 注册层paddleocr/_cli.py 将TableCellsDetection与其余十余个单模型文本检测、文本识别、版面分析、表格结构识别等一起注册为paddleocr命令的子命令产线集成层paddleocr/_pipelines/table_recognition_v2.py 在表格识别产线Table Recognition Pipeline V2中同时挂载了有线表格单元格检测WiredTableCellsDetection与无线表格单元格检测WirelessTableCellsDetection两个子模块分别对应有线表格与无线表格两类场景。因此你可以把表格单元格检测当作一个独立模块单独使用也可以理解它是表格识别产线的坐标源头——产线拿到单元格框后再结合文本识别与结构识别结果还原出完整表格。二、支持模型列表与性能概览当前仓库文档中表格单元格检测模块官方提供两个模型二者共用同一套评测指标与性能数据推理耗时仅包含模型推理耗时不包含前后处理耗时表中的常规模式耗时对应本地paddle_static推理引擎模型模型下载链接mAP(%)GPU推理耗时ms[常规模式 / 高性能模式]CPU推理耗时ms[常规模式 / 高性能模式]模型存储大小MB介绍RT-DETR-L_wired_table_cell_det推理模型 / 训练模型82.733.47 / 27.02402.55 / 256.56124RT-DETR 是一个实时的端到端目标检测模型。百度飞桨视觉团队基于 RT-DETR-L 作为基础模型在自建表格单元格检测数据集上完成预训练实现了对有线表格、无线表格均有较好性能的表格单元格检测。RT-DETR-L_wireless_table_cell_det推理模型 / 训练模型82.733.47 / 27.02402.55 / 256.56124同上上表为官方文档给出的公开性能数据测试环境为自建内部评测集硬件为 NVIDIA Tesla T4GPU Intel Xeon Gold 6271C 2.60GHzCPU软件环境为 Ubuntu 20.04 / CUDA 11.8 / cuDNN 8.9 / TensorRT 8.6.1.6paddlepaddle-gpu 3.0.0 / paddleocr 3.0.3。推理模式说明模式GPU配置CPU配置加速技术组合常规模式FP32精度 / 无TRT加速FP32精度 / 8线程PaddleInference高性能模式选择先验精度类型和加速策略的最优组合FP32精度 / 8线程选择先验最优后端Paddle/OpenVINO/TRT等选择模型时可参考有线表格优先RT-DETR-L_wired_table_cell_det无线表格优先RT-DETR-L_wireless_table_cell_det。若不确定表格类型或希望兼顾两者有线模型同样具备较好的无线表格检测能力官方描述为对有线表格、无线表格均有较好性能。三、快速开始在快速开始前请先安装 PaddleOCR 的 wheel 包详细请参考 安装教程。3.1 命令行CLI一行体验使用一行命令即可快速体验paddleocr table_cells_detection -i https://paddle-model-ecology.bj.bcebos.com/paddlex/imgs/demo_image/table_recognition.jpg上述示例默认使用paddle_static推理引擎请先按照飞桨框架安装完成 PaddlePaddle 安装。如果选择transformers作为推理引擎请确保已配置 Transformers 环境然后执行如下命令# 使用 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 环境然后执行如下命令# 使用 onnxruntime 引擎进行推理 paddleocr table_cells_detection -i https://paddle-model-ecology.bj.bcebos.com/paddlex/imgs/demo_image/table_recognition.jpg \ --engine onnxruntime在大多数场景下默认的paddle_static推理引擎通常具备更好的推理性能建议优先使用。从源码看CLI 子命令在 paddleocr/_models/_object_detection.py 的ObjectDetectionSubcommandExecutor中构建除通用参数--model_name、--model_dir、设备与引擎相关参数外还额外支持--img_size、--threshold、--layout_nms、--layout_unclip_ratio、--layout_merge_bboxes_mode等目标检测专属参数最终由perform_simple_inference完成推理并将结果打印或保存。注PaddleOCR 官方模型默认从 HuggingFace 获取如运行环境访问 HuggingFace 不便可通过环境变量修改模型源为 BOSPADDLE_PDX_MODEL_SOURCEBOS未来将支持更多主流模型源。3.2 Python API 集成您也可以将表格单元格检测模块中的模型推理集成到您的项目中。运行以下代码前请您下载示例图片到本地。默认使用paddle_static引擎需先完成 PaddlePaddle 安装from paddleocr import TableCellsDetection model TableCellsDetection(model_nameRT-DETR-L_wired_table_cell_det) output model.predict(table_recognition.jpg, threshold0.3, batch_size1) for res in output: res.print(json_formatFalse) res.save_to_img(./output/) res.save_to_json(./output/res.json)使用transformers引擎from paddleocr import TableCellsDetection model TableCellsDetection( model_nameRT-DETR-L_wired_table_cell_det, enginetransformers, ) output model.predict(table_recognition.jpg, threshold0.3, batch_size1) for res in output: res.print(json_formatFalse) res.save_to_img(./output/) res.save_to_json(./output/res.json)使用onnxruntime引擎from paddleocr import TableCellsDetection model TableCellsDetection( model_nameRT-DETR-L_wired_table_cell_det, engineonnxruntime, ) output model.predict(table_recognition.jpg, threshold0.3, batch_size1) for res in output: res.print(json_formatFalse) res.save_to_img(./output/) res.save_to_json(./output/res.json)训练后的模型如果想使用paddle_dynamic或transformers引擎请参考后文 5.2 权重转换 部分将模型由pdparams格式通过 PaddleX 转换为safetensors格式。从源码实现看paddleocr/_models/base.py 中的PaddleXPredictorWrapper是所有单模型的公共基类TableCellsDetection(...)实例化时会调用 PaddleX 的create_predictor创建底层预测器_create_paddlex_predictorpredict()方法实际通过predict_iter()将生成器结果收集为列表返回若依赖缺失基类会抛出包含安装指引的RuntimeError。这也解释了为什么文档示例中predict()返回的是一个可迭代的结果列表。3.3 预测结果示例与字段含义运行后得到的结果为{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一个整数表格单元格场景下为0label类别标签一个字符串表格单元格场景下为cellscore目标框置信度一个浮点数coordinate目标框坐标一个浮点数列表格式为[xmin, ymin, xmax, ymax]值得注意仓库单元测试 tests/models/test_table_cells_detection.py 对上述结果结构做了显式校验check_simple_inference_result与check_result_item_keys会验证每个预测结果对象的关键字段如boxes中的cls_id、label、score、coordinate并覆盖了img_size640、threshold0.5等参数透传场景。这意味你可以放心地把该输出结构作为业务下游的稳定契约。四、参数详解4.1TableCellsDetection实例化参数TableCellsDetection实例化表格单元格检测模型此处以RT-DETR-L_wired_table_cell_det为例具体参数说明如下参数参数说明参数类型默认值model_name含义模型名称。说明如果设置为None则使用RT-DETR-L_wired_table_cell_det。str\|NoneNonemodel_dir含义模型存储路径。str\|NoneNonedevice含义用于推理的设备。说明例如cpu、gpu、npu、gpu:0、gpu:0,1。如指定多个设备将进行并行推理。默认情况下优先使用 GPU 0若不可用则使用 CPU。str\|NoneNoneengine含义推理引擎。说明支持None默认值、paddle、paddle_static、paddle_dynamic、transformers、onnxruntime。保持为默认值None时本地推理默认使用paddle_static引擎。详细说明、取值、兼容性规则与示例请参见 推理引擎与配置说明。str\|NoneNoneengine_config含义推理引擎配置。说明推荐与engine搭配使用。详细字段、兼容性规则与示例请参见 推理引擎与配置说明。dict\|NoneNoneenable_hpi含义是否启用高性能推理。boolFalseuse_tensorrt含义是否启用 Paddle Inference 的 TensorRT 子图引擎。说明如果模型不支持通过 TensorRT 加速即使设置了此标志也不会使用加速。对于 CUDA 11.8 版本的飞桨兼容的 TensorRT 版本为 8.xx6建议安装 TensorRT 8.6.1.6。boolFalseprecision含义当使用 Paddle Inference 的 TensorRT 子图引擎时设置的计算精度。说明可选项fp32、fp16。strfp32enable_mkldnn含义是否启用 MKL-DNN 加速推理。说明如果 MKL-DNN 不可用或模型不支持通过 MKL-DNN 加速即使设置了此标志也不会使用加速。boolTruemkldnn_cache_capacity含义MKL-DNN 缓存容量。int10cpu_threads含义在 CPU 上推理时使用的线程数量。int10img_size含义输入图像大小。说明int如640表示将输入图像 resize 到 640x640 大小。list如[640, 512]表示将输入图像 resize 到宽为 640、高为 512 大小。int\|list\|NoneNonethreshold含义用于过滤掉低置信度预测结果的阈值。说明float如0.2表示过滤掉所有置信度小于 0.2 的目标框。dict字典的键为int类型代表类别 ID值为float类型阈值。如{0: 0.45, 2: 0.48, 7: 0.4}表示对类别 ID 为 0 的类别应用阈值 0.45、类别 ID 为 2 的应用 0.48、类别 ID 为 7 的应用 0.4。None使用模型默认配置。float\|dict\|NoneNone从 paddleocr/_models/_object_detection.py 的源码可以看到ObjectDetection.__init__会把img_size、threshold、layout_nms、layout_unclip_ratio、layout_merge_bboxes_mode统一收进_extra_init_args再经_get_extra_paddlex_predictor_init_args透传给 PaddleX 预测器因此这些参数在底层会直接影响检测头的输入尺寸与后处理 NMS/过滤逻辑。4.2predict()方法参数调用目标检测模型的predict()方法进行推理预测该方法会返回一个结果列表。另外本模块还提供了predict_iter()方法。两者在参数接受和结果返回方面是完全一致的区别在于predict_iter()返回的是一个generator能够逐步处理和获取预测结果适合处理大型数据集或希望节省内存的场景。可以根据实际需求选择使用这两种方法中的任意一种。predict()方法参数有input、batch_size和threshold具体说明如下参数参数说明参数类型默认值input含义待预测数据支持多种输入类型必填。说明Python Var如numpy.ndarray表示的图像数据str如图像文件或者 PDF 文件的本地路径/root/data/img.jpg如 URL 链接如图像文件或 PDF 文件的网络 URL如本地目录该目录下需包含待预测图像如/root/data/当前不支持目录中包含 PDF 文件的预测PDF 文件需要指定到具体文件路径list列表元素需为上述类型数据如[numpy.ndarray, numpy.ndarray]、[/root/data/img1.jpg, /root/data/img2.jpg]、[/root/data1, /root/data2]Python Var\|str\|list必填batch_size含义批大小。说明可设置为任意正整数。int1threshold含义参数含义与实例化参数基本相同。说明设置为None表示使用实例化参数否则该参数优先级更高。float\|dict\|NoneNone4.3 结果对象处理方法与属性对预测结果进行处理每个样本的预测结果均为对应的 Result 对象且支持打印、保存为图片、保存为json文件的操作方法方法说明参数参数类型参数说明默认值print()打印结果到终端format_jsonbool是否对输出内容使用JSON缩进格式化Trueindentint指定缩进级别以美化输出的JSON数据使其更具可读性仅当format_json为True时有效4ensure_asciibool控制是否将非ASCII字符转义为Unicode。设置为True时所有非ASCII字符将被转义False则保留原始字符仅当format_json为True时有效Falsesave_to_json()将结果保存为 json 格式的文件save_pathstr保存的文件路径当为目录时保存文件命名与输入文件类型命名一致无indentint指定缩进级别以美化输出的JSON数据使其更具可读性仅当format_json为True时有效4ensure_asciibool控制是否将非ASCII字符转义为Unicode。设置为True时所有非ASCII字符将被转义False则保留原始字符仅当format_json为True时有效Falsesave_to_img()将结果保存为图像格式的文件save_pathstr保存的文件路径当为目录时保存文件命名与输入文件类型命名一致无此外也支持通过属性获取带结果的可视化图像和预测结果属性属性说明json获取预测的json格式的结果img获取可视化图像典型用法是将res.img直接交给 Web 服务或前端展示例如在 Notbook 环境中内联显示将res.json送入下游的结构化处理逻辑。五、推理引擎关于推理引擎的详细说明、取值、兼容性规则与示例请参见 推理引擎与配置说明。PaddleOCR 3.5 引入统一的推理引擎配置方式用engine选择底层推理引擎飞桨框架paddle/paddle_static/paddle_dynamic、Transformers、ONNX Runtime用engine_config传递引擎专属配置。主要兼容性规则包括显式设置engine后enable_hpi不再生效显式传入engine_config后与该引擎对应的兼容参数如use_tensorrt、precision、enable_mkldnn、cpu_threads等会被忽略各引擎的依赖安装飞桨框架见飞桨框架安装Transformers 需transformers5.10.0ONNX Runtime 可安装onnxruntime-gpu。5.1 各引擎速度数据以下为官方文档给出的单张示例图片推理耗时单位 ms测试硬件为 NVIDIA A100 40GGPU Intel(R) Xeon(R) Gold 6248 CPU 2.50GHz软件环境为 Ubuntu 22.04 / CUDA 12.6 / cuDNN 9.5paddlepaddle-gpu 3.2.1 / paddleocr 3.5 / transformers 5.4.0 / torch 2.10 / onnxruntime-gpu 1.23.2modelenginePreprocessing (ms)Inference (ms)PostProcessing (ms)End-to-End (ms)RT-DETR-L_wired_table_cell_detpaddle_static3.5923.110.1427.02paddle_dynamic4.0470.380.1575.49transformers3.6937.300.7142.10onnxruntime2.709.100.1212.07RT-DETR-L_wireless_table_cell_detpaddle_static3.7723.440.1427.52paddle_dynamic4.0169.970.1575.10transformers3.6937.110.7141.91onnxruntime2.779.110.1212.14从该表可以得出几个实用结论在 A100 环境下onnxruntime端到端耗时最低约 12 ms适合对吞吐要求高的在线服务场景paddle_dynamic端到端耗时最高约 75 ms主要适合调试、二次开发等需要灵活性的场景paddle_static推理稳定、生态兼容最好是官方推荐的默认选择文档与仓库默认行为一致——paddleocr/_models/base.py 中engineNone时本地推理默认走paddle_static。5.2 权重转换使用推理引擎时系统会自动下载官方预训练模型。若需使用自训练模型配合paddle_dynamic或transformers引擎请参考 PaddleX 表格单元格检测模块权重转换部分将pdparams格式通过 PaddleX 转换为safetensors格式即可无缝集成到 PaddleOCR 的 API 中进行推理。若需使用自训练模型配合onnxruntime引擎请参考 PaddleX 获取 ONNX 模型的方式获取 onnx 模型即可无缝集成到 PaddleOCR 的 API 中进行推理。六、二次开发由于 PaddleOCR 并不直接提供表格单元格检测模块的训练因此如果需要训练表格单元格检测模型可以参考 PaddleX 表格单元格检测模块二次开发部分进行训练。训练后的模型可以无缝集成到 PaddleOCR 的 API 中进行推理——实例化TableCellsDetection时传入model_dir指向本地训练好的模型目录即可model_name与model_dir的配合方式在 paddleocr/_models/base.py 的PaddleXPredictorWrapper.__init__中有清晰体现model_name为None时回退到default_model_name而model_dir会被直接传给 PaddleX 的create_predictor作为本地模型来源。训练后的模型如果想使用paddle_dynamic或transformers引擎请参考上文 5.2 权重转换 部分完成格式转换。七、FAQ常见问题结合官方文档与仓库源码以下是表格单元格检测使用中最高频的几类问题默认模型是什么不指定model_name时默认使用RT-DETR-L_wired_table_cell_det该默认值定义于 paddleocr/_models/table_cells_detection.py 的default_model_name属性。模型下载慢或 HuggingFace 无法访问怎么办通过环境变量PADDLE_PDX_MODEL_SOURCEBOS将模型源切换为百度 BOS。想用非默认推理引擎但依赖没装根据引擎选择安装对应依赖飞桨框架见飞桨框架安装Transformers 需transformers5.10.0ONNX Runtime 需onnxruntime/onnxruntime-gpu若create_predictor时依赖缺失paddleocr/_models/base.py 会抛出带安装指引的RuntimeError。如何在代码里确认推理真的走通了仓库提供了现成的冒烟测试参考tests/models/test_table_cells_detection.py 使用tests/test_files/table.jpg作为输入对predict结果的关键字段与参数透传进行了断言可将其作为最小可用示例阅读。如何对大批量图片做内存友好推理使用predict_iter()返回生成器逐步取结果避免一次性将全部预测结果载入内存。单元格检测结果如何与表格识别产线衔接表格识别产线在 paddleocr/_pipelines/table_recognition_v2.py 中通过SubModules.WiredTableCellsDetection/SubModules.WirelessTableCellsDetection挂载本模块并支持use_ocr_results_with_table_cells等选项控制单元格框与 OCR 结果的融合策略可直接用paddleocr table_recognition产线命令体验完整链路。结语表格单元格检测作为 PaddleOCR 表格能力的关键一环通过两个 RT-DETR-L 模型覆盖有线/无线表格场景提供了 CLI 与 Python API 双入口、多推理引擎切换、灵活的结果导出方式并可借助 PaddleX 完成训练与权重格式转换后无缝回接。配合仓库内的源码paddleocr/_models/table_cells_detection.py、产线集成paddleocr/_pipelines/table_recognition_v2.py与测试用例tests/models/test_table_cells_detection.py你可以快速将图像/PDF → 单元格坐标 → 结构化表格的完整链路落地到自己的业务中。【免费下载链接】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），仅供参考 PaddleOCR 表格单元格检测模块实战指南：从模型选型、推理引擎配置到结果解析
PaddleOCR 表格单元格检测模块实战指南从模型选型、推理引擎配置到结果解析【免费下载链接】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导读表格单元格检测是表格识别链路中的关键前置环节负责在表格图像中精确定位每个单元格的边界框Bounding Box为后续的单元格内容识别与 HTML/Excel 结构还原提供坐标基础。本文以 PaddleOCR 仓库中的官方文档为核心结合仓库源码如 paddleocr/_models/table_cells_detection.py、paddleocr/_models/_object_detection.py与单元测试tests/models/test_table_cells_detection.py系统讲解表格单元格检测模块的模型选型、CLI 与 Python 双入口快速上手、paddle_static/transformers/onnxruntime三种推理引擎的切换、预测结果的字段含义与保存方式以及基于 PaddleX 的二次开发与权重转换流程。读完本文你将能独立完成表格单元格检测的部署、调参与结果消费并将其无缝接入自己的 OCR 业务系统。一、模块定位表格识别产线的坐标提供者表格单元格检测模块是表格识别任务的关键组成部分负责在表格图像中定位和标记每个单元格区域该模块的性能直接影响到整个表格识别过程的准确性和效率。表格单元格检测模块通常会输出各个单元格区域的边界框Bounding Boxes这些边界框将作为输入传递给表格识别相关产线进行后续处理。从仓库源码可以看出该模块在 PaddleOCR 中具有明确的工程化落点模型封装层paddleocr/_models/table_cells_detection.py 中定义了TableCellsDetection类它继承自ObjectDetection目标检测基类默认模型名为RT-DETR-L_wired_table_cell_det并注册了名为table_cells_detection的 CLI 子命令CLI 注册层paddleocr/_cli.py 将TableCellsDetection与其余十余个单模型文本检测、文本识别、版面分析、表格结构识别等一起注册为paddleocr命令的子命令产线集成层paddleocr/_pipelines/table_recognition_v2.py 在表格识别产线Table Recognition Pipeline V2中同时挂载了有线表格单元格检测WiredTableCellsDetection与无线表格单元格检测WirelessTableCellsDetection两个子模块分别对应有线表格与无线表格两类场景。因此你可以把表格单元格检测当作一个独立模块单独使用也可以理解它是表格识别产线的坐标源头——产线拿到单元格框后再结合文本识别与结构识别结果还原出完整表格。二、支持模型列表与性能概览当前仓库文档中表格单元格检测模块官方提供两个模型二者共用同一套评测指标与性能数据推理耗时仅包含模型推理耗时不包含前后处理耗时表中的常规模式耗时对应本地paddle_static推理引擎模型模型下载链接mAP(%)GPU推理耗时ms[常规模式 / 高性能模式]CPU推理耗时ms[常规模式 / 高性能模式]模型存储大小MB介绍RT-DETR-L_wired_table_cell_det推理模型 / 训练模型82.733.47 / 27.02402.55 / 256.56124RT-DETR 是一个实时的端到端目标检测模型。百度飞桨视觉团队基于 RT-DETR-L 作为基础模型在自建表格单元格检测数据集上完成预训练实现了对有线表格、无线表格均有较好性能的表格单元格检测。RT-DETR-L_wireless_table_cell_det推理模型 / 训练模型82.733.47 / 27.02402.55 / 256.56124同上上表为官方文档给出的公开性能数据测试环境为自建内部评测集硬件为 NVIDIA Tesla T4GPU Intel Xeon Gold 6271C 2.60GHzCPU软件环境为 Ubuntu 20.04 / CUDA 11.8 / cuDNN 8.9 / TensorRT 8.6.1.6paddlepaddle-gpu 3.0.0 / paddleocr 3.0.3。推理模式说明模式GPU配置CPU配置加速技术组合常规模式FP32精度 / 无TRT加速FP32精度 / 8线程PaddleInference高性能模式选择先验精度类型和加速策略的最优组合FP32精度 / 8线程选择先验最优后端Paddle/OpenVINO/TRT等选择模型时可参考有线表格优先RT-DETR-L_wired_table_cell_det无线表格优先RT-DETR-L_wireless_table_cell_det。若不确定表格类型或希望兼顾两者有线模型同样具备较好的无线表格检测能力官方描述为对有线表格、无线表格均有较好性能。三、快速开始在快速开始前请先安装 PaddleOCR 的 wheel 包详细请参考 安装教程。3.1 命令行CLI一行体验使用一行命令即可快速体验paddleocr table_cells_detection -i https://paddle-model-ecology.bj.bcebos.com/paddlex/imgs/demo_image/table_recognition.jpg上述示例默认使用paddle_static推理引擎请先按照飞桨框架安装完成 PaddlePaddle 安装。如果选择transformers作为推理引擎请确保已配置 Transformers 环境然后执行如下命令# 使用 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 环境然后执行如下命令# 使用 onnxruntime 引擎进行推理 paddleocr table_cells_detection -i https://paddle-model-ecology.bj.bcebos.com/paddlex/imgs/demo_image/table_recognition.jpg \ --engine onnxruntime在大多数场景下默认的paddle_static推理引擎通常具备更好的推理性能建议优先使用。从源码看CLI 子命令在 paddleocr/_models/_object_detection.py 的ObjectDetectionSubcommandExecutor中构建除通用参数--model_name、--model_dir、设备与引擎相关参数外还额外支持--img_size、--threshold、--layout_nms、--layout_unclip_ratio、--layout_merge_bboxes_mode等目标检测专属参数最终由perform_simple_inference完成推理并将结果打印或保存。注PaddleOCR 官方模型默认从 HuggingFace 获取如运行环境访问 HuggingFace 不便可通过环境变量修改模型源为 BOSPADDLE_PDX_MODEL_SOURCEBOS未来将支持更多主流模型源。3.2 Python API 集成您也可以将表格单元格检测模块中的模型推理集成到您的项目中。运行以下代码前请您下载示例图片到本地。默认使用paddle_static引擎需先完成 PaddlePaddle 安装from paddleocr import TableCellsDetection model TableCellsDetection(model_nameRT-DETR-L_wired_table_cell_det) output model.predict(table_recognition.jpg, threshold0.3, batch_size1) for res in output: res.print(json_formatFalse) res.save_to_img(./output/) res.save_to_json(./output/res.json)使用transformers引擎from paddleocr import TableCellsDetection model TableCellsDetection( model_nameRT-DETR-L_wired_table_cell_det, enginetransformers, ) output model.predict(table_recognition.jpg, threshold0.3, batch_size1) for res in output: res.print(json_formatFalse) res.save_to_img(./output/) res.save_to_json(./output/res.json)使用onnxruntime引擎from paddleocr import TableCellsDetection model TableCellsDetection( model_nameRT-DETR-L_wired_table_cell_det, engineonnxruntime, ) output model.predict(table_recognition.jpg, threshold0.3, batch_size1) for res in output: res.print(json_formatFalse) res.save_to_img(./output/) res.save_to_json(./output/res.json)训练后的模型如果想使用paddle_dynamic或transformers引擎请参考后文 5.2 权重转换 部分将模型由pdparams格式通过 PaddleX 转换为safetensors格式。从源码实现看paddleocr/_models/base.py 中的PaddleXPredictorWrapper是所有单模型的公共基类TableCellsDetection(...)实例化时会调用 PaddleX 的create_predictor创建底层预测器_create_paddlex_predictorpredict()方法实际通过predict_iter()将生成器结果收集为列表返回若依赖缺失基类会抛出包含安装指引的RuntimeError。这也解释了为什么文档示例中predict()返回的是一个可迭代的结果列表。3.3 预测结果示例与字段含义运行后得到的结果为{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一个整数表格单元格场景下为0label类别标签一个字符串表格单元格场景下为cellscore目标框置信度一个浮点数coordinate目标框坐标一个浮点数列表格式为[xmin, ymin, xmax, ymax]值得注意仓库单元测试 tests/models/test_table_cells_detection.py 对上述结果结构做了显式校验check_simple_inference_result与check_result_item_keys会验证每个预测结果对象的关键字段如boxes中的cls_id、label、score、coordinate并覆盖了img_size640、threshold0.5等参数透传场景。这意味你可以放心地把该输出结构作为业务下游的稳定契约。四、参数详解4.1TableCellsDetection实例化参数TableCellsDetection实例化表格单元格检测模型此处以RT-DETR-L_wired_table_cell_det为例具体参数说明如下参数参数说明参数类型默认值model_name含义模型名称。说明如果设置为None则使用RT-DETR-L_wired_table_cell_det。str\|NoneNonemodel_dir含义模型存储路径。str\|NoneNonedevice含义用于推理的设备。说明例如cpu、gpu、npu、gpu:0、gpu:0,1。如指定多个设备将进行并行推理。默认情况下优先使用 GPU 0若不可用则使用 CPU。str\|NoneNoneengine含义推理引擎。说明支持None默认值、paddle、paddle_static、paddle_dynamic、transformers、onnxruntime。保持为默认值None时本地推理默认使用paddle_static引擎。详细说明、取值、兼容性规则与示例请参见 推理引擎与配置说明。str\|NoneNoneengine_config含义推理引擎配置。说明推荐与engine搭配使用。详细字段、兼容性规则与示例请参见 推理引擎与配置说明。dict\|NoneNoneenable_hpi含义是否启用高性能推理。boolFalseuse_tensorrt含义是否启用 Paddle Inference 的 TensorRT 子图引擎。说明如果模型不支持通过 TensorRT 加速即使设置了此标志也不会使用加速。对于 CUDA 11.8 版本的飞桨兼容的 TensorRT 版本为 8.xx6建议安装 TensorRT 8.6.1.6。boolFalseprecision含义当使用 Paddle Inference 的 TensorRT 子图引擎时设置的计算精度。说明可选项fp32、fp16。strfp32enable_mkldnn含义是否启用 MKL-DNN 加速推理。说明如果 MKL-DNN 不可用或模型不支持通过 MKL-DNN 加速即使设置了此标志也不会使用加速。boolTruemkldnn_cache_capacity含义MKL-DNN 缓存容量。int10cpu_threads含义在 CPU 上推理时使用的线程数量。int10img_size含义输入图像大小。说明int如640表示将输入图像 resize 到 640x640 大小。list如[640, 512]表示将输入图像 resize 到宽为 640、高为 512 大小。int\|list\|NoneNonethreshold含义用于过滤掉低置信度预测结果的阈值。说明float如0.2表示过滤掉所有置信度小于 0.2 的目标框。dict字典的键为int类型代表类别 ID值为float类型阈值。如{0: 0.45, 2: 0.48, 7: 0.4}表示对类别 ID 为 0 的类别应用阈值 0.45、类别 ID 为 2 的应用 0.48、类别 ID 为 7 的应用 0.4。None使用模型默认配置。float\|dict\|NoneNone从 paddleocr/_models/_object_detection.py 的源码可以看到ObjectDetection.__init__会把img_size、threshold、layout_nms、layout_unclip_ratio、layout_merge_bboxes_mode统一收进_extra_init_args再经_get_extra_paddlex_predictor_init_args透传给 PaddleX 预测器因此这些参数在底层会直接影响检测头的输入尺寸与后处理 NMS/过滤逻辑。4.2predict()方法参数调用目标检测模型的predict()方法进行推理预测该方法会返回一个结果列表。另外本模块还提供了predict_iter()方法。两者在参数接受和结果返回方面是完全一致的区别在于predict_iter()返回的是一个generator能够逐步处理和获取预测结果适合处理大型数据集或希望节省内存的场景。可以根据实际需求选择使用这两种方法中的任意一种。predict()方法参数有input、batch_size和threshold具体说明如下参数参数说明参数类型默认值input含义待预测数据支持多种输入类型必填。说明Python Var如numpy.ndarray表示的图像数据str如图像文件或者 PDF 文件的本地路径/root/data/img.jpg如 URL 链接如图像文件或 PDF 文件的网络 URL如本地目录该目录下需包含待预测图像如/root/data/当前不支持目录中包含 PDF 文件的预测PDF 文件需要指定到具体文件路径list列表元素需为上述类型数据如[numpy.ndarray, numpy.ndarray]、[/root/data/img1.jpg, /root/data/img2.jpg]、[/root/data1, /root/data2]Python Var\|str\|list必填batch_size含义批大小。说明可设置为任意正整数。int1threshold含义参数含义与实例化参数基本相同。说明设置为None表示使用实例化参数否则该参数优先级更高。float\|dict\|NoneNone4.3 结果对象处理方法与属性对预测结果进行处理每个样本的预测结果均为对应的 Result 对象且支持打印、保存为图片、保存为json文件的操作方法方法说明参数参数类型参数说明默认值print()打印结果到终端format_jsonbool是否对输出内容使用JSON缩进格式化Trueindentint指定缩进级别以美化输出的JSON数据使其更具可读性仅当format_json为True时有效4ensure_asciibool控制是否将非ASCII字符转义为Unicode。设置为True时所有非ASCII字符将被转义False则保留原始字符仅当format_json为True时有效Falsesave_to_json()将结果保存为 json 格式的文件save_pathstr保存的文件路径当为目录时保存文件命名与输入文件类型命名一致无indentint指定缩进级别以美化输出的JSON数据使其更具可读性仅当format_json为True时有效4ensure_asciibool控制是否将非ASCII字符转义为Unicode。设置为True时所有非ASCII字符将被转义False则保留原始字符仅当format_json为True时有效Falsesave_to_img()将结果保存为图像格式的文件save_pathstr保存的文件路径当为目录时保存文件命名与输入文件类型命名一致无此外也支持通过属性获取带结果的可视化图像和预测结果属性属性说明json获取预测的json格式的结果img获取可视化图像典型用法是将res.img直接交给 Web 服务或前端展示例如在 Notbook 环境中内联显示将res.json送入下游的结构化处理逻辑。五、推理引擎关于推理引擎的详细说明、取值、兼容性规则与示例请参见 推理引擎与配置说明。PaddleOCR 3.5 引入统一的推理引擎配置方式用engine选择底层推理引擎飞桨框架paddle/paddle_static/paddle_dynamic、Transformers、ONNX Runtime用engine_config传递引擎专属配置。主要兼容性规则包括显式设置engine后enable_hpi不再生效显式传入engine_config后与该引擎对应的兼容参数如use_tensorrt、precision、enable_mkldnn、cpu_threads等会被忽略各引擎的依赖安装飞桨框架见飞桨框架安装Transformers 需transformers5.10.0ONNX Runtime 可安装onnxruntime-gpu。5.1 各引擎速度数据以下为官方文档给出的单张示例图片推理耗时单位 ms测试硬件为 NVIDIA A100 40GGPU Intel(R) Xeon(R) Gold 6248 CPU 2.50GHz软件环境为 Ubuntu 22.04 / CUDA 12.6 / cuDNN 9.5paddlepaddle-gpu 3.2.1 / paddleocr 3.5 / transformers 5.4.0 / torch 2.10 / onnxruntime-gpu 1.23.2modelenginePreprocessing (ms)Inference (ms)PostProcessing (ms)End-to-End (ms)RT-DETR-L_wired_table_cell_detpaddle_static3.5923.110.1427.02paddle_dynamic4.0470.380.1575.49transformers3.6937.300.7142.10onnxruntime2.709.100.1212.07RT-DETR-L_wireless_table_cell_detpaddle_static3.7723.440.1427.52paddle_dynamic4.0169.970.1575.10transformers3.6937.110.7141.91onnxruntime2.779.110.1212.14从该表可以得出几个实用结论在 A100 环境下onnxruntime端到端耗时最低约 12 ms适合对吞吐要求高的在线服务场景paddle_dynamic端到端耗时最高约 75 ms主要适合调试、二次开发等需要灵活性的场景paddle_static推理稳定、生态兼容最好是官方推荐的默认选择文档与仓库默认行为一致——paddleocr/_models/base.py 中engineNone时本地推理默认走paddle_static。5.2 权重转换使用推理引擎时系统会自动下载官方预训练模型。若需使用自训练模型配合paddle_dynamic或transformers引擎请参考 PaddleX 表格单元格检测模块权重转换部分将pdparams格式通过 PaddleX 转换为safetensors格式即可无缝集成到 PaddleOCR 的 API 中进行推理。若需使用自训练模型配合onnxruntime引擎请参考 PaddleX 获取 ONNX 模型的方式获取 onnx 模型即可无缝集成到 PaddleOCR 的 API 中进行推理。六、二次开发由于 PaddleOCR 并不直接提供表格单元格检测模块的训练因此如果需要训练表格单元格检测模型可以参考 PaddleX 表格单元格检测模块二次开发部分进行训练。训练后的模型可以无缝集成到 PaddleOCR 的 API 中进行推理——实例化TableCellsDetection时传入model_dir指向本地训练好的模型目录即可model_name与model_dir的配合方式在 paddleocr/_models/base.py 的PaddleXPredictorWrapper.__init__中有清晰体现model_name为None时回退到default_model_name而model_dir会被直接传给 PaddleX 的create_predictor作为本地模型来源。训练后的模型如果想使用paddle_dynamic或transformers引擎请参考上文 5.2 权重转换 部分完成格式转换。七、FAQ常见问题结合官方文档与仓库源码以下是表格单元格检测使用中最高频的几类问题默认模型是什么不指定model_name时默认使用RT-DETR-L_wired_table_cell_det该默认值定义于 paddleocr/_models/table_cells_detection.py 的default_model_name属性。模型下载慢或 HuggingFace 无法访问怎么办通过环境变量PADDLE_PDX_MODEL_SOURCEBOS将模型源切换为百度 BOS。想用非默认推理引擎但依赖没装根据引擎选择安装对应依赖飞桨框架见飞桨框架安装Transformers 需transformers5.10.0ONNX Runtime 需onnxruntime/onnxruntime-gpu若create_predictor时依赖缺失paddleocr/_models/base.py 会抛出带安装指引的RuntimeError。如何在代码里确认推理真的走通了仓库提供了现成的冒烟测试参考tests/models/test_table_cells_detection.py 使用tests/test_files/table.jpg作为输入对predict结果的关键字段与参数透传进行了断言可将其作为最小可用示例阅读。如何对大批量图片做内存友好推理使用predict_iter()返回生成器逐步取结果避免一次性将全部预测结果载入内存。单元格检测结果如何与表格识别产线衔接表格识别产线在 paddleocr/_pipelines/table_recognition_v2.py 中通过SubModules.WiredTableCellsDetection/SubModules.WirelessTableCellsDetection挂载本模块并支持use_ocr_results_with_table_cells等选项控制单元格框与 OCR 结果的融合策略可直接用paddleocr table_recognition产线命令体验完整链路。结语表格单元格检测作为 PaddleOCR 表格能力的关键一环通过两个 RT-DETR-L 模型覆盖有线/无线表格场景提供了 CLI 与 Python API 双入口、多推理引擎切换、灵活的结果导出方式并可借助 PaddleX 完成训练与权重格式转换后无缝回接。配合仓库内的源码paddleocr/_models/table_cells_detection.py、产线集成paddleocr/_pipelines/table_recognition_v2.py与测试用例tests/models/test_table_cells_detection.py你可以快速将图像/PDF → 单元格坐标 → 结构化表格的完整链路落地到自己的业务中。【免费下载链接】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），仅供参考