MinerU 实战指南5 步把 PDF 变成 LLM 可用的 Markdown【免费下载链接】MinerUTransforms complex documents like PDFs and Office docs into LLM-ready markdown/JSON for your Agentic workflows.项目地址: https://gitcode.com/GitHub_Trending/mi/MinerUMinerU 是一款文档解析工具把 PDF、图片、DOCX、PPTX、XLSX 转换成可供 LLM 直接消费的 Markdown 和 JSON。这篇文章先让机器在 3 分钟内跑通第一次解析再按硬件选后端、上 GPU 加速最后给出纯 CPU 机器的轻量客户端方案和一份避坑清单。1. 安装步骤3 种规格按需选择MinerU 把依赖拆成了模块基础包很轻core 包含本地解析的全部能力。先按设备情况挑一种装法安装命令包含内容适用场景uv pip install mineru仅基础依赖边缘设备、远程客户端uv pip install mineru[core]pipeline vlm gradio不含 vllm绝大多数本地机器uv pip install mineru[all]core s3 vllmLinux/ lmdeployWindows/ mlxmacOS想一次装齐uv pip install mineru[core]这条命令一次性装好本地解析能力首次运行时会自动下载模型文件之后直接加载本地缓存。要求 Python 3.10~3.13Windows 上受 ray 依赖限制最高到 3.12。2. 首次解析5 种后端按硬件选mineruCLI 提供 5 种解析后端默认是 hybrid-engine。下表分数为官方文档中 OmniDocBench v1.6 的端到端 Overall 得分后端精度得分硬件底线pipeline86.47纯 CPU 可跑GPU 加速需 4GB 显存hybrid-engine默认95.26medium/ 95.39high8GB 显存vlm-engine95.398GB 显存hybrid-http-client95.302GB 显存连 OpenAI 兼容服务vlm-http-client95.392GB 显存连 OpenAI 兼容服务装好后跑第一条解析命令mineru -p input.pdf -o output/-p是输入文件或目录-o是输出目录跑完会得到 Markdown、内容清单和切出的图片。纯 CPU 机器加-b pipeline中文文档 OCR 效果不理想时加-l ch指定语言仅 pipeline 后端支持。hybrid 后端还有--effort参数控制解析强度官方数据显示 medium 相比 high 综合精度只低 0.13解析速度可提升 35%~220%。默认 medium追求极限精度再切 high。3. 性能进阶vllm 的 GPU 加速显卡是 Volta 架构及以后、显存 8GB 及以上时可以装 vllm 或 lmdeploy 加速 VLM 推理。两者效果和使用方式几乎相同二选一安装即可不建议同时装以避免依赖冲突安装时用uv pip install mineru[core,vllm]即可把加速框架和核心装在一起。注意 vllm 默认安装会选 0.21 系列需要 CUDA 13.0 兼容驱动驱动较旧时参考 vllm 官方文档选择 cu129 对应的安装方式。本地装不上就用 Docker官方镜像基于 vllm/vllm-openai已预装 vllm 和依赖。docker run --gpus all --shm-size 32g -p 30000:30000 -p 8000:8000 -it mineru:latest /bin/bash这条命令把 GPU 和模型服务、FastAPI 的端口映射出来进容器即可直接运行mineru省去环境适配。驱动只支持 CUDA 12.9 时把 Dockerfile 顶部的默认基础镜像换成注释中的 cu129 版本。4. 部署上生产客户端/服务端分离分离部署适合一台 GPU 机器服务多台 CPU 机器GPU 端跑服务端其余机器装轻量客户端客户端显存要求只有 2GB。组件安装分工服务端mineru[all]或 Docker 镜像承载 GPU 与模型vlm-http-clientuv pip install mineruVLM 部分全部走远程服务hybrid-http-clientuv pip install mineru[pipeline]本地小模型 远程 VLM客户端用-u参数传入 OpenAI 兼容的服务地址服务端挂了多个模型时用MINERU_VL_MODEL_NAME指定模型、MINERU_VL_API_KEY做鉴权。hybrid-http-client 下按客户端显存调整小模型的 batch 倍率直接决定内存占用客户端显存MINERU_HYBRID_BATCH_RATIO≤6GB8≤4GB4≤3GB2≤2GB15. 避坑清单常见问题与环境变量环境变量的优先级高于命令行参数且对所有 mineru 系列工具生效。高频问题按出现频率排问题处理办法访问不了 HuggingFaceexport MINERU_MODEL_SOURCEmodelscope切国内镜像vllm 安装失败改用预构建 Docker 镜像或按 vllm 官方文档固定 CUDA 版本显存溢出--effort改 medium调低MINERU_API_MAX_CONCURRENT_REQUESTS默认 3与MINERU_HYBRID_BATCH_RATIO大文档内存吃紧调整MINERU_PROCESSING_WINDOW_SIZE默认 64它控制单次处理窗口大小长任务等待超时MINERU_TASK_RESULT_TIMEOUT_SECONDS默认 3600 秒按需调大只想处理纯文本时把MINERU_FORMULA_ENABLE和MINERU_TABLE_ENABLE设为 false 可以跳过公式与表格模型明显缩短耗时。下一步全部 CLI 参数页码范围、解析方法 auto/txt/ocr 等见 docs/zh/usage/cli_tools.md各扩展模块的详细说明见 docs/zh/quick_start/extension_modules.mdDocker 镜像与端口细节见 docs/zh/quick_start/docker_deployment.md【免费下载链接】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），仅供参考