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-gradioGradio 可视化服务mineru-apiFastAPI 后端服务mineru-router多 worker 路由服务命令行选项同时支持--foo value与--foovalue两种书写形式。关于vllm和lmdeploy各参数的完整取值说明请分别查阅 vLLM 官方 CLI serve 文档与 LMDeploy 官方 API Server 文档。2. 源码级原理未知参数如何被收集与转换透传能力的核心实现在 mineru/utils/cli_parser.py 的parse_unknown_args函数中它遍历 click 框架未识别的参数ctx.args凡是--开头的项都视为透传参数同时处理--foovalue和--foo value两种形式若参数后紧跟的不是另一个--选项则视为该参数的值仅出现--foo而没有值时默认置为True布尔开关语义参数名中的-会被统一替换为_与 Python 关键字参数命名对齐值会经过_coerce_cli_value依次尝试转换为布尔、整数、浮点数否则保留字符串见 mineru/utils/cli_parser.py。在服务端入口click 命令普遍配置了ignore_unknown_optionsTrue, allow_extra_argsTrue例如 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_modeserver)按设备类型修正参数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_DEVICES1 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_DEVICES1 # 仅第 1 号设备可见 CUDA_VISIBLE_DEVICES0,1 # 第 0、1 号设备可见 CUDA_VISIBLE_DEVICES0,1 # 与上一行等价引号可省略 CUDA_VISIBLE_DEVICES0,2,3 # 第 0、2、3 号设备可见第 1 号被屏蔽 CUDA_VISIBLE_DEVICES # 任何 GPU 均不可见纯 CPU 运行一个容易忽视的细节CUDA_VISIBLE_DEVICES会同时重排进程内看到的设备编号。例如设置CUDA_VISIBLE_DEVICES2后进程内唯一可见的卡会被编号为cuda:0而不是cuda:2。多卡隔离场景正是利用这一点实现互不干扰的并行部署。三、多卡部署的实战场景场景 1在 GPU 0 / GPU 1 上分别拉起两个 openai-server# 终端 1 CUDA_VISIBLE_DEVICES0 mineru-openai-server --engine vllm --port 30000 # 终端 2 CUDA_VISIBLE_DEVICES1 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_DEVICES0 mineru-api --host 127.0.0.1 --port 8000 # 终端 2 CUDA_VISIBLE_DEVICES1 mineru-api --host 127.0.0.1 --port 8001mineru-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_DEVICES0,1,2,3 mineru-router --host 127.0.0.1 --port 8002这条命令能成立的机制可以在 mineru/cli/router.py 中逐层验证设备列表解析--local-gpus选项默认值为auto见 mineru/cli/router.pyparse_local_gpus会将其解析为 CSV 设备列表auto时优先读取已设置的CUDA_VISIBLE_DEVICES否则用torch.cuda.device_count()自动探测见 mineru/cli/router.py。本示例中CUDA_VISIBLE_DEVICES0,1,2,3让 router 进程看到四张卡从而为每张卡规划一个 worker。逐 worker 注入可见设备每个受管 worker 启动时ManagedLocalServer.start见 mineru/cli/router.pyrouter 会在子进程环境中设置env[可见设备环境变量] 该 worker 的卡号再以python -m mineru.cli.fast_api --host ... --port 随机空闲端口 ...拉起独立 FastAPI 进程并轮询其/health端点直到就绪。透传 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。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 场景下四张卡不只是显存隔离还构成一个带负载均衡与故障感知的服务池。四、使用建议与常见约束端口冲突mineru-openai-server缺省端口为 30000vLLM 与 LMDeploy 路径一致多实例部署必须显式指定不同端口mineru-router缺省端口为 8002见 mineru/cli/router.py。引擎回退语义--engine auto的判定依据是运行时能否import对应引擎而不是显式配置若环境中同时安装 vLLM 与 LMDeployauto 模式总是优先 vLLM。参数覆盖优先级对--port、--gpu-memory-utilization、--logits-processorsvLLM以及--server-port、--cache-max-entry-count、--log-levelLMDeploy等参数用户显式传参优先于内置默认值——源码中对这些参数均有是否已存在的前置检查见 mineru/model/vlm/vllm_server.py 与 mineru/model/vlm/lmdeploy_server.py。模型路径自动化透传参数中若包含--modelvLLM 路径会将其移除并改用自动下载的 MinerU-VL 模型路径即引擎侧的--model不用于指向其他模型请勿依赖该参数换模型。设备环境变量的一致性CUDA_VISIBLE_DEVICES对五类入口全部有效且与 backend 无关这是 MinerU 推荐的设备隔离手段router 场景下则优先借助--local-gpus让 router 代为分配两者语义上等价都是按进程设置可见设备但后者额外提供了健康检查、任务调度与 worker 参数透传能力。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创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考 MinerU 进阶命令行参数实战：推理引擎参数透传与 CUDA_VISIBLE_DEVICES GPU 调度
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-gradioGradio 可视化服务mineru-apiFastAPI 后端服务mineru-router多 worker 路由服务命令行选项同时支持--foo value与--foovalue两种书写形式。关于vllm和lmdeploy各参数的完整取值说明请分别查阅 vLLM 官方 CLI serve 文档与 LMDeploy 官方 API Server 文档。2. 源码级原理未知参数如何被收集与转换透传能力的核心实现在 mineru/utils/cli_parser.py 的parse_unknown_args函数中它遍历 click 框架未识别的参数ctx.args凡是--开头的项都视为透传参数同时处理--foovalue和--foo value两种形式若参数后紧跟的不是另一个--选项则视为该参数的值仅出现--foo而没有值时默认置为True布尔开关语义参数名中的-会被统一替换为_与 Python 关键字参数命名对齐值会经过_coerce_cli_value依次尝试转换为布尔、整数、浮点数否则保留字符串见 mineru/utils/cli_parser.py。在服务端入口click 命令普遍配置了ignore_unknown_optionsTrue, allow_extra_argsTrue例如 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_modeserver)按设备类型修正参数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_DEVICES1 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_DEVICES1 # 仅第 1 号设备可见 CUDA_VISIBLE_DEVICES0,1 # 第 0、1 号设备可见 CUDA_VISIBLE_DEVICES0,1 # 与上一行等价引号可省略 CUDA_VISIBLE_DEVICES0,2,3 # 第 0、2、3 号设备可见第 1 号被屏蔽 CUDA_VISIBLE_DEVICES # 任何 GPU 均不可见纯 CPU 运行一个容易忽视的细节CUDA_VISIBLE_DEVICES会同时重排进程内看到的设备编号。例如设置CUDA_VISIBLE_DEVICES2后进程内唯一可见的卡会被编号为cuda:0而不是cuda:2。多卡隔离场景正是利用这一点实现互不干扰的并行部署。三、多卡部署的实战场景场景 1在 GPU 0 / GPU 1 上分别拉起两个 openai-server# 终端 1 CUDA_VISIBLE_DEVICES0 mineru-openai-server --engine vllm --port 30000 # 终端 2 CUDA_VISIBLE_DEVICES1 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_DEVICES0 mineru-api --host 127.0.0.1 --port 8000 # 终端 2 CUDA_VISIBLE_DEVICES1 mineru-api --host 127.0.0.1 --port 8001mineru-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_DEVICES0,1,2,3 mineru-router --host 127.0.0.1 --port 8002这条命令能成立的机制可以在 mineru/cli/router.py 中逐层验证设备列表解析--local-gpus选项默认值为auto见 mineru/cli/router.pyparse_local_gpus会将其解析为 CSV 设备列表auto时优先读取已设置的CUDA_VISIBLE_DEVICES否则用torch.cuda.device_count()自动探测见 mineru/cli/router.py。本示例中CUDA_VISIBLE_DEVICES0,1,2,3让 router 进程看到四张卡从而为每张卡规划一个 worker。逐 worker 注入可见设备每个受管 worker 启动时ManagedLocalServer.start见 mineru/cli/router.pyrouter 会在子进程环境中设置env[可见设备环境变量] 该 worker 的卡号再以python -m mineru.cli.fast_api --host ... --port 随机空闲端口 ...拉起独立 FastAPI 进程并轮询其/health端点直到就绪。透传 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。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 场景下四张卡不只是显存隔离还构成一个带负载均衡与故障感知的服务池。四、使用建议与常见约束端口冲突mineru-openai-server缺省端口为 30000vLLM 与 LMDeploy 路径一致多实例部署必须显式指定不同端口mineru-router缺省端口为 8002见 mineru/cli/router.py。引擎回退语义--engine auto的判定依据是运行时能否import对应引擎而不是显式配置若环境中同时安装 vLLM 与 LMDeployauto 模式总是优先 vLLM。参数覆盖优先级对--port、--gpu-memory-utilization、--logits-processorsvLLM以及--server-port、--cache-max-entry-count、--log-levelLMDeploy等参数用户显式传参优先于内置默认值——源码中对这些参数均有是否已存在的前置检查见 mineru/model/vlm/vllm_server.py 与 mineru/model/vlm/lmdeploy_server.py。模型路径自动化透传参数中若包含--modelvLLM 路径会将其移除并改用自动下载的 MinerU-VL 模型路径即引擎侧的--model不用于指向其他模型请勿依赖该参数换模型。设备环境变量的一致性CUDA_VISIBLE_DEVICES对五类入口全部有效且与 backend 无关这是 MinerU 推荐的设备隔离手段router 场景下则优先借助--local-gpus让 router 代为分配两者语义上等价都是按进程设置可见设备但后者额外提供了健康检查、任务调度与 worker 参数透传能力。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创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考