企业官网建设流程全解析

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

【免费下载链接】MinerUTransforms complex documents like PDFs and Office docs into LLM-ready markdown/JSON for your Agentic workflows.项目地址: https://gitcode.com/GitHub_Trending/mi/MinerU

本文基于 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之前做了如下预处理：

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

LMDeploy 路径的默认参数补全

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

值得注意的是，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 能力扩展到更复杂的多引擎、多设备生产环境。

【免费下载链接】MinerUTransforms complex documents like PDFs and Office docs into LLM-ready markdown/JSON for your Agentic workflows.项目地址: https://gitcode.com/GitHub_Trending/mi/MinerU