Transforms complex documents like PDFs and Office docs into LLM-ready markdown/JSON for your Agentic workflows.
Python ai4sciencedocument-analysisdocxextract-datalayout-analysisocrparserpdfpdf-converterpdf-extractor-llmpdf-extractor-pretrainpdf-extractor-ragpdf-parserpptxpythonxlsx
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.pynew file mode 100644index 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.pyindex 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_detfrom ....model.runtime.contracts import AtomicModelNamefrom ....model.runtime.hybrid import HybridLocalModelContext, run_ocr_inferencefrom ....types import RAW_ALGORITHM, RAW_FORMULA_NUMBER, RAW_PHONETIC, BBox, BlockType+from .snapshots import PageSnapshotCache, get_page_snapshot_entryfrom .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 Nonevector_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_geometrynative_page_size = table_page.page_sizerender_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_itemsdiff --git a/mineru/backend/analysis/pdf/text/content.py b/mineru/backend/analysis/pdf/text/content.pyindex 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_contentsfrom docvortex.document.pdf import PDFPage, PDFPageTextGeometry, PDFPageVectorGeometry, get_lines_from_charsfrom PIL import Image+from ..snapshots import PageSnapshotCache, get_page_snapshot_entry+from .....model.ocr.image import rotate_vertical_crop_if_neededfrom .....model.ocr.results import OcrConfidencefrom .....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.geometryif 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] = Noneblock_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.pyindex 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.charstight_bboxes = page_text_geometry.tight_bboxesorigins = 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):continuediff --git a/mineru/backend/analysis/pdf/window.py b/mineru/backend/analysis/pdf/window.pyindex 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_cachefrom .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] | Nonepage_vector_geometries: list[PDFPageVectorGeometry | None] | None = None+ page_snapshots: PageSnapshotCache | None = Nonedef 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 = Nonepage_vector_geometries: list[PDFPageVectorGeometry | None] | None = None+ page_snapshots: PageSnapshotCache | None = Nonetry: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_modelif 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)raisefinally: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.pynew file mode 100644index 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()