MinerU 命令行工具完全指南mineru、mineru-api、mineru-gradio 与 mineru-router 参数、环境变量与编排机制【免费下载链接】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 仓库中的中文文档 命令行工具使用说明 展开系统讲解 MinerU 提供的四套命令行入口——解析客户端mineru、FastAPI 服务mineru-api、Web 界面mineru-gradio和多 worker 路由服务mineru-router——的完整参数清单、环境变量配置以及它们之间的编排关系。读完后你可以独立完成从单机 PDF/Office 文档解析到多 GPU 服务化部署的各类命令行操作并理解每个参数在 mineru/cli/client.py 等源码中的实际作用。一、MinerU 的 CLI 入口清单MinerU 通过 pyproject.toml 中的[project.scripts]段注册了全部命令行入口命令对应源码入口作用minerumineru/cli/client.py 的main文档解析客户端PDF、图片、DOCX/PPTX/XLSXmineru-apimineru/cli/fast_api.py 的mainFastAPI 解析服务默认端口 8000mineru-gradiomineru/cli/gradio_app.py 的mainGradio Web 界面mineru-routermineru/cli/router.py 的main多 worker 路由服务默认端口 8002mineru-models-downloadmineru/cli/models_download.py模型下载mineru-vllm-server/mineru-lmdeploy-server/mineru-openai-servermineru/cli/vlm_server.py启动本地 VLM 推理服务vLLM / LMDeploy / OpenAI 兼容本文聚焦文档中重点说明的前四个命令。mineru支持的输入类型在源码 mineru/cli/common.py 中由pdf_suffixes、image_suffixes、office_suffixes三类后缀集合决定pyproject.toml 的依赖列表pypdfium2、python-docx、pypptx-with-oxml、openpyxl等也印证了对 PDF、图片与 Office 文档的原生支持。二、mineru基于 mineru-api 编排的解析客户端2.1 架构定位从当前版本开始mineru不再直接在本进程内跑解析管线而是基于mineru-api的编排客户端orchestration client。官方文档明确指出未传--api-url时CLI 会自动拉起本地临时mineru-api进程传入--api-url时CLI 会直连该 FastAPI 服务--url的含义已发生变化它不再表示 MinerU API 地址而是指服务端vlm/hybrid-http-client后端所需的 OpenAI 兼容地址。这一点在源码中得到完整印证。mineru/cli/client.py 的run_orchestrated_cli函数约 L910-L980中当api_url is None时执行local_server LocalAPIServer(extra_cli_argsextra_cli_args)并调用local_server.start()获得base_url随后轮询wait_for_local_api_ready等待健康检查通过任务结束后在finally中调用local_server.stop()当传入了api_url时则通过fetch_server_health获取服务健康信息含服务端max_concurrent_requests并据此协商本地并发提交数。2.2 完整参数清单mineru --help输出来自 docs/zh/usage/cli_tools.mdmineru --help Usage: mineru [OPTIONS] Options: -v, --version 显示版本并退出 -p, --path PATH 输入文件路径或目录必填 -o, --output PATH 输出目录必填 --api-url TEXT MinerU FastAPI 服务地址不传时自动拉起本地临时 mineru-api -m, --method [auto|txt|ocr] 解析方法auto默认、txt、ocr仅用于 pipeline 与 hybrid* 后端 -b, --backend [pipeline|vlm-engine|hybrid-engine|vlm-http-client|hybrid-http-client] 解析后端默认为 hybrid-engine --effort [medium|high] Hybrid 解析强度默认medium -l, --lang [ch|ch_server|korean|ta|te|ka|th|el|arabic|east_slavic|cyrillic|devanagari] 指定文档语言可提升 OCR 准确率仅用于 pipeline 后端 -u, --url TEXT 当使用 http-client 时传给服务端后端的 OpenAI 兼容地址 -s, --start INTEGER 开始解析的页码从 0 开始 -e, --end INTEGER 结束解析的页码从 0 开始 -f, --formula BOOLEAN 是否启用公式解析默认开启 -t, --table BOOLEAN 是否启用表格解析默认开启 --image-analysis BOOLEAN 是否启用 VLM 与 hybrid 的图片/图表分析Hybrid medium 强度会自动关闭图片/图表分析默认开启 --client-side-output-generation BOOLEAN 在客户端基于服务端返回的 middle JSON、图片与原文件 生成 Markdown 和 content list默认关闭 --help 显示帮助信息[!TIP]mineru当前支持本地PDF、图片与DOCX、PPTX、XLSX文件或目录输入。2.3 关键参数在源码中的行为输入收集与页码校验。collect_input_documentsmineru/cli/client.py L544-L606在目录输入时会遍历目录下全部文件用guess_suffix_by_path识别后缀并过滤出受支持文档对 PDF 还会调用probe_pdf_effective_pagesL521-L541用 pypdfium2 打开文件取真实页数并在start end时直接抛出Requested page range is empty异常。此外同批存在重名文档同名不同后缀时uniquify_task_stems会自动重命名并打印警告避免输出目录互相覆盖。任务拆分策略处理窗口。plan_tasksL654-L664按后端区分策略pipeline后端调用plan_pipeline_tasksL609-L651做最大剩余式装箱——文档按页数降序排列能把多个短文档合并进同一个不超过processing_window_size的任务批次中而vlm/hybrid类后端则一个文档一个任务。窗口大小来源于服务端健康接口返回的processing_window_size对应环境变量MINERU_PROCESSING_WINDOW_SIZE默认 64这解释了为什么 pipeline 批量处理多个文档时内存占用更可控。并发提交。提交并发数由resolve_submit_concurrency计算取客户端配置上限与服务端max_concurrent_requests的较小值再由execute_planned_tasksL781-L816用asyncio.Queue 固定数量 worker 协程消费任务单个任务失败不会中断其余任务最后统一汇总为N task(s) failed while processing documents异常并列出每个失败任务的文档名与错误信息。页码与语言参数。--start/--end从 0 开始计数负值会直接报--start must be greater than or equal to 0错误run_orchestrated_cliL927-L930。--lang的可选值集合来自 mineru/utils/ocr_language.py 的PUBLIC_OCR_LANGUAGES经validate_public_ocr_lang归一化仅对pipeline后端的 OCR 生效。客户端输出生成。开启--client-side-output-generation后build_request_form_dataL667-L702会把请求中的return_md、return_content_list置为False服务端只回传 middle JSON、模型输出、图片与原文件解压 ZIP 后由 mineru/cli/client_side_output.py 的regenerate_client_side_outputs在本地重建最终 Markdown 与 content list 产物该机制适合需要自定义渲染逻辑如 LaTeX 分隔符的集成场景。结果下载与可视化。每个任务完成后客户端download_result_zip拉取 ZIP 并safe_extract_zip到-o指定的输出目录随后 mineru/cli/visualization.py 中的可视化任务在独立子进程里生成版面可视化图仅 pipeline 后端绘制 span。在终端 TTY 下LiveTaskStatusRendererL179-L289还会实时刷新每个任务的状态条statuspending/processing、队列位次aheadN、task_id方便观察长任务的排队情况。三、mineru-apiFastAPI 解析服务mineru-api --help输出来自 docs/zh/usage/cli_tools.mdmineru-api --help Usage: mineru-api [OPTIONS] Options: --host TEXT 服务器主机地址默认127.0.0.1 --port INTEGER 服务器端口默认8000 --reload 启用自动重载开发模式 --enable-vlm-preload BOOLEAN 在 mineru-api 启动阶段预加载本地 VLM 模型 --help 显示此帮助信息并退出这些选项在 mineru/cli/fast_api.py L1399-L1416 中逐一以click.option定义默认值与文档一致--host默认127.0.0.1、--port默认8000、--enable-vlm-preload默认False。启动时main函数 L1417-L1470会通过arg_parse读取配置并拆分服务配置与模型配置split_service_and_model_config打印Start MinerU FastAPI Service: http://{host}:{port}与API documentation: http://{host}:{port}/docs--reload时走uvicorn.run(..., reloadTrue)开发模式否则构建uvicorn.Server运行并支持MINERU_API_SHUTDOWN_ON_STDIN_EOF环境变量控制的 stdin 关闭监听。源码中与文档环境变量对应的默认值也值得注意mineru/cli/fast_api.py 中DEFAULT_TASK_RETENTION_SECONDS 24 * 60 * 60任务完成后保留 24 小时、DEFAULT_TASK_CLEANUP_INTERVAL_SECONDS 5 * 60每 5 分钟清理一次、DEFAULT_OUTPUT_ROOT ./output输出根路径默认当前工作目录下的./output分别对应下文环境变量的MINERU_API_TASK_RETENTION_SECONDS、MINERU_API_TASK_CLEANUP_INTERVAL_SECONDS、MINERU_API_OUTPUT_ROOT。--enable-vlm-preload由 mineru/cli/vlm_preload.py 的maybe_preload_vlm_model实现在服务启动阶段把本地 VLM 模型加载进缓存使第一个 vlm/hybrid 任务不必再等模型加载适合固定单机部署场景。四、mineru-gradioWeb 界面入口mineru-gradio --help输出来自 docs/zh/usage/cli_tools.mdmineru-gradio --help Usage: mineru-gradio [OPTIONS] Options: --enable-example BOOLEAN 启用示例文件输入(需要将示例文件放置在当前 执行命令目录下的 examples 文件夹中) --enable-http-client BOOLEAN 在后端选项中启用 HTTP 客户端选项 --enable-api BOOLEAN 启用 Gradio API 以提供应用程序服务 --max-convert-pages INTEGER 设置从 PDF 转换为 Markdown 的最大页数 --server-name TEXT 设置 Gradio 应用程序的服务器主机名 --server-port INTEGER 设置 Gradio 应用程序的服务器端口 --api-url TEXT MinerU FastAPI 服务地址不传时自动拉起可复用的本地 mineru-api --enable-vlm-preload BOOLEAN 在 Gradio 拉起本地 mineru-api 时预加载本地 VLM 模型 --client-side-output-generation BOOLEAN 在客户端基于服务端返回的 middle JSON 生成 Markdown 和 content list --latex-delimiters-type [a|b|all] 设置在 Markdown 渲染中使用的 LaTeX 分隔符类型 (a 表示 $ 类型b 表示 ()[] 类型 all 表示两种类型都使用) --help 显示此帮助信息并退出对照源码 mineru/cli/gradio_app.py L1488-L1559 可补充各参数默认值--enable-example默认True示例文件放在当前执行目录的examples文件夹仓库自带 demo/office_docs 与 demo/pdfs 可作为此类示例文件的参考--enable-http-client默认False--enable-api默认True--max-convert-pages默认1000页--server-name/--server-port默认为None交由 Gradio 自动选择--latex-delimiters-type默认all。与mineru客户端一致--api-url不传时会自动拉起可复用的本地mineru-api注意与mineru的临时服务区分Gradio 拉起的 api 在会话期间持续复用。安装 Gradio 依赖可参考 pyproject.toml 中的mineru[gradio]可选依赖gradio5.49.1及gradio-pdf。五、mineru-router多 worker 路由服务mineru-router --help输出来自 docs/zh/usage/cli_tools.mdmineru-router --help Usage: mineru-router [OPTIONS] Options: --host TEXT 路由服务主机地址默认127.0.0.1 --port INTEGER 路由服务端口默认8002 --reload 启用自动重载开发模式 --upstream-url TEXT 现有 MinerU FastAPI 服务地址可重复传入多个 --local-gpus TEXT 本地 GPU worker 配置auto、none 或 0,1,2 形式 --worker-host TEXT 路由托管 worker 的监听地址默认127.0.0.1 --enable-vlm-preload BOOLEAN 在 router 托管的本地 mineru-api worker 中预加载本地 VLM 模型 --help 显示此帮助信息并退出在源码 mineru/cli/router.py L1572-L1605 中各选项与默认值与文档完全一致其中--upstream-url声明为multipleTrue因此可重复传入以接入多个已有mineru-api--local-gpus支持auto、none或0,1,2形式的 CSV源码中对应常量LOCAL_GPU_AUTO auto、LOCAL_GPU_NONE none。main函数会把上游地址、GPU 配置、worker 监听地址、VLM 预加载开关及透传给 worker 的额外命令行参数序列化为环境变量MINERU_ROUTER_UPSTREAM_URLS_JSON、MINERU_ROUTER_LOCAL_GPUS等供多进程模式下 worker 子进程继承。从源码结构看router 内部还实现了较完整的 worker 治理逻辑对上游 5xx 失败会统计UPSTREAM_FAILURE_THRESHOLD 3worker 健康检查连续失败达到WORKER_HEALTH_FAILURE_RESTART_THRESHOLD 5次后触发重启worker 列表按WORKER_REFRESH_INTERVAL_SECONDS 2.0秒刷新。这使得 router 既能托管本地多 GPU 的 mineru-api worker也能路由到已经部署的远端 mineru-api 实例两种 worker 来源SOURCE_LOCAL/SOURCE_REMOTE统一纳入负载均衡。六、环境变量完整说明官方文档强调环境变量通常优先级高于命令行参数且在所有命令行工具中生效。以下完整继承 docs/zh/usage/cli_tools.md 的全部条目环境变量作用默认值备注MINERU_TOOLS_CONFIG_JSON指定配置文件路径用户目录下的mineru.json可指向其他配置文件路径MINERU_FORMULA_ENABLE启用公式解析true设为false禁用公式解析MINERU_FORMULA_CH_SUPPORT中文公式解析优化实验性false设为true启用仅对pipeline后端生效MINERU_TABLE_ENABLE启用表格解析true设为false禁用表格解析MINERU_TABLE_MERGE_ENABLE启用表格合并功能true设为false禁用表格合并MINERU_PDF_RENDER_TIMEOUTPDF 渲染为图片的超时时间秒300在 Linux、macOS 和 Windows 系统中生效MINERU_PDF_RENDER_THREADSPDF 渲染 worker 并发数4在 Linux、macOS 和 Windows 系统中生效MINERU_PROCESSING_WINDOW_SIZE单次处理窗口大小64影响大文档处理的内存占用与吞吐需为正整数MINERU_API_MAX_CONCURRENT_REQUESTSmineru-api/mineru-router管理的 worker 最大并发请求数3需设置为正整数MINERU_API_ENABLE_FASTAPI_DOCS控制是否启用 FastAPI 自动生成的/docs、/openapi.json、/redoctrue生产环境建议按需关闭MINERU_API_OUTPUT_ROOTmineru-api输出目录根路径当前工作目录下的./output与 mineru/cli/fast_api.py 中DEFAULT_OUTPUT_ROOT ./output一致MINERU_LOCAL_API_STARTUP_TIMEOUT_SECONDS等待本地拉起的mineru-api进入健康状态的最长时间300秒适用于mineru的临时本地 API、mineru-gradio的 preload 启动以及mineru-router托管的本地 workerMINERU_TASK_RESULT_TIMEOUT_SECONDS客户端等待任务完成并进入终态的最长时间3600秒需设置为1适用于mineru、mineru-gradio、mineru-router等通过 API 客户端轮询任务状态的场景MINERU_TASK_RESULT_DOWNLOAD_TIMEOUT_SECONDS任务完成后获取结果的读取超时时间含服务端生成 ZIP 的等待与结果 ZIP 下载600秒需设置为1不代表整个下载过程的总耗时硬上限服务端持续返回数据时整体下载时间可能超过该值MINERU_API_TASK_RETENTION_SECONDS任务完成或失败后的保留时长秒86400秒24 小时对应 mineru/cli/fast_api.py 中DEFAULT_TASK_RETENTION_SECONDSMINERU_API_TASK_CLEANUP_INTERVAL_SECONDS任务清理轮询间隔秒300秒5 分钟对应DEFAULT_TASK_CLEANUP_INTERVAL_SECONDSMINERU_INTRA_OP_NUM_THREADSONNX 模型 intra_op 线程数影响单算子计算速度-1自动选择可设置为其他值调整线程数MINERU_INTER_OP_NUM_THREADSONNX 模型 inter_op 线程数影响多算子并行执行-1自动选择可设置为其他值调整线程数MINERU_HYBRID_BATCH_RATIOhybrid-* 后端中小模型处理的 batch 倍率—在hybrid-http-client中较常用可通过控制 batch 倍率调整单客户端显存占用官方建议值见下表MINERU_VL_MODEL_NAME指定 vlm/hybrid 后端使用的模型名称—便于在同一远程 OpenAI 兼容服务并存多模型时指定 MinerU 所需模型MINERU_VL_API_KEY指定 vlm/hybrid 后端使用的 API Key—用于在远程 OpenAI 兼容服务中进行身份验证官方文档给出的MINERU_HYBRID_BATCH_RATIO显存对照建议单个 client 端显存大小MINERU_HYBRID_BATCH_RATIO 6 GB8 4 GB4 3 GB2 2 GB1这些超时/并发类变量在源码中的落点可以逐一核对mineru-api/mineru-router的 worker 启动与健康等待逻辑位于 mineru/cli/api_client.pyLOCAL_API_STARTUP_TIMEOUT_SECONDS、TASK_RESULT_TIMEOUT_SECONDS、build_result_download_timeout等常量均在此定义并被 mineru/cli/router.py 导入而并发协商则通过健康接口返回的max_concurrent_requests完成见 mineru/cli/api_protocol.py 中的DEFAULT_MAX_CONCURRENT_REQUESTS、DEFAULT_PROCESSING_WINDOW_SIZE。七、典型使用示例结合文档与源码给出三类典型场景1. 单机直接解析自动拉起临时 mineru-api# 使用默认 hybrid-engine 后端解析一个 PDF mineru -p demo/pdfs/demo1.pdf -o ./output # 指定 pipeline 后端、指定页码范围与 OCR 语言 mineru -p demo/pdfs/demo1.pdf -o ./output -b pipeline -m ocr -l ch -s 0 -e 9 # 使用本地大模型的高精度 hybrid 后端high 强度含图片/图表分析 mineru -p demo/pdfs/demo1.pdf -o ./output -b hybrid-engine --effort high2. 对接远程 OpenAI 兼容 VLM 服务# 先用 mineru 自带的 vllm 入口起一个 OpenAI 兼容推理服务另开终端 mineru-vllm-server # 客户端通过 hybrid-http-client 后端 --url 指向该服务 MINERU_VL_MODEL_NAME模型名 mineru \ -p demo/pdfs/demo1.pdf -o ./output \ -b hybrid-http-client -u http://127.0.0.1:300003. 服务化部署mineru-api mineru-router# 起一个 mineru-api可先预加载 VLM 模型减少首任务延迟 mineru-api --host 127.0.0.1 --port 8000 --enable-vlm-preload true # 起一个 router复用上述 api 并自动拉起本地 GPU worker mineru-router --upstream-url http://127.0.0.1:8000 --local-gpus auto --port 8002 # 或直接以 Gradio 界面接入现有服务 mineru-gradio --api-url http://127.0.0.1:8000多机/多卡生产部署时可按文档建议将MINERU_API_MAX_CONCURRENT_REQUESTS、MINERU_TASK_RESULT_TIMEOUT_SECONDS等环境变量与MINERU_TOOLS_CONFIG_JSON配置文件结合使用控制每台 worker 的并发与客户端等待上限。八、小结mineru是基于mineru-api的编排客户端不传--api-url自动拉起临时本地服务传入则直连远端--url仅服务于vlm/hybrid-http-client的 OpenAI 兼容地址mineru-api是核心 FastAPI 服务默认127.0.0.1:8000支持 VLM 预加载与/docs文档任务保留 24 小时、每 5 分钟清理mineru-gradio提供 Web 操作界面可指定示例输入、HTTP 客户端后端选项、最大转换页数与 LaTeX 分隔符类型mineru-router默认端口8002把已有 mineru-api 实例与本地多 GPU 托管 worker统一编排进负载均衡并自带上游失败检测与 worker 自愈重启机制环境变量在所有 CLI 工具中生效且优先级高于命令行参数涵盖解析开关公式/表格/表格合并、渲染与窗口控制MINERU_PDF_RENDER_*、MINERU_PROCESSING_WINDOW_SIZE、API 超时与任务保留MINERU_TASK_RESULT_*、MINERU_API_TASK_*、ONNX 线程MINERU_*_OP_NUM_THREADS以及 hybrid 显存调优MINERU_HYBRID_BATCH_RATIO等维度。以上参数与行为均可在 docs/zh/usage/cli_tools.md、mineru/cli/client.py、mineru/cli/fast_api.py、mineru/cli/router.py、mineru/cli/gradio_app.py 与 pyproject.toml 中交叉核对如需进一步了解解析结果文件的目录结构可继续阅读 输出文件说明 与 高级 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），仅供参考