企业官网建设流程全解析

MinerU：快速把 PDF 和 Office 文档转成 LLM 可用的 Markdown，4 条路径覆盖纯 CPU 到多卡环境

【免费下载链接】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 是一个开源文档解析工具，把 PDF、图片、DOCX、PPTX、XLSX 转成结构化 Markdown 和 JSON，公式还原成 LaTeX，表格转 HTML，自动去除页眉页脚和页码，输出可直接喂给 LLM、RAG 管线。这篇文章按"本机快速跑通、有显卡要加速、没显卡走远程、多机分摊任务"四种环境，分别给出最短路径，并说明首次运行出错时该查哪里。

一、本机第一次跑通：装依赖、解析一个文件、核对输出

用一行命令装好依赖

先装 uv（比 pip 更快的包管理器），再装 core 依赖，它包含 VLM 和 pipeline 两种解析后端，不含 vllm：

uv pip install "mineru[core]"

机器有 8G 以上显存的 NVIDIA 显卡时，直接装全量更省事：

uv pip install "mineru[all]"

解析第一个 PDF

首次运行会自动下载模型并缓存，所以第一遍会比较慢。默认后端是 hybrid-engine（大模型 VLM 加小模型分工协作），没有显卡就加-b pipeline走纯 CPU 路线：

mineru -p demo/pdfs/demo1.pdf -o output

注：mineru命令在不传--api-url时会先自动拉起一个本地临时的 mineru-api 服务再执行解析，首次运行感觉慢是正常的，属预期行为。

输出目录里会生成 Markdown、按阅读顺序排列的 JSON 和图片裁剪文件。对照下图的版面框选结果，可以确认文本块、表格、公式是否都识别到位：

整条链路是：输入文档 → 版面识别 → 内容抽取（文本 / 公式 / 表格）→ Markdown 与 JSON 输出：

模型下载不下来怎么办

模型默认从 HuggingFace 拉取，国内网络不通时切换到 ModelScope 源：

export MINERU_MODEL_SOURCE=modelscope

二、显存 8G 以上的显卡怎么用上

显卡是 Volta 及以后架构（例如 V100、20/30/40 系）且显存 8G 起时，VLM 引擎能给到最高解析精度。Linux 下安装 vllm 推理框架（高吞吐大模型推理引擎）：

uv pip install "mineru[core,vllm]"

注：vllm 和 lmdeploy 二选一，不建议同时安装；Windows 用户选 lmdeploy。

装完直接跑解析命令即可，无需额外配置：

mineru -p input.pdf -o output -b hybrid-engine

精度不够时加--effort high切换高强度解析；默认 medium 档更快，但不支持图片/图表分析。自动检测显存不准时可用环境变量覆盖：

export MINERU_DEVICE_MODE=cuda export MINERU_VIRTUAL_VRAM_SIZE=16

三、没有显卡：轻量客户端连远程服务

机器只有 CPU 和网络时，装基础包即可（不含 torch，很轻），重计算放到远端。

在一台有显卡的机器上启动 OpenAI 兼容推理服务：

mineru-openai-server --port 30000

CPU 机器上装轻量客户端并指定服务地址：

uv pip install mineru mineru -p input.pdf -o output -b vlm-http-client -u http://server-ip:30000

如果远端跑的是通用 API 服务而非 VLM 端点，用 mineru-api 配合--api-url直连：

mineru-api --host 0.0.0.0 --port 8000 mineru -p input.pdf -o output --api-url http://server-ip:8000

四、多 GPU 或多台机器怎么分摊任务

批量生产环境用mineru-router做统一入口，它会自动按本地 GPU 拉起 worker，或聚合多个已有 mineru-api 实例做负载均衡：

mineru-router --host 0.0.0.0 --port 8002 --local-gpus auto

已有服务可以显式指定上游：

mineru-router --port 8002 \ --upstream-url http://gpu-1:8000 \ --upstream-url http://gpu-2:8000

接口与 mineru-api 完全一致，支持POST /tasks异步提交和POST /file_parse同步解析，客户端只需要把入口地址换过来。

五、首次运行常见的三个坑，查哪里

📌Linux 上结果缺字、中文显示异常：多数不是解析问题，而是系统缺 CJK 字体，导致 PDF 渲染成图片时丢字。安装fonts-noto-cjk后执行fc-cache -fv即可，详见 FAQdocs/zh/faq/index.md。

⚠️显存不够或推理慢：改-b pipeline回退到 CPU 可用方案（精度略低，4G 显存即可）；客户端模式想压显存，调小MINERU_HYBRID_BATCH_RATIO（8G 设 8、4G 设 4、2G 设 1）。

模型下载失败或超时：先确认MINERU_MODEL_SOURCE设置正确；第二次运行起直接走本地缓存。指定本地模型目录的方法在docs/zh/usage/model_source.md。

更多参数跑mineru --help可看全量选项，环境变量完整列表在docs/zh/usage/cli_tools.md。按自己的环境选定一条部署路径后，就可以把解析产物接进自己的 RAG 或 Agent 流程了。

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