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(vlm-server): honor env overrides for injected runtime defaults
myhloli275a4576fa3f
diff --git a/mineru/kit/vlm_server/llama_cpp_server.py b/mineru/kit/vlm_server/llama_cpp_server.pyindex fdb73787..8e559835 100644--- a/mineru/kit/vlm_server/llama_cpp_server.py+++ b/mineru/kit/vlm_server/llama_cpp_server.py@@ -6,7 +6,7 @@ llama-server 的全部服务能力由 llama.cpp 提供,本模块只补默认默认参数对齐 EngineCore::EngineCore(进程内 llama-cpp-engine)在 C++ 侧写死的 common_params 值,使 server 模式与解析模式的上下文容量、KV 分区、-并发与日志行为保持一致;用户显式传入的参数逐项让位。+并发与日志行为保持一致;用户以 CLI 旗标或 llama-server 环境变量设定时逐项让位。"""from __future__ import annotations@@ -171,7 +171,10 @@ def _read_gguf_context_length(model_path: Path) -> int:def main() -> None:args = sys.argv[1:]- if not _has_arg(args, "--port"):+ # 注入的每个默认值都让位两项:用户 CLI 旗标与对应环境变量(--help 的+ # env: 名单);llama.cpp 里 CLI 优先级高于环境变量,漏认 env 会让追加的+ # 默认值静默压掉操作员的环境配置。+ if not _has_arg(args, "--port") and not _has_env("LLAMA_ARG_PORT"):args.extend(["--port", DEFAULT_PORT])if not _has_arg(args, *GRAMMAR_SELECTOR_FLAGS):args.extend(["--grammar", VALID_UNICODE_GRAMMAR])@@ -204,21 +207,22 @@ def main() -> None:args.extend(["--mmproj", str(model_dir / repo.paths["mmproj"])])# /v1/models 与请求体里的 model 字段用 registry 的模型名,而不是 GGUF# 文件路径;用户自定义模型时不代设。- if not _has_arg(args, "-a", "--alias"):+ if not _has_arg(args, "-a", "--alias") and not _has_env("LLAMA_ARG_ALIAS"):args.extend(["--alias", repo.name])- # ---- 对齐 EngineCore::EngineCore 写死的 common_params(用户显式传入时逐项让位)----- user_defined_parallel = _has_arg(args, *PARALLEL_FLAGS)- user_defined_ctx = _has_arg(args, "-c", "--ctx-size")+ # ---- 对齐 EngineCore::EngineCore 写死的 common_params(用户 CLI 或环境变量设定时逐项让位)----+ user_defined_parallel = _has_arg(args, *PARALLEL_FLAGS) or _has_env("LLAMA_ARG_N_PARALLEL")+ user_defined_ctx = _has_arg(args, "-c", "--ctx-size") or _has_env("LLAMA_ARG_CTX_SIZE")if not user_defined_parallel:args.extend(["--parallel", str(DEFAULT_N_PARALLEL)])- if not _has_arg(args, "-ngl", "--gpu-layers", "--n-gpu-layers"):+ if not _has_arg(args, "-ngl", "--gpu-layers", "--n-gpu-layers") and not _has_env("LLAMA_ARG_N_GPU_LAYERS"):args.extend(["--n-gpu-layers", str(DEFAULT_N_GPU_LAYERS)])# mmproj_use_gpu = (n_gpu_layers > 0):纯 CPU(ngl=0)时 mmproj 也不上 GPU;# server 的 --mmproj-offload 默认无条件 enabled、不联动 ngl,需要显式对齐。- if not _has_arg(args, "--mmproj-offload", "--no-mmproj-offload"):+ if not _has_arg(args, "--mmproj-offload", "--no-mmproj-offload") and not _has_env("LLAMA_ARG_MMPROJ_OFFLOAD"):try:- mmproj_use_gpu = int(_flag_value(args, "-ngl", "--gpu-layers", "--n-gpu-layers") or DEFAULT_N_GPU_LAYERS) > 0+ ngl_value = _flag_value(args, "-ngl", "--gpu-layers", "--n-gpu-layers") or os.environ.get("LLAMA_ARG_N_GPU_LAYERS")+ mmproj_use_gpu = int(ngl_value or DEFAULT_N_GPU_LAYERS) > 0except ValueError:mmproj_use_gpu = Trueif not mmproj_use_gpu:@@ -226,9 +230,9 @@ def main() -> None:# EngineCore 用 kv_unified=false 的硬分区 KV(每 slot 私有 n_ctx_seq,互不侵占,# 见 engine_core.cpp 的注释);llama-server 默认 unified=enabled,需显式关闭,# 并同步关闭 idle-slot RAM 缓存(EngineCore 的 cache_idle_slots=false / cache_ram_mib=0)。- if not _has_arg(args, *KV_UNIFIED_FLAGS):+ if not _has_arg(args, *KV_UNIFIED_FLAGS) and not _has_env("LLAMA_ARG_KV_UNIFIED"):args.append("--no-kv-unified")- if not _has_arg(args, "--cache-ram", "-cram"):+ if not _has_arg(args, "--cache-ram", "-cram") and not _has_env("LLAMA_ARG_CACHE_RAM"):args.extend(["--cache-ram", "0"])# 总上下文 = n_ctx_seq(默认 0 → 训练上下文,读 GGUF) × n_parallel,复刻diff --git a/tests/unittest/test_llama_cpp_server.py b/tests/unittest/test_llama_cpp_server.pyindex d1d092e7..1b0c4594 100644--- a/tests/unittest/test_llama_cpp_server.py+++ b/tests/unittest/test_llama_cpp_server.py@@ -292,6 +292,78 @@ def test_main_env_projector_source_suppresses_default_pair(assert str(model_dir / "mmproj.gguf") not in argv+def test_main_env_parallel_suppresses_default_and_ctx_conversion(+ monkeypatch: pytest.MonkeyPatch, tmp_path: Path, capsys: pytest.CaptureFixture[str]+) -> None:+ """env 设定并发视为用户已定义:不追加默认并发,也不做训练上下文 ×N 换算。"""+ monkeypatch.setenv("LLAMA_ARG_N_PARALLEL", "8")+ argv, _, _ = _run_main(monkeypatch, tmp_path, capsys, [])++ assert "--parallel" not in argv+ assert "--ctx-size" not in argv+++def test_main_env_ctx_suppresses_ctx_conversion_only(+ monkeypatch: pytest.MonkeyPatch, tmp_path: Path, capsys: pytest.CaptureFixture[str]+) -> None:+ """env 只设定上下文:换算跳过,默认并发照常补齐。"""+ monkeypatch.setenv("LLAMA_ARG_CTX_SIZE", "32768")+ argv, _, _ = _run_main(monkeypatch, tmp_path, capsys, [])++ assert "--ctx-size" not in argv+ assert "--parallel" in argv+++ ("ngl_env", "expect_no_mmproj_offload"),+ [("0", True), ("2", False)],+ ids=["cpu-only", "gpu"],+)+def test_main_env_ngl_suppresses_default_and_drives_mmproj_offload(+ monkeypatch: pytest.MonkeyPatch,+ tmp_path: Path,+ capsys: pytest.CaptureFixture[str],+ ngl_env: str,+ expect_no_mmproj_offload: bool,+) -> None:+ """env 设定 GPU 层数时不追加默认 99;ngl=0 的纯 CPU 场景 mmproj 同步离卡。"""+ monkeypatch.setenv("LLAMA_ARG_N_GPU_LAYERS", ngl_env)+ argv, _, _ = _run_main(monkeypatch, tmp_path, capsys, [])++ assert "--n-gpu-layers" not in argv+ assert ("--no-mmproj-offload" in argv) is expect_no_mmproj_offload+++ ("env_name", "suppressed_flag"),+ [+ ("LLAMA_ARG_PORT", "--port"),+ ("LLAMA_ARG_KV_UNIFIED", "--no-kv-unified"),+ ("LLAMA_ARG_CACHE_RAM", "--cache-ram"),+ ],+ ids=["port", "kv-unified", "cache-ram"],+)+def test_main_env_setting_suppresses_matching_default(+ monkeypatch: pytest.MonkeyPatch, tmp_path: Path, capsys: pytest.CaptureFixture[str], env_name: str, suppressed_flag: str+) -> None:+ """env 已配置的项不再追加默认值(CLI 追加会以更高优先级压掉环境配置)。"""+ monkeypatch.setenv(env_name, "1")+ argv, _, _ = _run_main(monkeypatch, tmp_path, capsys, [])++ assert suppressed_flag not in argv+++def test_main_env_alias_suppresses_registry_alias(+ monkeypatch: pytest.MonkeyPatch, tmp_path: Path, capsys: pytest.CaptureFixture[str]+) -> None:+ """env 设定 alias 时不代设 registry 模型名,默认模型对仍正常补齐。"""+ monkeypatch.setenv("LLAMA_ARG_ALIAS", "env-alias")+ argv, _, model_dir = _run_main(monkeypatch, tmp_path, capsys, [])++ assert "mineru-test-model" not in argv+ assert str(model_dir / "main.gguf") in argv++@pytest.mark.parametrize("alias_args",[["-a", "my-model"], ["--alias", "my-model"], ["--alias=my-model"]],