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
fix(api-server): scope --log-level to server-side logs only
myhloli0e1124a4f16c
diff --git a/docs/next/cli/mineru-kit-api-server.md b/docs/next/cli/mineru-kit-api-server.mdindex 716e0bbf..3d2e0d60 100644--- a/docs/next/cli/mineru-kit-api-server.md+++ b/docs/next/cli/mineru-kit-api-server.md@@ -95,9 +95,10 @@ OCR 模式通过每次 `POST /v1/parse/jobs` 请求的 `ocr_mode` 设置,可`mineru-kit api-server`、`mineru-api` 和 `python -m mineru.parser.api_server` 均支持 `--log-level`,可选 `critical`、`error`、`warning`、`info`、`debug`、`trace`,大小写不敏感。未显式传入时使用全局-`log.level`(默认 `info`,可被 `MINERU_LOG_LEVEL` 覆盖)。该参数控制 Uvicorn 的启停、HTTP 访问、-ASGI 日志、API 服务自身日志,以及模型加载/解析阶段 Loguru 默认 stderr sink。宿主程序显式添加的-Loguru sink 和 tqdm 进度条保留各自原有设置。+`log.level`(默认 `info`,可被 `MINERU_LOG_LEVEL` 覆盖)。该参数仅控制服务侧日志:Uvicorn 的启停、+HTTP 访问、ASGI 日志和 API 服务自身日志。模型加载/解析阶段的 Loguru 默认 stderr sink 不受该参数+影响,始终跟随全局 `log.level`(即 `MINERU_LOG_LEVEL` > YAML `log.level` > 默认 `info`);宿主程序+显式添加的 Loguru sink 和 tqdm 进度条同样保留各自原有设置。```bashmineru-kit api-server --log-level warning@@ -106,7 +107,10 @@ python -m mineru.parser.api_server --log-level debug```Doclib(包括命令行解析时使用的本地服务及自动重启)、Gradio 和 Router 自动拉起的 api-server-均显式使用 `--log-level warning`,保留警告与错误并隐藏服务 info 日志。连接外部服务时,其日志级别由服务部署者控制。+均显式使用 `--log-level warning`,保留警告与错误并隐藏服务 info 日志(含每条 HTTP 请求的访问日志);+这些托管子进程的模型/解析日志仍由 `MINERU_LOG_LEVEL` 控制,例如排障时设+`MINERU_LOG_LEVEL=debug` 后启动 `mineru-kit webui`,可在控制台看到模型 DEBUG 日志而不会被+HTTP 访问日志刷屏。连接外部服务时,其日志级别由服务部署者控制。`mineru-kit parse` 的本地模式直接调用 parser,不启动 api-server。### 使用远程 MinerU VLM 服务diff --git a/docs/next/config.md b/docs/next/config.mdindex 0a4b52d9..3a62e814 100644--- a/docs/next/config.md+++ b/docs/next/config.md@@ -121,7 +121,9 @@ MinerU VLM 的跨页单元格检测保持关闭。任一功能启用时,`api_k全局日志级别由 `log.level` 控制,默认 `info`,可选 `trace`、`debug`、`info`、`warning`、`error`、`critical`。环境变量 `MINERU_LOG_LEVEL` 可覆盖 YAML;该配置作用于当前进程的 Loguru 默认 stderr sink,不会移除宿主程序显式添加的-自定义 sink。`doclib.log.level` 与 api-server 启动参数 `--log-level` 是局部覆盖。+自定义 sink。`doclib.log.level` 是 Doclib 进程日志级别的局部覆盖;api-server+启动参数 `--log-level` 是服务侧(Uvicorn/HTTP 访问/服务自身 stdlib 日志)的局部+覆盖,不影响 Loguru 默认 sink。## 2. 两阶段配置模型diff --git a/mineru/kit/commands/api_server.py b/mineru/kit/commands/api_server.pyindex 61ef1ae9..4b057dae 100644--- a/mineru/kit/commands/api_server.py+++ b/mineru/kit/commands/api_server.py@@ -67,7 +67,8 @@ def api_server_cmd("--log-level",help=t("API service log level: critical, error, warning, info, debug, trace; default: global log.level. "- "Also filters the Loguru default model-log sink"+ "Server-scope only (Uvicorn startup, HTTP access, ASGI, and service logs); "+ "the Loguru default sink always follows global log.level"),),) -> None:@@ -124,9 +125,7 @@ def main() -> None:configure_standard_streams()configure_global_log_level()app = typer.Typer(add_completion=False)- app.command(help=t("Start the self-hosted MinerU parsing API service."))(- api_server_cmd- )+ app.command(help=t("Start the self-hosted MinerU parsing API service."))(api_server_cmd)app()diff --git a/mineru/parser/api_server.py b/mineru/parser/api_server.pyindex 4708e199..8a952650 100644--- a/mineru/parser/api_server.py+++ b/mineru/parser/api_server.py@@ -2498,8 +2498,9 @@ def _build_server_log_config(log_level: str) -> dict[str, Any]:default=None,type=click.Choice(["critical", "error", "warning", "info", "debug", "trace"], case_sensitive=False),help=(- "API service log level: critical, error, warning, info, debug, trace; "- "default: global log.level. Also filters the Loguru default model-log sink."+ "API service log level: critical, error, warning, info, debug, trace; default: global log.level. "+ "Server-scope only (Uvicorn startup, HTTP access, ASGI, and service logs); "+ "the Loguru default sink always follows global log.level."),)@click.option(@@ -2611,7 +2612,8 @@ def main() -> None:"""合并显式 VLM 参数后启动 MinerU v1 REST API 服务,不修改全局配置。"""configure_standard_streams()- effective_log_level = configure_global_log_level(log_level)+ global_log_level = configure_global_log_level()+ server_log_level = (log_level if log_level is not None else global_log_level).lower()shutdown_requested = threading.Event()server_ref: list[uvicorn.Server | None] = [None]@@ -2673,8 +2675,8 @@ def main(application,host=host,port=port,- log_level=effective_log_level,- log_config=_build_server_log_config(effective_log_level),+ log_level=server_log_level,+ log_config=_build_server_log_config(server_log_level),)server = uvicorn.Server(config)server_ref[0] = serverdiff --git a/mineru/utils/translations.py b/mineru/utils/translations.pyindex a68bc8ad..667957ef 100644--- a/mineru/utils/translations.py+++ b/mineru/utils/translations.py@@ -432,9 +432,7 @@ ZH_MESSAGES: dict[str, str] = {"将文件或目录解析为 markdown、middle JSON 或 zip 输出。"),"Start the Gradio document parsing web UI backed by the MinerU V1 API.": "启动基于 MinerU V1 API 的 Gradio 文档解析界面。",- "Start the self-hosted MinerU parsing API service.": (- "启动自托管的 MinerU 解析 API 服务。"- ),+ "Start the self-hosted MinerU parsing API service.": ("启动自托管的 MinerU 解析 API 服务。"),"Start the local VLM server with OpenAI-compatible chat completions.": ("启动本地 VLM 服务,提供 OpenAI 兼容的 chat completions。"),@@ -502,8 +500,11 @@ ZH_MESSAGES: dict[str, str] = {"VLM HTTP timeout in seconds (default: 600)": "VLM HTTP 超时秒数(默认 600)","VLM inference concurrency (default: 100)": "VLM 推理并发数(默认 100)","API service log level: critical, error, warning, info, debug, trace; default: global log.level. "- "Also filters the Loguru default model-log sink": (- "API 服务日志级别: critical、error、warning、info、debug、trace;默认取全局 log.level。同时过滤 Loguru 默认模型日志 sink"+ "Server-scope only (Uvicorn startup, HTTP access, ASGI, and service logs); "+ "the Loguru default sink always follows global log.level": (+ "API 服务日志级别: critical、error、warning、info、debug、trace;默认取全局 log.level。"+ "仅作用于服务侧日志(Uvicorn 启停、HTTP 访问、ASGI 及服务自身);"+ "Loguru 默认 sink 始终跟随全局 log.level"),# ------------------------------------------------------- kit vlm-server"VLM serving engine: auto, llama-cpp, vllm, lmdeploy, mlx": "VLM 推理服务引擎: auto、llama-cpp、vllm、lmdeploy、mlx",diff --git a/tests/unittest/test_api_server_logging.py b/tests/unittest/test_api_server_logging.pyindex f35ee5ee..22788305 100644--- a/tests/unittest/test_api_server_logging.py+++ b/tests/unittest/test_api_server_logging.py@@ -33,12 +33,12 @@ def _invoke_entrypoint(monkeypatch: pytest.MonkeyPatch, entrypoint: str, args: l@pytest.mark.parametrize("entrypoint", ["module", "kit", "alias"])@pytest.mark.parametrize("level", [None, "critical", "ERROR", "Warning", "info", "debug", "TRACE"])def test_log_level_reaches_server(monkeypatch: pytest.MonkeyPatch, entrypoint: str, level: str | None) -> None:- """默认级别与大小写混合参数均传递到服务配置,且不进入应用业务参数。"""+ """显式 --log-level 只作用于服务配置,loguru 全局级别始终取全局配置,且不进入应用业务参数。"""application = object()create_app = MagicMock(return_value=application)config = MagicMock(return_value=object())- expected = (level or "debug").lower()- configure_global = MagicMock(return_value=expected)+ expected_server_level = (level or "debug").lower()+ configure_global = MagicMock(return_value="debug")server = SimpleNamespace(run=MagicMock(), should_exit=False)monkeypatch.setattr(api_server.mineru_config.log, "level", "debug")monkeypatch.setattr(api_server, "create_app", create_app)@@ -49,13 +49,13 @@ def test_log_level_reaches_server(monkeypatch: pytest.MonkeyPatch, entrypoint: smonkeypatch.setattr(api_server.ManagedProcessControlWatcher, "from_environment", lambda callback: None)assert _invoke_entrypoint(monkeypatch, entrypoint, [] if level is None else ["--log-level", level]) == 0- configure_global.assert_called_once_with(None if level is None else expected)+ configure_global.assert_called_once_with()config.assert_called_once()assert config.call_args.args == (application,)- assert config.call_args.kwargs["log_level"] == expected+ assert config.call_args.kwargs["log_level"] == expected_server_levelassert (config.call_args.kwargs["log_config"]["loggers"][api_server.logger.name]["level"]- == (api_server.uvicorn.config.LOG_LEVELS[expected])+ == (api_server.uvicorn.config.LOG_LEVELS[expected_server_level]))assert "log_level" not in create_app.call_args.kwargsserver.run.assert_called_once()