用途与实际影响
这项功能怎样使用
为什么需要它
采购表、双栏文档和公式页容易被普通提字打散。这个模块把结构作为明确结果需求：模型负责还原可见关系，原图负责最终复核，不把一段流畅文本当作表格已经准确恢复。
举个实际例子
我可以说：“把采购订单的商品、型号、数量、单价和金额按行列保留下来。”系统会检查列数、商品与数字对应关系和合计；识别出来的数字仍要回到原图核对，不能直接当成正确业务金额。
最后我会得到什么
拿到可阅读的表格、公式和页面位置，也有供程序处理的结构化文件；商品与金额关系可回原页核对。它不直接生成 Excel，也不能凭识别到印章就判断真假。
正常时
结构与文字一起返回，可以按页和区域核对。
发现问题时
行列、阅读顺序、公式或坐标有误时保留原始输出并回原图检查，不静默改写。
入口不可用或证据不足时
结构模型或输入不支持时返回明确失败；普通提字的结果不能冒充结构解析成功。
从哪里开始
在 LocalOCR 请求中明确说“保留表格行列、公式或区域”，并指定原件。
需要准备什么
- 有结构的图片或扫描 PDF
- 需保留的列、公式、印章区域或页码
从开始到拿到结果
- 1
识别哪些关系不能丢
系统从页面找出表头、行列、公式和区域，再选择能保留这些关系的识别路线。
- 2
逐页还原可见关系
系统按实际模型解析页面，保存表格块、文字行、顺序和位置。
- 3
回到原页核对
取得可读和结构文件后核对关键单元格；不把整齐排版当金额正确，也不宣称生成 Excel。
技术实现与依据
这里保留实现、关键条件、精确入口、历史记录和验证结果。
结构字段与解析路线已实现关键规则与设计选择
表格和版面必须明确提出，auto 不自动进入 structure（结构化版面）。
PDF 坐标属于实际渲染像素，按对应页的比例与尺寸核对；做过非线性矫正时不能伪称可以直接映射原图。
图表识别当前关闭；印章区域识别不证明印章真伪。
本模块用到的名词
- table HTML（表格结构标记）
- 保存行列关系的模型输出，可供后续转换；格式存在不代表单元格内容正确。
- reading order（阅读顺序）
- 文档块应按什么顺序阅读；多栏和复杂布局下仍需核对。
- rendered pixels（渲染像素）
- PDF 被转成图片后的坐标单位，与原 PDF 的点坐标不同。
专业定义
提取文字之外，还要保留表格行列、阅读顺序、公式和原图位置。
解决什么
防止表格行列被拼成无关系的文本、公式信息被过度简化，以及把不同坐标空间混用导致复核指错区域。
当前怎样实现
- pp-structure-v3 profile 使用 PP-StructureV3 + PP-OCRv5；当前 PaddleOCR 结构接口不能把普通 OCRv6 配置直接套入该路线。
- use_table_recognition、use_formula_recognition、use_seal_recognition、use_region_detection 与 format_block_content 已开启，use_chart_recognition=false。
- engines/structure.py 保留版面、表格 HTML、公式、印章、区域和原始 OCR（光学字符识别） 行，避免只保留展示文本而丢掉独立位置证据。
- engines/vl.py 为复杂 PDF 提供视觉语言解析；VL 与显式 Structure（结构化版面） 是不同选择，不用一个模型名称覆盖所有文档场景。
- 正常 iter_input_pages 采用 216 DPI 和 24M 像素上限逐页渲染并删除上一临时页，独立 input_page_count 验 PDF 页/TIFF 帧；旧显式物化函数默认 scale=2.0，不能当当前所有结果的固定比例。
- 普通 OCR（光学字符识别） 对平面截图默认关闭文档形变矫正；VL 与 Structure（结构化版面） 的文档配置仍开启，复核时应核对实际坐标所属图像空间。
- 保留的 9 月 3 日采购表 figure_title 因 figure 标签进入 excluded_regions，Markdown 漏标题且 text_lines 把 PO 读成 P0；当前标签过滤代码仍有该条件，新的表格合成测试没有证明这张旧图已修复。
执行流程
- 1
说明需要表格、公式、印章区域或复杂版面，而不只说提字。
- 2
选择 VL 或显式 Structure（结构化版面），核对实际 profile。
- 3
PDF 逐页渲染，图片按其对应输入空间处理。
- 4
保留结构块、原始文字行、顺序与位置，生成可读和结构化输出。
- 5
按原页核对行列、公式、边界与坐标，不以表格看着整齐代替正确性。
边界
- 只有输出中实际存在的结构才可宣称提取成功，不能从模型能力标签猜结果。
- 不保证恢复任意复杂表格，也不代替公式推导或印章鉴真。
- 没有直接生成 Word、Excel 或可搜索 PDF 的现行导出入口。
失败与恢复
- 表格合并或阅读顺序错误
- 保留原始结构与文字行，按原图校对；下游转换不得掩盖不确定性。
- 框的位置对不上 PDF
- 先核对页码、render_scale、渲染尺寸和矫正空间，不直接把像素框作为 PDF 点坐标。
- 模型未加载或结构解析失败
- 保留明确错误；若另选普通提字，应注明能力降级和本次实际输出。
真实入口
E:\Projects\Tools\LocalOCR\localocr\engines\structure.py结构与原始文字保留
E:\Projects\Tools\LocalOCR\localocr\engines\vl.py复杂文档路线
E:\Projects\Tools\LocalOCR\localocr\pdf_utils.py页面渲染与坐标
E:\Projects\Tools\LocalOCR\localocr\model_profiles.json实际结构选项
E:\Projects\Tools\LocalOCR\tests\test_structure.py结构字段回归
如何验证
- 源码与配置已核对表格、公式、印章、区域开启而图表关闭的实际状态。
- test_structure.py 与相关输出测试验证字段、文字行和坐标保留，不代表真实模型对任意文档准确。
- 9 月 3 日采购表保留六列五条商品和合计，却漏标题并有 PO/P0 错字；9 月 17 日结构表格的九个单元格及自动表格案例通过，两个不同样例不能相互改写结果。
与其他模块的关系
输入路线决定何时选择结构解析；本模块拥有结构含义，结果模块拥有输出身份与质量解释，后续文档排版由独立工具完成。