PaddleOCR 文本图像矫正Text Image Unwarping模块使用教程UVDoc 模型推理实战【免费下载链接】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本文档介绍 PaddleOCR 3.x 中文本图像矫正模块Text Image Unwarping的完整使用流程。该模块基于 UVDoc 模型对文档图像中的扭曲、倾斜、透视形变进行几何矫正以提升后续文字识别的准确率是文档图像预处理与 RAG/LLM 数据管线中的关键一环。读完本文你将掌握该模块的命令行一键推理、Python API 集成、多推理引擎切换、结果解析与保存以及相关参数的底层含义与调优方法。1. 模块概述文本图像矫正Text Image Rectification的核心目的是对图像施加几何变换纠正文档图像中的**形变distortion、倾斜inclination、透视变形perspective deformation**等问题从而为后续更准确的文字识别OCR提供规整的输入。在实际应用中手机拍摄的文档照片、扫描书籍的弯曲页面、拍摄屏幕或展板的照片往往带有明显的几何畸变直接送入识别模型会显著降低识别精度。文本图像矫正模块正是为了解决这一痛点而设计先矫正、后识别是构建高鲁棒性文档解析流水线的常见前置步骤。从源码结构看该模块位于 paddleocr/_models/text_image_unwarping.py通过TextImageUnwarping类对 PaddleX 的底层预测器进行封装同时注册了名为text_image_unwarping的 CLI 子命令见 paddleocr/_models/text_image_unwarping.py#L44-L54并提供predict()与predict_iter()两种推理入口。2. 支持模型列表当前版本该模块内置的官方模型为UVDocHigh-accuracy text image rectification model高精度文本图像矫正模型相关信息如下模型模型下载链接CERGPU 推理耗时ms[常规模式 / 高性能模式]CPU 推理耗时ms[常规模式 / 高性能模式]模型存储大小MB说明UVDoc推理模型 / 训练模型0.17919.05 / 19.05- / 869.8230.3高精度文本图像矫正模型说明上表中的推理耗时仅包含模型推理时间不包含前后处理时间常规模式数值对应本地paddle_static推理引擎。测试环境说明性能测试环境测试数据集DocUNet benchmark 数据集硬件配置GPU 为 NVIDIA Tesla T4CPU 为 Intel Xeon Gold 6271C 2.60GHz软件环境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 等从源码层面看TextImageUnwarping的默认模型名为UVDoc见 paddleocr/_models/text_image_unwarping.py#L32-L34当不显式指定model_name时即使用该默认模型底层通过paddlex.create_predictor(model_name..., model_dir...)创建预测器见 paddleocr/_models/base.py#L71-L82。3. 快速开始3.1 环境准备❗ 快速开始之前请先安装 PaddleOCR wheel 包安装细节参考 安装教程。以下示例默认使用paddle_static推理引擎运行前请按照 PaddlePaddle 框架安装 先安装 PaddlePaddle。3.2 命令行一键推理你可以通过一条命令快速体验文本图像矫正paddleocr text_image_unwarping -i https://paddle-model-ecology.bj.bcebos.com/paddlex/imgs/demo_image/doc_test.jpgpaddleocr是 PaddleOCR 提供的统一命令行入口text_image_unwarping是文本图像矫正模块对应的子命令注册于 paddleocr/_models/text_image_unwarping.py#L44-L48-i/--input指定输入路径或 URL必填支持本地图片、本地 PDF、图片目录或网络 URL见 paddleocr/_utils/cli.py#L31-L40命令行还支持--model_name、--model_dir、--device、--engine、--enable_hpi、--use_tensorrt、--precision、--enable_mkldnn、--cpu_threads等参数见 paddleocr/_models/base.py#L94-L102。切换推理引擎如果你选择transformers作为推理引擎请确保已配置好 Transformers 环境然后运行# 使用 transformers 引擎进行推理 paddleocr text_image_unwarping -i https://paddle-model-ecology.bj.bcebos.com/paddlex/imgs/demo_image/doc_test.jpg \ --engine transformers如果你选择onnxruntime作为推理引擎请确保已配置好 ONNX Runtime 环境然后运行# 使用 onnxruntime 引擎进行推理 paddleocr text_image_unwarping -i https://paddle-model-ecology.bj.bcebos.com/paddlex/imgs/demo_image/doc_test.jpg \ --engine onnxruntime在大多数场景下默认的paddle_static推理引擎能提供更好的推理性能是首选推荐。注意官方模型默认从 HuggingFace 下载。如果无法访问 HuggingFace请设置环境变量PADDLE_PDX_MODEL_SOURCEBOS将模型源切换为 BOS。未来将支持更多模型来源。3.3 Python API 集成你也可以将文本图像矫正模块的模型推理集成到自己的项目中。运行以下代码前请先将示例图片下载到本地from paddleocr import TextImageUnwarping model TextImageUnwarping(model_nameUVDoc) output model.predict(doc_test.jpg, batch_size1) for res in output: res.print() res.save_to_img(save_path./output/) res.save_to_json(save_path./output/res.json)上述示例默认使用paddle_static推理引擎。若选择transformers引擎from paddleocr import TextImageUnwarping model TextImageUnwarping( model_nameUVDoc, enginetransformers, ) output model.predict(doc_test.jpg, batch_size1) for res in output: res.print() res.save_to_img(save_path./output/) res.save_to_json(save_path./output/res.json)若选择onnxruntime引擎from paddleocr import TextImageUnwarping model TextImageUnwarping( model_nameUVDoc, engineonnxruntime, ) output model.predict(doc_test.jpg, batch_size1) for res in output: res.print() res.save_to_img(save_path./output/) res.save_to_json(save_path./output/res.json)在大多数场景下默认的paddle_static推理引擎能提供更好的推理性能是首选推荐。从源码实现看TextImageUnwarping继承自PaddleXPredictorWrapper其predict()方法内部通过list(self.predict_iter(...))一次性收集全部结果而predict_iter()直接透传底层paddlex_predictor.predict()见 paddleocr/_models/base.py#L53-L58。3.4 预测结果解读运行完成后得到的结果如下{res: {input_path: doc_test.jpg, page_index: None, doctr_img: ...}}结果中各参数的含义input_path表示待矫正图像的路径page_index页码索引处理 PDF 时有效单张图片时为Nonedoctr_img表示矫正后的图像结果。由于数据量较大不便于直接打印此处以...代替。你可以通过res.save_to_img()将预测结果保存为图片通过res.save_to_json()将预测结果保存为 json 文件。从测试用例也可以印证结果结构tests/models/test_text_image_unwarping.py#L40-L45断言预测结果的键集合为{input_path, page_index, input_img, doctr_img}即结果中同时包含输入图像与矫正后的图像。4. 核心参数详解4.1TextImageUnwarping实例化参数TextImageUnwarping用于实例化图像矫正模型此处以UVDoc为例具体参数说明如下参数说明类型默认值model_name含义模型名称strNonemodel_dir含义模型存储路径strNonedevice含义推理使用的设备。示例cpu、gpu、npu、gpu:0、gpu:0,1。指定多个设备时会进行并行推理注意并非所有场景都支持并行。默认优先使用 GPU 0否则使用 CPUstrNoneengine含义推理引擎。说明支持None默认、paddle、paddle_static、paddle_dynamic、transformers、onnxruntime。为None时本地推理默认使用paddle_static引擎。详细说明、取值、兼容性规则与示例参见 推理引擎与配置说明str\|NoneNoneengine_config含义推理引擎配置。说明建议与engine配合使用。支持的字段、兼容性规则与示例参见 推理引擎与配置说明dict\|NoneNoneenable_hpi含义是否使用高性能推理boolFalseuse_tensorrt含义是否使用 Paddle Inference 的 TensorRT 子图引擎。说明若模型不支持 TensorRT 加速即使设置该标志也不会启用加速。Paddle 搭配 CUDA 11.8 时兼容的 TensorRT 版本为 8.xx6推荐安装 TensorRT 8.6.1.6boolFalseprecision含义使用 Paddle Inference TensorRT 子图引擎时的 TensorRT 精度。选项fp32、fp16等strfp32enable_mkldnn含义是否启用 MKL-DNN 推理加速。说明若 MKL-DNN 不可用或模型不支持即使设置该标志也不会启用加速boolTruemkldnn_cache_capacity含义MKL-DNN 缓存容量int10cpu_threads含义CPU 推理使用的线程数int10这些参数的默认值在源码中有明确定义见 paddleocr/_constants.pyDEFAULT_USE_TENSORRT False、DEFAULT_PRECISION fp32、DEFAULT_ENABLE_MKLDNN True、DEFAULT_MKLDNN_CACHE_CAPACITY 10、DEFAULT_CPU_THREADS 10支持的精度列表为[fp32, fp16]支持的推理引擎列表为[paddle, paddle_static, paddle_dynamic, transformers, onnxruntime]见 paddleocr/_common_args.py#L29-L35。若传入未知参数或非法引擎/精度值会抛出ValueError提示见 paddleocr/_common_args.py#L52-L69。关于引擎配置的底层逻辑在默认paddle_static引擎下源码会根据设备类型自动构建引擎配置见 paddleocr/_common_args.py#L77-L99GPU 设备上若开启use_tensorrt会将run_mode设置为trt_fp32或trt_fp16否则为paddleCPU 设备上若开启enable_mkldnn则配置mkldnn_cache_capacity与cpu_threads否则run_mode为paddle。这也解释了为什么use_tensorrt、precision、enable_mkldnn等参数只有在paddle_static引擎下才真正生效。4.2predict()/predict_iter()方法参数调用图像矫正模型的predict()方法进行推理预测该方法会返回一个结果列表。此外该模块还提供predict_iter()方法。两种方法在参数接收与结果返回上保持一致区别在于predict_iter()返回一个generator可以逐步获取预测结果适合处理大规模数据集或内存受限的场景。你可以根据实际需求选择使用。predict()方法包含input和batch_size两个参数参数说明类型默认值input含义待预测的输入数据必填。说明支持多种输入类型Python 变量如图像数据的numpy.ndarraystr① 本地图像或 PDF 文件路径如/root/data/img.jpg② 图像或 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含义批大小。说明正整数int14.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文件保存路径。指定为目录时保存的文件名与输入文件类型保持一致Noneindentint指定美化输出JSON数据的缩进级别使其更易读仅在format_json为True时生效4ensure_asciibool控制是否将非ASCII字符转义为Unicode。为True时所有非ASCII字符被转义False保留原字符仅在format_json为True时生效Falsesave_to_img()将结果保存为图片格式文件save_pathstr文件保存路径。指定为目录时保存的文件名与输入文件类型保持一致None4.4 预测结果属性此外还可以通过以下属性获取带可视化的图片结果和预测结果属性说明json以json格式获取预测结果img以dict格式获取可视化图片在命令行场景下perform_simple_inference会遍历predict_iter()返回的每个结果依次调用res.print()并在指定--save_path时调用res.save_all(save_path)保存全部输出见 paddleocr/_utils/cli.py#L48-L75。5. 二次开发当前模块暂不支持微调训练仅支持推理集成。关于该模块的微调训练计划在未来版本支持。因此现阶段使用该模块的正确方式是直接加载官方 UVDoc 预训练模型进行推理或将其作为数据预处理环节集成到更大的文档解析流水线中。6. 推理引擎推理引擎的详细说明、取值、兼容性规则与示例请参考 推理引擎与配置说明。6.1 速度数据不同推理引擎下的端到端耗时对比UVDoc 模型如下模型引擎预处理ms推理ms后处理ms端到端msUVDocpaddle_static14.9618.601.9336.66UVDocpaddle_dynamic10.9027.591.9640.94UVDoctransformers13.546.740.9133.07UVDoconnxruntime10.608.441.7521.30测试环境说明测试数据示例图片硬件配置GPU 为 NVIDIA A100 40GCPU 为 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.2从表中数据可以看出在 A100 环境下onnxruntime引擎的端到端耗时最低21.30 mstransformers引擎的纯推理耗时最低6.74 ms而默认的paddle_static引擎则在兼容性与性能之间取得了较好的平衡这也是其作为默认引擎的原因。需要注意的是不同硬件与软件环境下各引擎的相对性能可能不同建议结合自身部署环境实测选择。7. FAQQ1为什么use_tensorrtTrue没有生效ATensorRT 加速仅在使用 Paddle Inference 的paddle_static引擎且模型支持 TensorRT 子图加速时才可能生效参见 paddleocr/_common_args.py#L77-L99 中 GPU 分支的run_mode配置逻辑。如果模型不支持 TensorRT 加速或当前未运行在 GPU 设备上即使设置该标志也不会启用加速。Q2为什么precision设置为fp16报错A源码中支持的精度列表为[fp32, fp16]见 paddleocr/_constants.py#L21传入列表之外的精度会抛出ValueError。请检查拼写例如应使用小写fp16而非FP16。Q3模型下载失败或无法从 HuggingFace 下载A官方模型默认从 HuggingFace 下载。如果无法访问 HuggingFace请设置环境变量PADDLE_PDX_MODEL_SOURCEBOS将模型源切换为 BOS 镜像。Q4predict()和predict_iter()有什么区别A两者参数与结果一致区别在于predict()一次性返回完整结果列表内部通过list(self.predict_iter(...))收集见 paddleocr/_models/base.py#L56-L58而predict_iter()返回生成器generator可逐个获取结果适合大规模数据集或内存受限场景。Q5该模块可以微调吗A当前版本不支持微调训练仅支持推理集成。微调训练支持已在未来规划中。8. 进一步阅读推理引擎完整配置说明推理引擎与配置说明高性能推理配置高性能推理说明并行推理说明并行推理说明模块源码paddleocr/_models/text_image_unwarping.py通用预测器封装基类paddleocr/_models/base.py通用参数解析与引擎配置paddleocr/_common_args.py模块测试用例tests/models/test_text_image_unwarping.py其他模块使用教程参见 docs/version3.x/module_usage/ 目录其中包含文本检测、文本识别、文档方向分类、版面分析、表格结构识别等模块的同类教程可与文本图像矫正模块组合成完整的文档解析流水线。【免费下载链接】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 文本图像矫正Text Image Unwarping模块使用教程UVDoc 模型推理实战【免费下载链接】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本文档介绍 PaddleOCR 3.x 中文本图像矫正模块Text Image Unwarping的完整使用流程。该模块基于 UVDoc 模型对文档图像中的扭曲、倾斜、透视形变进行几何矫正以提升后续文字识别的准确率是文档图像预处理与 RAG/LLM 数据管线中的关键一环。读完本文你将掌握该模块的命令行一键推理、Python API 集成、多推理引擎切换、结果解析与保存以及相关参数的底层含义与调优方法。1. 模块概述文本图像矫正Text Image Rectification的核心目的是对图像施加几何变换纠正文档图像中的**形变distortion、倾斜inclination、透视变形perspective deformation**等问题从而为后续更准确的文字识别OCR提供规整的输入。在实际应用中手机拍摄的文档照片、扫描书籍的弯曲页面、拍摄屏幕或展板的照片往往带有明显的几何畸变直接送入识别模型会显著降低识别精度。文本图像矫正模块正是为了解决这一痛点而设计先矫正、后识别是构建高鲁棒性文档解析流水线的常见前置步骤。从源码结构看该模块位于 paddleocr/_models/text_image_unwarping.py通过TextImageUnwarping类对 PaddleX 的底层预测器进行封装同时注册了名为text_image_unwarping的 CLI 子命令见 paddleocr/_models/text_image_unwarping.py#L44-L54并提供predict()与predict_iter()两种推理入口。2. 支持模型列表当前版本该模块内置的官方模型为UVDocHigh-accuracy text image rectification model高精度文本图像矫正模型相关信息如下模型模型下载链接CERGPU 推理耗时ms[常规模式 / 高性能模式]CPU 推理耗时ms[常规模式 / 高性能模式]模型存储大小MB说明UVDoc推理模型 / 训练模型0.17919.05 / 19.05- / 869.8230.3高精度文本图像矫正模型说明上表中的推理耗时仅包含模型推理时间不包含前后处理时间常规模式数值对应本地paddle_static推理引擎。测试环境说明性能测试环境测试数据集DocUNet benchmark 数据集硬件配置GPU 为 NVIDIA Tesla T4CPU 为 Intel Xeon Gold 6271C 2.60GHz软件环境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 等从源码层面看TextImageUnwarping的默认模型名为UVDoc见 paddleocr/_models/text_image_unwarping.py#L32-L34当不显式指定model_name时即使用该默认模型底层通过paddlex.create_predictor(model_name..., model_dir...)创建预测器见 paddleocr/_models/base.py#L71-L82。3. 快速开始3.1 环境准备❗ 快速开始之前请先安装 PaddleOCR wheel 包安装细节参考 安装教程。以下示例默认使用paddle_static推理引擎运行前请按照 PaddlePaddle 框架安装 先安装 PaddlePaddle。3.2 命令行一键推理你可以通过一条命令快速体验文本图像矫正paddleocr text_image_unwarping -i https://paddle-model-ecology.bj.bcebos.com/paddlex/imgs/demo_image/doc_test.jpgpaddleocr是 PaddleOCR 提供的统一命令行入口text_image_unwarping是文本图像矫正模块对应的子命令注册于 paddleocr/_models/text_image_unwarping.py#L44-L48-i/--input指定输入路径或 URL必填支持本地图片、本地 PDF、图片目录或网络 URL见 paddleocr/_utils/cli.py#L31-L40命令行还支持--model_name、--model_dir、--device、--engine、--enable_hpi、--use_tensorrt、--precision、--enable_mkldnn、--cpu_threads等参数见 paddleocr/_models/base.py#L94-L102。切换推理引擎如果你选择transformers作为推理引擎请确保已配置好 Transformers 环境然后运行# 使用 transformers 引擎进行推理 paddleocr text_image_unwarping -i https://paddle-model-ecology.bj.bcebos.com/paddlex/imgs/demo_image/doc_test.jpg \ --engine transformers如果你选择onnxruntime作为推理引擎请确保已配置好 ONNX Runtime 环境然后运行# 使用 onnxruntime 引擎进行推理 paddleocr text_image_unwarping -i https://paddle-model-ecology.bj.bcebos.com/paddlex/imgs/demo_image/doc_test.jpg \ --engine onnxruntime在大多数场景下默认的paddle_static推理引擎能提供更好的推理性能是首选推荐。注意官方模型默认从 HuggingFace 下载。如果无法访问 HuggingFace请设置环境变量PADDLE_PDX_MODEL_SOURCEBOS将模型源切换为 BOS。未来将支持更多模型来源。3.3 Python API 集成你也可以将文本图像矫正模块的模型推理集成到自己的项目中。运行以下代码前请先将示例图片下载到本地from paddleocr import TextImageUnwarping model TextImageUnwarping(model_nameUVDoc) output model.predict(doc_test.jpg, batch_size1) for res in output: res.print() res.save_to_img(save_path./output/) res.save_to_json(save_path./output/res.json)上述示例默认使用paddle_static推理引擎。若选择transformers引擎from paddleocr import TextImageUnwarping model TextImageUnwarping( model_nameUVDoc, enginetransformers, ) output model.predict(doc_test.jpg, batch_size1) for res in output: res.print() res.save_to_img(save_path./output/) res.save_to_json(save_path./output/res.json)若选择onnxruntime引擎from paddleocr import TextImageUnwarping model TextImageUnwarping( model_nameUVDoc, engineonnxruntime, ) output model.predict(doc_test.jpg, batch_size1) for res in output: res.print() res.save_to_img(save_path./output/) res.save_to_json(save_path./output/res.json)在大多数场景下默认的paddle_static推理引擎能提供更好的推理性能是首选推荐。从源码实现看TextImageUnwarping继承自PaddleXPredictorWrapper其predict()方法内部通过list(self.predict_iter(...))一次性收集全部结果而predict_iter()直接透传底层paddlex_predictor.predict()见 paddleocr/_models/base.py#L53-L58。3.4 预测结果解读运行完成后得到的结果如下{res: {input_path: doc_test.jpg, page_index: None, doctr_img: ...}}结果中各参数的含义input_path表示待矫正图像的路径page_index页码索引处理 PDF 时有效单张图片时为Nonedoctr_img表示矫正后的图像结果。由于数据量较大不便于直接打印此处以...代替。你可以通过res.save_to_img()将预测结果保存为图片通过res.save_to_json()将预测结果保存为 json 文件。从测试用例也可以印证结果结构tests/models/test_text_image_unwarping.py#L40-L45断言预测结果的键集合为{input_path, page_index, input_img, doctr_img}即结果中同时包含输入图像与矫正后的图像。4. 核心参数详解4.1TextImageUnwarping实例化参数TextImageUnwarping用于实例化图像矫正模型此处以UVDoc为例具体参数说明如下参数说明类型默认值model_name含义模型名称strNonemodel_dir含义模型存储路径strNonedevice含义推理使用的设备。示例cpu、gpu、npu、gpu:0、gpu:0,1。指定多个设备时会进行并行推理注意并非所有场景都支持并行。默认优先使用 GPU 0否则使用 CPUstrNoneengine含义推理引擎。说明支持None默认、paddle、paddle_static、paddle_dynamic、transformers、onnxruntime。为None时本地推理默认使用paddle_static引擎。详细说明、取值、兼容性规则与示例参见 推理引擎与配置说明str\|NoneNoneengine_config含义推理引擎配置。说明建议与engine配合使用。支持的字段、兼容性规则与示例参见 推理引擎与配置说明dict\|NoneNoneenable_hpi含义是否使用高性能推理boolFalseuse_tensorrt含义是否使用 Paddle Inference 的 TensorRT 子图引擎。说明若模型不支持 TensorRT 加速即使设置该标志也不会启用加速。Paddle 搭配 CUDA 11.8 时兼容的 TensorRT 版本为 8.xx6推荐安装 TensorRT 8.6.1.6boolFalseprecision含义使用 Paddle Inference TensorRT 子图引擎时的 TensorRT 精度。选项fp32、fp16等strfp32enable_mkldnn含义是否启用 MKL-DNN 推理加速。说明若 MKL-DNN 不可用或模型不支持即使设置该标志也不会启用加速boolTruemkldnn_cache_capacity含义MKL-DNN 缓存容量int10cpu_threads含义CPU 推理使用的线程数int10这些参数的默认值在源码中有明确定义见 paddleocr/_constants.pyDEFAULT_USE_TENSORRT False、DEFAULT_PRECISION fp32、DEFAULT_ENABLE_MKLDNN True、DEFAULT_MKLDNN_CACHE_CAPACITY 10、DEFAULT_CPU_THREADS 10支持的精度列表为[fp32, fp16]支持的推理引擎列表为[paddle, paddle_static, paddle_dynamic, transformers, onnxruntime]见 paddleocr/_common_args.py#L29-L35。若传入未知参数或非法引擎/精度值会抛出ValueError提示见 paddleocr/_common_args.py#L52-L69。关于引擎配置的底层逻辑在默认paddle_static引擎下源码会根据设备类型自动构建引擎配置见 paddleocr/_common_args.py#L77-L99GPU 设备上若开启use_tensorrt会将run_mode设置为trt_fp32或trt_fp16否则为paddleCPU 设备上若开启enable_mkldnn则配置mkldnn_cache_capacity与cpu_threads否则run_mode为paddle。这也解释了为什么use_tensorrt、precision、enable_mkldnn等参数只有在paddle_static引擎下才真正生效。4.2predict()/predict_iter()方法参数调用图像矫正模型的predict()方法进行推理预测该方法会返回一个结果列表。此外该模块还提供predict_iter()方法。两种方法在参数接收与结果返回上保持一致区别在于predict_iter()返回一个generator可以逐步获取预测结果适合处理大规模数据集或内存受限的场景。你可以根据实际需求选择使用。predict()方法包含input和batch_size两个参数参数说明类型默认值input含义待预测的输入数据必填。说明支持多种输入类型Python 变量如图像数据的numpy.ndarraystr① 本地图像或 PDF 文件路径如/root/data/img.jpg② 图像或 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含义批大小。说明正整数int14.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文件保存路径。指定为目录时保存的文件名与输入文件类型保持一致Noneindentint指定美化输出JSON数据的缩进级别使其更易读仅在format_json为True时生效4ensure_asciibool控制是否将非ASCII字符转义为Unicode。为True时所有非ASCII字符被转义False保留原字符仅在format_json为True时生效Falsesave_to_img()将结果保存为图片格式文件save_pathstr文件保存路径。指定为目录时保存的文件名与输入文件类型保持一致None4.4 预测结果属性此外还可以通过以下属性获取带可视化的图片结果和预测结果属性说明json以json格式获取预测结果img以dict格式获取可视化图片在命令行场景下perform_simple_inference会遍历predict_iter()返回的每个结果依次调用res.print()并在指定--save_path时调用res.save_all(save_path)保存全部输出见 paddleocr/_utils/cli.py#L48-L75。5. 二次开发当前模块暂不支持微调训练仅支持推理集成。关于该模块的微调训练计划在未来版本支持。因此现阶段使用该模块的正确方式是直接加载官方 UVDoc 预训练模型进行推理或将其作为数据预处理环节集成到更大的文档解析流水线中。6. 推理引擎推理引擎的详细说明、取值、兼容性规则与示例请参考 推理引擎与配置说明。6.1 速度数据不同推理引擎下的端到端耗时对比UVDoc 模型如下模型引擎预处理ms推理ms后处理ms端到端msUVDocpaddle_static14.9618.601.9336.66UVDocpaddle_dynamic10.9027.591.9640.94UVDoctransformers13.546.740.9133.07UVDoconnxruntime10.608.441.7521.30测试环境说明测试数据示例图片硬件配置GPU 为 NVIDIA A100 40GCPU 为 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.2从表中数据可以看出在 A100 环境下onnxruntime引擎的端到端耗时最低21.30 mstransformers引擎的纯推理耗时最低6.74 ms而默认的paddle_static引擎则在兼容性与性能之间取得了较好的平衡这也是其作为默认引擎的原因。需要注意的是不同硬件与软件环境下各引擎的相对性能可能不同建议结合自身部署环境实测选择。7. FAQQ1为什么use_tensorrtTrue没有生效ATensorRT 加速仅在使用 Paddle Inference 的paddle_static引擎且模型支持 TensorRT 子图加速时才可能生效参见 paddleocr/_common_args.py#L77-L99 中 GPU 分支的run_mode配置逻辑。如果模型不支持 TensorRT 加速或当前未运行在 GPU 设备上即使设置该标志也不会启用加速。Q2为什么precision设置为fp16报错A源码中支持的精度列表为[fp32, fp16]见 paddleocr/_constants.py#L21传入列表之外的精度会抛出ValueError。请检查拼写例如应使用小写fp16而非FP16。Q3模型下载失败或无法从 HuggingFace 下载A官方模型默认从 HuggingFace 下载。如果无法访问 HuggingFace请设置环境变量PADDLE_PDX_MODEL_SOURCEBOS将模型源切换为 BOS 镜像。Q4predict()和predict_iter()有什么区别A两者参数与结果一致区别在于predict()一次性返回完整结果列表内部通过list(self.predict_iter(...))收集见 paddleocr/_models/base.py#L56-L58而predict_iter()返回生成器generator可逐个获取结果适合大规模数据集或内存受限场景。Q5该模块可以微调吗A当前版本不支持微调训练仅支持推理集成。微调训练支持已在未来规划中。8. 进一步阅读推理引擎完整配置说明推理引擎与配置说明高性能推理配置高性能推理说明并行推理说明并行推理说明模块源码paddleocr/_models/text_image_unwarping.py通用预测器封装基类paddleocr/_models/base.py通用参数解析与引擎配置paddleocr/_common_args.py模块测试用例tests/models/test_text_image_unwarping.py其他模块使用教程参见 docs/version3.x/module_usage/ 目录其中包含文本检测、文本识别、文档方向分类、版面分析、表格结构识别等模块的同类教程可与文本图像矫正模块组合成完整的文档解析流水线。【免费下载链接】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），仅供参考
)
)
