Skip to content

Transforms complex documents like PDFs and Office docs into LLM-ready markdown/JSON for your Agentic workflows.

Own Content List renderers and extended render contracts in MinerU

myhloli6392f7233bb2
diff --git a/CLAUDE.md b/CLAUDE.md
index 3e1a84af..07610bc3 100644
--- a/CLAUDE.md
+++ b/CLAUDE.md
@@ -152,7 +152,7 @@ class MinerUParser(DocumentParser):
### 1. 唯一实现归属
-`docvortex` 独立拥有原生文档解析、PDF 基础访问与分类、公共文档类型、确定性后处理、素材、九种渲染格式和导出实现,不得反向依赖 MinerU。
+`docvortex` 独立拥有原生文档解析、PDF 基础访问与分类、公共文档类型、确定性后处理、素材、七种通用渲染格式和导出实现,不得反向依赖 MinerU。
MinerU 保留 OCR/VLM/Hybrid 推理、模型生命周期、LLM 增强、tier 策略、CLI/API/Gradio/Doclib。通过 DocVortex 公开接口复用能力,不导入其私有实现。
@@ -181,7 +181,7 @@ ModelJson 仍保存 raw pages 与 page_index_map;MiddleJson 仍保存有序 Pa
DocVortex 的确定性后处理独立构造有效 MiddleJson。`mineru.backend.postprocess.document` 在其后显式执行 MinerU 的可选 LLM 增强。
-`mineru.render` 是稳定兼容门面,底层 renderer、RenderPlan、选项类型与错误类型均来自 DocVortex。公式定界符等宿主配置显式传入,不让 DocVortex 读取 MinerU 配置。
+`mineru.render` 保留九种输出:Content List V1/V2 实现及专用选项归属 MinerU,其余七种 renderer 和通用选项来自 DocVortex。两边各自定义 RenderFormat,RenderMode 与共享文档类型仍复用。Content List 通过 `docvortex.render.fragments` 调用共享片段能力,不导入私有实现。公式定界符等宿主配置显式传入,不让 DocVortex 读取 MinerU 配置。
九种输出为 Markdown、HTML、LaTeX、DOCX、EPUB、PDF、Structured Content、Content List V1/V2。LaTeX/EPUB/PDF/Content List 的低层能力不自动扩展所有产品入口。PDF 输出继续采用语义重排版。
diff --git a/docs/content-list-ownership-validation.md b/docs/content-list-ownership-validation.md
new file mode 100644
index 00000000..d3fe2d72
--- /dev/null
+++ b/docs/content-list-ownership-validation.md
@@ -0,0 +1,28 @@
+# Content List 归属迁移验证
+
+Content List V1/V2 的实现及专用公共逻辑已迁入
+`mineru.render._internal.content_list`。公共函数签名、宿主配置读取方式和列表输出
+保持不变。`ContentType`、`ContentTypeV2` 由 `mineru.types` 定义。
+
+MinerU 独立定义九种目标的 `RenderFormat` 与专用选项。通用选项、`RenderMode`、
+素材接口和文档类型继续共享 DocVortex;DocVortex 自身只提供七种目标。
+迁入代码通过 `docvortex.render.fragments` 使用公共能力,没有导入引擎私有模块。
+
+迁移前冻结全类型夹具、中文论文3和中文论文4的 V1/V2 输出,共六份规范化 JSON。
+迁移后通过 MinerU 公共函数输出,与冻结文件逐字节一致,源文档树保持不变。
+原 Content List 单测继续保留,并迁入两项公式分隔符测试、增加独立契约归属检查。
+
+本地完整回归:**3957 passed、4 skipped、4 deselected**。四项历史排除不变:
+
+- `test_doclib_app_startup.py::test_basic_extra_includes_preflight_runtime_dependencies`
+- `test_doclib_app_startup.py::test_standard_is_the_highest_model_runtime_extra`
+- `test_legacy_schema_adapter.py::test_doclib_compaction_rejects_unknown_legacy_schema`
+- `test_mfr_latex_utils.py::test_pp_formulanet_fix_latex_uses_shared_mathring_repair`
+
+DocVortex 本地完整回归 416 项通过,独立 Python 3.14 wheel 验证 45 项通过;
+[三平台 CI](https://github.com/myhloli/DocVortex/actions/runs/34047782292) 已通过。
+既有少线表金标差异仍为单独诊断项,不计入本次修复。
+
+仓库显示名为 `myhloli/DocVortex`,包、CLI 和本地目录仍为小写 `docvortex`。
+只清理 DocVortex 指定版权头,MinerU 继续遵守原有文件头约定;其他许可证与归属保留。
+更新 0.1.0 wheel/sdist 与现有发行草稿,本次不发布到 PyPI。
diff --git a/mineru/render/_internal/__init__.py b/mineru/render/_internal/__init__.py
new file mode 100644
index 00000000..1e8af959
--- /dev/null
+++ b/mineru/render/_internal/__init__.py
@@ -0,0 +1,4 @@
+# Copyright (c) Opendatalab. All rights reserved.
+"""MinerU 产品专用 renderer 的内部实现。"""
+
+__all__: list[str] = []
diff --git a/mineru/render/_internal/content_list/__init__.py b/mineru/render/_internal/content_list/__init__.py
new file mode 100644
index 00000000..d51738a4
--- /dev/null
+++ b/mineru/render/_internal/content_list/__init__.py
@@ -0,0 +1,4 @@
+# Copyright (c) Opendatalab. All rights reserved.
+"""Content List V1/V2 私有渲染实现。"""
+
+__all__: list[str] = []
diff --git a/mineru/render/_internal/content_list/common.py b/mineru/render/_internal/content_list/common.py
new file mode 100644
index 00000000..cc9b074e
--- /dev/null
+++ b/mineru/render/_internal/content_list/common.py
@@ -0,0 +1,298 @@
+# Copyright (c) Opendatalab. All rights reserved.
+"""Content List V1/V2 共用的严格 MiddleJson 投影能力。"""
+
+from __future__ import annotations
+
+import re
+from collections.abc import Iterator
+from dataclasses import dataclass
+from typing import TypeAlias
+
+from docvortex.content.inline import inline_plain_text
+from docvortex.options import LatexDelimitersConfig
+from ....types import (
+ BBox,
+ AlgorithmBodyBlock,
+ ChartAnnotationBlock,
+ ChartBlock,
+ ChartBodyBlock,
+ CodeAnnotationBlock,
+ CodeBlock,
+ CodeBodyBlock,
+ CodeInlineSpan,
+ DocTitleBlock,
+ EquationInlineSpan,
+ HyperlinkSpan,
+ ImageAnnotationBlock,
+ ImageBlock,
+ ImageBodyBlock,
+ ImagePayloadBlock,
+ IndexBlock,
+ InlineSpan,
+ ListBlock,
+ PageBlock,
+ ParagraphTitleBlock,
+ RefTextBlock,
+ TableAnnotationBlock,
+ TableBlock,
+ TableBodyBlock,
+ TextBlock,
+ TextSpan,
+)
+from docvortex.render.fragments import strip_index_page_tail
+from docvortex.render.fragments import parse_list_item_marker
+from docvortex.render.fragments import normalize_image_source, resolve_image_source
+from docvortex.render.fragments import render_inline_content
+from docvortex.render.fragments import format_embedded_html
+
+VisualBlock: TypeAlias = ImageBlock | TableBlock | ChartBlock | CodeBlock
+VisualBodyBlock: TypeAlias = ImageBodyBlock | TableBodyBlock | ChartBodyBlock | CodeBodyBlock | AlgorithmBodyBlock
+VisualAnnotationBlock: TypeAlias = ImageAnnotationBlock | TableAnnotationBlock | ChartAnnotationBlock | CodeAnnotationBlock
+ListLeafBlock: TypeAlias = TextBlock | RefTextBlock
+IndexLeafBlock: TypeAlias = TextBlock | DocTitleBlock | ParagraphTitleBlock
+
+
+@dataclass(frozen=True, slots=True)
+class ReferenceGroup:
+ """保存同页连续参考文献块,供两个兼容 renderer 统一输出列表。"""
+
+ blocks: tuple[RefTextBlock, ...]
+
+
+@dataclass(frozen=True, slots=True)
+class ListLeaf:
+ """保存递归列表叶子及其相对深度。"""
+
+ block: ListLeafBlock
+ depth: int
+
+
+@dataclass(frozen=True, slots=True)
+class IndexLeaf:
+ """保存递归目录叶子及其相对深度。"""
+
+ block: IndexLeafBlock
+ depth: int
+
+
+PageRenderUnit: TypeAlias = PageBlock | ReferenceGroup
+
+
+def iter_page_units(blocks: list[PageBlock]) -> Iterator[PageRenderUnit]:
+ """保持阅读顺序遍历页面,并把连续 ref_text 合并为一个渲染单元。"""
+ reference_blocks: list[RefTextBlock] = []
+
+ def flush_references() -> Iterator[ReferenceGroup]:
+ """输出并清空当前参考文献分组。"""
+ nonlocal reference_blocks
+ if not reference_blocks:
+ return iter(())
+ group = ReferenceGroup(tuple(reference_blocks))
+ reference_blocks = []
+ return iter((group,))
+
+ for block in blocks:
+ if isinstance(block, RefTextBlock):
+ reference_blocks.append(block)
+ continue
+ yield from flush_references()
+ yield block
+ yield from flush_references()
+
+
+def unit_bbox(unit: PageRenderUnit) -> BBox | None:
+ """返回普通块 bbox,或计算参考文献分组的最小包围盒。"""
+ if not isinstance(unit, ReferenceGroup):
+ return unit.bbox
+ bboxes = [block.bbox for block in unit.blocks if block.bbox is not None]
+ if not bboxes:
+ return None
+ return (
+ min(bbox[0] for bbox in bboxes),
+ min(bbox[1] for bbox in bboxes),
+ max(bbox[2] for bbox in bboxes),
+ max(bbox[3] for bbox in bboxes),
+ )
+
+
+def normalize_bbox(bbox: BBox | None) -> list[int] | None:
+ """把 MiddleJson 的 0-1 bbox 转换为 Content List 的 0-1000 整数框。"""
+ if bbox is None:
+ return None
+ return [int(value * 1000) for value in bbox]
+
+
+def resolve_legacy_image_source(block: ImagePayloadBlock, asset_base_url: str) -> str:
+ """按统一图片优先级解析并规范化旧 Content List 资源字段。"""
+ source = resolve_image_source(block, asset_base_url)
+ return normalize_image_source(source) if source else ""
+
+
+def visual_body(block: VisualBlock) -> VisualBodyBlock:
+ """返回严格视觉父块中的唯一 body。"""
+ for child in block.content:
+ if isinstance(child, (ImageBodyBlock, TableBodyBlock, ChartBodyBlock, CodeBodyBlock, AlgorithmBodyBlock)):
+ return child
+ raise ValueError(f"Missing visual body: {block.type}")
+
+
+def sorted_annotations(block: VisualBlock, accepted_types: set[str]) -> list[VisualAnnotationBlock]:
+ """按 index 优先、原位置兜底的顺序返回指定视觉说明。"""
+ annotations: list[tuple[int, VisualAnnotationBlock]] = []
+ for position, child in enumerate(block.content):
+ if isinstance(child, (ImageAnnotationBlock, TableAnnotationBlock, ChartAnnotationBlock, CodeAnnotationBlock)):
+ if str(child.type) in accepted_types:
+ annotations.append((position, child))
+ annotations.sort(
+ key=lambda item: (
+ item[1].index is None,
+ item[1].index if item[1].index is not None else 0,
+ item[0],
+ )
+ )
+ return [child for _, child in annotations]
+
+
+def render_annotation_texts(
+ block: VisualBlock,
+ accepted_types: set[str],
+ delimiters: LatexDelimitersConfig,
+) -> list[str]:
+ """把一组视觉说明渲染为 V1 使用的 Markdown 字符串数组。"""
+ return [render_inline_content(child.content, delimiters) for child in sorted_annotations(block, accepted_types)]
+
+
+def render_annotation_spans(block: VisualBlock, accepted_types: set[str]) -> list[dict[str, object]]:
+ """把一组视觉说明按顺序展平为 V2 span 数组。"""
+ spans: list[dict[str, object]] = []
+ for child in sorted_annotations(block, accepted_types):
+ spans.extend(serialize_v2_spans(child.content))
+ return spans
+
+
+def render_embedded_content(
+ content: str,
+ *,
+ asset_base_url: str,
+ delimiters: LatexDelimitersConfig,
+) -> str:
+ """保留视觉结构内容,只重写相对图片地址和安全行内公式标签。"""
+ if not content:
+ return ""
+ return format_embedded_html(
+ content,
+ asset_base_url=asset_base_url,
+ delimiters=delimiters,
+ ).strip()
+
+
+def serialize_v2_spans(content: list[InlineSpan]) -> list[dict[str, object]]:
+ """把严格 InlineSpan 转换为统一的 3.4.5 风格 V2 span。"""
+ return [_serialize_v2_span(span) for span in content]
+
+
+def _serialize_v2_span(span: InlineSpan) -> dict[str, object]:
+ """序列化单个 V2 span,并显式收敛链接 children 与样式字段。"""
+ if isinstance(span, TextSpan):
+ payload: dict[str, object] = {"type": "text", "content": span.content}
+ if span.styles:
+ payload["style"] = list(span.styles)
+ return payload
+ if isinstance(span, EquationInlineSpan):
+ return {"type": "equation_inline", "content": span.content.strip()}
+ if isinstance(span, CodeInlineSpan):
+ return {"type": "code_inline", "content": span.content}
+ if isinstance(span, HyperlinkSpan):
+ children = [_serialize_v2_span(child) for child in span.content]
+ payload = {
+ "type": "hyperlink",
+ "content": inline_plain_text(span.content),
+ "url": span.url,
+ }
+ if len(children) == 1 and children[0]["type"] == "text":
+ if style := children[0].get("style"):
+ payload["style"] = style
+ else:
+ payload["children"] = children
+ return payload
+ raise TypeError(f"Unsupported InlineSpan type: {type(span).__name__}")
+
+
+def string_as_v2_spans(content: str) -> list[dict[str, object]]:
+ """把代码字符串包装为 V2 文本 span,空字符串保持为空数组。"""
+ if not content:
+ return []
+ return [{"type": "text", "content": content}]
+
+
+def flatten_list_leaves(block: ListBlock, depth: int = 0) -> list[ListLeaf]:
+ """按源顺序递归展平列表叶子。"""
+ leaves: list[ListLeaf] = []
+ for child in block.content:
+ if isinstance(child, ListBlock):
+ leaves.extend(flatten_list_leaves(child, depth + 1))
+ else:
+ leaves.append(ListLeaf(block=child, depth=depth))
+ return leaves
+
+
+def infer_list_attribute(block: ListBlock) -> str:
+ """根据最浅层有效条目的 marker 推断 ordered/unordered。"""
+ leaves = flatten_list_leaves(block)
+ if not leaves:
+ return "unordered"
+ minimum_depth = min(leaf.depth for leaf in leaves)
+ kinds = [
+ parse_list_item_marker(leaf.block.content).kind
+ for leaf in leaves
+ if leaf.depth == minimum_depth and inline_plain_text(leaf.block.content).strip()
+ ]
+ return "ordered" if kinds and all(kind == "ordered" for kind in kinds) else "unordered"
+
+
+def flatten_index_leaves(block: IndexBlock, depth: int = 0) -> list[IndexLeaf]:
+ """按源顺序递归展平目录叶子。"""
+ leaves: list[IndexLeaf] = []
+ for child in block.content:
+ if isinstance(child, IndexBlock):
+ leaves.extend(flatten_index_leaves(child, depth + 1))
+ else:
+ leaves.append(IndexLeaf(block=child, depth=depth))
+ return leaves
+
+
+def normalized_index_content(block: IndexLeafBlock) -> list[InlineSpan]:
+ """删除目录叶子可信页码尾缀,并保留其余行内语义。"""
+ return strip_index_page_tail(block.content)
+
+
+def classify_table(content: str) -> tuple[str, int]:
+ """按 rowspan、colspan 和嵌套 table 判断 V2 表格类型。"""
+ table_count = len(re.findall(r"<table\b", content, flags=re.IGNORECASE))
+ table_nest_level = 2 if table_count > 1 else 1
+ complex_table = table_nest_level > 1 or re.search(r"\b(?:rowspan|colspan)\b", content, flags=re.IGNORECASE)
+ return ("complex_table" if complex_table else "simple_table", table_nest_level)
+
+
+__all__ = [
+ "IndexLeaf",
+ "ListLeaf",
+ "PageRenderUnit",
+ "ReferenceGroup",
+ "classify_table",
+ "flatten_index_leaves",
+ "flatten_list_leaves",
+ "infer_list_attribute",
+ "iter_page_units",
+ "normalize_bbox",
+ "normalized_index_content",
+ "render_annotation_spans",
+ "render_annotation_texts",
+ "render_embedded_content",
+ "resolve_legacy_image_source",
+ "serialize_v2_spans",
+ "sorted_annotations",
+ "string_as_v2_spans",
+ "unit_bbox",
+ "visual_body",
+]
diff --git a/mineru/render/_internal/content_list/v1.py b/mineru/render/_internal/content_list/v1.py
new file mode 100644
index 00000000..6fd85006
--- /dev/null
+++ b/mineru/render/_internal/content_list/v1.py
@@ -0,0 +1,256 @@
+# Copyright (c) Opendatalab. All rights reserved.
+"""严格 MiddleJson 到扁平 Content List V1 的渲染实现。"""
+
+from __future__ import annotations
+
+from typing import Any
+
+from docvortex.options import LatexDelimitersConfig
+from ....types import (
+ RAW_ALGORITHM,
+ AlgorithmBodyBlock,
+ BlockType,
+ ChartBlock,
+ CodeBlock,
+ CodeBodyBlock,
+ DocTitleBlock,
+ EquationBlock,
+ ImageBlock,
+ IndexBlock,
+ ListBlock,
+ MiddleJson,
+ PageAuxTextBlock,
+ PageFootnoteBlock,
+ ParagraphTitleBlock,
+ TableBlock,
+ TextBlock,
+)
+from docvortex.render.fragments import render_inline_content, render_internal_link
+from .common import (
+ PageRenderUnit,
+ ReferenceGroup,
+ flatten_index_leaves,
+ flatten_list_leaves,
+ iter_page_units,
+ normalize_bbox,
+ normalized_index_content,
+ render_annotation_texts,
+ render_embedded_content,
+ resolve_legacy_image_source,
+ unit_bbox,
+ visual_body,
+)
+
+_IMAGE_CAPTION_TYPES = {str(BlockType.IMAGE_CAPTION)}
+_IMAGE_FOOTNOTE_TYPES = {str(BlockType.IMAGE_FOOTNOTE)}
+_TABLE_CAPTION_TYPES = {str(BlockType.TABLE_CAPTION)}
+_TABLE_FOOTNOTE_TYPES = {str(BlockType.TABLE_FOOTNOTE)}
+_CHART_CAPTION_TYPES = {str(BlockType.CHART_CAPTION)}
+_CHART_FOOTNOTE_TYPES = {str(BlockType.CHART_FOOTNOTE)}
+_CODE_CAPTION_TYPES = {str(BlockType.CODE_CAPTION)}
+_CODE_FOOTNOTE_TYPES = {str(BlockType.CODE_FOOTNOTE)}
+
+
+def render_content_list(
+ middle_json: MiddleJson,
+ *,
+ asset_base_url: str = "",
+ latex_delimiters: LatexDelimitersConfig | None = None,
+) -> list[dict[str, Any]]:
+ """把严格 MiddleJson 无副作用地渲染为扁平 Content List V1。"""
+ if not isinstance(middle_json, MiddleJson):
+ raise TypeError("render_content_list expects a MiddleJson instance")
+ if not isinstance(asset_base_url, str):
+ raise TypeError("asset_base_url must be a string")
+
+ delimiters = latex_delimiters or LatexDelimitersConfig()
+ output: list[dict[str, Any]] = []
+ for page in middle_json.pages:
+ for unit in iter_page_units(page.blocks):
+ item = _render_unit(
+ unit,
+ page_idx=page.page_idx,
+ asset_base_url=asset_base_url,
+ delimiters=delimiters,
+ )
+ if item is not None:
+ output.append(item)
+ return output
+
+
+def _render_unit(
+ unit: PageRenderUnit,
+ *,
+ page_idx: int,
+ asset_base_url: str,
+ delimiters: LatexDelimitersConfig,
+) -> dict[str, Any] | None:
+ """把一个页面渲染单元转换为 V1 item,并补齐 bbox 与 page_idx。"""
+ item = _render_unit_content(unit, asset_base_url=asset_base_url, delimiters=delimiters)
+ if item is None:
+ return None
+ if bbox := normalize_bbox(unit_bbox(unit)):
+ item["bbox"] = bbox
+ item["page_idx"] = page_idx
+ return item
+
+
+def _render_unit_content(
+ unit: PageRenderUnit,
+ *,
+ asset_base_url: str,
+ delimiters: LatexDelimitersConfig,
+) -> dict[str, Any] | None:
+ """按严格 block 类型构造 V1 专有字段。"""
+ if isinstance(unit, ReferenceGroup):
+ return {
+ "type": "list",
+ "sub_type": "ref_text",
+ "list_items": [render_inline_content(block.content, delimiters) for block in unit.blocks if block.content],
+ }
+ if isinstance(unit, TextBlock):
+ item = {"type": "text", "text": render_inline_content(unit.content, delimiters)}
+ _add_anchor(item, unit.anchor)
+ return item
+ if isinstance(unit, (DocTitleBlock, ParagraphTitleBlock)):
+ item: dict[str, Any] = {
+ "type": "text",
+ "text": render_inline_content(unit.content, delimiters),
+ "text_level": unit.level,
+ }
+ _add_anchor(item, unit.anchor)
+ return item
+ if isinstance(unit, PageFootnoteBlock):
+ item = {"type": "page_footnote", "text": render_inline_content(unit.content, delimiters)}
+ _add_anchor(item, unit.anchor)
+ return item
+ if isinstance(unit, PageAuxTextBlock):
+ return {"type": str(unit.type), "text": render_inline_content(unit.content, delimiters)}
+ if isinstance(unit, EquationBlock):
+ item = {
+ "type": "equation",
+ "img_path": resolve_legacy_image_source(unit, asset_base_url),
+ }
+ if latex := unit.content.strip():
+ item["text"] = latex
+ item["text_format"] = "latex"
+ return item
+ if isinstance(unit, ListBlock):
+ return {
+ "type": "list",
+ "sub_type": str(unit.sub_type or BlockType.TEXT),
+ "list_items": [
+ render_inline_content(leaf.block.content, delimiters)
+ for leaf in flatten_list_leaves(unit)
+ if leaf.block.content
+ ],
+ }
+ if isinstance(unit, IndexBlock):
+ return {"type": "index", "list_items": _render_index_items(unit, delimiters)}
+ if isinstance(unit, ImageBlock):
+ return _render_image(unit, asset_base_url, delimiters)
+ if isinstance(unit, TableBlock):
+ return _render_table(unit, asset_base_url, delimiters)
+ if isinstance(unit, ChartBlock):
+ return _render_chart(unit, asset_base_url, delimiters)
+ if isinstance(unit, CodeBlock):
+ return _render_code(unit, delimiters)
+ return None
+
+
+def _render_index_items(block: IndexBlock, delimiters: LatexDelimitersConfig) -> list[str]:
+ """把递归目录叶子渲染为带缩进和可选内部链接的 V1 字符串。"""
+ items: list[str] = []
+ for leaf in flatten_index_leaves(block):
+ content = normalized_index_content(leaf.block)
+ label = render_inline_content(content, delimiters).strip()
+ if not label:
+ continue
+ if leaf.block.anchor:
+ label = render_internal_link(label, leaf.block.anchor)
+ items.append(f"{' ' * leaf.depth}- {label}")
+ return items
+
+
+def _render_image(
+ block: ImageBlock,
+ asset_base_url: str,
+ delimiters: LatexDelimitersConfig,
+) -> dict[str, Any]:
+ """构造 V1 图片 item。"""
+ body = visual_body(block)
+ item: dict[str, Any] = {
+ "type": "image",
+ "img_path": resolve_legacy_image_source(body, asset_base_url),
+ "image_caption": render_annotation_texts(block, _IMAGE_CAPTION_TYPES, delimiters),
+ "image_footnote": render_annotation_texts(block, _IMAGE_FOOTNOTE_TYPES, delimiters),
+ }
+ if content := render_embedded_content(body.content, asset_base_url=asset_base_url, delimiters=delimiters):
+ item["content"] = content
+ if block.sub_type:
+ item["sub_type"] = block.sub_type
+ return item
+
+
+def _render_table(
+ block: TableBlock,
+ asset_base_url: str,
+ delimiters: LatexDelimitersConfig,
+) -> dict[str, Any]:
+ """构造 V1 表格 item。"""
+ body = visual_body(block)
+ item: dict[str, Any] = {
+ "type": "table",
+ "img_path": resolve_legacy_image_source(body, asset_base_url),
+ "table_caption": render_annotation_texts(block, _TABLE_CAPTION_TYPES, delimiters),
+ "table_footnote": render_annotation_texts(block, _TABLE_FOOTNOTE_TYPES, delimiters),
+ }
+ if content := render_embedded_content(body.content, asset_base_url=asset_base_url, delimiters=delimiters):
+ item["table_body"] = content
+ return item
+
+
+def _render_chart(
+ block: ChartBlock,
+ asset_base_url: str,
+ delimiters: LatexDelimitersConfig,
+) -> dict[str, Any]:
+ """构造 V1 图表 item。"""
+ body = visual_body(block)
+ item: dict[str, Any] = {
+ "type": "chart",
+ "img_path": resolve_legacy_image_source(body, asset_base_url),
+ "content": render_embedded_content(body.content, asset_base_url=asset_base_url, delimiters=delimiters),
+ "chart_caption": render_annotation_texts(block, _CHART_CAPTION_TYPES, delimiters),
+ "chart_footnote": render_annotation_texts(block, _CHART_FOOTNOTE_TYPES, delimiters),
+ }
+ if block.sub_type:
+ item["sub_type"] = block.sub_type
+ return item
+
+
+def _render_code(block: CodeBlock, delimiters: LatexDelimitersConfig) -> dict[str, Any]:
+ """构造 V1 代码或算法 item。"""
+ body = visual_body(block)
+ if isinstance(body, CodeBodyBlock):
+ body_content = body.content
+ elif isinstance(body, AlgorithmBodyBlock):
+ body_content = render_inline_content(body.content, delimiters)
+ else:
+ raise TypeError(f"Unsupported code body: {type(body).__name__}")
+ return {
+ "type": "code",
+ "sub_type": "algorithm" if block.sub_type == RAW_ALGORITHM else "code",
+ "code_body": body_content,
+ "code_caption": render_annotation_texts(block, _CODE_CAPTION_TYPES, delimiters),
+ "code_footnote": render_annotation_texts(block, _CODE_FOOTNOTE_TYPES, delimiters),
+ }
+
+
+def _add_anchor(item: dict[str, Any], anchor: str | None) -> None:
+ """把非空文档锚点写入兼容 item。"""
+ if anchor and anchor.strip():
+ item["anchor"] = anchor.strip()
+
+
+__all__ = ["render_content_list"]
diff --git a/mineru/render/_internal/content_list/v2.py b/mineru/render/_internal/content_list/v2.py
new file mode 100644
index 00000000..06f01efd
--- /dev/null
+++ b/mineru/render/_internal/content_list/v2.py
@@ -0,0 +1,319 @@
+# Copyright (c) Opendatalab. All rights reserved.
+"""严格 MiddleJson 到按页 Content List V2 的渲染实现。"""
+
+from __future__ import annotations
+
+from typing import Any
+
+from docvortex.options import LatexDelimitersConfig
+from ....types import (
+ RAW_ALGORITHM,
+ AlgorithmBodyBlock,
+ BlockType,
+ ChartBlock,
+ CodeBlock,
+ CodeBodyBlock,
+ DocTitleBlock,
+ EquationBlock,
+ ImageBlock,
+ IndexBlock,
+ ListBlock,
+ MiddleJson,
+ PageAuxTextBlock,
+ PageFootnoteBlock,
+ ParagraphTitleBlock,
+ TableBlock,
+ TextBlock,
+)
+from .common import (
+ PageRenderUnit,
+ ReferenceGroup,
+ classify_table,
+ flatten_index_leaves,
+ flatten_list_leaves,
+ infer_list_attribute,
+ iter_page_units,
+ normalize_bbox,
+ normalized_index_content,
+ render_annotation_spans,
+ render_embedded_content,
+ resolve_legacy_image_source,
+ serialize_v2_spans,
+ string_as_v2_spans,
+ unit_bbox,
+ visual_body,
+)
+
+_IMAGE_CAPTION_TYPES = {str(BlockType.IMAGE_CAPTION)}
+_IMAGE_FOOTNOTE_TYPES = {str(BlockType.IMAGE_FOOTNOTE)}
+_TABLE_CAPTION_TYPES = {str(BlockType.TABLE_CAPTION)}
+_TABLE_FOOTNOTE_TYPES = {str(BlockType.TABLE_FOOTNOTE)}
+_CHART_CAPTION_TYPES = {str(BlockType.CHART_CAPTION)}
+_CHART_FOOTNOTE_TYPES = {str(BlockType.CHART_FOOTNOTE)}
+_CODE_CAPTION_TYPES = {str(BlockType.CODE_CAPTION)}
+_CODE_FOOTNOTE_TYPES = {str(BlockType.CODE_FOOTNOTE)}
+
+
+def render_content_list_v2(
+ middle_json: MiddleJson,
+ *,
+ asset_base_url: str = "",
+ latex_delimiters: LatexDelimitersConfig | None = None,
+) -> list[list[dict[str, Any]]]:
+ """把严格 MiddleJson 无副作用地渲染为按页 Content List V2。"""
+ if not isinstance(middle_json, MiddleJson):
+ raise TypeError("render_content_list_v2 expects a MiddleJson instance")
+ if not isinstance(asset_base_url, str):
+ raise TypeError("asset_base_url must be a string")
+
+ delimiters = latex_delimiters or LatexDelimitersConfig()
+ output: list[list[dict[str, Any]]] = []
+ for page in middle_json.pages:
+ page_items: list[dict[str, Any]] = []
+ for unit in iter_page_units(page.blocks):
+ item = _render_unit(unit, asset_base_url=asset_base_url, delimiters=delimiters)
+ if item is not None:
+ page_items.append(item)
+ output.append(page_items)
+ return output
+
+
+def _render_unit(
+ unit: PageRenderUnit,
+ *,
+ asset_base_url: str,
+ delimiters: LatexDelimitersConfig,
+) -> dict[str, Any] | None:
+ """把一个页面渲染单元转换为 V2 item,并补齐归一化 bbox。"""
+ item = _render_unit_content(unit, asset_base_url=asset_base_url, delimiters=delimiters)
+ if item is None:
+ return None
+ if bbox := normalize_bbox(unit_bbox(unit)):
+ item["bbox"] = bbox
+ return item
+
+
+def _render_unit_content(
+ unit: PageRenderUnit,
+ *,
+ asset_base_url: str,
+ delimiters: LatexDelimitersConfig,
+) -> dict[str, Any] | None:
+ """按严格 block 类型构造 V2 的 type + content 字段。"""
+ if isinstance(unit, ReferenceGroup):
+ return _reference_list_item(unit)
+ if isinstance(unit, TextBlock):
+ item = {"type": "paragraph", "content": {"paragraph_content": serialize_v2_spans(unit.content)}}
+ _add_anchor(item, unit.anchor)
+ return item
+ if isinstance(unit, (DocTitleBlock, ParagraphTitleBlock)):
+ item: dict[str, Any] = {
+ "type": "title",
+ "content": {
+ "title_content": serialize_v2_spans(unit.content),
+ "level": unit.level,
+ },
+ }
+ _add_anchor(item, unit.anchor)
+ return item
+ if isinstance(unit, PageFootnoteBlock):
+ item = {
+ "type": "page_footnote",
+ "content": {"page_footnote_content": serialize_v2_spans(unit.content)},
+ }
+ _add_anchor(item, unit.anchor)
+ return item
+ if isinstance(unit, PageAuxTextBlock):
+ content_type = _page_content_type(str(unit.type))
+ return {
+ "type": content_type,
+ "content": {f"{content_type}_content": serialize_v2_spans(unit.content)},
+ }
+ if isinstance(unit, EquationBlock):
+ return {
+ "type": "equation_interline",
+ "content": {
+ "math_content": unit.content.strip(),
+ "math_type": "latex",
+ "image_source": {"path": resolve_legacy_image_source(unit, asset_base_url)},
+ },
+ }
+ if isinstance(unit, ListBlock):
+ return _render_list(unit)
+ if isinstance(unit, IndexBlock):
+ return _render_index(unit)
+ if isinstance(unit, ImageBlock):
+ return _render_image(unit, asset_base_url, delimiters)
+ if isinstance(unit, TableBlock):
+ return _render_table(unit, asset_base_url, delimiters)
+ if isinstance(unit, ChartBlock):
+ return _render_chart(unit, asset_base_url, delimiters)
+ if isinstance(unit, CodeBlock):
+ return _render_code(unit)
+ return None
+
+
+def _page_content_type(block_type: str) -> str:
+ """把 MiddleJson 页面辅助块类型映射为 V2 类型。"""
+ mapping = {
+ str(BlockType.HEADER): "page_header",
+ str(BlockType.FOOTER): "page_footer",
+ str(BlockType.PAGE_NUMBER): "page_number",
+ str(BlockType.ASIDE_TEXT): "page_aside_text",
+ }
+ return mapping[block_type]
+
+
+def _reference_list_item(group: ReferenceGroup) -> dict[str, Any]:
+ """把连续参考文献块转换为一个 reference_list item。"""
+ return {
+ "type": "list",
+ "content": {
+ "list_type": "reference_list",
+ "list_items": [
+ {"item_type": "text", "item_content": serialize_v2_spans(block.content)}
+ for block in group.blocks
+ if block.content
+ ],
+ },
+ }
+
+
+def _render_list(block: ListBlock) -> dict[str, Any]:
+ """把递归列表展平为统一 V2 list item。"""
+ list_type = "reference_list" if block.sub_type == BlockType.REF_TEXT else "text_list"
+ content: dict[str, Any] = {
+ "list_type": list_type,
+ "list_items": [
+ {"item_type": "text", "item_content": serialize_v2_spans(leaf.block.content)}
+ for leaf in flatten_list_leaves(block)
+ if leaf.block.content
+ ],
+ }
+ if list_type == "text_list":
+ content["attribute"] = infer_list_attribute(block)
+ return {"type": "list", "content": content}
+
+
+def _render_index(block: IndexBlock) -> dict[str, Any]:
+ """把递归目录展平为统一 V2 index item。"""
+ list_items: list[dict[str, Any]] = []
+ for leaf in flatten_index_leaves(block):
+ content = normalized_index_content(leaf.block)
+ if not content:
+ continue
+ item: dict[str, Any] = {
+ "item_type": "text",
+ "item_content": serialize_v2_spans(content),
+ }
+ _add_anchor(item, leaf.block.anchor)
+ list_items.append(item)
+ return {
+ "type": "index",
+ "content": {
+ "list_type": "text_list",
+ "list_items": list_items,
+ },
+ }
+
+
+def _render_image(
+ block: ImageBlock,
+ asset_base_url: str,
+ delimiters: LatexDelimitersConfig,
+) -> dict[str, Any]:
+ """构造 V2 图片 item。"""
+ body = visual_body(block)
+ body_content = render_embedded_content(body.content, asset_base_url=asset_base_url, delimiters=delimiters)
+ content: dict[str, Any] = {
+ "image_source": {"path": resolve_legacy_image_source(body, asset_base_url)},
+ "image_caption": render_annotation_spans(block, _IMAGE_CAPTION_TYPES),
+ "image_footnote": render_annotation_spans(block, _IMAGE_FOOTNOTE_TYPES),
+ }
+ if body_content or block.sub_type:
+ content["content"] = body_content
+ item: dict[str, Any] = {"type": "image", "content": content}
+ if block.sub_type:
+ item["sub_type"] = block.sub_type
+ return item
+
+
+def _render_table(
+ block: TableBlock,
+ asset_base_url: str,
+ delimiters: LatexDelimitersConfig,
+) -> dict[str, Any]:
+ """构造 V2 表格 item并计算复杂度。"""
+ body = visual_body(block)
+ html = render_embedded_content(body.content, asset_base_url=asset_base_url, delimiters=delimiters)
+ table_type, table_nest_level = classify_table(html)
+ return {
+ "type": "table",
+ "content": {
+ "image_source": {"path": resolve_legacy_image_source(body, asset_base_url)},
+ "table_caption": render_annotation_spans(block, _TABLE_CAPTION_TYPES),
+ "table_footnote": render_annotation_spans(block, _TABLE_FOOTNOTE_TYPES),
+ "html": html,
+ "table_type": table_type,
+ "table_nest_level": table_nest_level,
+ },
+ }
+
+
+def _render_chart(
+ block: ChartBlock,
+ asset_base_url: str,
+ delimiters: LatexDelimitersConfig,
+) -> dict[str, Any]:
+ """构造 V2 图表 item。"""
+ body = visual_body(block)
+ item: dict[str, Any] = {
+ "type": "chart",
+ "content": {
+ "image_source": {"path": resolve_legacy_image_source(body, asset_base_url)},
+ "content": render_embedded_content(body.content, asset_base_url=asset_base_url, delimiters=delimiters),
+ "chart_caption": render_annotation_spans(block, _CHART_CAPTION_TYPES),
+ "chart_footnote": render_annotation_spans(block, _CHART_FOOTNOTE_TYPES),
+ },
+ }
+ if block.sub_type:
+ item["sub_type"] = block.sub_type
+ return item
+
+
+def _render_code(block: CodeBlock) -> dict[str, Any]:
+ """构造 V2 代码或算法 item。"""
+ body = visual_body(block)
+ captions = render_annotation_spans(block, _CODE_CAPTION_TYPES)
+ footnotes = render_annotation_spans(block, _CODE_FOOTNOTE_TYPES)
+ if block.sub_type == RAW_ALGORITHM:
+ if not isinstance(body, AlgorithmBodyBlock):
+ raise TypeError("algorithm subtype requires AlgorithmBodyBlock")
+ return {
+ "type": "algorithm",
+ "content": {
+ "algorithm_caption": captions,
+ "algorithm_content": serialize_v2_spans(body.content),
+ "algorithm_footnote": footnotes,
+ },
+ }
+ if not isinstance(body, CodeBodyBlock):
+ raise TypeError("code subtype requires CodeBodyBlock")
+ return {
+ "type": "code",
+ "content": {
+ "code_caption": captions,
+ "code_content": string_as_v2_spans(body.content),
+ "code_footnote": footnotes,
+ "code_language": block.guess_lang or "txt",
+ },
+ }
+
+
+def _add_anchor(item: dict[str, Any], anchor: str | None) -> None:
+ """把非空文档锚点写入 V2 item 或目录叶子。"""
+ if anchor and anchor.strip():
+ item["anchor"] = anchor.strip()
+
+
+__all__ = ["render_content_list_v2"]
diff --git a/mineru/render/content_list.py b/mineru/render/content_list.py
index e59d98a8..7ca406f7 100644
--- a/mineru/render/content_list.py
+++ b/mineru/render/content_list.py
@@ -15,7 +15,7 @@ def render_content_list(
) -> list[dict[str, Any]]:
"""惰性加载 Content List V1 实现并渲染严格 MiddleJson。"""
from ..config import config
- from docvortex.render.content_list import render_content_list as _render_content_list
+ from ._internal.content_list.v1 import render_content_list as _render_content_list
return _render_content_list(middle_json, asset_base_url=asset_base_url, latex_delimiters=config.render.latex_delimiters)
diff --git a/mineru/render/content_list_v2.py b/mineru/render/content_list_v2.py
index 48881bff..aca910a3 100644
--- a/mineru/render/content_list_v2.py
+++ b/mineru/render/content_list_v2.py
@@ -15,7 +15,7 @@ def render_content_list_v2(
) -> list[list[dict[str, Any]]]:
"""惰性加载 Content List V2 实现并渲染严格 MiddleJson。"""
from ..config import config
- from docvortex.render.content_list_v2 import render_content_list_v2 as _render_content_list_v2
+ from ._internal.content_list.v2 import render_content_list_v2 as _render_content_list_v2
return _render_content_list_v2(middle_json, asset_base_url=asset_base_url, latex_delimiters=config.render.latex_delimiters)
diff --git a/mineru/render/contracts.py b/mineru/render/contracts.py
index 8c57bfe5..5cc2c330 100644
--- a/mineru/render/contracts.py
+++ b/mineru/render/contracts.py
@@ -1,10 +1,13 @@
# Copyright (c) Opendatalab. All rights reserved.
-"""共享 DocVortex 渲染契约的 MinerU 公共门面。"""
+"""MinerU 九种渲染目标及共享 DocVortex 选项的公共契约。"""
+from dataclasses import dataclass
+from enum import Enum
+from typing import Any, TypeAlias
+
+from docvortex.options import LatexDelimitersConfig
from docvortex.render.contracts import (
AssetResolver,
- ContentListRenderOptions,
- ContentListV2RenderOptions,
DocxRenderOptions,
EpubRenderOptions,
HtmlRenderOptions,
@@ -12,13 +15,71 @@ from docvortex.render.contracts import (
LatexRenderOptions,
MarkdownRenderOptions,
PdfRenderOptions,
- RenderFormat,
RenderMode,
- RenderOptions,
- RenderOutput,
StructuredContentRenderOptions,
)
+
+class RenderFormat(str, Enum):
+ """统一渲染入口支持的目标格式。"""
+
+ MARKDOWN = "markdown"
+ HTML = "html"
+ LATEX = "latex"
+ DOCX = "docx"
+ EPUB = "epub"
+ STRUCTURED_CONTENT = "structured_content"
+ CONTENT_LIST = "content_list"
+ CONTENT_LIST_V2 = "content_list_v2"
+ PDF = "pdf"
+
+
+def _validate_asset_base_url(asset_base_url: object) -> None:
+ """校验产品专用 renderer 的素材根地址,保持既有错误类型。"""
+ if not isinstance(asset_base_url, str):
+ raise TypeError("asset_base_url must be a string")
+
+
+@dataclass(frozen=True, slots=True)
+class ContentListRenderOptions:
+ """扁平 Content List V1 renderer 的统一入口选项。"""
+
+ latex_delimiters: LatexDelimitersConfig | None = None
+
+ asset_base_url: str = ""
+
+ def __post_init__(self) -> None:
+ """在构造时校验图片资源根地址。"""
+ _validate_asset_base_url(self.asset_base_url)
+
+
+@dataclass(frozen=True, slots=True)
+class ContentListV2RenderOptions:
+ """按页 Content List V2 renderer 的统一入口选项。"""
+
+ latex_delimiters: LatexDelimitersConfig | None = None
+
+ asset_base_url: str = ""
+
+ def __post_init__(self) -> None:
+ """在构造时校验图片资源根地址。"""
+ _validate_asset_base_url(self.asset_base_url)
+
+
+RenderOptions: TypeAlias = (
+ MarkdownRenderOptions
+ | HtmlRenderOptions
+ | LatexRenderOptions
+ | DocxRenderOptions
+ | EpubRenderOptions
+ | PdfRenderOptions
+ | StructuredContentRenderOptions
+ | ContentListRenderOptions
+ | ContentListV2RenderOptions
+)
+RenderOutput: TypeAlias = str | bytes | dict[str, Any] | list[dict[str, Any]] | list[list[dict[str, Any]]]
+
+
__all__ = [
"AssetResolver",
"ContentListRenderOptions",
diff --git a/mineru/types.py b/mineru/types.py
index cc53730d..0652bd26 100644
--- a/mineru/types.py
+++ b/mineru/types.py
@@ -14,8 +14,6 @@ from docvortex.schema import (
FileSuffix,
FILE_SUFFIXES,
BlockType,
- ContentType,
- ContentTypeV2,
BlockTypes,
PageBlockTypes,
BLOCK_TYPES,
@@ -182,6 +180,48 @@ def select_parsing_rule_tier(available_tiers: Iterable[object] | str | None = No
return "flash"
+class ContentType:
+ """MinerU 推理及兼容输出使用的内容标签。"""
+
+ IMAGE = "image"
+ TABLE = "table"
+ CHART = "chart"
+ TEXT = "text"
+ INTERLINE_EQUATION = "interline_equation"
+ INLINE_EQUATION = "inline_equation"
+ EQUATION = "equation"
+ HYPERLINK = "hyperlink"
+
+
+class ContentTypeV2:
+ """MinerU Content List V2 的稳定内容标签。"""
+
+ CODE = "code"
+ ALGORITHM = "algorithm"
+ EQUATION_INTERLINE = "equation_interline"
+ IMAGE = "image"
+ TABLE = "table"
+ CHART = "chart"
+ TABLE_SIMPLE = "simple_table"
+ TABLE_COMPLEX = "complex_table"
+ LIST = "list"
+ LIST_TEXT = "text_list"
+ LIST_REF = "reference_list"
+ INDEX = "index"
+ TITLE = "title"
+ PARAGRAPH = "paragraph"
+ SPAN_TEXT = "text"
+ SPAN_EQUATION_INLINE = "equation_inline"
+ SPAN_PHONETIC = "phonetic"
+ SPAN_MD = "md"
+ SPAN_CODE_INLINE = "code_inline"
+ PAGE_HEADER = "page_header"
+ PAGE_FOOTER = "page_footer"
+ PAGE_NUMBER = "page_number"
+ PAGE_ASIDE_TEXT = "page_aside_text"
+ PAGE_FOOTNOTE = "page_footnote"
+
+
__all__ = [
"RawBlockType",
"RAW_ALGORITHM",
diff --git a/tests/unittest/test_content_list_ownership.py b/tests/unittest/test_content_list_ownership.py
new file mode 100644
index 00000000..4406713c
--- /dev/null
+++ b/tests/unittest/test_content_list_ownership.py
@@ -0,0 +1,73 @@
+"""验证产品专用 Content List 契约与共享渲染片段的边界。"""
+
+from __future__ import annotations
+
+from typing import Any
+
+import pytest
+
+from docvortex.options import LatexDelimiterConfig, LatexDelimitersConfig
+from docvortex.render import RenderFormat as EngineFormat
+from docvortex.render.contracts import MarkdownRenderOptions as EngineMarkdownOptions
+from docvortex.schema import MiddleJson, PageInfo, TextBlock, TextSpan, EquationInlineSpan, ChartBlock, ChartBodyBlock
+
+from mineru.config import config
+from mineru.render import RenderFormat, MarkdownRenderOptions, render_content_list, render_content_list_v2
+from mineru.types import ContentType, ContentTypeV2
+
+
+def test_product_owns_extended_contracts() -> None:
+ """宿主九种格式独立于引擎七种格式,通用选项与语义类型继续共享。"""
+ assert len(RenderFormat) == 9 and len(EngineFormat) == 7
+ assert RenderFormat is not EngineFormat
+ assert MarkdownRenderOptions is EngineMarkdownOptions
+ assert ContentType.__module__ == ContentTypeV2.__module__ == "mineru.types"
+ assert ContentType.TEXT == "text" and ContentTypeV2.SPAN_MD == "md"
+
+
[email protected]("version", [1, 2])
+def test_migrated_inline_delimiter_cases(version: int, monkeypatch: pytest.MonkeyPatch) -> None:
+ """迁入两种列表的公式分隔符断言,通过宿主配置显式传入实现。"""
+ middle = MiddleJson(
+ pages=[
+ PageInfo(
+ page_idx=0,
+ blocks=[
+ TextBlock(
+ type="text",
+ index=0,
+ content=[
+ TextSpan(type="text", content="Text"),
+ EquationInlineSpan(type="equation_inline", content="x"),
+ ],
+ ),
+ ChartBlock(
+ type="chart",
+ index=1,
+ content=[
+ ChartBodyBlock(type="chart_body", index=1, content="<table><tr><td><eq>x</eq></td></tr></table>")
+ ],
+ ),
+ ],
+ )
+ ],
+ file_suffix="html",
+ is_full_document=True,
+ )
+ before = middle.to_dict(skip_defaults=False)
+ delimiters = LatexDelimitersConfig(inline=LatexDelimiterConfig(left="\\(", right="\\)"))
+ monkeypatch.setattr(config.render, "latex_delimiters", delimiters)
+ value = render_content_list(middle) if version == 1 else render_content_list_v2(middle)
+
+ def strings(item: Any) -> list[str]:
+ """读取所有文本叶子,避免依赖两个列表各自的包装层级。"""
+ if isinstance(item, str):
+ return [item]
+ if isinstance(item, dict):
+ return [text for child in item.values() for text in strings(child)]
+ if isinstance(item, list):
+ return [text for child in item for text in strings(child)]
+ return []
+
+ assert any("\\(x\\)" in text for text in strings(value))
+ assert middle.to_dict(skip_defaults=False) == before