Skip to content

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

feat(doclib): speed up parse-server probe on failure

jinzhenj619faa05fbc9
diff --git a/mineru/doclib/background/parse_server_health.py b/mineru/doclib/background/parse_server_health.py
index c439afc5..34feed81 100644
--- a/mineru/doclib/background/parse_server_health.py
+++ b/mineru/doclib/background/parse_server_health.py
@@ -12,7 +12,7 @@ import sys
import time
from contextlib import contextmanager
from dataclasses import dataclass, field
-from typing import IO, TYPE_CHECKING, Iterator, cast
+from typing import IO, TYPE_CHECKING, Final, Iterator, cast
import httpx
@@ -31,6 +31,11 @@ if TYPE_CHECKING:
MAX_RESTART_ATTEMPTS = 3
DEFAULT_MANAGED_URL = "http://127.0.0.1:16580"
+# Local-probe failure backoff: each consecutive failure waits 5s more
+# (5/10/15/20/25/30s...), capped at the normal interval, so a server that
+# becomes ready during startup is detected quickly.
+_FAILURE_BACKOFF_STEP_SEC: Final[int] = 5
+
_NON_RETRYABLE_MODEL_PRELOAD_ERRORS = frozenset(
{
"model_preload_dependency_missing",
@@ -326,6 +331,7 @@ class ParseServerHealthCheck:
async def run(self) -> None:
self.running = True
health = get_health()
+ consecutive_local_failures = 0
while self.running:
# refresh config on each cycle (hot-reload)
@@ -337,9 +343,11 @@ class ParseServerHealthCheck:
health.self_hosted_url = self_hosted_url if self_hosted_url else None
# probe local
+ probed_local = False
if health.local_mode != "disabled":
url = self._local_url(health)
if url:
+ probed_local = True
api_key = None
if health.local_mode == "self_hosted":
api_key = (await self.config_svc.get("parse_server.local.self_hosted_api_key")) or None
@@ -413,7 +421,20 @@ class ParseServerHealthCheck:
logger.warning("Managed parse-server is unhealthy, attempting restart")
await self._try_restart_managed(health)
- await asyncio.sleep(self.interval_sec)
+ # A failed local probe shortens the wait (5/10/20s, capped at the
+ # normal interval) so a server that becomes ready during startup is
+ # detected quickly; any success or non-probed cycle restores it.
+ if probed_local and not health.local.probe.healthy:
+ consecutive_local_failures += 1
+ else:
+ consecutive_local_failures = 0
+ await asyncio.sleep(self._next_interval_sec(consecutive_local_failures))
+
+ def _next_interval_sec(self, consecutive_local_failures: int) -> int:
+ """下一次探测的等待秒数;每多失败一次多等 5 秒,封顶正常间隔。"""
+ if consecutive_local_failures <= 0:
+ return self.interval_sec
+ return min(consecutive_local_failures * _FAILURE_BACKOFF_STEP_SEC, self.interval_sec)
async def _try_restart_managed_for_tier_change(
self,
diff --git a/tests/unittest/test_parse_server_health.py b/tests/unittest/test_parse_server_health.py
new file mode 100644
index 00000000..5ea9645c
--- /dev/null
+++ b/tests/unittest/test_parse_server_health.py
@@ -0,0 +1,41 @@
+# Copyright (c) Opendatalab. All rights reserved.
+"""Parse-server 健康探测的失败退避节奏。"""
+
+from mineru.doclib.background.parse_server_health import ParseServerHealthCheck
+
+
+def _checker(interval_sec: int = 30) -> ParseServerHealthCheck:
+ return ParseServerHealthCheck(
+ config_svc=None,
+ interval_sec=interval_sec,
+ probe_timeout_sec=10,
+ startup_grace_sec=30,
+ stop_timeout_sec=10,
+ )
+
+
+def test_healthy_or_unprobed_cycles_keep_normal_interval() -> None:
+ checker = _checker()
+ assert checker._next_interval_sec(0) == 30
+ # 退避序列走完后封顶回正常间隔(长期宕机不放大探测频率)。
+ assert checker._next_interval_sec(9) == 30
+
+
+def test_failure_backoff_speeds_up_probe() -> None:
+ checker = _checker()
+ # 连续失败按 5/10/15/20/25/30 秒加速重试:start 阶段 server ready 后 5 秒内被发现。
+ assert checker._next_interval_sec(1) == 5
+ assert checker._next_interval_sec(2) == 10
+ assert checker._next_interval_sec(3) == 15
+ assert checker._next_interval_sec(4) == 20
+ assert checker._next_interval_sec(5) == 25
+ assert checker._next_interval_sec(6) == 30
+ assert checker._next_interval_sec(7) == 30
+
+
+def test_backoff_never_exceeds_normal_interval() -> None:
+ """interval 配置小于退避值时,取较小值。"""
+ checker = _checker(interval_sec=8)
+ assert checker._next_interval_sec(1) == 5
+ assert checker._next_interval_sec(2) == 8
+ assert checker._next_interval_sec(0) == 8