Skip to content

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

feat: reuse owned PDF text snapshots across analysis windows

myhlolibf9014904cee
diff --git a/mineru/backend/analysis/pdf/snapshots.py b/mineru/backend/analysis/pdf/snapshots.py
new file mode 100644
index 00000000..bedf62ab
--- /dev/null
+++ b/mineru/backend/analysis/pdf/snapshots.py
@@ -0,0 +1,78 @@
+# Copyright (c) Opendatalab. All rights reserved.
+"""仅在当前真实 PDF 窗口内持有自有文字快照,按需补齐矢量和链接。"""
+
+from __future__ import annotations
+
+from dataclasses import dataclass
+from typing import TYPE_CHECKING, Any
+from weakref import ReferenceType, ref
+
+from docvortex.document.pdf import PDFPage, PDFPageTextGeometry, PDFPageVectorGeometry
+
+if TYPE_CHECKING:
+ from docvortex.document.pdf import PDFPageSnapshot
+
+
+@dataclass
+class _PageSnapshotEntry:
+ """文字 owner 跨阶段共享,页面只保留弱引用以免延长文档生命周期。"""
+
+ page_ref: ReferenceType[PDFPage]
+ text_owner: Any
+ full_snapshot: PDFPageSnapshot | None = None
+
+ def validate_page(self, page: PDFPage) -> None:
+ """拒绝将当前窗口条目误用于其他页面对象。"""
+ if self.page_ref() is not page:
+ raise ValueError("window snapshot belongs to a different PDF page")
+
+ def get_full_snapshot(self, page: PDFPage) -> PDFPageSnapshot:
+ """仅在表格或正文确实需要时补齐矢量和链接,并复用已持有的文字 owner。"""
+ self.validate_page(page)
+ if self.full_snapshot is None:
+ self.full_snapshot = page.get_snapshot()
+ return self.full_snapshot
+
+ def close(self) -> None:
+ """清除强引用;快照不持有需手工关闭的 PDFium 页面句柄。"""
+ self.full_snapshot = None
+ self.text_owner = None
+
+
+PageSnapshotCache = list[_PageSnapshotEntry | None]
+
+
+def create_page_snapshot_cache(pages: list[PDFPage], *, enabled: bool) -> PageSnapshotCache | None:
+ """只为真实页面开启新通道,旧 fake 页面及不提供新公开接口的环境保持原调用。"""
+ if not enabled or not pages or not callable(getattr(PDFPage, "get_text_snapshot", None)):
+ return None
+ # MagicMock(spec=PDFPage) 可伪造 isinstance,必须检查真实类型。
+ return [None] * len(pages) if all(type(page) is PDFPage for page in pages) else None
+
+
+def get_page_snapshot_entry(
+ cache: PageSnapshotCache | None,
+ index: int,
+ page: PDFPage,
+ *,
+ geometry: PDFPageTextGeometry | None = None,
+ vector_geometry: PDFPageVectorGeometry | None = None,
+) -> _PageSnapshotEntry | None:
+ """显式几何始终优先;只对空缓存的真实页面惰性读取一次 owned 文字。"""
+ if cache is None or type(page) is not PDFPage or geometry is not None or vector_geometry is not None:
+ return None
+ entry = cache[index]
+ if entry is None:
+ entry = _PageSnapshotEntry(ref(page), page.get_text_snapshot())
+ cache[index] = entry
+ entry.validate_page(page)
+ return entry if entry.text_owner is not None else None
+
+
+def clear_page_snapshot_cache(cache: PageSnapshotCache | None) -> None:
+ """成功、失败与取消均释放完整窗口的 owned 数据,即使外层仍持有条目对象。"""
+ if cache is not None:
+ for entry in cache:
+ if entry is not None:
+ entry.close()
+ cache.clear()
diff --git a/mineru/backend/analysis/pdf/tables.py b/mineru/backend/analysis/pdf/tables.py
index 398917cf..c3cc64fb 100644
--- a/mineru/backend/analysis/pdf/tables.py
+++ b/mineru/backend/analysis/pdf/tables.py
@@ -28,6 +28,7 @@ from ....model.ocr.image import mask_formula_regions_for_ocr_det
from ....model.runtime.contracts import AtomicModelName
from ....model.runtime.hybrid import HybridLocalModelContext, run_ocr_inference
from ....types import RAW_ALGORITHM, RAW_FORMULA_NUMBER, RAW_PHONETIC, BBox, BlockType
+from .snapshots import PageSnapshotCache, get_page_snapshot_entry
from .constants import (
BATCH_RATIO,
OCR_DET_BASE_BATCH_SIZE,
@@ -207,6 +208,7 @@ def _apply_native_txt_table_priority(
effort: Literal["medium", "high"],
page_text_geometries: list[PDFPageTextGeometry | None] | None = None,
page_vector_geometries: list[PDFPageVectorGeometry | None] | None = None,
+ page_snapshots: PageSnapshotCache | None = None,
) -> _NativeTablePrioritySummary:
"""在 Medium/High TXT 模型表格识别前回填高置信原生 HTML。"""
@@ -263,14 +265,25 @@ def _apply_native_txt_table_priority(
try:
page_text_geometry = page_text_geometries[page_idx] if page_text_geometries is not None else None
vector_geometry = page_vector_geometries[page_idx] if page_vector_geometries is not None else None
- if vector_geometry is None:
- vector_geometry = pdf_page.get_vector_geometry()
- table_page = prepare_table_page(pdf_page, geometry=page_text_geometry, vector_geometry=vector_geometry)
- page_text_geometry = table_page.geometry
- if page_text_geometries is not None:
- page_text_geometries[page_idx] = page_text_geometry
- if page_vector_geometries is not None:
- page_vector_geometries[page_idx] = vector_geometry
+ snapshot_entry = get_page_snapshot_entry(
+ page_snapshots,
+ page_idx,
+ pdf_page,
+ geometry=page_text_geometry,
+ vector_geometry=vector_geometry,
+ )
+ if snapshot_entry is not None:
+ # 表格恢复仍消费其真实可变 geometry,但不提前把该兼容副本放进窗口正文缓存。
+ table_page = prepare_table_page(pdf_page, snapshot=snapshot_entry.get_full_snapshot(pdf_page))
+ else:
+ if vector_geometry is None:
+ vector_geometry = pdf_page.get_vector_geometry()
+ table_page = prepare_table_page(pdf_page, geometry=page_text_geometry, vector_geometry=vector_geometry)
+ page_text_geometry = table_page.geometry
+ if page_text_geometries is not None:
+ page_text_geometries[page_idx] = page_text_geometry
+ if page_vector_geometries is not None:
+ page_vector_geometries[page_idx] = vector_geometry
native_page_size = table_page.page_size
render_scale = float(image_dict.get("scale", 1.0) or 1.0)
except Exception as exc:
@@ -468,6 +481,8 @@ def _resolve_txt_table_orientations(
pdf_pages: list[PDFPage],
images_list: list[dict[str, Any]],
page_text_geometries: list[PDFPageTextGeometry | None] | None = None,
+ *,
+ page_snapshots: PageSnapshotCache | None = None,
) -> list[dict[str, Any]]:
"""优先用原生 PDF 文本行写回表格角度,并返回需要视觉兜底的表格。"""
fallback_table_items: list[dict[str, Any]] = []
@@ -499,16 +514,27 @@ def _resolve_txt_table_orientations(
if page_idx not in page_lines_cache:
try:
geometry = page_text_geometries[page_idx] if page_text_geometries is not None else None
- if geometry is None and page_text_geometries is not None:
- try:
- geometry = pdf_page.get_chars_with_geometry()
- except Exception as exc:
- # 扩展几何失败不应让本来可成功的普通字符投票改走视觉模型。
- logger.debug(f"Hybrid table orientation uses plain chars after geometry failure: {exc}")
- else:
- page_text_geometries[page_idx] = geometry
- chars = geometry.chars if geometry is not None else pdf_page.get_chars()
- page_lines_cache[page_idx] = get_lines_from_chars(chars)
+ snapshot_entry = None
+ geometry_failed = False
+ try:
+ snapshot_entry = get_page_snapshot_entry(page_snapshots, page_idx, pdf_page, geometry=geometry)
+ except Exception as exc:
+ geometry_failed = True
+ logger.debug(f"Hybrid table orientation uses plain chars after owned geometry failure: {exc}")
+ if snapshot_entry is not None:
+ # 方向投票只需要粗行几何和文字,不物化整页 Char/font,也不读取路径或链接。
+ page_lines_cache[page_idx] = snapshot_entry.text_owner.get_line_summaries(0.7, 0.1)
+ else:
+ if geometry is None and page_text_geometries is not None and not geometry_failed:
+ try:
+ geometry = pdf_page.get_chars_with_geometry()
+ except Exception as exc:
+ # 扩展几何失败不应让本来可成功的普通字符投票改走视觉模型。
+ logger.debug(f"Hybrid table orientation uses plain chars after geometry failure: {exc}")
+ else:
+ page_text_geometries[page_idx] = geometry
+ chars = geometry.chars if geometry is not None else pdf_page.get_chars()
+ page_lines_cache[page_idx] = get_lines_from_chars(chars)
except Exception as exc:
logger.warning(f"Hybrid txt table orientation falls back to visual model: page_idx={page_idx}, error={exc}")
page_lines_cache[page_idx] = None
@@ -534,6 +560,8 @@ def _apply_table_orientations(
images_list: list[dict[str, Any]],
hybrid_model: HybridLocalModelContext,
page_text_geometries: list[PDFPageTextGeometry | None] | None = None,
+ *,
+ page_snapshots: PageSnapshotCache | None = None,
) -> None:
"""按解析模式写回表格角度,文本证据不足时批量调用视觉方向模型。"""
if parse_mode == "txt":
@@ -542,6 +570,7 @@ def _apply_table_orientations(
pdf_pages,
images_list,
page_text_geometries,
+ **({"page_snapshots": page_snapshots} if page_snapshots is not None else {}),
)
elif parse_mode == "ocr":
fallback_table_items = table_items
diff --git a/mineru/backend/analysis/pdf/text/content.py b/mineru/backend/analysis/pdf/text/content.py
index 0790f616..175c2ed1 100644
--- a/mineru/backend/analysis/pdf/text/content.py
+++ b/mineru/backend/analysis/pdf/text/content.py
@@ -11,6 +11,8 @@ from docvortex.content.text import merge_text_line_contents
from docvortex.document.pdf import PDFPage, PDFPageTextGeometry, PDFPageVectorGeometry, get_lines_from_chars
from PIL import Image
+from ..snapshots import PageSnapshotCache, get_page_snapshot_entry
+
from .....model.ocr.image import rotate_vertical_crop_if_needed
from .....model.ocr.results import OcrConfidence
from .....model.runtime.hybrid import HybridLocalModelContext, run_ocr_inference
@@ -359,6 +361,7 @@ def _fill_window_block_content_and_lines(
page_text_geometries: list[PDFPageTextGeometry | None] | None = None,
*,
page_vector_geometries: list[PDFPageVectorGeometry | None] | None = None,
+ page_snapshots: PageSnapshotCache | None = None,
) -> list[list[dict[str, Any]]]:
"""按页完成 span 回填与行级元数据构造,返回不含页面级 sidecar 的 model list。"""
page_counts = {
@@ -372,6 +375,8 @@ def _fill_window_block_content_and_lines(
page_counts["text_geometries"] = len(page_text_geometries)
if page_vector_geometries is not None:
page_counts["vector_geometries"] = len(page_vector_geometries)
+ if page_snapshots is not None:
+ page_counts["snapshots"] = len(page_snapshots)
if len(set(page_counts.values())) != 1:
raise ValueError(f"Hybrid block content page count mismatch: {page_counts}")
@@ -425,13 +430,29 @@ def _fill_window_block_content_and_lines(
or isinstance(page_char_count, bool)
or page_char_count <= MAX_NATIVE_TEXT_CHARS_PER_PAGE
):
- evidence = prepare_text_evidence(
+ vector_geometry = page_vector_geometries[page_idx] if page_vector_geometries is not None else None
+ snapshot_entry = get_page_snapshot_entry(
+ page_snapshots,
+ page_idx,
pdf_page,
geometry=page_text_geometry,
- vector_geometry=page_vector_geometries[page_idx] if page_vector_geometries is not None else None,
- excluded_script_regions=inline_math_regions,
- table_regions=table_regions,
+ vector_geometry=vector_geometry,
)
+ if snapshot_entry is not None:
+ evidence = prepare_text_evidence(
+ pdf_page,
+ snapshot=snapshot_entry.get_full_snapshot(pdf_page),
+ excluded_script_regions=inline_math_regions,
+ table_regions=table_regions,
+ )
+ else:
+ evidence = prepare_text_evidence(
+ pdf_page,
+ geometry=page_text_geometry,
+ vector_geometry=vector_geometry,
+ excluded_script_regions=inline_math_regions,
+ table_regions=table_regions,
+ )
page_text_geometry = evidence.geometry
if page_text_geometries is not None:
page_text_geometries[page_idx] = page_text_geometry
@@ -444,6 +465,12 @@ def _fill_window_block_content_and_lines(
page_text_geometry=page_text_geometry,
detect_scripts=not use_shared_script_sidecar,
)
+ # 后续只消费已物化证据;逐页释放 Rust owner,避免与窗口 Python 几何长期双份驻留。
+ if page_snapshots is not None:
+ entry = page_snapshots[page_idx]
+ if entry is not None:
+ entry.close()
+ page_snapshots[page_idx] = None
block_lines = _group_page_spans_by_block(
page_model_list,
diff --git a/mineru/backend/analysis/pdf/text/native.py b/mineru/backend/analysis/pdf/text/native.py
index fd7d356d..429ac55b 100644
--- a/mineru/backend/analysis/pdf/text/native.py
+++ b/mineru/backend/analysis/pdf/text/native.py
@@ -99,7 +99,21 @@ def txt_spans_extract(
page_chars = page_text_geometry.chars
tight_bboxes = page_text_geometry.tight_bboxes
origins = page_text_geometry.origins
- page_all_chars = _get_chars_for_span_fill(page_chars)
+ base_lines: list[dict[str, Any]] | None = None
+
+ def get_page_lines() -> list[dict[str, Any]]:
+ """只在局部旋转或竖排实际需要时组行,两个消费者共享当前真实字符的结果。"""
+ nonlocal base_lines
+ if type(page_chars) is not list:
+ return get_lines_from_chars(page_chars)
+ if base_lines is None:
+ base_lines = get_lines_from_chars(page_chars)
+ return base_lines
+
+ page_all_chars = _get_chars_for_span_fill(
+ page_chars,
+ line_provider=get_page_lines if type(page_chars) is list else None,
+ )
# 计算所有span的高度的中位数
span_height_list = []
@@ -137,7 +151,7 @@ def txt_spans_extract(
"""垂直的span框直接用line进行填充"""
if len(vertical_spans) > 0:
- pdf_lines = [line for line in get_lines_from_chars(page_chars) if _is_supported_rotation(line["rotation"])]
+ pdf_lines = [line for line in get_page_lines() if _is_supported_rotation(line["rotation"])]
for pdf_line in pdf_lines:
for span in vertical_spans:
if calculate_overlap_area_in_bbox1_area_ratio(pdf_line["bbox"].bbox, span.bbox) > 0.5:
@@ -209,7 +223,11 @@ def _is_visible_standard_rotation_char(char: Char) -> bool:
return x1 > x0 and y1 > y0 and _is_supported_rotation(float(char.get("rotation", 0)))
-def _get_chars_for_span_fill(page_chars: list[Char] | dict[str, list[Char]]) -> list[Char]:
+def _get_chars_for_span_fill(
+ page_chars: list[Char] | dict[str, list[Char]],
+ *,
+ line_provider: Callable[[], list[dict[str, Any]]] | None = None,
+) -> list[Char]:
"""选择允许参与 span 回填的字符,保留正文内仿斜体并过滤整行斜向水印。"""
if isinstance(page_chars, dict):
all_chars = page_chars["chars"]
@@ -222,7 +240,8 @@ def _get_chars_for_span_fill(page_chars: list[Char] | dict[str, list[Char]]) ->
if not rotated_chars:
return [char for char in all_chars if _get_char_fill_key(char) in fill_char_keys]
- for line in get_lines_from_chars(all_chars):
+ lines = line_provider() if line_provider is not None else get_lines_from_chars(all_chars)
+ for line in lines:
line_rotation = float(line.get("rotation", 0))
if not _is_supported_rotation(line_rotation):
continue
diff --git a/mineru/backend/analysis/pdf/window.py b/mineru/backend/analysis/pdf/window.py
index 16b0111d..af5aae58 100644
--- a/mineru/backend/analysis/pdf/window.py
+++ b/mineru/backend/analysis/pdf/window.py
@@ -60,6 +60,7 @@ from .ocr import (
_build_ocr_det_type_and_mfr_enable,
_ocr_det,
)
+from .snapshots import PageSnapshotCache, clear_page_snapshot_cache, create_page_snapshot_cache
from .tables import (
_apply_medium_table_recognition,
_apply_native_txt_table_priority,
@@ -213,6 +214,7 @@ def _process_text_and_formulas(
page_text_geometries: list[PDFPageTextGeometry | None] | None = None,
*,
page_vector_geometries: list[PDFPageVectorGeometry | None] | None = None,
+ page_snapshots: PageSnapshotCache | None = None,
np_images: list[np.ndarray] | None = None,
) -> list[list[dict[str, Any]]]:
"""在当前窗口内完成 OCR、公式、原生文本及 block 行信息回填。"""
@@ -316,6 +318,7 @@ def _process_text_and_formulas(
local_model_context,
page_text_geometries,
page_vector_geometries=page_vector_geometries,
+ **({"page_snapshots": page_snapshots} if page_snapshots is not None else {}),
)
@@ -334,6 +337,7 @@ class _WindowInputs:
accepted_native_tables: list[list[dict[str, Any]]]
page_text_geometries: list[PDFPageTextGeometry | None] | None
page_vector_geometries: list[PDFPageVectorGeometry | None] | None = None
+ page_snapshots: PageSnapshotCache | None = None
def close(self) -> None:
"""推理及回填真正退出后关闭图片,仅清除本层拥有的容器。"""
@@ -348,6 +352,7 @@ class _WindowInputs:
self.page_text_geometries.clear()
if self.page_vector_geometries is not None:
self.page_vector_geometries.clear()
+ clear_page_snapshot_cache(self.page_snapshots)
def _prepare_pdf_window(
@@ -367,6 +372,7 @@ def _prepare_pdf_window(
table_items = []
page_text_geometries: list[PDFPageTextGeometry | None] | None = None
page_vector_geometries: list[PDFPageVectorGeometry | None] | None = None
+ page_snapshots: PageSnapshotCache | None = None
try:
window_pages = _get_window_pdf_pages(document, window)
with stage_timer("pdf.render"):
@@ -385,6 +391,7 @@ def _prepare_pdf_window(
[None] * len(window_pages) if parse_mode == "txt" and effort in {"medium", "high", "xhigh"} else None
)
page_vector_geometries = [None] * len(window_pages) if page_text_geometries is not None else None
+ page_snapshots = create_page_snapshot_cache(window_pages, enabled=page_text_geometries is not None)
local_model_context = hybrid_model
if local_model_context is None:
@@ -407,6 +414,7 @@ def _prepare_pdf_window(
images_list,
local_model_context,
page_text_geometries,
+ **({"page_snapshots": page_snapshots} if page_snapshots is not None else {}),
)
vl_style_layout_blocks = _build_vl_style_layout_blocks(images_layout_res, images_pil_list)
@@ -421,6 +429,7 @@ def _prepare_pdf_window(
effort=effort,
page_text_geometries=page_text_geometries,
page_vector_geometries=page_vector_geometries,
+ **({"page_snapshots": page_snapshots} if page_snapshots is not None else {}),
)
if native_table_summary.total:
native_table_stats = {
@@ -462,6 +471,7 @@ def _prepare_pdf_window(
accepted_native_tables,
page_text_geometries,
page_vector_geometries,
+ page_snapshots=page_snapshots,
)
except BaseException:
try:
@@ -474,6 +484,7 @@ def _prepare_pdf_window(
page_text_geometries.clear()
if page_vector_geometries is not None:
page_vector_geometries.clear()
+ clear_page_snapshot_cache(page_snapshots)
raise
finally:
table_items.clear()
@@ -532,6 +543,7 @@ def _finish_pdf_window(
images_layout_res,
page_text_geometries,
page_vector_geometries=state.page_vector_geometries,
+ **({"page_snapshots": state.page_snapshots} if state.page_snapshots is not None else {}),
np_images=np_images,
)
diff --git a/tests/unittest/test_pdf_window_snapshots.py b/tests/unittest/test_pdf_window_snapshots.py
new file mode 100644
index 00000000..a3fdd20b
--- /dev/null
+++ b/tests/unittest/test_pdf_window_snapshots.py
@@ -0,0 +1,400 @@
+"""验证真实 TXT 窗口的 owned 快照共享、旧调用语义和释放边界。"""
+
+from __future__ import annotations
+
+import asyncio
+from io import BytesIO
+from typing import Any
+from unittest.mock import AsyncMock, MagicMock
+from weakref import ref
+
+import pytest
+from PIL import Image
+from reportlab.pdfgen.canvas import Canvas
+
+from docvortex.document.pdf import Bbox, PDFDocument, PDFPage, PDFPageTextGeometry, PDFPageVectorGeometry
+from mineru.backend.analysis.pdf import snapshots, tables, window
+from mineru.backend.analysis.pdf.text import content, native
+from mineru.backend.analysis.pdf.text.models import _AnalyzeSpan
+from mineru.types import BlockType, ContentType
+
+
+def _pdf() -> bytes:
+ """提供真实三行文字和矩形路径,满足方向投票且无需模型。"""
+ stream = BytesIO()
+ canvas = Canvas(stream, pagesize=(200, 200))
+ for y in (150, 120, 90):
+ canvas.drawString(20, y, "Table text 123")
+ canvas.rect(10, 70, 180, 100)
+ canvas.save()
+ return stream.getvalue()
+
+
+def _require_owned(page: PDFPage) -> Any:
+ """参考后端跳过真实扩展断言,Rust 模式必须具备 owned 入口。"""
+ owner = page.get_text_snapshot()
+ if owner is None:
+ pytest.skip("owned text snapshot unavailable in reference backend")
+ return owner
+
+
+class _Payload:
+ """提供可弱引用的资源,用于观察窗口是否真正释放强引用。"""
+
+
+def _state(page: PDFPage, cache: snapshots.PageSnapshotCache) -> window._WindowInputs:
+ """构造不持有图片的窗口,聚焦关闭和取消的资源所有权。"""
+ return window._WindowInputs(
+ window._ProcessingWindow(0, 1, 0, 0),
+ [],
+ [page],
+ [],
+ [],
+ [],
+ [],
+ [],
+ [],
+ [None],
+ [None],
+ page_snapshots=cache,
+ )
+
+
+def test_fake_pages_and_explicit_geometry_do_not_probe_snapshot(monkeypatch: pytest.MonkeyPatch) -> None:
+ """MagicMock 的伪造接口和显式可变几何不得进入新快照通道。"""
+ fake = MagicMock(spec=PDFPage)
+ assert snapshots.create_page_snapshot_cache([fake], enabled=True) is None
+ assert snapshots.get_page_snapshot_entry([None], 0, fake) is None
+ fake.get_text_snapshot.assert_not_called()
+ with PDFDocument(_pdf()) as document:
+ page = document[0]
+ geometry = PDFPageTextGeometry(chars=[], tight_bboxes={}, origins={})
+ vectors = PDFPageVectorGeometry((), ())
+ blocked = MagicMock(side_effect=AssertionError("explicit geometry entered snapshot"))
+ monkeypatch.setattr(page, "get_text_snapshot", blocked)
+ cache = [None]
+ assert snapshots.get_page_snapshot_entry(cache, 0, page, geometry=geometry) is None
+ assert snapshots.get_page_snapshot_entry(cache, 0, page, vector_geometry=vectors) is None
+ blocked.assert_not_called()
+
+
+def test_unsupported_owned_probe_is_cached(monkeypatch: pytest.MonkeyPatch) -> None:
+ """不支持的原生入口每页只探测一次,不将 None 当作未探测反复读取。"""
+ with PDFDocument(_pdf()) as document:
+ page = document[0]
+ getter = MagicMock(return_value=None)
+ monkeypatch.setattr(page, "get_text_snapshot", getter)
+ cache = [None]
+ assert snapshots.get_page_snapshot_entry(cache, 0, page) is None
+ assert snapshots.get_page_snapshot_entry(cache, 0, page) is None
+ getter.assert_called_once_with()
+ snapshots.clear_page_snapshot_cache(cache)
+ assert cache == []
+
+
[email protected]("effort", ["medium", "high", "xhigh"])
+def test_non_table_window_does_not_eagerly_materialize_snapshots(effort: str, monkeypatch: pytest.MonkeyPatch) -> None:
+ """没有表格时保持 VLM 前无原生字符工作,三个 TXT 档位只分配空缓存。"""
+ with PDFDocument(_pdf()) as document:
+ page = document[0]
+ monkeypatch.setattr(window, "_get_window_pdf_pages", lambda *_: [page])
+ owner = MagicMock(side_effect=AssertionError("eager owner"))
+ full = MagicMock(side_effect=AssertionError("eager full snapshot"))
+ monkeypatch.setattr(page, "get_text_snapshot", owner)
+ monkeypatch.setattr(page, "get_snapshot", full)
+ image = Image.new("RGB", (200, 200))
+ monkeypatch.setattr(window, "load_images_from_pdf_bytes_range", lambda **_: [{"img_pil": image, "scale": 1.0}])
+ model = MagicMock()
+ model.layout_model.batch_predict.return_value = [[]]
+ state = window._prepare_pdf_window(
+ b"",
+ document,
+ window._ProcessingWindow(0, 1, 0, 0),
+ page_count=1,
+ effort=effort,
+ parse_mode="txt",
+ hybrid_model=model,
+ )
+ assert state.page_snapshots == [None]
+ owner.assert_not_called()
+ full.assert_not_called()
+ state.close()
+ assert state.page_snapshots == []
+
+
+def test_direction_table_and_body_share_owner_without_legacy_repacking(monkeypatch: pytest.MonkeyPatch) -> None:
+ """方向只读轻量粗行,表格不回填旧缓存,正文直接消费同一完整快照。"""
+ with PDFDocument(_pdf()) as document, Image.new("RGB", (200, 200)) as image:
+ page = document[0]
+ owner = _require_owned(page)
+ owner_getter = MagicMock(wraps=page.get_text_snapshot)
+ full_getter = MagicMock(wraps=page.get_snapshot)
+ legacy_getter = MagicMock(side_effect=AssertionError("legacy geometry materialized before owned prepare"))
+ monkeypatch.setattr(page, "get_text_snapshot", owner_getter)
+ monkeypatch.setattr(page, "get_snapshot", full_getter)
+ monkeypatch.setattr(page, "get_chars_with_geometry", legacy_getter)
+ cache = snapshots.create_page_snapshot_cache([page], enabled=True)
+ geometries: list[PDFPageTextGeometry | None] = [None]
+ vectors: list[PDFPageVectorGeometry | None] = [None]
+ layout = {"label": "table", "bbox": [0, 0, 200, 200]}
+ images = [{"img_pil": image, "scale": 1.0}]
+ assert (
+ tables._resolve_txt_table_orientations(
+ [{"page_idx": 0, "layout_item": layout}],
+ [page],
+ images,
+ geometries,
+ page_snapshots=cache,
+ )
+ == []
+ )
+ assert cache[0].text_owner is owner
+ assert cache[0].full_snapshot is None
+ assert geometries == [None]
+ full_getter.assert_not_called()
+ legacy_getter.assert_not_called()
+ monkeypatch.setattr(tables, "recover_table_region", lambda *_args, **_kwargs: None)
+ summary = tables._apply_native_txt_table_priority(
+ [[{"type": "table", "bbox": [0.0, 0.0, 1.0, 1.0]}]],
+ [[layout]],
+ [page],
+ images,
+ effort="high",
+ page_text_geometries=geometries,
+ page_vector_geometries=vectors,
+ page_snapshots=cache,
+ )
+ assert summary.errors == 0 and summary.total == 1
+ assert geometries == [None] and vectors == [None]
+ full = cache[0].full_snapshot
+ assert full is not None
+ captured = []
+ original = content.prepare_text_evidence
+
+ def prepare(*args: Any, **kwargs: Any) -> Any:
+ """确认正文直接走 snapshot 参数,保留真实 DocVortex 证据计算。"""
+ assert kwargs.get("snapshot") is full and "geometry" not in kwargs
+ result = original(*args, **kwargs)
+ captured.append(result.geometry)
+ return result
+
+ def fill(*args: Any, page_text_geometry: Any, **kwargs: Any) -> list:
+ """字符回填使用证据联合物化的同一几何,禁止再次打开文本页。"""
+ assert page_text_geometry is captured[0]
+ return []
+
+ monkeypatch.setattr(content, "prepare_text_evidence", prepare)
+ monkeypatch.setattr(content, "_fill_native_pdf_text_spans", fill)
+ monkeypatch.setattr(content, "_group_page_spans_by_block", lambda *_: {})
+ monkeypatch.setattr(content, "_apply_window_post_ocr", lambda *_: None)
+ monkeypatch.setattr(content, "_apply_block_content_and_line_metadata", lambda *_: None)
+ monkeypatch.setattr(content, "apply_text_evidence", lambda *_: None)
+ content._fill_window_block_content_and_lines(
+ images,
+ [page],
+ [[]],
+ [[]],
+ [[]],
+ "txt",
+ "high",
+ set(),
+ MagicMock(),
+ geometries,
+ page_vector_geometries=vectors,
+ page_snapshots=cache,
+ )
+ assert geometries[0] is captured[0]
+ assert cache == [None]
+ owner_getter.assert_called_once_with()
+ full_getter.assert_called_once_with()
+ legacy_getter.assert_not_called()
+
+
+def test_explicit_geometry_mutation_wins_over_cached_owner(monkeypatch: pytest.MonkeyPatch) -> None:
+ """已经提供的可变字符即使伴随 owned 缓存也必须原样交给表格入口。"""
+ with PDFDocument(_pdf()) as document, Image.new("RGB", (200, 200)) as image:
+ page = document[0]
+ owner = _require_owned(page)
+ geometry = page.get_chars_with_geometry()
+ geometry.chars[0]["char"] = "changed"
+ cache = [snapshots._PageSnapshotEntry(ref(page), owner)]
+ captured = []
+ original = tables.prepare_table_page
+
+ def prepare(*args: Any, **kwargs: Any) -> Any:
+ """保留显式对象身份和修改,不能以旧 snapshot 偷换它。"""
+ assert kwargs["geometry"] is geometry and "snapshot" not in kwargs
+ assert kwargs["geometry"].chars[0]["char"] == "changed"
+ result = original(*args, **kwargs)
+ captured.append(result)
+ return result
+
+ monkeypatch.setattr(tables, "prepare_table_page", prepare)
+ monkeypatch.setattr(tables, "recover_table_region", lambda *_args, **_kwargs: None)
+ tables._apply_native_txt_table_priority(
+ [[{"type": "table", "bbox": [0.0, 0.0, 1.0, 1.0]}]],
+ [[]],
+ [page],
+ [{"img_pil": image, "scale": 1}],
+ effort="high",
+ page_text_geometries=[geometry],
+ page_snapshots=cache,
+ )
+ assert captured[0].geometry is geometry
+ snapshots.clear_page_snapshot_cache(cache)
+
+
+def test_window_close_releases_payload_even_when_entry_is_still_referenced() -> None:
+ """关闭窗口必须清除条目中的强引用,不只清空外层列表。"""
+ with PDFDocument(_pdf()) as document:
+ page = document[0]
+ owner, full = _Payload(), _Payload()
+ owner_ref, full_ref = ref(owner), ref(full)
+ entry = snapshots._PageSnapshotEntry(ref(page), owner, full)
+ cache = [entry]
+ state = _state(page, cache)
+ del owner, full
+ assert owner_ref() is not None and full_ref() is not None
+ state.close()
+ assert owner_ref() is None and full_ref() is None
+ assert entry.text_owner is None and entry.full_snapshot is None and cache == []
+
+
+def test_prepare_failure_releases_snapshot_cache(monkeypatch: pytest.MonkeyPatch) -> None:
+ """准备尚未返回 state 时失败也释放 owned 强引用并关闭已渲染图片。"""
+ with PDFDocument(_pdf()) as document:
+ page = document[0]
+ owner = _Payload()
+ owner_ref = ref(owner)
+ entry = snapshots._PageSnapshotEntry(ref(page), owner)
+ cache = [entry]
+ del owner
+ monkeypatch.setattr(window, "_get_window_pdf_pages", lambda *_: [page])
+ monkeypatch.setattr(window, "create_page_snapshot_cache", lambda *_args, **_kwargs: cache)
+ image = Image.new("RGB", (10, 10))
+ monkeypatch.setattr(window, "load_images_from_pdf_bytes_range", lambda **_: [{"img_pil": image, "scale": 1}])
+ model = MagicMock()
+ model.layout_model.batch_predict.side_effect = RuntimeError("layout failed")
+ with pytest.raises(RuntimeError, match="layout failed"):
+ window._prepare_pdf_window(
+ b"",
+ document,
+ window._ProcessingWindow(0, 1, 0, 0),
+ page_count=1,
+ effort="high",
+ parse_mode="txt",
+ hybrid_model=model,
+ )
+ assert cache == [] and owner_ref() is None
+
+
+def test_async_cancellation_releases_owned_window(monkeypatch: pytest.MonkeyPatch) -> None:
+ """VLM 等待期间取消,原有 finally 路径须清空快照并释放数据。"""
+ with PDFDocument(_pdf()) as document:
+ page = document[0]
+ owner = _Payload()
+ owner_ref = ref(owner)
+ cache = [snapshots._PageSnapshotEntry(ref(page), owner)]
+ state = _state(page, cache)
+ del owner
+ monkeypatch.setattr(window, "_prepare_locked_window", lambda *_args, **_kwargs: state)
+ monkeypatch.setattr(window, "_inference_options", lambda *_args: {})
+ monkeypatch.setattr(window, "get_document_render_session", lambda *_args: None)
+ monkeypatch.setattr(window, "trim_process_heap", lambda: None)
+
+ async def run() -> None:
+ """等待推理真正开始再取消,避免只覆盖尚未取得资源的情况。"""
+ entered = asyncio.Event()
+
+ async def infer(**kwargs: Any) -> None:
+ """模拟持有窗口的远端推理等待。"""
+ entered.set()
+ await asyncio.Event().wait()
+
+ predictor = MagicMock()
+ predictor.aio_batch_extract_with_layout = AsyncMock(side_effect=infer)
+ task = asyncio.create_task(
+ window.aio_process_pdf_windows(
+ b"",
+ document,
+ effort="high",
+ parse_mode="txt",
+ image_analysis=False,
+ hybrid_model=MagicMock(),
+ vlm_predictor=predictor,
+ )
+ )
+ await asyncio.wait_for(entered.wait(), 5)
+ task.cancel()
+ with pytest.raises(asyncio.CancelledError):
+ await task
+
+ asyncio.run(run())
+ assert cache == [] and owner_ref() is None
+
+
+def test_standard_text_does_not_eagerly_group_lines(monkeypatch: pytest.MonkeyPatch) -> None:
+ """普通无旋转文字即使进入回填函数也不提前生成基础行。"""
+ page = MagicMock()
+ page.get_char_count.return_value = 1
+ blocked = MagicMock(side_effect=AssertionError("eager grouping"))
+ monkeypatch.setattr(native, "get_lines_from_chars", blocked)
+ char = {"char": "A", "char_idx": 0, "rotation": 0.0, "bbox": Bbox([0.0, 0.0, 5.0, 10.0]), "font": {}}
+ assert native.txt_spans_extract(page, [], object(), 1.0, [], [], page_chars=[char]) == []
+ blocked.assert_not_called()
+
+
+def test_rotated_and_vertical_fill_share_lazy_grouping(monkeypatch: pytest.MonkeyPatch) -> None:
+ """局部旋转筛选和竖排回填共用一次基于真实可变字符的组行。"""
+ chars = [
+ {"char": "A", "char_idx": 0, "rotation": 0.0, "bbox": Bbox([0.0, 0.0, 5.0, 10.0]), "font": {}},
+ {"char": "B", "char_idx": 1, "rotation": 0.1, "bbox": Bbox([5.0, 0.0, 10.0, 10.0]), "font": {}},
+ ]
+ grouped = [{"bbox": Bbox([30.0, 0.0, 35.0, 100.0]), "rotation": 0.0, "spans": [{"text": "AB", "chars": chars}]}]
+ reader = MagicMock(return_value=grouped)
+ monkeypatch.setattr(native, "get_lines_from_chars", reader)
+ monkeypatch.setattr(native, "fill_char_in_spans", lambda *_args, **_kwargs: [])
+ monkeypatch.setattr(native, "_prepare_post_ocr_spans", lambda _needed, spans, *_: spans)
+ page = MagicMock()
+ page.get_char_count.return_value = 2
+ spans = [
+ _AnalyzeSpan(ContentType.TEXT, (0.0, 0.0, 20.0, 10.0)),
+ _AnalyzeSpan(ContentType.TEXT, (0.0, 15.0, 20.0, 25.0)),
+ _AnalyzeSpan(ContentType.TEXT, (30.0, 0.0, 35.0, 100.0)),
+ ]
+ native.txt_spans_extract(
+ page, spans, object(), 1.0, [(0.0, 0.0, 200.0, 200.0, None, None, None, BlockType.TEXT)], [], page_chars=chars
+ )
+ reader.assert_called_once_with(chars)
+ assert spans[2].content == "AB"
+
+
+def test_raw_character_limit_precedes_owned_snapshot(monkeypatch: pytest.MonkeyPatch) -> None:
+ """正文继续按原始字符数限制回退,不先创建快照或用去重后的数量替代。"""
+ with PDFDocument(_pdf()) as document, Image.new("RGB", (200, 200)) as image:
+ page = document[0]
+ monkeypatch.setattr(page, "get_char_count", lambda: native.MAX_NATIVE_TEXT_CHARS_PER_PAGE + 1)
+ blocked = MagicMock(side_effect=AssertionError("high character count opened owned snapshot"))
+ monkeypatch.setattr(page, "get_text_snapshot", blocked)
+ monkeypatch.setattr(content, "prepare_text_evidence", blocked)
+ monkeypatch.setattr(content, "_fill_native_pdf_text_spans", lambda *_args, **_kwargs: [])
+ monkeypatch.setattr(content, "_group_page_spans_by_block", lambda *_: {})
+ monkeypatch.setattr(content, "_apply_window_post_ocr", lambda *_: None)
+ monkeypatch.setattr(content, "_apply_block_content_and_line_metadata", lambda *_: None)
+ monkeypatch.setattr(content, "apply_text_evidence", lambda *_: None)
+ cache = [None]
+ content._fill_window_block_content_and_lines(
+ [{"img_pil": image, "scale": 1.0}],
+ [page],
+ [[]],
+ [[]],
+ [[]],
+ "txt",
+ "xhigh",
+ set(),
+ MagicMock(),
+ [None],
+ page_snapshots=cache,
+ )
+ assert cache == [None]
+ blocked.assert_not_called()