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
Add log level option for API server and enhance logging configuration
myhloli8e7384aa204f
diff --git a/docs/next/cli/mineru-kit-api-server.md b/docs/next/cli/mineru-kit-api-server.mdindex 1ebef0b5..d3743ca0 100644--- a/docs/next/cli/mineru-kit-api-server.md+++ b/docs/next/cli/mineru-kit-api-server.md@@ -91,6 +91,23 @@ OCR 模式通过每次 `POST /v1/parse/jobs` 请求的 `ocr_mode` 设置,可模型默认在首次解析时懒加载。`--preload-models` 会在 Basic 或 Standard 服务启动时提前初始化所需模型或 VLM 客户端,并在失败时让能力接口返回明确错误;Flash 没有本地模型,该参数对 Flash 无操作。Doclib managed parse-server 会自动启用模型预加载。+### 服务日志级别++`mineru-kit api-server`、`mineru-api` 和 `python -m mineru.parser.api_server` 均支持 `--log-level`,+可选 `critical`、`error`、`warning`、`info`、`debug`、`trace`,大小写不敏感,直接启动时默认 `info`。+该参数控制 Uvicorn 的启停、HTTP 访问、ASGI 日志及 API 服务自身日志。模型加载、解析阶段的模型日志、+模型原生日志和 tqdm 进度条保留各自原有设置。++```bash+mineru-kit api-server --log-level warning+mineru-api --log-level error+python -m mineru.parser.api_server --log-level debug+```++Doclib(包括命令行解析时使用的本地服务及自动重启)、Gradio 和 Router 自动拉起的 api-server+均显式使用 `--log-level warning`,保留警告与错误并隐藏服务 info 日志。连接外部服务时,其日志级别由服务部署者控制。+`mineru-kit parse` 的本地模式直接调用 parser,不启动 api-server。+### 使用远程 MinerU VLM 服务```bashdiff --git a/mineru/doclib/background/parse_server_health.py b/mineru/doclib/background/parse_server_health.pyindex 6e6d3db2..80d55f2d 100644--- a/mineru/doclib/background/parse_server_health.py+++ b/mineru/doclib/background/parse_server_health.py@@ -111,6 +111,8 @@ def api_server_args_for_tier(tier: DeploymentTier, *, host: str, port: int) -> l"--allow-local-source","--no-flash","--preload-models",+ "--log-level",+ "warning",]diff --git a/mineru/kit/commands/api_server.py b/mineru/kit/commands/api_server.pyindex ad8f2388..ee75124a 100644--- a/mineru/kit/commands/api_server.py+++ b/mineru/kit/commands/api_server.py@@ -62,6 +62,11 @@ def api_server_cmd(vlm_max_concurrency: int | None = typer.Option(None, "--vlm-max-concurrency", min=1, help="VLM inference concurrency (default: 100)"),+ log_level: str = typer.Option(+ "info",+ "--log-level",+ help="API service log level: critical, error, warning, info, debug, trace; preserves model logs and progress bars",+ ),) -> None:"""转发显式启动参数,启动 self-hosted MinerU 解析 API 服务。"""try:@@ -87,6 +92,8 @@ def api_server_cmd(host,"--port",str(port),+ "--log-level",+ log_level,"--concurrency",str(concurrency),"--url-timeout",diff --git a/mineru/kit/gradio/client.py b/mineru/kit/gradio/client.pyindex f7bfc7ce..d63af1fe 100644--- a/mineru/kit/gradio/client.py+++ b/mineru/kit/gradio/client.py@@ -424,6 +424,8 @@ class ManagedLocalApiServer:str(self.concurrency),"--language",self.language,+ "--log-level",+ "warning",*(["--disable-image-analysis"] if self.disable_image_analysis else []),*(["--preload-models"] if self.preload_models else []),*(["--api-key", self.api_key] if self.api_key else []),diff --git a/mineru/kit/router/workers.py b/mineru/kit/router/workers.pyindex edd14dff..48960023 100644--- a/mineru/kit/router/workers.py+++ b/mineru/kit/router/workers.py@@ -203,6 +203,8 @@ class ManagedLocalWorker:self.settings.worker_tier,"--concurrency",str(self.settings.worker_concurrency),+ "--log-level",+ "warning",*(["--preload-models"] if self.settings.preload_models else []),]diff --git a/mineru/parser/api_server.py b/mineru/parser/api_server.pyindex ab1e1a81..72101ada 100644--- a/mineru/parser/api_server.py+++ b/mineru/parser/api_server.py@@ -24,9 +24,10 @@ import threadingimport timeimport zipfilefrom contextlib import asynccontextmanager+from copy import deepcopyfrom dataclasses import dataclassfrom datetime import datetime, timezone-from typing import Annotated, AsyncIterator, Awaitable, Callable, Literal, NoReturn, TypedDict+from typing import Annotated, Any, AsyncIterator, Awaitable, Callable, Literal, NoReturn, TypedDictfrom urllib.parse import urlparseimport click@@ -2347,9 +2348,29 @@ def create_app(# ── CLI ──────────────────────────────────────────────────────────────+def _build_server_log_config(log_level: str) -> dict[str, Any]:+ """为服务日志构造独立配置,保留 root、模型日志和进度条的既有设置。"""+ log_config = deepcopy(uvicorn.config.LOGGING_CONFIG)+ for name in ("uvicorn", "uvicorn.error", "uvicorn.access", "uvicorn.asgi"):+ log_config["loggers"].setdefault(name, {})["level"] = uvicorn.config.LOG_LEVELS[log_level]+ log_config["loggers"][logger.name] = {+ "handlers": ["default"],+ "level": uvicorn.config.LOG_LEVELS[log_level],+ "propagate": False,+ }+ return log_config++@click.command()@click.option("--host", default="127.0.0.1", help="Server host")@click.option("--port", default=8000, type=int, help="Server port")+ "--log-level",+ default="info",+ type=click.Choice(["critical", "error", "warning", "info", "debug", "trace"], case_sensitive=False),+ show_default=True,+ help="API service log level; model logs and progress bars keep their existing settings.",+)@click.option("--upload-dir",default="",@@ -2456,6 +2477,7 @@ def main(vlm_model: str | None,vlm_http_timeout: int | None,vlm_max_concurrency: int | None,+ log_level: str,) -> None:"""合并显式 VLM 参数后启动 MinerU v1 REST API 服务,不修改全局配置。"""configure_standard_streams()@@ -2520,6 +2542,8 @@ def main(application,host=host,port=port,+ log_level=log_level,+ log_config=_build_server_log_config(log_level),)server = uvicorn.Server(config)server_ref[0] = serverdiff --git a/tests/unittest/test_api_server_logging.py b/tests/unittest/test_api_server_logging.pynew file mode 100644index 00000000..5d35a858--- /dev/null+++ b/tests/unittest/test_api_server_logging.py@@ -0,0 +1,143 @@+"""验证 API 启动入口的日志级别、配置隔离和实际输出。"""++from __future__ import annotations++import json+import subprocess+import sys+from types import SimpleNamespace+from typing import Any+from unittest.mock import MagicMock++import pytest+from click.testing import CliRunner+from typer.testing import CliRunner as TyperRunner++from mineru.kit.commands import api_server as kit_api+from mineru.kit.main import app as kit_app+from mineru.parser import api_server+++def _invoke_entrypoint(monkeypatch: pytest.MonkeyPatch, entrypoint: str, args: list[str]) -> int:+ """调用三个正式入口的真实参数解析链,同时避免启动真实服务。"""+ if entrypoint == "module":+ return CliRunner().invoke(api_server.main, args).exit_code+ if entrypoint == "kit":+ return TyperRunner().invoke(kit_app, ["api-server", *args]).exit_code+ monkeypatch.setattr(sys, "argv", ["mineru-api", *args])+ with pytest.raises(SystemExit) as caught:+ kit_api.main()+ return int(caught.value.code)++[email protected]("entrypoint", ["module", "kit", "alias"])[email protected]("level", [None, "critical", "ERROR", "Warning", "info", "debug", "TRACE"])+def test_log_level_reaches_server(monkeypatch: pytest.MonkeyPatch, entrypoint: str, level: str | None) -> None:+ """默认级别与大小写混合参数均传递到服务配置,且不进入应用业务参数。"""+ application = object()+ create_app = MagicMock(return_value=application)+ config = MagicMock(return_value=object())+ server = SimpleNamespace(run=MagicMock(), should_exit=False)+ monkeypatch.setattr(api_server, "create_app", create_app)+ monkeypatch.setattr(api_server.uvicorn, "Config", config)+ monkeypatch.setattr(api_server.uvicorn, "Server", MagicMock(return_value=server))+ monkeypatch.setattr(api_server.ManagedProcessControlWatcher, "from_environment", lambda callback: None)++ assert _invoke_entrypoint(monkeypatch, entrypoint, [] if level is None else ["--log-level", level]) == 0+ expected = (level or "info").lower()+ config.assert_called_once()+ assert config.call_args.args == (application,)+ assert config.call_args.kwargs["log_level"] == expected+ assert (+ config.call_args.kwargs["log_config"]["loggers"][api_server.logger.name]["level"]+ == (api_server.uvicorn.config.LOG_LEVELS[expected])+ )+ assert "log_level" not in create_app.call_args.kwargs+ server.run.assert_called_once()++[email protected]("entrypoint", ["module", "kit", "alias"])+def test_invalid_log_level_fails_before_initialization(monkeypatch: pytest.MonkeyPatch, entrypoint: str) -> None:+ """非法级别在建立应用、加载模型或创建服务之前失败。"""+ create_app = MagicMock()+ config = MagicMock()+ monkeypatch.setattr(api_server, "create_app", create_app)+ monkeypatch.setattr(api_server.uvicorn, "Config", config)+ assert _invoke_entrypoint(monkeypatch, entrypoint, ["--log-level", "silent"]) != 0+ create_app.assert_not_called()+ config.assert_not_called()++[email protected]("level", ["info", "warning", "error"])+def test_service_log_output_is_filtered_without_changing_model_logs(level: str) -> None:+ """在独立进程验证真实日志输出、重复配置以及 root、模型日志和 tqdm 的隔离。"""+ script = r"""+import io+import json+import logging+import sys+from contextlib import redirect_stdout, redirect_stderr+from copy import deepcopy++import uvicorn+from loguru import logger as model_logger+from tqdm import tqdm+from mineru.parser.api_server import _build_server_log_config++level = sys.argv[1]+root = logging.getLogger()+root_stream = io.StringIO()+root_handler = logging.StreamHandler(root_stream)+root.handlers = [root_handler]+root.setLevel(logging.DEBUG)+model_stream = io.StringIO()+model_sink = model_logger.add(model_stream, level="INFO", format="{message}")+before = deepcopy(uvicorn.config.LOGGING_CONFIG)+stdout, stderr, progress = io.StringIO(), io.StringIO(), io.StringIO()+with redirect_stdout(stdout), redirect_stderr(stderr):+ for _ in range(2):+ uvicorn.Config(object(), log_level=level, log_config=_build_server_log_config(level))+ for name in ("uvicorn", "uvicorn.error", "uvicorn.asgi", "mineru.parser.api_server"):+ service_logger = logging.getLogger(name)+ service_logger.info("%s INFO_MARKER", name)+ service_logger.warning("%s WARNING_MARKER", name)+ service_logger.error("%s ERROR_MARKER", name)+ access_logger = logging.getLogger("uvicorn.access")+ for severity in (logging.INFO, logging.WARNING, logging.ERROR):+ access_logger.log(severity, '%s - "%s %s HTTP/%s" %d', "127.0.0.1", "GET", f"/access-{severity}", "1.1", 200)+ logging.getLogger("mineru.model.probe").info("STDLIB_MODEL_INFO")+ root.debug("ROOT_DEBUG")+ model_logger.info("LOGURU_MODEL_INFO")+ with tqdm(total=1, desc="VLM Predict", file=progress) as bar:+ bar.update(1)+assert uvicorn.config.LOGGING_CONFIG == before+assert root.handlers == [root_handler] and root.level == logging.DEBUG+model_logger.remove(model_sink)+print(json.dumps({"stdout": stdout.getvalue(), "stderr": stderr.getvalue(),+ "model": model_stream.getvalue(), "root": root_stream.getvalue(), "progress": progress.getvalue()}))+"""+ completed = subprocess.run([sys.executable, "-c", script, level], capture_output=True, text=True, check=True, timeout=30)+ output: dict[str, Any] = json.loads(completed.stdout)+ assert output["stderr"].count("INFO_MARKER") == (4 if level == "info" else 0)+ assert output["stderr"].count("WARNING_MARKER") == (0 if level == "error" else 4)+ assert output["stderr"].count("ERROR_MARKER") == 4+ assert ("/access-20" in output["stdout"]) is (level == "info")+ assert ("/access-30" in output["stdout"]) is (level != "error")+ assert output["stdout"].count("/access-40") == 1+ assert "STDLIB_MODEL_INFO" in output["root"]+ assert "ROOT_DEBUG" in output["root"]+ assert "LOGURU_MODEL_INFO" in output["model"]+ assert "VLM Predict" in output["progress"]+++def test_log_configuration_is_independent() -> None:+ """修改一次生成的配置不会污染 Uvicorn 模板或后续服务配置。"""+ original = api_server.uvicorn.config.LOGGING_CONFIG+ config = api_server._build_server_log_config("warning")+ config["formatters"]["default"]["fmt"] = "changed"+ config["loggers"]["uvicorn"]["level"] = 1+ fresh = api_server._build_server_log_config("info")+ assert fresh["formatters"]["default"]["fmt"] == original["formatters"]["default"]["fmt"]+ assert fresh["loggers"]["uvicorn"]["level"] == 20+ assert "root" not in fresh+ assert fresh["disable_existing_loggers"] is Falsediff --git a/tests/unittest/test_doclib_cache_semantics.py b/tests/unittest/test_doclib_cache_semantics.pyindex 9d7c52c3..3110c04a 100644--- a/tests/unittest/test_doclib_cache_semantics.py+++ b/tests/unittest/test_doclib_cache_semantics.py@@ -354,6 +354,8 @@ def test_managed_api_server_args_use_tier_and_selected_port_for_process_start()"--allow-local-source","--no-flash","--preload-models",+ "--log-level",+ "warning",]assert api_server_args_for_tier("basic", host="127.0.0.2", port=16581) == ["--tier",@@ -365,6 +367,8 @@ def test_managed_api_server_args_use_tier_and_selected_port_for_process_start()"--allow-local-source","--no-flash","--preload-models",+ "--log-level",+ "warning",]@@ -632,6 +636,7 @@ def test_start_managed_parse_server_selects_port_and_writes_logs(monkeypatch: pyassert cmd[cmd.index("--host") + 1] == "127.0.0.2"assert "--port" in cmdassert cmd[cmd.index("--port") + 1] == "16582"+ assert cmd[cmd.index("--log-level") + 1] == "warning"assert kwargs["stdout"] is not subprocess.DEVNULLassert kwargs["stderr"] is not subprocess.DEVNULLassert kwargs["stdout"] is not kwargs["stderr"]diff --git a/tests/unittest/test_kit_gradio.py b/tests/unittest/test_kit_gradio.pyindex 30314782..f4c05a8a 100644--- a/tests/unittest/test_kit_gradio.py+++ b/tests/unittest/test_kit_gradio.py@@ -744,6 +744,7 @@ def test_managed_local_api_command_uses_kit_entrypoint() -> None:api_key="secret",)command = server._command(8123, Path("/tmp/mineru-upload"))+ assert command[command.index("--log-level") + 1] == "warning"assert command[:4] == [server._command(8123, Path("/tmp/mineru-upload"))[0], "-m", "mineru.kit.main", "api-server"]assert "--tier" in command and command[command.index("--tier") + 1] == "standard"assert "--no-flash" not in commanddiff --git a/tests/unittest/test_v1_router.py b/tests/unittest/test_v1_router.pyindex f384fa31..0615290c 100644--- a/tests/unittest/test_v1_router.py+++ b/tests/unittest/test_v1_router.py@@ -856,6 +856,7 @@ def test_managed_router_worker_builds_new_api_server_command(tmp_path: Path) ->worker = ManagedLocalWorker("local-0", "127.0.0.1", "0", settings)command = worker.command(18000, tmp_path)+ assert command[command.index("--log-level") + 1] == "warning"assert command[:5] == [command[0], "-m", "mineru.kit.main", "api-server", "--host"]assert command[0].endswith("python")