MinerU 进阶命令行参数实战：推理引擎参数透传与 CUDA_VISIBLE_DEVICES GPU 调度

本文基于 MinerU 官方文档 advanced_cli_parameters.md 展开，系统讲解 MinerU 五大命令行入口（mineru、mineru-openai-server、mineru-gradio、mineru-api、mineru-router）如何透传 vLLM/LMDeploy 推理引擎参数、如何用 CUDA_VISIBLE_DEVICES 精确控制 GPU 可见性，并结合 mineru/utils/cli_parser.py、mineru/cli/router.py 等源码，说明参数透传的底层实现与多卡部署的关键细节，帮助你在多卡环境下灵活编排 MinerU 的各类服务。

一、参数透传机制：哪些参数可以透传，MinerU 如何解析

1. 透传范围与命令形式

MinerU 支持将官方推理引擎（vLLM、LMDeploy）的全部受支持参数，直接以命令行参数的形式传入，适用于以下命令：

• mineru：本地命令行解析入口
• mineru-openai-server：基于 VLM 的 OpenAI 兼容推理服务
• mineru-gradio：Gradio 可视化服务
• mineru-api：FastAPI 后端服务
• mineru-router：多 worker 路由服务

命令行选项同时支持 --foo value 与 --foo=value 两种书写形式。关于 vllm 和 lmdeploy 各参数的完整取值说明，请分别查阅 vLLM 官方 CLI serve 文档与 LMDeploy 官方 API Server 文档。

2. 源码级原理：未知参数如何被收集与转换

透传能力的核心实现在 mineru/utils/cli_parser.py 的 parse_unknown_args 函数中：

• 它遍历 click 框架"未识别"的参数（ctx.args），凡是 -- 开头的项都视为透传参数；
• 同时处理 --foo=value 和 --foo value 两种形式，若参数后紧跟的不是另一个 -- 选项，则视为该参数的值；
• 仅出现 --foo 而没有值时，默认置为 True（布尔开关语义）；
• 参数名中的 - 会被统一替换为 _，与 Python 关键字参数命名对齐；
• 值会经过 _coerce_cli_value 依次尝试转换为布尔、整数、浮点数，否则保留字符串（见 mineru/utils/cli_parser.py）。

在服务端入口，click 命令普遍配置了 ignore_unknown_options=True, allow_extra_args=True，例如 mineru/cli/vlm_server.py 与 mineru/cli/router.py，这正是未知参数不会被 click 报错拒绝、而是被完整收集并继续透传给底层引擎的前提。

3. mineru-openai-server：引擎选择与参数接管

mineru-openai-server 的入口逻辑在 mineru/cli/vlm_server.py：

• --engine 支持 auto（默认）、vllm、lmdeploy 三种取值；
• auto 模式下优先尝试 import vllm，成功则使用 vLLM，否则回退 LMDeploy，两者都缺失时直接报错退出；
• 确定引擎后，将 sys.argv 重写为"程序名 + 剩余命令行参数"，交由对应引擎的 main() 接管。

vLLM 路径的默认参数补全

vLLM 路径的实际逻辑在 mineru/model/vlm/vllm_server.py，它在调用 vllm.entrypoints.cli.main 之前做了如下预处理：

处理项	说明
--port	用户未指定时，默认补 --port 30000
--gpu-memory-utilization	用户未指定时，按设备类型自动补默认值（set_default_gpu_memory_utilization()）
--model	用户传入的 --model 会被移除；未指定时通过 auto_download_and_get_model_root_path("/", "vlm") 自动下载 MinerU-VL 模型并作为位置参数拼入 vllm serve 命令
--logits-processors	未指定时自动追加 mineru_vl_utils:MinerULogitsProcessor，用于保证输出格式的稳定性
设备适配参数	调用 mod_kwargs_by_device_type(args, vllm_mode="server") 按设备类型修正参数
OMP_NUM_THREADS	环境变量未设置时默认置为 1，避免线程竞争

最终命令形态为 vllm serve <模型路径> <透传参数>。也就是说，你传给 mineru-openai-server 的任意 vLLM 参数（如 --tensor-parallel-size、--max-model-len 等）都会原样进入 vllm serve。

LMDeploy 路径的默认参数补全

LMDeploy 路径在 mineru/model/vlm/lmdeploy_server.py，默认值与设备适配逻辑为：

参数	默认行为
--server-port	未指定时补 --server-port 30000
--cache-max-entry-count	未指定时补 --cache-max-entry-count 0.5
--log-level	未指定时补 --log-level ERROR
--device	取值限定为 cuda、ascend、maca、camb，默认 cuda；可用环境变量 MINERU_LMDEPLOY_DEVICE 覆盖
--backend	取值限定为 pytorch、turbomind；缺省时由 set_lmdeploy_backend(device_type) 按设备选择；可用环境变量 MINERU_LMDEPLOY_BACKEND 覆盖
模型路径	通过 auto_download_and_get_model_root_path("/", "vlm") 自动下载，作为位置参数拼入

值得注意的是，LMDeploy 路径额外提供了 MINERU_LMDEPLOY_DEVICE 与 MINERU_LMDEPLOY_BACKEND 两个环境变量作为参数来源的补充，这在容器化部署（Dockerfile 中固化环境变量）时比反复敲命令行更方便。

二、GPU 设备选择：CUDA_VISIBLE_DEVICES 基础用法

1. 任意入口均可用

在任何场景下，都可以通过在命令行最前面追加 CUDA_VISIBLE_DEVICES 环境变量来指定进程可见的 GPU 设备，例如：

CUDA_VISIBLE_DEVICES=1 mineru -p <input_path> -o <output_path>

该方式对所有命令行调用（mineru、mineru-openai-server、mineru-gradio、mineru-api、mineru-router）均有效，且对 pipeline 与 vlm 两种 backend 均适用——因为设备可见性由 CUDA 运行时在进程启动时依据该环境变量决定，MinerU 各后端均在此约束之下分配设备。

2. 常见配置示例

CUDA_VISIBLE_DEVICES=1  # 仅第 1 号设备可见
CUDA_VISIBLE_DEVICES=0,1  # 第 0、1 号设备可见
CUDA_VISIBLE_DEVICES="0,1"  # 与上一行等价，引号可省略
CUDA_VISIBLE_DEVICES=0,2,3  # 第 0、2、3 号设备可见，第 1 号被屏蔽
CUDA_VISIBLE_DEVICES=""  # 任何 GPU 均不可见（纯 CPU 运行）

一个容易忽视的细节：CUDA_VISIBLE_DEVICES 会同时"重排"进程内看到的设备编号。例如设置 CUDA_VISIBLE_DEVICES=2 后，进程内唯一可见的卡会被编号为 cuda:0，而不是 cuda:2。多卡隔离场景正是利用这一点实现互不干扰的并行部署。

三、多卡部署的实战场景

场景 1：在 GPU 0 / GPU 1 上分别拉起两个 openai-server

# 终端 1
CUDA_VISIBLE_DEVICES=0 mineru-openai-server --engine vllm --port 30000
# 终端 2
CUDA_VISIBLE_DEVICES=1 mineru-openai-server --engine vllm --port 30001

注意两个要点：

• 端口必须错开（--port），因为两个进程相互独立，不存在端口自动探测机制，而 vLLM 路径在未指定 --port 时都会默认落到 30000（见 mineru/model/vlm/vllm_server.py）；
• 每个进程因 CUDA_VISIBLE_DEVICES 屏蔽了对方 GPU，即使内部按"单卡"逻辑运行也不会发生显存争抢。

场景 2：在 GPU 0 / GPU 1 上分别拉起两个 fastapi 服务

# 终端 1
CUDA_VISIBLE_DEVICES=0 mineru-api --host 127.0.0.1 --port 8000
# 终端 2
CUDA_VISIBLE_DEVICES=1 mineru-api --host 127.0.0.1 --port 8001

mineru-api（实现于 mineru/cli/fast_api.py）同样导入了 mineru/utils/cli_parser.py 的 arg_parse 来收集未知参数，因此引擎级参数透传在此入口同样成立；结合 --enable-vlm-preload 等选项（见 mineru/cli/vlm_preload.py）还可以在进程启动阶段预先加载 VLM 模型，缩短首个请求的冷启动时间。

场景 3：用 mineru-router 管理跨四张 GPU 的 fastapi 服务

CUDA_VISIBLE_DEVICES=0,1,2,3 mineru-router --host 127.0.0.1 --port 8002

这条命令能成立的机制可以在 mineru/cli/router.py 中逐层验证：

1. 设备列表解析：--local-gpus 选项默认值为 auto（见 mineru/cli/router.py），parse_local_gpus 会将其解析为 CSV 设备列表；auto 时优先读取已设置的 CUDA_VISIBLE_DEVICES，否则用 torch.cuda.device_count() 自动探测（见 mineru/cli/router.py）。本示例中 CUDA_VISIBLE_DEVICES=0,1,2,3 让 router 进程看到四张卡，从而为每张卡规划一个 worker。
2. 逐 worker 注入可见设备：每个受管 worker 启动时（ManagedLocalServer.start，见 mineru/cli/router.py），router 会在子进程环境中设置 env[可见设备环境变量] = <该 worker 的卡号>，再以 python -m mineru.cli.fast_api --host ... --port <随机空闲端口> ... 拉起独立 FastAPI 进程，并轮询其 /health 端点直到就绪。
3. 透传 worker 参数：mineru-router 命令行上不属于自身选项的额外参数，会被收集为 worker_extra_args（见 mineru/cli/router.py），通过 MINERU_ROUTER_WORKER_ARGS_JSON 环境变量传给每个 worker 进程。因此你完全可以写 mineru-router --port 8002 --enable-vlm-preload true ... 这类组合，把服务级参数下发给底层 mineru-api。
4. Ascend NPU 适配：get_local_device_visible_env_name 会按设备类型选择环境变量——NPU 设备使用 ASCEND_RT_VISIBLE_DEVICES 而非 CUDA_VISIBLE_DEVICES（见 mineru/cli/router.py），这是多卡/多 NPU 编排时容易被忽略的平台差异。

从源码结构看，router 还会周期性地通过健康检查（/health 携带协议版本比对）刷新 worker 状态，并按任务负载评分选择上游（WorkerState.score），这意味着 router 场景下"四张卡"不只是显存隔离，还构成一个带负载均衡与故障感知的服务池。

四、使用建议与常见约束

1. 端口冲突：mineru-openai-server 缺省端口为 30000（vLLM 与 LMDeploy 路径一致），多实例部署必须显式指定不同端口；mineru-router 缺省端口为 8002（见 mineru/cli/router.py）。
2. 引擎回退语义：--engine auto 的判定依据是运行时能否 import 对应引擎，而不是显式配置；若环境中同时安装 vLLM 与 LMDeploy，auto 模式总是优先 vLLM。
3. 参数覆盖优先级：对 --port、--gpu-memory-utilization、--logits-processors（vLLM）以及 --server-port、--cache-max-entry-count、--log-level（LMDeploy）等参数，用户显式传参优先于内置默认值——源码中对这些参数均有"是否已存在"的前置检查（见 mineru/model/vlm/vllm_server.py 与 mineru/model/vlm/lmdeploy_server.py）。
4. 模型路径自动化：透传参数中若包含 --model，vLLM 路径会将其移除并改用自动下载的 MinerU-VL 模型路径，即引擎侧的 --model 不用于指向其他模型，请勿依赖该参数换模型。
5. 设备环境变量的一致性：CUDA_VISIBLE_DEVICES 对五类入口全部有效且与 backend 无关，这是 MinerU 推荐的设备隔离手段；router 场景下则优先借助 --local-gpus 让 router 代为分配，两者语义上等价（都是按进程设置可见设备），但后者额外提供了健康检查、任务调度与 worker 参数透传能力。
6. LMDeploy 的设备白名单：--device 仅接受 cuda、ascend、maca、camb，--backend 仅接受 pytorch、turbomind，非法取值会直接抛出 ValueError，部署到非 NVIDIA 加速卡时需留意。

通过以上内容，你可以完整复现官方文档中的三类多卡部署形态，并在源码层面确认每一个默认值、透传规则与平台适配分支的实际行为，从而将 MinerU 的 CLI 能力扩展到更复杂的多引擎、多设备生产环境。