Skip to content

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

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.md
index 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 进度条同样保留各自原有设置。
```bash
mineru-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.md
index 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.py
index 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.py
index 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] = server
diff --git a/mineru/utils/translations.py b/mineru/utils/translations.py
index 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.py
index 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: s
monkeypatch.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_level
assert (
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.kwargs
server.run.assert_called_once()