Legacy Structured Content 结构盘点¶
状态: Legacy 读者: Structured Content schema 设计者、render 开发者、backend 开发者、编程 Agent 范围: 记录已删除的 PageInfo Structured Content converter,供理解历史 backend 差异 非目标: 定义最终 Structured Content schema;重写 render 实现
1. 定位¶
本文记录的是严格 MiddleJson render 公共面落地前的 legacy list[list[dict]] 实现。
当前 mineru.render.structured_content 是严格 MiddleJson 到文档级 dict 的公共 renderer,
其现行契约以 Rendering Contract 为准。下文中的“当前”均指 legacy 实现被删除前的历史快照。
需要说明的是:本文的 Legacy 定位只针对“文档级 structured_content”这一输出面;
本文盘点所用的 ContentTypeV2 item 类型词汇(paragraph/title/image/table/list/equation_interline 等,
mineru/types.py)仍是现行 Content List V2 renderer(RenderFormat.CONTENT_LIST_V2)输出的类型词汇,
并非整体废弃。
本文只回答:
- 当前
structured_content从哪里生成。 - 顶层结构是什么。
- 每类 item 当前有哪些字段。
- Pipeline、VLM/Hybrid、Office 之间有哪些差异。
- 哪些现状不应直接固化进 Structured Content schema。
2. 生成路径¶
历史统一入口:
Legacy ParseResult.structured_content()
-> legacy render_structured_content(pages, img_bucket_path="")
-> 根据 PageInfo._backend 分发
-> PDF pipeline/vlm/hybrid: 已删除的 backend converter
-> office: render/office/output.py
当前调用点:
| 调用点 | 当前产物名 |
|---|---|
ParseResult.save() |
{prefix}_structured_content.json |
| 旧 CLI dump | {pdf_file_name}_structured_content.json |
| client-side output regeneration | {doc_stem}_structured_content.json |
| 当前 parse API server | output_files.structured_content |
这些是实现现状。NEXT 版公开 API / CLI / SDK 统一使用 structured_content / structured-content。
3. 顶层结构¶
Legacy render_structured_content() 返回:
含义:
[
[
{"type": "title", "content": {}},
{"type": "paragraph", "content": {}}
],
[
{"type": "table", "content": {}}
]
]
规则:
| 层级 | 含义 |
|---|---|
| 外层 list | 文档页序列。 |
| 内层 list | 当前页的内容 item 序列。 |
| item | 一个 block render 后的结构化内容。 |
当前缺失:
- 没有顶层 envelope。
- 没有
schema_version。 - 没有显式
pages字段。 - 每页没有
page_idx/page_size/page_number。 - item 默认没有
page_idx;页号只能从外层数组位置推断。 - 没有稳定
locator。
4. Item 通用形态¶
大多数 item 形态:
通用字段:
| 字段 | 类型 | 当前来源 | 说明 |
|---|---|---|---|
type |
string | ContentTypeV2 |
item 类型。 |
content |
object | backend converter | 每类 item 的主体字段不同。 |
bbox |
array[int, int, int, int] | PDF backend | 可选。Pipeline/VLM/Hybrid 通常有,Office 通常没有。 |
sub_type |
string | 部分视觉块 | 可选。主要来自 image/chart/code 等 block 的 sub_type。 |
anchor |
string | Office | 可选。主要来自 DOCX 标题、目录或列表项。 |
4.1 BBox¶
当前 PDF backend 的 structured_content item bbox 是归一化到 0-1000 的整数框:
现状问题:
- Pipeline/VLM/Hybrid 会输出 item 级 bbox。
- Office 通常不输出 bbox。
- structured_content converter 没有统一过滤
EMPTY_BBOX;如果 source bbox 是(0, 0, 0, 0),当前可能输出[0, 0, 0, 0]。 - Pipeline helper 返回 tuple,VLM 直接返回 list;JSON 序列化后都会变成 array。
- bbox 只在 item 级别出现;PDF span 通常没有 bbox,Office span 可能因为
asdict(span)携带 bbox。
Structured Content 需要重新定义 unknown bbox,不应把 [0, 0, 0, 0] 误当成真实框。
5. Type 集合¶
当前 ContentTypeV2 定义了以下类型:
| 类别 | 值 |
|---|---|
| 代码与算法 | code, algorithm |
| 公式 | equation_interline, equation_inline |
| 视觉内容 | image, table, chart |
| 表格细分 | simple_table, complex_table |
| 列表 | list, text_list, reference_list, index |
| 文本结构 | title, paragraph |
| span | text, phonetic, md, code_inline |
| 页边内容 | page_header, page_footer, page_number, page_aside_text |
| 页面脚注 | page_footnote(语义上独立于低价值页边内容) |
当前实现并没有使用全部类型:
md和code_inline当前没有在主要 structured_content converter 中稳定产出。hyperlink可能从 Office raw span 中出现,但它不在ContentTypeV2中。index由 Pipeline 和 Office 输出;VLM converter 当前没有显式index分支。
6. Span 结构¶
6.1 PDF backend span¶
Pipeline、VLM、Hybrid 的文本类 content 通常由简化 span 组成:
[
{"type": "text", "content": "hello"},
{"type": "equation_inline", "content": "x+y"},
{"type": "phonetic", "content": "..."}
]
当前支持:
| span type | 含义 |
|---|---|
text |
普通文本。 |
equation_inline |
行内公式。 |
phonetic |
VLM phonetic / phonetic block 的文本。 |
PDF backend 会合并相邻同类 text span,并做换行、连字符和 CJK 空格处理。
6.2 Office span¶
Office structured_content 直接使用 asdict(span) 输出 span,因此字段更接近 Middle JSON 的 Span:
{
"type": "text",
"bbox": [0, 0, 0, 0],
"content": "hello",
"score": 0,
"image_path": "",
"image_base64": "",
"html": "",
"latex": "",
"_cross_page": false,
"_np_img": null,
"_url": "",
"_style": ["bold"],
"_children": [],
"_extra": {}
}
Office inline equation 会把 type 从 inline_equation 改成 equation_inline。
Office hyperlink 可能输出:
{
"type": "hyperlink",
"content": "link text",
"_url": "https://example.com",
"_style": ["underline"],
"_children": []
}
现状问题:
- Office span 会泄漏
_url、_style、_children、_extra等内部字段。 - Office span 的
bbox通常是 unknown。 - Office span 比 PDF span 重得多,和 PDF span 结构不一致。
7. Item 类型结构¶
7.1 Paragraph¶
当前输出:
来源:
| Backend | block type |
|---|---|
| Pipeline | text, abstract |
| VLM/Hybrid | text, phonetic |
| Office | text |
差异:
- VLM
phoneticblock 会输出paragraphitem,但内部 span type 可能是phonetic。 - Pipeline
abstract被归入paragraph。 - Office paragraph content 使用 raw Office span。
7.2 Title¶
当前输出:
规则:
- 如果 title level 为 0,Pipeline/VLM/Office 都可能降级输出为
paragraph。 - Office title 可能有顶层
anchor。 - Office title 可能在
title_content前插入自动section_number文本 span。
7.3 Page Header / Footer / Number / Aside / Footnote¶
当前输出:
动态 content key:
| item type | content key |
|---|---|
page_header |
page_header_content |
page_footer |
page_footer_content |
page_number |
page_number_content |
page_aside_text |
page_aside_text_content |
page_footnote |
page_footnote_content |
差异:
- Pipeline/VLM 支持
page_header、page_footer、page_number、page_aside_text、page_footnote。 - Office 支持
page_header、page_footer、page_footnote,没有显式page_number/page_aside_text分支。
7.4 Interline Equation¶
Pipeline/VLM 输出:
{
"type": "equation_interline",
"content": {
"math_content": "E = mc^2",
"math_type": "latex",
"image_source": {"path": "images/eq_0.jpg"}
},
"bbox": [100, 200, 900, 260]
}
Office 输出:
差异:
- PDF backend 带
image_source。 - Office 不带
image_source。
7.5 Image¶
当前输出:
{
"type": "image",
"content": {
"image_source": {"path": "images/img_0.jpg"},
"content": "optional image description",
"image_caption": [],
"image_footnote": []
},
"sub_type": "optional",
"bbox": [100, 100, 900, 600]
}
差异:
| Backend | 字段差异 |
|---|---|
| Pipeline | content 仅在 image content 或 sub_type 存在时写入;支持 image_footnote;可写 sub_type。 |
| VLM/Hybrid | 总是写 content,空则为 "";支持 image_footnote;可写 sub_type。 |
| Office | 写 image_source 和 image_caption;通常不写 content / image_footnote / sub_type。 |
7.6 Table¶
当前输出:
{
"type": "table",
"content": {
"image_source": {"path": "images/table_0.jpg"},
"table_caption": [],
"table_footnote": [],
"html": "<table>...</table>",
"table_type": "simple_table",
"table_nest_level": 1
},
"bbox": [100, 100, 900, 600]
}
table_type:
| 值 | 当前判定 |
|---|---|
simple_table |
HTML 中没有 colspan / rowspan,且嵌套 table 数量不超过 1。 |
complex_table |
HTML 中有 colspan / rowspan,或嵌套 table 数量大于 1。 |
差异:
- Pipeline/VLM 带
image_source和table_footnote。 - Office 不带
image_source/table_footnote,但会格式化表格 HTML 中的图片路径和<eq>标签。
7.7 Chart¶
当前输出:
{
"type": "chart",
"content": {
"image_source": {"path": "images/chart_0.jpg"},
"content": "",
"chart_caption": [],
"chart_footnote": []
},
"sub_type": "optional",
"bbox": [100, 100, 900, 600]
}
差异:
| Backend | 字段差异 |
|---|---|
| Pipeline | content 固定为空字符串;支持 chart_caption / chart_footnote。 |
| VLM/Hybrid | content 使用 chart body content;支持 chart_caption / chart_footnote;可写 sub_type。 |
| Office | content 是格式化后的 chart HTML / 文本;支持 chart_caption;通常不写 chart_footnote。 |
7.8 Code¶
Pipeline/VLM 输出:
{
"type": "code",
"content": {
"code_caption": [],
"code_content": [],
"code_footnote": [],
"code_language": "python"
},
"bbox": [100, 100, 900, 600]
}
差异:
- Pipeline 支持
code_footnote。 - VLM/Hybrid 当前不写
code_footnote。 - Office 当前没有
code分支。
7.9 Algorithm¶
Pipeline/VLM 输出:
{
"type": "algorithm",
"content": {
"algorithm_caption": [],
"algorithm_content": [],
"algorithm_footnote": []
},
"bbox": [100, 100, 900, 600]
}
差异:
- Pipeline 支持
algorithm_footnote。 - VLM/Hybrid 当前不写
algorithm_footnote。 - Office 当前没有
algorithm分支。
7.10 List¶
普通列表当前输出:
{
"type": "list",
"content": {
"list_type": "text_list",
"attribute": "unordered",
"list_items": [
{
"item_type": "text",
"item_content": []
}
]
},
"bbox": [100, 100, 900, 600]
}
引用列表当前输出:
{
"type": "list",
"content": {
"list_type": "reference_list",
"list_items": [
{
"item_type": "text",
"item_content": []
}
]
}
}
差异:
| Backend | 字段差异 |
|---|---|
| Pipeline | 普通 list 有 attribute,ref_text 会输出 list_type=reference_list。 |
| VLM/Hybrid | 普通 list 通常没有 attribute;sub_type=ref_text 时输出 reference_list。 |
| Office | 普通 list 有 attribute;每个 item 额外有 ilevel、prefix,可能有 anchor。 |
Office list item:
7.11 Index¶
Pipeline/Office 输出:
{
"type": "index",
"content": {
"list_type": "text_list",
"list_items": [
{
"item_type": "text",
"item_content": []
}
]
}
}
差异:
- Pipeline index item 和 list item 形态接近。
- Office index item 复用
_flatten_structured_list_items(),因此可能带ilevel、prefix、anchor。 - VLM converter 当前没有显式
index分支。
8. Backend 差异汇总¶
| 维度 | Pipeline | VLM / Hybrid | Office |
|---|---|---|---|
| 顶层 | 按页二维数组 | 按页二维数组 | 按页二维数组 |
| item bbox | 有,0-1000 | 有,0-1000 | 通常无 |
| span 形态 | 简化 span | 简化 span | raw Span asdict |
paragraph |
text / abstract | text / phonetic | text |
page_number |
支持 | 支持 | 不支持 |
page_aside_text |
支持 | 支持 | 不支持 |
code / algorithm |
支持 | 支持 | 不支持 |
index |
支持 | 无显式分支 | 支持 |
| table footnote | 支持 | 支持 | 不支持 |
| chart footnote | 支持 | 支持 | 不支持 |
| code footnote | 支持 | 不支持 | 不支持 |
top-level anchor |
不常见 | 不常见 | 支持 |
list item prefix / ilevel |
不支持 | 不支持 | 支持 |
9. 当前结构的直接风险¶
这些现状不建议直接固化为 Structured Content schema:
- 顶层是裸二维数组,缺少 version、metadata 和显式 page 对象。
- 页号依赖外层数组下标,缺少稳定
page_idx。 - item 缺少稳定
id/locator。 - Office span 泄漏内部字段,且和 PDF span 结构不一致。
bbox=[0,0,0,0]可能表示 unknown,而不是真实区域。- 同一语义在不同 backend 下字段不一致,例如 table/image/chart footnote、code footnote、list attribute。
- media path 拼接规则不统一,空 path 可能产生不理想路径。
- VLM converter 对未显式支持的 block type 没有统一返回
None的规则。
10. 作为 Structured Content 起点的建议¶
后续设计 Structured Content schema 时,可以保留这些方向:
- 以 page 为组织单位。
- 以 item 表达标题、段落、列表、公式、图片、表格、图表、代码、页边内容。
content内继续按类型保存语义字段。- 文本内容使用 span list,而不是直接拼成字符串。
table_type、table_nest_level、image_source、caption / footnote 的语义可以继续保留。
需要重新定义这些部分:
- 顶层 envelope。
- page object。
- item id / locator。
- span schema。
- unknown bbox。
- media source。
- backend 差异的 normalization 规则。
本页原文 Markdown:在 AtomGit 查看·内容源自开源项目 mi/MinerU