MinerU 扩展模块安装实战：core、vllm、lmdeploy、s3 与轻量 HTTP Client 模式详解

MinerU 扩展模块安装实战core、vllm、lmdeploy、s3 与轻量 HTTP Client 模式详解【免费下载链接】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 各扩展模块core、s3、vllm、lmdeploy、pipeline 等的安装命令、适用场景与显存/驱动要求并结合 pyproject.toml 中的依赖声明和 mineru/cli/backend_options.py 等源码说明每个扩展模块如何对应到具体的解析后端与服务端入口帮助你在不同硬件条件下选择并落地最合适的安装方案。一、为什么 MinerU 要拆分扩展模块MinerU 将 PDF、图片、DOCX、PPTX、XLSX 解析为可供 LLM 使用的 Markdown/JSON。不同使用场景对依赖的诉求差异很大只做本地文档解析需要core含 torch、transformers、onnxruntime、gradio 等重依赖想用 vLLM 或 LMDeploy 加速 VLM 推理需要对应的推理框架需要从 S3 读写文件需要boto3边缘设备只做客户端只依赖基础包即可无需任何 GPU 依赖。因此 MinerU 在 pyproject.toml 中通过[project.optional-dependencies]定义了细粒度的扩展分组按需安装可以避免在不必要的设备上引入庞大的推理框架依赖。二、常见场景与安装命令2.1 核心功能安装corecore模块是 MinerU 的核心依赖包含常用解析功能不包含vllm/lmdeploy/s3等可选模块。安装此模块可以确保 MinerU 基本功能正常运行uv pip install mineru[core]从 pyproject.toml 的声明看core是三个分组的组合core [ mineru[vlm], mineru[pipeline], mineru[gradio], ]其中vlm组引入torch2.6.0,3、transformers4.57.3,5.0.0、accelerate1.5.1用于本地 VLM 推理pipeline组引入PyYAML、shapely、pyclipper、torch、torchvision、onnxruntime1.17.0等用于传统 OCR/版面分析管线gradio组引入gradio与gradio-pdf用于 WebUI。这意味着安装core后即可覆盖本地pipeline、vlm-engine、hybrid-engine三种后端见 mineru/cli/backend_options.py 中的LOCAL_BACKEND_CHOICES。2.2 使用 S3 输入输出s3如需通过 S3 读取或写入文件请安装s3扩展模块uv pip install mineru[s3]该分组在 pyproject.toml 中仅引入boto31.28.43是一个非常轻量的可选依赖。MinerU 内部在 mineru/data/io/s3.py 中封装了 S3 的输入/输出访问逻辑安装后即可在数据读写路径中使用 S3 地址。2.3 使用 vllm 加速 VLM 模型推理说明vllm和lmdeploy对 VLM 的推理加速效果和使用方式几乎相同可根据实际情况选择其中之一安装使用但不建议同时安装这两个模块以避免潜在的依赖冲突。vllm模块提供了对 VLM 模型推理的加速支持适用于具有Volta 及以后架构的显卡8G 显存及以上。安装此模块可以显著提升模型推理速度uv pip install mineru[core,vllm]在 pyproject.toml 中该分组的版本约束为vllm0.10.1.1,0.22.0。安装时需要注意以下几点源自官方指南的提示由于vllm扩展包已放开到 0.21 系列版本默认安装通常会选择当前允许范围内更高的vllm版本。请确保物理机显卡驱动支持所安装vllm包对应的 CUDA 运行时默认路径需要CUDA 13.0 兼容驱动如需使用 CUDA 12.9 兼容环境可参考 vLLM 官方安装文档选择对应的 CUDA 安装方式或直接使用 Docker 部署 中的vllm/vllm-openai:v0.21.0-cu129基础镜像如在安装包含vllm的扩展包过程中发生异常同样可参考 vLLM 官方文档尝试解决。源码印证vLLM 服务端如何被拉起MinerU 在 pyproject.toml 的[project.scripts]中注册了mineru-vllm-server入口指向 mineru/cli/vlm_server.py 的vllm_server函数其实际实现位于 mineru/model/vlm/vllm_server.py。从源码可以看出几个关键默认行为默认监听端口为30000未显式传--port时自动追加[--port, 30000]这正是轻量客户端示例中-u http://127.0.0.1:30000的由来若未显式指定模型路径会调用auto_download_and_get_model_root_path(/, vlm)自动下载并定位 VLM 模型默认按设备类型设置--gpu-memory-utilization并可通过自定义 logits processor 追加--logits-processors mineru_vl_utils:MinerULogitsProcessor启动前会将OMP_NUM_THREADS默认设为1然后以serve model_path ...方式调用 vLLM 自带的main入口。2.4 使用 lmdeploy 加速 VLM 模型推理说明与 vllm 相同二选一即可不建议同时安装。lmdeploy模块同样提供对 VLM 模型推理的加速支持适用于Volta 及以后架构的显卡8G 显存及以上uv pip install mineru[core,lmdeploy]pyproject.toml 中该分组声明为lmdeploy0.10.2,0.12与qwen-vl-utils0.0.14,1。如在安装过程中发生异常可参考 LMDeploy 官方安装文档尝试解决。从 mineru/cli/vlm_server.py 的openai_server命令看MinerU 还提供了统一的mineru-openai-server入口当--engine auto默认时它优先尝试导入vllm失败则回退到lmdeploy两者都未安装时直接报错退出。因此在只安装了lmdeploy的机器上mineru-openai-server会自动选择 LMDeploy 引擎对外提供 OpenAI 兼容服务与安装了vllm的机器使用体验一致。2.5 安装轻量版 client 连接兼容 OpenAI 服务器vlm-http-client 模式如果需要在边缘设备上安装轻量版 client 端以连接兼容 OpenAI 接口的服务端来使用 VLM 模式可以直接安装 mineru 基础包——它非常轻量适合在只有 CPU 和网络连接的设备上使用uv pip install mineru mineru -p input_path -o output_path -b vlm-http-client -u http://127.0.0.1:30000这里的-b vlm-http-client对应源码 mineru/cli/backend_options.py 中的BACKEND_VLM_HTTP_CLIENT属于HTTP_CLIENT_BACKEND_CHOICES-u参数在 mineru/cli/client.py 的定义中要求当 backend 为vlm/hybrid-http-client时必须指定 OpenAI 兼容服务的server_url例如http://127.0.0.1:30000。demo/demo.py 中的示例注释同样确认vlm-http-client用于连接远程 OpenAI 兼容 VLM 服务。根据 mineru/cli/api_request.py 中的说明该模式通过远程算力获得高精度适合 OpenAI 兼容服务器目前仅支持中文和英文文档。2.6 安装轻量版 client 连接兼容 OpenAI 服务器hybrid-http-client 模式如果要在边缘设备上连接兼容 OpenAI 接口的服务端使用 hybrid 模式可以安装 mineru 的pipeline扩展包。它相对较轻量可以在只有 CPU 和网络连接的设备上使用同时在支持 GPU 加速的设备上可以更快运行uv pip install mineru[pipeline] mineru -p input_path -o output_path -b hybrid-http-client -u http://127.0.0.1:30000hybrid-http-client与vlm-http-client的核心差异结合 mineru/cli/api_request.py 与 mineru/cli/client.py 的说明模式本地算力需求特点语言支持vlm-http-client几乎无CPU网络即可高精度全部依赖远程算力中文、英文hybrid-http-client少量本地算力混合解析远程算力为主本地承担部分环节可通过--effort切换 medium/high 行为多语言--effort参数的取值与默认值在 mineru/cli/backend_options.py 中定义为HYBRID_EFFORT_CHOICES (medium, high)、DEFAULT_HYBRID_EFFORT medium仅对hybrid-*后端生效。2.7 一站式安装all补充说明除官方指南列出的场景外pyproject.toml 还定义了all分组按操作系统平台自动裁剪可选依赖all [ mineru[core], mineru[s3], mineru[mlx] ; sys_platform darwin, mineru[vllm] ; sys_platform linux, mineru[lmdeploy] ; sys_platform win32, ]即macOS 上追加mlxmlx-vlm0.3.3,0.4Linux 上追加vllmWindows 上追加lmdeploy。这体现了官方按平台选择推理引擎的思路与 vllm/lmdeploy 二选一的说明相互印证。需要说明的是该分组不在扩展模块指南的正文场景中属于源码中的补充能力适合希望在单一平台上尽量装全的用户自行评估后使用。三、扩展模块与解析后端的对应关系MinerU 的mineru命令通过-b/--backend选择解析后端。mineru/cli/backend_options.py 定义了全部公开后端选项BACKEND_PIPELINE pipeline BACKEND_VLM_ENGINE vlm-engine BACKEND_HYBRID_ENGINE hybrid-engine BACKEND_VLM_HTTP_CLIENT vlm-http-client BACKEND_HYBRID_HTTP_CLIENT hybrid-http-client DEFAULT_BACKEND BACKEND_HYBRID_ENGINE本地后端pipeline/vlm-engine/hybrid-engine依赖core其中vlm-engine依赖 vlm 分组的 torch/transformersHTTP 客户端后端vlm-http-client/hybrid-http-client分别对应 2.5、2.6 节的轻量安装方案默认后端为hybrid-engineDEFAULT_BACKEND即安装core后不带-b参数时直接走本地 hybrid 解析旧名称vlm-auto-engine、hybrid-auto-engine会被normalize_backend自动映射为新名称。四、服务端命令速查在 GPU 机器上提供 OpenAI 兼容服务时pyproject.toml 注册了以下入口均实现于 mineru/cli/vlm_server.py 及 mineru/model/vlm/ 下的各 server 模块命令作用依赖扩展mineru-vllm-server以 vLLM 启动 VLM 服务默认端口 30000自动下载模型mineru[core,vllm]mineru-lmdeploy-server以 LMDeploy 启动 VLM 服务mineru[core,lmdeploy]mineru-openai-server--engine auto自动选择 vllm/lmdeploy 启动 OpenAI 兼容服务二者装其一即可mineru-api启动 MinerU FastAPI Web API 服务mineru[core]边缘设备侧则只需基础包或pipeline分组通过-u指定服务端地址即可接入实现重算力在服务器、轻客户端在边缘的部署形态。五、选型建议与注意事项本地 GPU 解析显存 ≥8G 且显卡为 Volta 及以后架构时安装mineru[core,vllm]或mineru[core,lmdeploy]二选一以获得 VLM 推理加速不满足硬件条件时mineru[core]使用本地hybrid-engine/vlm-engine后端。驱动/CUDA 匹配默认安装的 vllm 高版本路径要求 CUDA 13.0 兼容驱动CUDA 12.9 环境建议使用 Docker 部署 中的v0.21.0-cu129镜像该 Dockerfile 默认集成 vllm 推理框架适合规避环境兼容问题。纯客户端场景只有 CPU网络的设备装基础包用vlm-http-client中英文文档需要多语言或愿意付出少量本地算力时装mineru[pipeline]用hybrid-http-client。S3 对象存储读写追加安装mineru[s3]底层基于boto3。依赖冲突预防vllm 与 lmdeploy 不建议共存所有版本约束以当前仓库 pyproject.toml 的实际声明为准跨大版本升级前请重新核对。按上述选择安装扩展模块后即可在 GPU 服务器或边缘设备上运行对应的解析/服务命令完成 MinerU 在不同算力条件下的完整部署。【免费下载链接】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），仅供参考