PaddleOCR PP-Structure 文档恢复实战开启 return_word_box 让识别结果返回每个文字的位置【免费下载链接】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 仓库中ppstructure文档恢复Document Recovery管线讲解如何通过--return_word_boxTrue让识别模型在返回文本内容的同时输出每个单词/单字的精确位置框并配套英文、中文两类文档的完整落地步骤。读完本文你将掌握return_word_box的开关方式、输出 JSON 的字段语义、从识别解码到单词框计算的底层原理以及如何将位置信息用于版面恢复、Markdown/Docx 生成与结构化数据抽取。一、为什么文档恢复需要文字位置在横向排版横排的文档中PP-Structure 的识别模型不仅能输出识别出的文字内容还能输出每一个文字/单词所在的坐标位置。这一能力对文档恢复Document Recovery与 AI 结构化数据处理至关重要版面恢复恢复出的 Word/Markdown 需要还原原文的阅读顺序、段落缩进与分栏结构而这一切都依赖每个文字块的空间坐标段落合并PP-Structure 依据文字框的 x 坐标偏移判断段落首行缩进见下文check_merge_method逻辑没有位置信息就无法正确分段结构化输出将 OCR 结果交给 LLM 或下游系统时带坐标的文本所谓 grounding可以定位这句话在文档的哪个区域显著提升检索与引用价值。return_word_box正是控制该能力的核心开关默认关闭开启后识别结果的每个文本行会额外携带text_word单词/单字内容与text_word_region单词/单字级坐标框两个字段。二、return_word_box输出结构一行文字返回了什么从 predict_system.py 中_predict_text的实现可以看到开启开关后每个文本行返回的 dict 从 3 个字段扩展为 5 个字段字段含义开启前开启后text整行识别文本✔✔confidence整行置信度✔✔text_region整行的四点检测框[x1,y1],[x2,y1],[x2,y2],[x1,y2]形式✔✔text_word单词/单字内容列表如[Hello, world]或中文字符序列✘✔text_word_region与text_word一一对应的单词/单字级四点框列表✘✔关键实现片段ppstructure/predict_system.pyif self.return_word_box: word_box_content_list, word_box_list cal_ocr_word_box( rec_str, box, rec_res[2] ) res.append({ text: rec_str, confidence: float(rec_conf), text_region: box.tolist(), text_word: word_box_content_list, text_word_region: word_box_list, }) else: res.append({ text: rec_str, confidence: float(rec_conf), text_region: box.tolist(), })也就是说return_word_box并不改变识别模型本身而是在后处理阶段基于整行检测框 识别解码时的逐字对齐信息把整行框拆成单词/单字级别的子框。三、源码原理单词框是如何算出来的3.1 识别解码阶段的逐字信息单词框的源头在识别后处理。在 rec_postprocess.py 中BaseRecLabelDecode.decode支持return_word_box参数当开启时会把解码得到的字符索引序列转成word_list单词内容、word_col_list单词覆盖的列区间、state_list每个单词属于cn中文还是其他语言三份信息作为识别结果的第三个元素返回if return_word_box: word_list, word_col_list, state_list self.get_word_info(text, selection) result_list.append(( text, np.mean(conf_list).tolist(), [len(text_index[batch_idx]), word_list, word_col_list, state_list], ))对于 CTC 解码路径CTCLabelDecode 还会用实际宽高比修正列数保证列区间与真实图像坐标对齐。因此rec_res[2]中携带的是解码层面的逐字对齐信息这是后续坐标换算的数据基础。3.2 从列区间到像素坐标cal_ocr_word_box真正把解码列区间换算成图像像素框的是 ppstructure/utility.py 中的cal_ocr_word_boxcol_num, word_list, word_col_list, state_list rec_word_info cell_width (bbox_x_end - bbox_x_start) / col_num其换算思路是用整行检测框的宽度除以解码总列数得到每个字符列的像素宽度cell_width对于英文等非中文单词state ! cn直接把单词覆盖的列区间映射回像素区间得到矩形四点框对于中文单字state cn先统计已切分出的汉字宽度取均值avg_char_width再以每个字的列中心为中心、向两侧各延伸半个平均字宽生成单字框——这是对连续中文缺乏显式切分时的近似策略。center_x (center_idx 0.5) * cell_width cell_x_start max(int(center_x - avg_char_width / 2), 0) bbox_x_start cell_x_end (min(int(center_x avg_char_width / 2), bbox_x_end - bbox_x_start) bbox_x_start)3.3 完整调用链一次开启return_word_box的文档恢复推理单词框计算的完整链路为predict_system.py (StructureSystem.__call__) └─ _predict_text → TextSystem 检测识别 └─ rec_postprocess.py decode(return_word_boxTrue) → 逐字列信息 └─ cal_ocr_word_box(rec_str, box, rec_res[2]) → 单词/单字像素框 └─ draw_structure_result(vis_font_path) → 绘制整行框 单词框可视化 └─ (recoveryTrue) recovery_to_doc / recovery_to_markdown → 还原 docx/markdown其中draw_structure_resultppstructure/utility.py在可视化时会把text_word_region中的每个子框都画出来跳过宽或高为 0 的异常框这就是结果图中看到整行大框 行内单词小框双层框的来源。四、实战一英文文档恢复返回单词位置4.1 下载四个推理模型在仓库ppstructure/目录下执行以下命令下载英文检测、识别、表格结构、版面分析四类推理模型cd PaddleOCR/ppstructure ## download model mkdir inference cd inference ## Download the detection model of the ultra-lightweight English PP-OCRv3 model and unzip it wget https://paddleocr.bj.bcebos.com/PP-OCRv3/english/en_PP-OCRv3_det_infer.tar tar xf en_PP-OCRv3_det_infer.tar ## Download the recognition model of the ultra-lightweight English PP-OCRv3 model and unzip it wget https://paddle-model-ecology.bj.bcebos.com/paddlex/official_inference_model/paddle3.0.0/en_PP-OCRv3_mobile_rec_infer.tar tar xf en_PP-OCRv3_mobile_rec_infer.tar ## Download the ultra-lightweight English table inch model and unzip it wget https://paddleocr.bj.bcebos.com/ppstructure/models/slanet/paddle3.0b2/en_ppstructure_mobile_v2.0_SLANet_infer.tar tar xf en_ppstructure_mobile_v2.0_SLANet_infer.tar ## Download the layout model of publaynet dataset and unzip it wget https://paddleocr.bj.bcebos.com/ppstructure/models/layout/picodet_lcnet_x1_0_fgd_layout_infer.tar tar xf picodet_lcnet_x1_0_fgd_layout_infer.tar cd ..4.2 执行推理在ppstructure/目录下运行注意将--image_dir替换为你自己的英文文档图片路径python predict_system.py \ --image_dir./docs/ppstructure/images/table_1.png \ --det_model_dirinference/en_PP-OCRv3_det_infer \ --rec_model_dirinference/en_PP-OCRv3_mobile_rec_infer \ --rec_char_dict_path../ppocr/utils/en_dict.txt \ --table_model_dirinference/en_ppstructure_mobile_v2.0_SLANet_infer \ --table_char_dict_path../ppocr/utils/dict/table_structure_dict.txt \ --layout_model_dirinference/picodet_lcnet_x1_0_fgd_layout_infer \ --layout_dict_path../ppocr/utils/dict/layout_dict/layout_publaynet_dict.txt \ --vis_font_path../doc/fonts/simfang.ttf \ --recoveryTrue \ --output../output/ \ --return_word_boxTrue推理完成后在../output/structure/table_1/show_0.jpg查看可视化结果每个版面区域被不同颜色框标注文字区域内部可以看到整行文字框 行内逐词小框的双层结构这正是return_word_box生效的直观体现。五、实战二中文文档恢复返回单字位置中文与英文的差异在于英文按空格分词每个单词一个框中文没有空格cal_ocr_word_box会按平均字宽为每个单字生成一个框state cn分支。5.1 下载四个推理模型cd PaddleOCR/ppstructure ## download model cd inference ## Download the detection model of the ultra-lightweight Chinese PP-OCRv3 model and unzip it wget https://paddle-model-ecology.bj.bcebos.com/paddlex/official_inference_model/paddle3.0.0/PP-OCRv3_mobile_det_infer.tar tar xf PP-OCRv3_mobile_det_infer.tar ## Download the recognition model of the ultra-lightweight Chinese PP-OCRv3 model and unzip it wget https://paddle-model-ecology.bj.bcebos.com/paddlex/official_inference_model/paddle3.0.0/PP-OCRv3_mobile_rec_infer.tar tar xf PP-OCRv3_mobile_rec_infer.tar ## Download the ultra-lightweight Chinese table inch model and unzip it wget https://paddleocr.bj.bcebos.com/ppstructure/models/slanet/paddle3.0b2/ch_ppstructure_mobile_v2.0_SLANet_infer.tar tar xf ch_ppstructure_mobile_v2.0_SLANet_infer.tar ## Download the layout model of CDLA dataset and unzip it wget https://paddleocr.bj.bcebos.com/ppstructure/models/layout/picodet_lcnet_x1_0_fgd_layout_cdla_infer.tar tar xf picodet_lcnet_x1_0_fgd_layout_cdla_infer.tar cd ..中文场景使用 CDLA 版面数据集训练的版面模型layout_dict_path相应换成 CDLA 字典。5.2 准备测试图片下载/上传一张中文文档截图作为测试输入即下方示例中的2.png也可替换为任意中文论文、合同或报告截图5.3 执行推理python predict_system.py \ --image_dir./docs/table/2.png \ --det_model_dirinference/PP-OCRv3_mobile_det_infer \ --rec_model_dirinference/PP-OCRv3_mobile_rec_infer \ --rec_char_dict_path../ppocr/utils/ppocr_keys_v1.txt \ --table_model_dirinference/ch_ppstructure_mobile_v2.0_SLANet_infer \ --table_char_dict_path../ppocr/utils/dict/table_structure_dict_ch.txt \ --layout_model_dirinference/picodet_lcnet_x1_0_fgd_layout_cdla_infer \ --layout_dict_path../ppocr/utils/dict/layout_dict/layout_cdla_dict.txt \ --vis_font_path../doc/fonts/chinese_cht.ttf \ --recoveryTrue \ --output../output/ \ --return_word_boxTrue推理完成后在../output/structure/2/show_0.jpg查看可视化。中文文档的每个文本块内部可以看到逐字级的细框红色、绿色、蓝色等不同颜色区分不同版面区域覆盖了原文的段落、图注与公式区域六、参数详解与默认值对照上述命令中的关键参数在 ppstructure/utility.py 的init_args中定义整理如下参数类型默认值说明--image_dirstr必填输入图片或图片目录支持多图--det_model_dirstr无文本检测推理模型目录--rec_model_dirstr无文本识别推理模型目录--rec_char_dict_pathstr无识别字典英文用en_dict.txt中文用ppocr_keys_v1.txt--table_model_dirstr无表格结构推理模型目录SLANet--table_char_dict_pathstr../ppocr/utils/dict/table_structure_dict_ch.txt表格结构字典--layout_model_dirstr无版面分析推理模型目录--layout_dict_pathstr../ppocr/utils/dict/layout_dict/layout_publaynet_dict.txt版面类别字典中文用layout_cdla_dict.txt--layout_score_thresholdfloat0.5版面框置信度阈值--layout_nms_thresholdfloat0.5版面框 NMS 阈值--vis_font_pathstr无可视化绘制字体英文推荐simfang.ttf中文推荐chinese_cht.ttf--recoveryboolFalse是否启用版面恢复还原 docx/markdown--recovery_to_markdownboolFalse是否额外输出 Markdown 文件--outputstr./output结果输出根目录--return_word_boxboolFalse是否返回每个单词/单字的位置框--modestrstructure推理模式可选structure/kie--layoutboolTrue是否启用版面分析--tableboolTrue表格区域是否走表格识别--ocrboolTrue非表格区域是否走 OCR--image_orientationboolFalse是否启用图像方向识别自动旋转 90/180/270 度注意--layoutFalse时--ocr会被强制置为 False见 predict_system.py 的告警逻辑二者存在联动约束。七、结果文件与后续处理开启--recoveryTrue后每个图片会在output/structure/图片名/目录下生成show_0.jpg双层框可视化结果图整行框 单词/单字框res_0.txt结构化 JSON 结果每个版面区域一行文本区域包含text、confidence、text_region、text_word、text_word_region字段由save_structure_res写出见 predict_system.py图片名_ocr.docx恢复出的 Word 文档recovery_to_doc.py图片名_ocr.md恢复出的 Markdown需另加--recovery_to_markdownTruerecovery_to_markdown.py表格区域会额外输出*.xlsx图片区域输出裁剪后的*.jpg。恢复阶段对位置信息的依赖点分栏识别sorted_layout_boxesrecovery_to_doc.py依据每个区域bbox的 x 坐标与页面中线的关系把区域归为左栏/右栏/通栏还原论文双栏排版段落判断check_merge_methodrecovery_to_markdown.py比较文本行首 x 坐标与整个文本区 bbox 左边界的差值是否大于行高以此区分首行缩进与末行不满两种段落标志阅读顺序_filter_text_res通过整行框与版面框的相交判断_has_intersection见 predict_system.py把 OCR 结果归入对应版面区域保证输出顺序正确。八、注意事项模型下载文中的 wget 链接为 PP-OCRv3 系列官方推理模型Paddle 3.0 生态目录若版本更新导致链接失效可前往 PaddleOCR 官方模型库查找替代下载地址输入路径命令中的./docs/ppstructure/images/table_1.png、./docs/table/2.png为示例图片路径请替换为实际存在的本地图片字典与字体必须配套英文识别配en_dict.txtsimfang.ttf中文识别配ppocr_keys_v1.txtchinese_cht.ttf错配会导致乱码或绘制失败性能影响return_word_boxTrue会增加少量后处理计算量逐字框换算 可视化绘制对整体推理耗时影响很小但建议生产环境按需开启中文单字框为近似结果中文没有空格分词单字框基于平均字宽近似估计在字体宽度差异较大的场景可能存在 ±半个字宽的偏差这是当前实现的固有特性见cal_ocr_word_box源码。九、总结return_word_box是 PP-Structure 文档恢复管线中从内容识别走向结构化输出的关键开关。开启后识别结果从一行一个框升级为一行一框 行内逐词/逐字小框配合版面分析、表格识别与恢复模块即可把一张图片/PDF 还原为带精确空间坐标的分层结构化数据——既可直接生成可编辑的 docx/markdown也可作为 LLM/RAG 系统的带位置索引输入。相关延伸可继续阅读仓库内的 PP-Structure 总览、快速开始 以及 恢复为 Word/Markdown 文档。【免费下载链接】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 PP-Structure 文档恢复实战：开启 return_word_box 让识别结果返回每个文字的位置
PaddleOCR PP-Structure 文档恢复实战开启 return_word_box 让识别结果返回每个文字的位置【免费下载链接】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 仓库中ppstructure文档恢复Document Recovery管线讲解如何通过--return_word_boxTrue让识别模型在返回文本内容的同时输出每个单词/单字的精确位置框并配套英文、中文两类文档的完整落地步骤。读完本文你将掌握return_word_box的开关方式、输出 JSON 的字段语义、从识别解码到单词框计算的底层原理以及如何将位置信息用于版面恢复、Markdown/Docx 生成与结构化数据抽取。一、为什么文档恢复需要文字位置在横向排版横排的文档中PP-Structure 的识别模型不仅能输出识别出的文字内容还能输出每一个文字/单词所在的坐标位置。这一能力对文档恢复Document Recovery与 AI 结构化数据处理至关重要版面恢复恢复出的 Word/Markdown 需要还原原文的阅读顺序、段落缩进与分栏结构而这一切都依赖每个文字块的空间坐标段落合并PP-Structure 依据文字框的 x 坐标偏移判断段落首行缩进见下文check_merge_method逻辑没有位置信息就无法正确分段结构化输出将 OCR 结果交给 LLM 或下游系统时带坐标的文本所谓 grounding可以定位这句话在文档的哪个区域显著提升检索与引用价值。return_word_box正是控制该能力的核心开关默认关闭开启后识别结果的每个文本行会额外携带text_word单词/单字内容与text_word_region单词/单字级坐标框两个字段。二、return_word_box输出结构一行文字返回了什么从 predict_system.py 中_predict_text的实现可以看到开启开关后每个文本行返回的 dict 从 3 个字段扩展为 5 个字段字段含义开启前开启后text整行识别文本✔✔confidence整行置信度✔✔text_region整行的四点检测框[x1,y1],[x2,y1],[x2,y2],[x1,y2]形式✔✔text_word单词/单字内容列表如[Hello, world]或中文字符序列✘✔text_word_region与text_word一一对应的单词/单字级四点框列表✘✔关键实现片段ppstructure/predict_system.pyif self.return_word_box: word_box_content_list, word_box_list cal_ocr_word_box( rec_str, box, rec_res[2] ) res.append({ text: rec_str, confidence: float(rec_conf), text_region: box.tolist(), text_word: word_box_content_list, text_word_region: word_box_list, }) else: res.append({ text: rec_str, confidence: float(rec_conf), text_region: box.tolist(), })也就是说return_word_box并不改变识别模型本身而是在后处理阶段基于整行检测框 识别解码时的逐字对齐信息把整行框拆成单词/单字级别的子框。三、源码原理单词框是如何算出来的3.1 识别解码阶段的逐字信息单词框的源头在识别后处理。在 rec_postprocess.py 中BaseRecLabelDecode.decode支持return_word_box参数当开启时会把解码得到的字符索引序列转成word_list单词内容、word_col_list单词覆盖的列区间、state_list每个单词属于cn中文还是其他语言三份信息作为识别结果的第三个元素返回if return_word_box: word_list, word_col_list, state_list self.get_word_info(text, selection) result_list.append(( text, np.mean(conf_list).tolist(), [len(text_index[batch_idx]), word_list, word_col_list, state_list], ))对于 CTC 解码路径CTCLabelDecode 还会用实际宽高比修正列数保证列区间与真实图像坐标对齐。因此rec_res[2]中携带的是解码层面的逐字对齐信息这是后续坐标换算的数据基础。3.2 从列区间到像素坐标cal_ocr_word_box真正把解码列区间换算成图像像素框的是 ppstructure/utility.py 中的cal_ocr_word_boxcol_num, word_list, word_col_list, state_list rec_word_info cell_width (bbox_x_end - bbox_x_start) / col_num其换算思路是用整行检测框的宽度除以解码总列数得到每个字符列的像素宽度cell_width对于英文等非中文单词state ! cn直接把单词覆盖的列区间映射回像素区间得到矩形四点框对于中文单字state cn先统计已切分出的汉字宽度取均值avg_char_width再以每个字的列中心为中心、向两侧各延伸半个平均字宽生成单字框——这是对连续中文缺乏显式切分时的近似策略。center_x (center_idx 0.5) * cell_width cell_x_start max(int(center_x - avg_char_width / 2), 0) bbox_x_start cell_x_end (min(int(center_x avg_char_width / 2), bbox_x_end - bbox_x_start) bbox_x_start)3.3 完整调用链一次开启return_word_box的文档恢复推理单词框计算的完整链路为predict_system.py (StructureSystem.__call__) └─ _predict_text → TextSystem 检测识别 └─ rec_postprocess.py decode(return_word_boxTrue) → 逐字列信息 └─ cal_ocr_word_box(rec_str, box, rec_res[2]) → 单词/单字像素框 └─ draw_structure_result(vis_font_path) → 绘制整行框 单词框可视化 └─ (recoveryTrue) recovery_to_doc / recovery_to_markdown → 还原 docx/markdown其中draw_structure_resultppstructure/utility.py在可视化时会把text_word_region中的每个子框都画出来跳过宽或高为 0 的异常框这就是结果图中看到整行大框 行内单词小框双层框的来源。四、实战一英文文档恢复返回单词位置4.1 下载四个推理模型在仓库ppstructure/目录下执行以下命令下载英文检测、识别、表格结构、版面分析四类推理模型cd PaddleOCR/ppstructure ## download model mkdir inference cd inference ## Download the detection model of the ultra-lightweight English PP-OCRv3 model and unzip it wget https://paddleocr.bj.bcebos.com/PP-OCRv3/english/en_PP-OCRv3_det_infer.tar tar xf en_PP-OCRv3_det_infer.tar ## Download the recognition model of the ultra-lightweight English PP-OCRv3 model and unzip it wget https://paddle-model-ecology.bj.bcebos.com/paddlex/official_inference_model/paddle3.0.0/en_PP-OCRv3_mobile_rec_infer.tar tar xf en_PP-OCRv3_mobile_rec_infer.tar ## Download the ultra-lightweight English table inch model and unzip it wget https://paddleocr.bj.bcebos.com/ppstructure/models/slanet/paddle3.0b2/en_ppstructure_mobile_v2.0_SLANet_infer.tar tar xf en_ppstructure_mobile_v2.0_SLANet_infer.tar ## Download the layout model of publaynet dataset and unzip it wget https://paddleocr.bj.bcebos.com/ppstructure/models/layout/picodet_lcnet_x1_0_fgd_layout_infer.tar tar xf picodet_lcnet_x1_0_fgd_layout_infer.tar cd ..4.2 执行推理在ppstructure/目录下运行注意将--image_dir替换为你自己的英文文档图片路径python predict_system.py \ --image_dir./docs/ppstructure/images/table_1.png \ --det_model_dirinference/en_PP-OCRv3_det_infer \ --rec_model_dirinference/en_PP-OCRv3_mobile_rec_infer \ --rec_char_dict_path../ppocr/utils/en_dict.txt \ --table_model_dirinference/en_ppstructure_mobile_v2.0_SLANet_infer \ --table_char_dict_path../ppocr/utils/dict/table_structure_dict.txt \ --layout_model_dirinference/picodet_lcnet_x1_0_fgd_layout_infer \ --layout_dict_path../ppocr/utils/dict/layout_dict/layout_publaynet_dict.txt \ --vis_font_path../doc/fonts/simfang.ttf \ --recoveryTrue \ --output../output/ \ --return_word_boxTrue推理完成后在../output/structure/table_1/show_0.jpg查看可视化结果每个版面区域被不同颜色框标注文字区域内部可以看到整行文字框 行内逐词小框的双层结构这正是return_word_box生效的直观体现。五、实战二中文文档恢复返回单字位置中文与英文的差异在于英文按空格分词每个单词一个框中文没有空格cal_ocr_word_box会按平均字宽为每个单字生成一个框state cn分支。5.1 下载四个推理模型cd PaddleOCR/ppstructure ## download model cd inference ## Download the detection model of the ultra-lightweight Chinese PP-OCRv3 model and unzip it wget https://paddle-model-ecology.bj.bcebos.com/paddlex/official_inference_model/paddle3.0.0/PP-OCRv3_mobile_det_infer.tar tar xf PP-OCRv3_mobile_det_infer.tar ## Download the recognition model of the ultra-lightweight Chinese PP-OCRv3 model and unzip it wget https://paddle-model-ecology.bj.bcebos.com/paddlex/official_inference_model/paddle3.0.0/PP-OCRv3_mobile_rec_infer.tar tar xf PP-OCRv3_mobile_rec_infer.tar ## Download the ultra-lightweight Chinese table inch model and unzip it wget https://paddleocr.bj.bcebos.com/ppstructure/models/slanet/paddle3.0b2/ch_ppstructure_mobile_v2.0_SLANet_infer.tar tar xf ch_ppstructure_mobile_v2.0_SLANet_infer.tar ## Download the layout model of CDLA dataset and unzip it wget https://paddleocr.bj.bcebos.com/ppstructure/models/layout/picodet_lcnet_x1_0_fgd_layout_cdla_infer.tar tar xf picodet_lcnet_x1_0_fgd_layout_cdla_infer.tar cd ..中文场景使用 CDLA 版面数据集训练的版面模型layout_dict_path相应换成 CDLA 字典。5.2 准备测试图片下载/上传一张中文文档截图作为测试输入即下方示例中的2.png也可替换为任意中文论文、合同或报告截图5.3 执行推理python predict_system.py \ --image_dir./docs/table/2.png \ --det_model_dirinference/PP-OCRv3_mobile_det_infer \ --rec_model_dirinference/PP-OCRv3_mobile_rec_infer \ --rec_char_dict_path../ppocr/utils/ppocr_keys_v1.txt \ --table_model_dirinference/ch_ppstructure_mobile_v2.0_SLANet_infer \ --table_char_dict_path../ppocr/utils/dict/table_structure_dict_ch.txt \ --layout_model_dirinference/picodet_lcnet_x1_0_fgd_layout_cdla_infer \ --layout_dict_path../ppocr/utils/dict/layout_dict/layout_cdla_dict.txt \ --vis_font_path../doc/fonts/chinese_cht.ttf \ --recoveryTrue \ --output../output/ \ --return_word_boxTrue推理完成后在../output/structure/2/show_0.jpg查看可视化。中文文档的每个文本块内部可以看到逐字级的细框红色、绿色、蓝色等不同颜色区分不同版面区域覆盖了原文的段落、图注与公式区域六、参数详解与默认值对照上述命令中的关键参数在 ppstructure/utility.py 的init_args中定义整理如下参数类型默认值说明--image_dirstr必填输入图片或图片目录支持多图--det_model_dirstr无文本检测推理模型目录--rec_model_dirstr无文本识别推理模型目录--rec_char_dict_pathstr无识别字典英文用en_dict.txt中文用ppocr_keys_v1.txt--table_model_dirstr无表格结构推理模型目录SLANet--table_char_dict_pathstr../ppocr/utils/dict/table_structure_dict_ch.txt表格结构字典--layout_model_dirstr无版面分析推理模型目录--layout_dict_pathstr../ppocr/utils/dict/layout_dict/layout_publaynet_dict.txt版面类别字典中文用layout_cdla_dict.txt--layout_score_thresholdfloat0.5版面框置信度阈值--layout_nms_thresholdfloat0.5版面框 NMS 阈值--vis_font_pathstr无可视化绘制字体英文推荐simfang.ttf中文推荐chinese_cht.ttf--recoveryboolFalse是否启用版面恢复还原 docx/markdown--recovery_to_markdownboolFalse是否额外输出 Markdown 文件--outputstr./output结果输出根目录--return_word_boxboolFalse是否返回每个单词/单字的位置框--modestrstructure推理模式可选structure/kie--layoutboolTrue是否启用版面分析--tableboolTrue表格区域是否走表格识别--ocrboolTrue非表格区域是否走 OCR--image_orientationboolFalse是否启用图像方向识别自动旋转 90/180/270 度注意--layoutFalse时--ocr会被强制置为 False见 predict_system.py 的告警逻辑二者存在联动约束。七、结果文件与后续处理开启--recoveryTrue后每个图片会在output/structure/图片名/目录下生成show_0.jpg双层框可视化结果图整行框 单词/单字框res_0.txt结构化 JSON 结果每个版面区域一行文本区域包含text、confidence、text_region、text_word、text_word_region字段由save_structure_res写出见 predict_system.py图片名_ocr.docx恢复出的 Word 文档recovery_to_doc.py图片名_ocr.md恢复出的 Markdown需另加--recovery_to_markdownTruerecovery_to_markdown.py表格区域会额外输出*.xlsx图片区域输出裁剪后的*.jpg。恢复阶段对位置信息的依赖点分栏识别sorted_layout_boxesrecovery_to_doc.py依据每个区域bbox的 x 坐标与页面中线的关系把区域归为左栏/右栏/通栏还原论文双栏排版段落判断check_merge_methodrecovery_to_markdown.py比较文本行首 x 坐标与整个文本区 bbox 左边界的差值是否大于行高以此区分首行缩进与末行不满两种段落标志阅读顺序_filter_text_res通过整行框与版面框的相交判断_has_intersection见 predict_system.py把 OCR 结果归入对应版面区域保证输出顺序正确。八、注意事项模型下载文中的 wget 链接为 PP-OCRv3 系列官方推理模型Paddle 3.0 生态目录若版本更新导致链接失效可前往 PaddleOCR 官方模型库查找替代下载地址输入路径命令中的./docs/ppstructure/images/table_1.png、./docs/table/2.png为示例图片路径请替换为实际存在的本地图片字典与字体必须配套英文识别配en_dict.txtsimfang.ttf中文识别配ppocr_keys_v1.txtchinese_cht.ttf错配会导致乱码或绘制失败性能影响return_word_boxTrue会增加少量后处理计算量逐字框换算 可视化绘制对整体推理耗时影响很小但建议生产环境按需开启中文单字框为近似结果中文没有空格分词单字框基于平均字宽近似估计在字体宽度差异较大的场景可能存在 ±半个字宽的偏差这是当前实现的固有特性见cal_ocr_word_box源码。九、总结return_word_box是 PP-Structure 文档恢复管线中从内容识别走向结构化输出的关键开关。开启后识别结果从一行一个框升级为一行一框 行内逐词/逐字小框配合版面分析、表格识别与恢复模块即可把一张图片/PDF 还原为带精确空间坐标的分层结构化数据——既可直接生成可编辑的 docx/markdown也可作为 LLM/RAG 系统的带位置索引输入。相关延伸可继续阅读仓库内的 PP-Structure 总览、快速开始 以及 恢复为 Word/Markdown 文档。【免费下载链接】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），仅供参考
