Skip to content

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

33.1 KB
Raw Blame
# Copyright (c) Opendatalab. All rights reserved.
"""PDF 处理窗口、资源生命周期和窗口内阶段编排。"""

from __future__ import annotations

import asyncio
from collections.abc import Callable
from dataclasses import dataclass
from typing import TYPE_CHECKING, Any, Literal

if TYPE_CHECKING:
    from docvortex.document.pdf import PDFRenderSession
    from PIL.Image import Image
    from ....model.vlm.contracts import VlmPredictor
    from ....model.vlm.text_recognition import TextRecognitionResult
    from .inline_recognition import InlineRecognitionBatch

import numpy as np
from docvortex.assets import image_size as _normalize_page_size
from docvortex.document.pdf import PDFDocument, PDFPage, PDFPageTextGeometry, PDFPageVectorGeometry
from docvortex.document.pdf.visuals import attach_visual_block_images as _attach_visual_block_images
from docvortex.document.pdf.visuals import attach_visual_block_images_from_pdf
from loguru import logger

from ....utils.timing import stage_timer

from ....model.runtime.execution import local_model_stage
from ....utils.async_utils import drain_future, run_sync
from ....model.runtime.memory import trim_process_heap
from ..contracts import AnalyzeEffort
from .constants import (
    BATCH_RATIO,
    LAYOUT_BASE_BATCH_SIZE,
    MFR_BASE_BATCH_SIZE,
    NOT_EXTRACT_TYPES,
    PIPELINE_DET_TYPE,
)
from .images import (
    get_document_render_session,
    get_load_images_threads,
    get_load_images_timeout,
    load_images_from_pdf_bytes_range,
)
from .layout import (
    _build_vl_style_layout_blocks,
    _collect_table_items,
    _convert_vlm_results_to_model_list,
    _normalize_xhigh_vlm_blocks,
)
from .normalization import _apply_layout_title_split
from .snapshots import PageSnapshotCache, clear_page_snapshot_cache, create_page_snapshot_cache
from .visual_containers import supplement_missing_image_block_containers as _supplement_missing_image_block_containers

if TYPE_CHECKING:
    from ....model.runtime.hybrid import HybridLocalModelContext


def _configured_window_size(default: int = 64) -> int:
    """读取 PDF 分析窗口大小,非法配置回退到正整数默认值。"""
    import os

    raw_value = os.getenv("MINERU_PROCESSING_WINDOW_SIZE")
    if raw_value is None:
        return default
    try:
        return max(1, int(raw_value))
    except ValueError:
        logger.warning(f"Invalid MINERU_PROCESSING_WINDOW_SIZE value: {raw_value}, use default {default}")
        return default


@dataclass(frozen=True)
class _ProcessingWindow:
    """记录单个 Hybrid 处理窗口的页码范围。"""

    index: int
    total: int
    start: int
    end: int


def _build_processing_windows(page_count: int, configured_window_size: int) -> list[_ProcessingWindow]:
    """根据页数和配置窗口大小生成稳定的 Hybrid 分段处理计划。"""
    effective_window_size = min(page_count, configured_window_size) if page_count else 0
    if effective_window_size <= 0:
        return []

    total_windows = (page_count + effective_window_size - 1) // effective_window_size
    return [
        _ProcessingWindow(
            index=window_index,
            total=total_windows,
            start=window_start,
            end=min(page_count - 1, window_start + effective_window_size - 1),
        )
        for window_index, window_start in enumerate(range(0, page_count, effective_window_size))
    ]


def _get_window_pdf_pages(pdf_doc: PDFDocument, window: _ProcessingWindow) -> list[PDFPage]:
    """按窗口闭区间获取对应的 PDFPage 对象,供窗口内后续处理复用。"""
    return [pdf_doc[page_idx] for page_idx in range(window.start, window.end + 1)]


def _log_processing_window_plan(page_count: int, configured_window_size: int, total_windows: int) -> None:
    """输出 Hybrid 分段处理计划日志,避免同步和异步入口文案漂移。"""
    logger.info(
        f"Hybrid processing-window run. page_count={page_count}, "
        f"window_size={configured_window_size}, total_windows={total_windows}"
    )


def _log_processing_window(window: _ProcessingWindow, page_count: int, image_count: int) -> None:
    """输出单个 Hybrid 处理窗口的页码范围日志。"""
    logger.info(
        f"Hybrid processing window {window.index + 1}/{window.total}: "
        f"pages {window.start + 1}-{window.end + 1}/{page_count} "
        f"({image_count} pages)"
    )


def _close_images(images_list: list[dict[str, Any]]) -> None:
    """尽力关闭窗口内全部 PIL 图片,确保异常路径也能释放图像资源。"""
    for image_dict in images_list or []:
        pil_img = image_dict.get("img_pil")
        if pil_img is not None:
            try:
                pil_img.close()
            except Exception:
                pass


def _process_flash_ocr(
    images_list: list[dict[str, Any]],
    pdf_pages: list[PDFPage],
    model_list: list[list[dict[str, Any]]],
    local_model_context: HybridLocalModelContext,
    images_layout_res: list[list[dict[str, Any]]],
    *,
    np_images: list[np.ndarray] | None = None,
) -> list[list[dict[str, Any]]]:
    """使用本地 OCR 为 Flash layout block 填充正文和表格内容。"""
    from .ocr import _apply_ocr_rec_results, _ocr_det
    from .tables import _fill_flash_ocr_table_contents
    from .text.content import _fill_window_block_content_and_lines, _validate_text_formula_window_inputs

    _validate_text_formula_window_inputs(
        images_list,
        pdf_pages,
        model_list,
        images_layout_res,
    )

    if np_images is None:
        np_images = [np.asarray(image_dict["img_pil"]).copy() for image_dict in images_list]
    empty_formula_list: list[list[dict[str, Any]]] = [[] for _ in model_list]
    with stage_timer("pdf.ocr_detection"):
        ocr_res_list = _ocr_det(
            local_model_context,
            np_images,
            model_list,
            empty_formula_list,
            True,
            PIPELINE_DET_TYPE,
        )
    with stage_timer("pdf.ocr_recognition"):
        _apply_ocr_rec_results(local_model_context, ocr_res_list)
    with stage_timer("pdf.text_fill"):
        model_list = _fill_window_block_content_and_lines(
            images_list,
            pdf_pages,
            model_list,
            empty_formula_list,
            ocr_res_list,
            "ocr",
            "flash",
            PIPELINE_DET_TYPE,
            local_model_context,
        )
    _fill_flash_ocr_table_contents(
        images_list,
        model_list,
        local_model_context,
    )
    return model_list


def _process_text_and_formulas(
    images_list: list[dict[str, Any]],
    pdf_pages: list[PDFPage],
    model_list: list[list[dict[str, Any]]],
    parse_mode: Literal["txt", "ocr"],
    effort: Literal["medium", "high", "xhigh"],
    local_model_context: HybridLocalModelContext,
    images_layout_res: list[list[dict[str, Any]]],
    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,
    recognized_inline_formulas: list[list[dict[str, Any]]] | None = None,
) -> list[list[dict[str, Any]]]:
    """在当前窗口内完成 OCR、公式、原生文本及 block 行信息回填。"""
    from .formulas import (
        _apply_medium_display_formula_results,
        _apply_medium_formula_number_ocr,
        _build_formula_inputs,
        _split_formula_results,
        optimize_hybrid_formula_number_blocks,
    )
    from .ocr import _apply_ocr_rec_results, _build_ocr_det_type_and_mfr_enable, _ocr_det
    from .tables import _apply_medium_table_recognition
    from .text.content import _fill_window_block_content_and_lines, _validate_text_formula_window_inputs


    _validate_text_formula_window_inputs(
        images_list,
        pdf_pages,
        model_list,
        images_layout_res,
    )
    images_pil_list = [image_dict["img_pil"] for image_dict in images_list]

    # 遍历model_list,对文本块截图交由OCR识别
    # 根据 parse_mode 和 effort 决定需要ocr的文本块的类型以及只开det还是det+rec
    ocr_det_type, mfr_enable = _build_ocr_det_type_and_mfr_enable(
        parse_mode=parse_mode,
        effort=effort,
    )

    # 窗口持有独立页图数组;只有直接调用本阶段且未提供数组时才构建。
    if np_images is None:
        np_images = [np.asarray(pil_image).copy() for pil_image in images_pil_list]

    mfd_res = _build_formula_inputs(images_layout_res)
    images_formula_list = mfd_res
    interline_enable = effort == "medium"

    # high/xhigh TXT 的 VLM 与局部 MFR 回退已在窗口阶段完成,不能重新识别成功切片。
    if effort in {"high", "xhigh"} and parse_mode == "txt":
        if recognized_inline_formulas is None:
            raise ValueError("High/Xhigh TXT requires window inline recognition results")
        images_formula_list = recognized_inline_formulas

    # 只有 medium 在此阶段运行完整 MFR;OCR 遮罩始终使用原始 mfd_res。
    if mfr_enable:
        mfr_inputs = mfd_res
        # 全部被过滤时保持逐页空结果,不能让原始表内公式重新进入正文 sidecar。
        images_formula_list = [[] for _ in mfd_res]
        if any(mfr_inputs):
            with stage_timer("pdf.formulas"):
                images_formula_list = local_model_context.mfr_model.batch_predict(
                    mfr_inputs,
                    np_images,
                    batch_size=BATCH_RATIO * MFR_BASE_BATCH_SIZE,
                    interline_enable=interline_enable,
                )

    inline_formula_list, display_formula_list = _split_formula_results(images_formula_list)
    if effort == "medium":
        # 表格解析必须早于正文行填充,确保表内图片和行内公式只由表格模型消费一次。
        with stage_timer("pdf.table_recognition"):
            _apply_medium_table_recognition(
                local_model_context,
                model_list,
                inline_formula_list,
                np_images,
            )
        # 将行间公式span回填入block
        _apply_medium_display_formula_results(
            model_list,
            display_formula_list,
            images_pil_list,
        )
        # 使用ocr识别行间公式标号
        with stage_timer("pdf.formula_numbers"):
            _apply_medium_formula_number_ocr(
                local_model_context,
                model_list,
                np_images,
            )

    # 行间公式标号回填到block
    for page_model_list in model_list:
        page_model_list[:] = optimize_hybrid_formula_number_blocks(page_model_list)

    need_rec_img = parse_mode == "ocr" and effort == "medium"
    # vlm没有执行ocr,需要ocr_det
    with stage_timer("pdf.ocr_detection"):
        ocr_res_list = _ocr_det(
            local_model_context,
            np_images,
            model_list,
            mfd_res,
            need_rec_img,
            ocr_det_type,
        )

    # 如果有rec_img则做ocr_rec
    if need_rec_img:
        with stage_timer("pdf.ocr_recognition"):
            _apply_ocr_rec_results(local_model_context, ocr_res_list)

    with stage_timer("pdf.text_fill"):
        return _fill_window_block_content_and_lines(
            images_list,
            pdf_pages,
            model_list,
            inline_formula_list,
            ocr_res_list,
            parse_mode,
            effort,
            ocr_det_type,
            local_model_context,
            page_text_geometries,
            page_vector_geometries=page_vector_geometries,
            **({"page_snapshots": page_snapshots} if page_snapshots is not None else {}),
        )


@dataclass
class _WindowInputs:
    """在准备、推理与回填阶段之间显式传递当前窗口资源。"""

    window: _ProcessingWindow
    images_list: list[dict[str, Any]]
    window_pages: list[PDFPage]
    images_pil_list: list[Image]
    np_images: list[np.ndarray]
    images_layout_res: list[list[dict[str, Any]]]
    vl_style_layout_blocks: list[list[dict[str, Any]]]
    high_vlm_blocks: list[list[dict[str, Any]]]
    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
    inline_recognition: InlineRecognitionBatch | None = None
    inline_outputs: list[TextRecognitionResult] | None = None

    def close(self) -> None:
        """推理及回填真正退出后关闭图片,仅清除本层拥有的容器。"""
        try:
            try:
                if self.inline_recognition is not None:
                    self.inline_recognition.close()
            finally:
                _close_images(self.images_list)
        finally:
            self.inline_outputs = None
            self.inline_recognition = None
            self.images_list.clear()
            self.images_pil_list.clear()
            self.np_images.clear()
            self.window_pages.clear()
            if self.page_text_geometries is not None:
                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(
    file_bytes: bytes,
    document: PDFDocument,
    window: _ProcessingWindow,
    *,
    page_count: int,
    effort: AnalyzeEffort,
    parse_mode: Literal["txt", "ocr"],
    hybrid_model: HybridLocalModelContext,
) -> _WindowInputs:
    """渲染并准备布局、原生表格和 VLM 输入;失败时由本阶段关闭图片。"""
    from .tables import _apply_native_txt_table_priority, _apply_table_orientations, _split_native_high_table_blocks

    images_list: list[dict[str, Any]] = []
    images_pil_list = []
    np_images = []
    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"):
            images_list = load_images_from_pdf_bytes_range(
                pdf_bytes=file_bytes,
                document=document,
                start_page_id=window.start,
                end_page_id=window.end,
                image_type="pil_img",
            )
        if len(window_pages) != len(images_list):
            raise ValueError("Hybrid processing window PDF page count does not match image count")
        images_pil_list = [image_dict["img_pil"] for image_dict in images_list]
        _log_processing_window(window, page_count, len(images_pil_list))
        page_text_geometries = (
            [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:
            raise ValueError("Hybrid local model context is required outside Flash TXT mode")
        np_images = [np.asarray(pil_image).copy() for pil_image in images_pil_list]
        with stage_timer("pdf.layout"):
            images_layout_res = local_model_context.layout_model.batch_predict(
                images_pil_list, batch_size=min(8, BATCH_RATIO * LAYOUT_BASE_BATCH_SIZE)
            )

        # 使用小模型layout时对layout的表格做旋转检测
        if effort in ["flash", "medium", "high"]:
            table_items = _collect_table_items(images_layout_res, np_images)
            if table_items:
                with stage_timer("pdf.table_orientation"):
                    _apply_table_orientations(
                        table_items,
                        parse_mode,
                        window_pages,
                        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)

        if parse_mode == "txt" and effort in {"medium", "high"}:
            with stage_timer("pdf.native_tables"):
                native_table_summary = _apply_native_txt_table_priority(
                    vl_style_layout_blocks,
                    images_layout_res,
                    window_pages,
                    images_list,
                    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 = {
                    "effort": effort,
                    "total": native_table_summary.total,
                    "accepted": native_table_summary.accepted,
                    "complex_fallbacks": native_table_summary.complex_fallbacks,
                    "rejected": native_table_summary.rejected,
                    "errors": native_table_summary.errors,
                    "removed_internal_text": native_table_summary.removed_internal_text,
                    "removed_formula_blocks": native_table_summary.removed_formula_blocks,
                    "removed_formula_layout_items": native_table_summary.removed_formula_layout_items,
                }
                logger.bind(native_table_priority=native_table_stats).debug(
                    "Hybrid native table priority. "
                    f"effort={native_table_stats['effort']}, total={native_table_stats['total']}, "
                    f"accepted={native_table_stats['accepted']}, "
                    f"complex_fallbacks={native_table_stats['complex_fallbacks']}, "
                    f"rejected={native_table_stats['rejected']}, "
                    f"errors={native_table_stats['errors']}, "
                    f"removed_internal_text={native_table_stats['removed_internal_text']}, "
                    f"removed_formula_blocks={native_table_stats['removed_formula_blocks']}, "
                    f"removed_formula_layout_items={native_table_stats['removed_formula_layout_items']}"
                )

        high_vlm_blocks = vl_style_layout_blocks
        accepted_native_tables = []
        if parse_mode == "txt" and effort == "high":
            high_vlm_blocks, accepted_native_tables = _split_native_high_table_blocks(vl_style_layout_blocks)
        return _WindowInputs(
            window,
            images_list,
            window_pages,
            images_pil_list,
            np_images,
            images_layout_res,
            vl_style_layout_blocks,
            high_vlm_blocks,
            accepted_native_tables,
            page_text_geometries,
            page_vector_geometries,
            page_snapshots=page_snapshots,
        )
    except BaseException:
        try:
            _close_images(images_list)
        finally:
            images_list.clear()
            images_pil_list.clear()
            np_images.clear()
            if page_text_geometries is not None:
                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()


def _prepare_window_result(
    state: _WindowInputs,
    window_model_list: list[Any],
    *,
    effort: AnalyzeEffort,
    parse_mode: Literal["txt", "ocr"],
) -> list[list[dict[str, Any]]]:
    """先确定最终版面与原生表格归属,再准备表外行内切片。"""
    from .inline_recognition import prepare_inline_recognition
    from .tables import _restore_native_high_table_blocks

    if parse_mode == "txt" and effort == "high":
        window_model_list = _restore_native_high_table_blocks(window_model_list, state.accepted_native_tables)
    if effort in {"high", "xhigh"}:
        window_model_list = _convert_vlm_results_to_model_list(window_model_list)
    if effort == "xhigh":
        _normalize_xhigh_vlm_blocks(window_model_list)
        _apply_layout_title_split(
            window_model_list,
            state.images_layout_res,
            [_normalize_page_size(image) for image in state.images_pil_list],
        )
    if parse_mode == "txt" and effort in {"high", "xhigh"}:
        state.inline_recognition = prepare_inline_recognition(
            state.images_layout_res, window_model_list, state.images_pil_list
        )
        state.inline_outputs = []
    return window_model_list


def _finish_pdf_window(
    state: _WindowInputs,
    window_model_list: list[list[dict[str, Any]]],
    *,
    effort: AnalyzeEffort,
    parse_mode: Literal["txt", "ocr"],
    hybrid_model: HybridLocalModelContext,
) -> list[list[dict[str, Any]]]:
    """在本地模型锁内完成失败片段回退、正文回填与视觉素材。"""
    from .formulas import optimize_hybrid_formula_number_blocks
    from .inline_recognition import finish_inline_recognition
    from .ocr import _apply_seal_ocr

    images_list = state.images_list
    window_pages = state.window_pages
    np_images = state.np_images
    images_layout_res = state.images_layout_res
    vl_style_layout_blocks = state.vl_style_layout_blocks
    page_text_geometries = state.page_text_geometries
    window = state.window
    local_model_context = hybrid_model
    inline_options: dict[str, list[list[dict[str, Any]]]] = {}
    if state.inline_recognition is not None:
        if state.inline_outputs is None:
            raise ValueError("Missing window inline recognition outputs")
        inline_options["recognized_inline_formulas"] = finish_inline_recognition(
            state.inline_recognition, state.inline_outputs, hybrid_model, np_images, page_offset=window.start
        )

    if effort == "flash":
        window_model_list = _process_flash_ocr(
            images_list,
            window_pages,
            window_model_list,
            local_model_context,
            images_layout_res,
            np_images=np_images,
        )
        # Flash OCR 在表内对象清理后复用统一公式编号合并,确保视觉裁图包含编号区域。
        for page_model_list in window_model_list:
            page_model_list[:] = optimize_hybrid_formula_number_blocks(page_model_list)
    else:
        window_model_list = _process_text_and_formulas(
            images_list,
            window_pages,
            window_model_list,
            parse_mode,
            effort,
            local_model_context,
            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,
            **inline_options,
        )

    if effort in {"medium", "high"}:
        with stage_timer("pdf.seals"):
            _apply_seal_ocr(local_model_context, window_model_list, np_images)
    elif effort == "xhigh":
        _supplement_missing_image_block_containers(
            window_model_list,
            vl_style_layout_blocks,
        )

    with stage_timer("pdf.image_assets"):
        _attach_visual_block_images(
            window_model_list,
            images_list,
            page_start_index=window.start,
        )
    return window_model_list


def _inference_options(
    state: _WindowInputs,
    effort: AnalyzeEffort,
    parse_mode: Literal["txt", "ocr"],
    image_analysis: bool,
) -> dict[str, Any]:
    """生成同步、异步共同使用的抽取参数,保持 TXT 类型过滤与图片开关。"""
    options = {"images": state.images_pil_list, "image_analysis": image_analysis if effort == "xhigh" else False}
    if effort == "high":
        options["blocks_list"] = state.high_vlm_blocks
    if parse_mode == "txt":
        options["not_extract_list"] = NOT_EXTRACT_TYPES
    return options


def _process_pdf_window(
    file_bytes: bytes,
    document: PDFDocument,
    window: _ProcessingWindow,
    *,
    page_count: int,
    effort: AnalyzeEffort,
    parse_mode: Literal["txt", "ocr"],
    image_analysis: bool,
    hybrid_model: HybridLocalModelContext | None,
    vlm_predictor: VlmPredictor | None,
) -> list[list[dict[str, Any]]]:
    """同步编排共享窗口阶段,在 VLM 等待期间释放本地模型执行锁。"""
    if hybrid_model is None:
        raise ValueError("Hybrid local model context is required outside Flash TXT mode")
    with local_model_stage(hybrid_model.device):
        state = _prepare_pdf_window(
            file_bytes,
            document,
            window,
            page_count=page_count,
            effort=effort,
            parse_mode=parse_mode,
            hybrid_model=hybrid_model,
        )
    try:
        result = state.vl_style_layout_blocks
        if effort in {"high", "xhigh"}:
            if vlm_predictor is None:
                raise ValueError("VLM predictor is required for high/xhigh")
            options = _inference_options(state, effort, parse_mode, image_analysis)
            if effort == "high":
                result = vlm_predictor.batch_extract_with_layout(**options)
            else:
                result = vlm_predictor.batch_two_step_extract(**options)
        result = _prepare_window_result(state, result, effort=effort, parse_mode=parse_mode)
        if state.inline_recognition is not None and state.inline_recognition.crops:
            with stage_timer("pdf.inline_vlm"):
                state.inline_outputs = vlm_predictor.batch_recognize_text(state.inline_recognition.images)
        with local_model_stage(hybrid_model.device):
            return _finish_pdf_window(state, result, effort=effort, parse_mode=parse_mode, hybrid_model=hybrid_model)
    finally:
        state.close()


def _prepare_locked_window(
    file_bytes: bytes,
    document: PDFDocument,
    window: _ProcessingWindow,
    *,
    page_count: int,
    effort: AnalyzeEffort,
    parse_mode: Literal["txt", "ocr"],
    hybrid_model: HybridLocalModelContext,
) -> _WindowInputs:
    """在线程内取得和释放本地模型锁,避免事件循环线程等待同步锁。"""
    with local_model_stage(hybrid_model.device):
        return _prepare_pdf_window(
            file_bytes,
            document,
            window,
            page_count=page_count,
            effort=effort,
            parse_mode=parse_mode,
            hybrid_model=hybrid_model,
        )


def _finish_locked_window(
    state: _WindowInputs,
    result: list[Any],
    *,
    effort: AnalyzeEffort,
    parse_mode: Literal["txt", "ocr"],
    hybrid_model: HybridLocalModelContext,
) -> list[list[dict[str, Any]]]:
    """回填阶段与同步入口共用本地模型执行锁。"""
    with local_model_stage(hybrid_model.device):
        return _finish_pdf_window(state, result, effort=effort, parse_mode=parse_mode, hybrid_model=hybrid_model)


async def _run_window_prepare(prepare: Callable[[], None], render_session: PDFRenderSession | None) -> None:
    """取消时先中止会话渲染,再等待准备线程退出,避免文档提前关闭。"""
    if render_session is None:
        return await run_sync(prepare)
    work = asyncio.create_task(asyncio.to_thread(prepare))
    try:
        return await asyncio.shield(work)
    except asyncio.CancelledError:
        cleanup = asyncio.create_task(asyncio.to_thread(render_session.cancel))
        try:
            await drain_future(cleanup)
        finally:
            try:
                await drain_future(work)
            except BaseException:
                pass
        raise


async def aio_process_pdf_windows(
    file_bytes: bytes,
    document: PDFDocument,
    *,
    effort: AnalyzeEffort,
    parse_mode: Literal["txt", "ocr"],
    image_analysis: bool,
    hybrid_model: HybridLocalModelContext,
    vlm_predictor: VlmPredictor,
) -> list[list[dict[str, Any]]]:
    """逐窗口原生异步推理;仅不同文档可交错推进,保留单文档内存上界。"""
    page_count = document.page_count
    window_size = _configured_window_size(default=64)
    windows = _build_processing_windows(page_count, window_size)
    _log_processing_window_plan(page_count, window_size, len(windows))
    model_list = []
    render_session = get_document_render_session(document) if windows else None
    for window in windows:
        state = None
        try:
            # 让资源在外层拥有:准备线程取消后仍需要关闭其成功返回的图片。
            holder: list[_WindowInputs] = []

            def prepare() -> None:
                """显式交接窗口所有权,使取消不会丢失线程返回的资源。"""
                holder.append(
                    _prepare_locked_window(
                        file_bytes,
                        document,
                        window,
                        page_count=page_count,
                        effort=effort,
                        parse_mode=parse_mode,
                        hybrid_model=hybrid_model,
                    )
                )

            try:
                await _run_window_prepare(prepare, render_session)
            finally:
                state = holder[0] if holder else None
            options = _inference_options(state, effort, parse_mode, image_analysis)
            if effort == "high":
                result = await vlm_predictor.aio_batch_extract_with_layout(**options)
            else:
                result = await vlm_predictor.aio_batch_two_step_extract(**options)
            result = await run_sync(_prepare_window_result, state, result, effort=effort, parse_mode=parse_mode)
            if state.inline_recognition is not None and state.inline_recognition.crops:
                with stage_timer("pdf.inline_vlm"):
                    state.inline_outputs = await vlm_predictor.aio_batch_recognize_text(state.inline_recognition.images)
            model_list.extend(
                await run_sync(
                    _finish_locked_window,
                    state,
                    result,
                    effort=effort,
                    parse_mode=parse_mode,
                    hybrid_model=hybrid_model,
                )
            )
        except asyncio.CancelledError:
            if render_session is not None:
                cleanup = asyncio.create_task(asyncio.to_thread(render_session.cancel))
                await drain_future(cleanup)
            raise
        finally:
            if state is not None:
                await run_sync(state.close)
            await run_sync(trim_process_heap)
    return model_list


def process_pdf_windows(
    file_bytes: bytes,
    document: PDFDocument,
    *,
    effort: AnalyzeEffort,
    parse_mode: Literal["txt", "ocr"],
    image_analysis: bool,
    flash_txt_mode: bool,
    hybrid_model: HybridLocalModelContext | None,
    vlm_predictor: VlmPredictor | None,
) -> list[list[dict[str, Any]]]:
    """按固定阶段处理全部 PDF 窗口并返回完整 model-list。"""
    page_count = document.page_count
    model_list: list[list[dict[str, Any]]] = []
    if flash_txt_mode:
        # Flash 原生结果只按视觉块需求补图,不再进入供推理使用的全页渲染窗口。
        from docvortex.analyzers.native import PdfModel
        from docvortex.document.pdf.constants import MODEL_JSON_VISUAL_BLOCK_TYPES

        model_list = PdfModel().predict(document)
        # 纯文本不创建会话输入文件;视觉容器会在引擎补图前折叠为 image。
        needs_images = any(
            block.get("type") in MODEL_JSON_VISUAL_BLOCK_TYPES or block.get("type") == "image_block"
            for page in model_list
            for block in page
        )
        render_session = get_document_render_session(document) if needs_images else None
        attach_visual_block_images_from_pdf(
            document,
            model_list,
            window_size=_configured_window_size(default=64),
            timeout=get_load_images_timeout(),
            threads=get_load_images_threads(),
            **({"session": render_session} if render_session is not None else {}),
        )
        return model_list

    configured_window_size = _configured_window_size(default=64)
    windows = _build_processing_windows(page_count, configured_window_size)
    _log_processing_window_plan(page_count, configured_window_size, len(windows))

    for window in windows:
        try:
            model_list.extend(
                _process_pdf_window(
                    file_bytes,
                    document,
                    window,
                    page_count=page_count,
                    effort=effort,
                    parse_mode=parse_mode,
                    image_analysis=image_analysis,
                    hybrid_model=hybrid_model,
                    vlm_predictor=vlm_predictor,
                )
            )
        finally:
            # 单窗口作用域退出后再回收,避免上一窗口临时数组与下一窗口渲染重叠。
            trim_process_heap()

    return model_list


__all__ = ["process_pdf_windows", "aio_process_pdf_windows"]