Skip to content

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

18.4 KB
Raw Blame
"""验证常驻推理运行时的共享、取消确认和应用租约。"""

from __future__ import annotations

import asyncio
import threading
from types import SimpleNamespace
from concurrent.futures import ThreadPoolExecutor
from typing import Any

import pytest

from mineru.model.runtime.ownership import RuntimeOwner, runtime_owner
from mineru.model.vlm.async_runtime import AsyncVlmPredictor
from mineru.model.vlm.handles import RuntimeHandle
from mineru.utils.async_utils import run_sync


class _AsyncClient:
    """只实现异步推理的引擎替身,记录真实执行循环与并发峰值。"""

    def __init__(self) -> None:
        """在运行时线程内创建同步观测信号和异步阻塞门。"""
        self.loop = asyncio.get_running_loop()
        self.client = SimpleNamespace(health_probe_mode="none")
        self.active = 0
        self.peak = 0
        self.closed = False
        self.block = False
        self.entered = threading.Event()
        self.drained = threading.Event()

    async def aio_batch_extract_with_layout(self, images: list[Any], blocks_list: list[Any], **kwargs: Any) -> list[Any]:
        """逐请求使用传入的共享额度,模拟异步引擎执行与取消后的清理。"""
        assert asyncio.get_running_loop() is self.loop

        async def infer(image: Any) -> Any:
            """模拟一次独立引擎请求,清理期间必须保留并发名额。"""
            async with kwargs["semaphore"]:
                self.active += 1
                self.peak = max(self.peak, self.active)
                self.entered.set()
                try:
                    await asyncio.sleep(60 if self.block else 0.01)
                    return image
                finally:
                    await asyncio.sleep(0.03)
                    self.active -= 1
                    self.drained.set()

        from mineru_vl_utils.vlm_client.utils import gather_tasks

        return await gather_tasks([infer(image) for image in images])

    async def aio_batch_two_step_extract(self, images: list[Any], **kwargs: Any) -> list[Any]:
        """两阶段入口复用同一引擎和请求额度。"""
        return await self.aio_batch_extract_with_layout(images, [], **kwargs)

    def batch_extract_with_layout(self, *args: Any, **kwargs: Any) -> None:
        """一旦误用同步推理立即失败。"""
        raise AssertionError("Synchronous inference must not run")

    async def aclose(self) -> None:
        """关闭只允许发生在所属循环且所有请求已经完成清理。"""
        assert asyncio.get_running_loop() is self.loop
        assert self.active == 0
        self.closed = True


@pytest.fixture
def native_runtime() -> Any:
    """创建可跨线程使用的原生异步运行时并保证用例后关闭。"""
    runtime = AsyncVlmPredictor(lambda: RuntimeHandle(_AsyncClient(), backend="test"), backend="test", max_concurrency=2)
    runtime.wait_ready()
    try:
        yield runtime
    finally:
        runtime.shutdown()


def test_sync_async_and_different_loops_share_engine_and_limit(native_runtime: AsyncVlmPredictor) -> None:
    """同步线程和多个事件循环共享一份引擎及跨文档并发额度。"""

    def invoke(index: int) -> list[int]:
        """交错使用同步入口和不同线程中的异步入口。"""
        if index % 2:
            return asyncio.run(native_runtime.aio_batch_two_step_extract([index]))
        return native_runtime.batch_extract_with_layout([index], [[]])

    with ThreadPoolExecutor(max_workers=8) as executor:
        assert list(executor.map(invoke, range(8))) == [[i] for i in range(8)]
    assert native_runtime._predictor.peak == 2
    assert native_runtime._predictor.active == 0


def test_repeated_cancel_waits_for_engine_cleanup(native_runtime: AsyncVlmPredictor) -> None:
    """重复取消不能提前释放调用方资源,也不能二次打断底层清理。"""
    client = native_runtime._predictor
    client.block = True

    async def run() -> None:
        """取消请求后再次取消外层任务,清理完成之前不得返回。"""
        task = asyncio.create_task(native_runtime.aio_batch_two_step_extract([1]))
        assert await asyncio.to_thread(client.entered.wait, 2)
        task.cancel()
        await asyncio.sleep(0.005)
        task.cancel()
        assert not task.done()
        with pytest.raises(asyncio.CancelledError):
            await task
        assert client.drained.is_set()
        assert client.active == 0

    asyncio.run(run())
    client.block = False
    assert native_runtime.batch_two_step_extract([2]) == [2]


def test_shutdown_drains_active_requests_and_rejects_new(native_runtime: AsyncVlmPredictor) -> None:
    """关闭时等待在途请求真正退出,然后拒绝旧代理继续提交。"""
    client = native_runtime._predictor
    client.block = True
    with ThreadPoolExecutor() as executor:
        future = executor.submit(native_runtime.batch_two_step_extract, [1])
        assert native_runtime._predictor.entered.wait(2)
        native_runtime.shutdown()
        with pytest.raises(asyncio.CancelledError):
            future.result()
    assert client.closed
    assert native_runtime._predictor is None
    assert not native_runtime._thread.is_alive()
    with pytest.raises(RuntimeError, match="shutting down"):
        native_runtime.batch_two_step_extract([2])


def test_runtime_cannot_synchronously_wait_on_itself(native_runtime: AsyncVlmPredictor) -> None:
    """明确拒绝运行时线程内的同步桥接,避免自我等待死锁。"""

    async def nested() -> None:
        """在所属循环中故意调用同步接口。"""
        native_runtime.batch_two_step_extract([1])

    with pytest.raises(RuntimeError, match="runtime thread"):
        native_runtime._call(nested)


def test_application_owners_share_and_release_runtime(monkeypatch: pytest.MonkeyPatch) -> None:
    """一个应用退出不关闭其他应用的引擎,最后租约释放后允许重新构造。"""
    from mineru.model.vlm.runtime import ModelSingleton

    monkeypatch.setattr(ModelSingleton, "_models", {})
    monkeypatch.setattr(
        ModelSingleton, "_create_model", lambda *args, **kwargs: RuntimeHandle(_AsyncClient(), backend="http-client")
    )
    manager = ModelSingleton()
    first, second = RuntimeOwner(), RuntimeOwner()

    def get(owner: RuntimeOwner | None) -> AsyncVlmPredictor:
        """在指定应用或进程级租约中获取同一远程配置。"""
        token = runtime_owner.set(owner)
        try:
            return manager.get_model("http-client", None, "http://unused", max_concurrency=2)
        finally:
            runtime_owner.reset(token)

    try:
        predictor = get(first)
        client = predictor._predictor
        assert get(second) is predictor
        manager.release_owner(first)
        assert predictor.batch_two_step_extract([1]) == [1]
        assert not predictor._predictor.closed
        manager.release_owner(second)
        assert client.closed
        assert predictor._predictor is None
        replacement = get(None)
        assert replacement is not predictor
        third = RuntimeOwner()
        assert get(third) is replacement
        manager.release_owner(third)
        assert not replacement._predictor.closed
        with pytest.raises(RuntimeError, match="owner is closed"):
            get(first)
    finally:
        manager.shutdown()


def test_cancelled_initialization_is_drained_before_owner_release(monkeypatch: pytest.MonkeyPatch) -> None:
    """取消初始化时先等构造线程结束,再释放缓存和模型句柄。"""
    from mineru.model.vlm.runtime import ModelSingleton

    entered, release = threading.Event(), threading.Event()
    clients = []

    def factory(*args: Any, **kwargs: Any) -> RuntimeHandle:
        """模拟无法强行中断的模型初始化。"""
        entered.set()
        assert release.wait(3)
        client = _AsyncClient()
        clients.append(client)
        return RuntimeHandle(client, backend="http-client")

    monkeypatch.setattr(ModelSingleton, "_models", {})
    monkeypatch.setattr(ModelSingleton, "_create_model", factory)
    owner = RuntimeOwner()
    manager = ModelSingleton()

    async def run() -> None:
        """重复取消等待初始化的调用,确认不会留下迟到的模型。"""
        token = runtime_owner.set(owner)
        try:
            task = asyncio.create_task(run_sync(manager.get_model, "http-client", None, "http://unused"))
            assert await asyncio.to_thread(entered.wait, 2)
            task.cancel()
            await asyncio.sleep(0)
            assert not task.done()
            release.set()
            with pytest.raises(asyncio.CancelledError):
                await task
            await run_sync(manager.release_owner, owner)
        finally:
            release.set()
            runtime_owner.reset(token)

    asyncio.run(run())
    assert clients[0].closed
    assert not manager._models


def test_failed_initialization_does_not_poison_cache(monkeypatch: pytest.MonkeyPatch) -> None:
    """初始化失败应退出线程并允许相同配置重新尝试。"""
    from mineru.model.vlm.runtime import ModelSingleton

    def fail(*args: Any, **kwargs: Any) -> None:
        """模拟模型发现或引擎初始化失败。"""
        raise ValueError("initialization failed")

    monkeypatch.setattr(ModelSingleton, "_models", {})
    monkeypatch.setattr(ModelSingleton, "_create_model", fail)
    manager = ModelSingleton()
    with pytest.raises(ValueError, match="initialization failed"):
        manager.get_model("http-client", None, "http://unused")
    assert not manager._models
    monkeypatch.setattr(
        ModelSingleton, "_create_model", lambda *args, **kwargs: RuntimeHandle(_AsyncClient(), backend="http-client")
    )
    try:
        assert manager.get_model("http-client", None, "http://unused").batch_two_step_extract([1]) == [1]
    finally:
        manager.shutdown()


def test_vllm_sync_and_async_names_resolve_to_one_async_engine(monkeypatch: pytest.MonkeyPatch) -> None:
    """同步引擎名称在托管边界规范化,防止初始化两套 vLLM 权重。"""
    from mineru.model.vlm import runtime

    calls = []

    def factory(self: Any, backend: str, *args: Any, **kwargs: Any) -> RuntimeHandle:
        """记录实际请求构造的后端,并拒绝离线同步引擎。"""
        assert backend == "vllm-async-engine"
        calls.append(backend)
        return RuntimeHandle(_AsyncClient(), backend=backend)

    monkeypatch.setattr(runtime.ModelSingleton, "_models", {})
    monkeypatch.setattr(runtime.ModelSingleton, "_create_model", factory)
    monkeypatch.setattr(runtime, "get_device", lambda: "cuda")
    manager = runtime.ModelSingleton()
    try:
        sync = manager.get_model("vllm-engine", "/mock/model", None)
        asynchronous = manager.get_model("vllm-async-engine", "/mock/model", None)
        assert sync is asynchronous
        assert sync.batch_two_step_extract([1]) == [1]
        assert asyncio.run(asynchronous.aio_batch_two_step_extract([2])) == [2]
        assert calls == ["vllm-async-engine"]
    finally:
        manager.shutdown()


def test_real_model_factory_constructs_async_llm_on_owner_loop(monkeypatch: pytest.MonkeyPatch) -> None:
    """真实 MinerU 工厂必须在所属循环构造 AsyncLLM,并只关闭一次自有引擎。"""
    import sys
    from types import ModuleType
    from mineru.model.vlm import runtime

    events = []

    class EngineArgs:
        """保留传给 vLLM 的显式模型构造参数。"""

        def __init__(self, **kwargs: object) -> None:
            """不执行 GPU 分配,只记录配置。"""
            self.options = kwargs

    class Engine:
        """仅替换 vLLM 本身,保留 MinerU 的真实加载与关闭链。"""

        @classmethod
        def from_engine_args(cls, args: EngineArgs) -> Any:
            """要求构造发生在运行中的专属循环,而非调用方线程。"""
            events.append(("load", threading.current_thread().name, asyncio.get_running_loop(), args.options))
            return cls()

        def shutdown(self) -> None:
            """记录自有引擎的唯一关闭动作。"""
            events.append(("close",))

    modules = {
        name: ModuleType(name)
        for name in [
            "vllm",
            "vllm.config",
            "vllm.engine",
            "vllm.engine.arg_utils",
            "vllm.v1",
            "vllm.v1.engine",
            "vllm.v1.engine.async_llm",
        ]
    }
    modules["vllm.config"].CompilationConfig = EngineArgs
    modules["vllm.engine.arg_utils"].AsyncEngineArgs = EngineArgs
    modules["vllm.v1.engine.async_llm"].AsyncLLM = Engine
    for name, module in modules.items():
        monkeypatch.setitem(sys.modules, name, module)
    monkeypatch.setattr(runtime.ModelSingleton, "_models", {})
    monkeypatch.setattr(runtime, "get_device", lambda: "cuda")
    monkeypatch.delenv("OMP_NUM_THREADS", raising=False)
    monkeypatch.setattr(runtime, "mod_kwargs_by_device_type", lambda kwargs, **options: kwargs)
    monkeypatch.setattr(runtime, "enable_custom_logits_processors", lambda: False)
    monkeypatch.setattr(runtime, "set_default_gpu_memory_utilization", lambda: 0.8)
    monkeypatch.setattr(runtime, "MinerUClient", lambda **kwargs: _AsyncClient())
    manager = runtime.ModelSingleton()
    try:
        predictor = manager.get_model("vllm-engine", "/mock/model", None)
        assert predictor.batch_two_step_extract([1]) == [1]
        assert events[0][0:2] == ("load", "mineru-vllm-async-engine")
        assert events[0][3]["model"] == "/mock/model"
        assert manager.get_model("vllm-async-engine", "/mock/model", None) is predictor
    finally:
        manager.shutdown()
    assert [event[0] for event in events] == ["load", "close"]


def test_owner_cleanup_failure_still_closes_other_runtimes(monkeypatch: pytest.MonkeyPatch) -> None:
    """一个连接关闭失败也必须完成其余应用自有运行时的清理。"""
    from mineru.model.vlm.runtime import ModelSingleton

    clients = []

    async def fail_close() -> None:
        """模拟底层传输关闭异常。"""
        raise RuntimeError("close failed")

    def factory(*args: Any, **kwargs: Any) -> RuntimeHandle:
        """仅第一个客户端关闭时失败。"""
        client = _AsyncClient()
        if not clients:
            client.aclose = fail_close
        clients.append(client)
        return RuntimeHandle(client, backend="http-client")

    monkeypatch.setattr(ModelSingleton, "_models", {})
    monkeypatch.setattr(ModelSingleton, "_create_model", factory)
    owner = RuntimeOwner()
    manager = ModelSingleton()
    token = runtime_owner.set(owner)
    try:
        first = manager.get_model("http-client", None, "http://first")
        second = manager.get_model("http-client", None, "http://second")
    finally:
        runtime_owner.reset(token)
    with pytest.raises(RuntimeError, match="close failed"):
        manager.release_owner(owner)
    assert not manager._models
    assert not first._thread.is_alive()
    assert not second._thread.is_alive()
    assert clients[1].closed


@pytest.mark.parametrize("enabled", [False, True])
@pytest.mark.parametrize("async_mode", [False, True])
def test_vllm_runtime_uses_standard_progress_label(
    monkeypatch: pytest.MonkeyPatch,
    capsys: pytest.CaptureFixture[str],
    enabled: bool,
    async_mode: bool,
) -> None:
    """同步桥接和原生异步入口都通过真实高层抽取显示同一文案,不创建嵌套进度。"""
    from PIL import Image
    from mineru_vl_utils import MinerUClient
    from mineru_vl_utils.structs import ContentBlock
    from mineru_vl_utils.vlm_client.vllm_async_engine_client import VllmAsyncEngineVlmClient

    backend = object.__new__(VllmAsyncEngineVlmClient)
    backend.max_concurrency = 2
    from mineru_vl_utils.vlm_client.vllm_health import VllmHealthProbe

    async def check_health() -> None:
        """本测试只验证进度与清理,声明替身引擎健康可用。"""

    backend._health_probe = VllmHealthProbe(check_health)

    async def predict(image: Any, prompt: str = "", **kwargs: Any) -> str:
        """仅替换 GPU 单请求,保持真实异步批处理和布局回填。"""
        return "recognized"

    def create() -> MinerUClient:
        """在运行时线程创建高层客户端,复用已注入的无 GPU 后端。"""
        return MinerUClient(backend="vllm-async-engine", vllm_async_llm=object(), use_tqdm=enabled)

    monkeypatch.setattr(backend, "aio_predict", predict)
    monkeypatch.setattr("mineru_vl_utils.mineru_client.new_vlm_client", lambda **kwargs: backend)
    runtime = AsyncVlmPredictor(
        lambda: RuntimeHandle(create(), backend="vllm-async-engine"), backend="vllm-async-engine", max_concurrency=2
    )
    image = Image.new("RGB", (32, 32))
    blocks = [[ContentBlock("text", [0, 0, 1, 1])]]
    try:
        runtime.wait_ready()
        results = (
            asyncio.run(runtime.aio_batch_extract_with_layout([image], blocks))
            if async_mode
            else runtime.batch_extract_with_layout([image], blocks)
        )
        assert results[0][0].content == "recognized"
        stderr = capsys.readouterr().err
        assert ("VLM Predict" in stderr) is enabled
        assert "External Layout Extraction" not in stderr
        assert "Processed prompts" not in stderr
        if enabled:
            assert "1/1" in stderr
    finally:
        runtime.shutdown()
        image.close()


def test_fatal_runtime_latches_and_rejects_new_inference(native_runtime: AsyncVlmPredictor) -> None:
    """明确引擎死亡锁定本地运行时和所属应用,后续操作不再调用旧引擎。"""
    from mineru.model.vlm.errors import EngineDeadError

    owner = RuntimeOwner()
    native_runtime.owners.add(owner)

    async def fatal() -> None:
        """模拟引擎自身报告死亡。"""
        raise EngineDeadError("dead")

    with pytest.raises(EngineDeadError):
        asyncio.run(native_runtime._acall(fatal))
    assert owner.engine_error == "dead"
    with pytest.raises(EngineDeadError):
        native_runtime.batch_two_step_extract([1])
    assert native_runtime._predictor.active == 0


def test_ordinary_runtime_error_does_not_latch(native_runtime: AsyncVlmPredictor) -> None:
    """包含 EngineCore 的普通解析错误不影响下次推理。"""

    async def invalid() -> None:
        """模拟普通调用错误。"""
        raise ValueError("EngineCore invalid input")

    with pytest.raises(ValueError):
        asyncio.run(native_runtime._acall(invalid))
    assert native_runtime.batch_two_step_extract([1]) == [1]