Skip to content

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

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.md
index 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 服务
```bash
diff --git a/mineru/doclib/background/parse_server_health.py b/mineru/doclib/background/parse_server_health.py
index 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.py
index 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.py
index 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.py
index 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.py
index ab1e1a81..72101ada 100644
--- a/mineru/parser/api_server.py
+++ b/mineru/parser/api_server.py
@@ -24,9 +24,10 @@ import threading
import time
import zipfile
from contextlib import asynccontextmanager
+from copy import deepcopy
from dataclasses import dataclass
from datetime import datetime, timezone
-from typing import Annotated, AsyncIterator, Awaitable, Callable, Literal, NoReturn, TypedDict
+from typing import Annotated, Any, AsyncIterator, Awaitable, Callable, Literal, NoReturn, TypedDict
from urllib.parse import urlparse
import 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] = server
diff --git a/tests/unittest/test_api_server_logging.py b/tests/unittest/test_api_server_logging.py
new file mode 100644
index 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 False
diff --git a/tests/unittest/test_doclib_cache_semantics.py b/tests/unittest/test_doclib_cache_semantics.py
index 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: py
assert cmd[cmd.index("--host") + 1] == "127.0.0.2"
assert "--port" in cmd
assert cmd[cmd.index("--port") + 1] == "16582"
+ assert cmd[cmd.index("--log-level") + 1] == "warning"
assert kwargs["stdout"] is not subprocess.DEVNULL
assert kwargs["stderr"] is not subprocess.DEVNULL
assert kwargs["stdout"] is not kwargs["stderr"]
diff --git a/tests/unittest/test_kit_gradio.py b/tests/unittest/test_kit_gradio.py
index 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 command
diff --git a/tests/unittest/test_v1_router.py b/tests/unittest/test_v1_router.py
index 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")