前面我们介绍了如何使用MinerU的网页端进行文件的处理。但是我们总不能每次文档都去网页上处理吧，所以我们需要有工程化的手段来实现。介绍两种方案：
使用API服务
这种方式适合小团队，要处理的pdf不多，对处理速度要求不高的情况。个人实验也建议用这种。
登录MinerU的网站，进入token页面，申请token：https://mineru.net/apiManage/token
这个过程需要官方审批，审批也挺快的，申请下来之后，就有一个token可以用了。
每一个用户每天可以解析10000份文件，可以优先解析2000页文档，一般来说是够用了。
有了这个token之后，就可以通过api来做文件解析了。
使用CURL可以做单文档的解析：
下面的*** 换成你的token，https://cdn-mineru.openxlab.org.cn/demo/example.pdf 换成你自己的pdf的文档，一定要是公网可以访问的地址。可以放到oss上，或者是有公网域名的minio上面。
curl --location --request POST 'https://mineru.net/api/v4/extract/task' \
--header 'Authorization: Bearer ***' \
--header 'Content-Type: application/json' \
--header 'Accept: */*' \
--data-raw '{
"url": "https://cdn-mineru.openxlab.org.cn/demo/example.pdf",
"model_version": "vlm"
}'
这个接口是创建解析任务的，他会返回给一个task_id，然后可以通过这个task_id来查看任务的状态。
可以通过以下方式查看任务状态，task_id换成上面返回的那个id：
curl --location --request GET 'https://mineru.net/api/v4/extract/task/{task_id}' \
--header 'Authorization: Bearer *****' \
--header 'Accept: */*'
返回结果状态有这么几个：任务处理状态，done:完成，pending: 排队中，running: 正在解析，failed：解析失败，converting：格式转换中
过一段时间再查询，如果解析完了，会能得到一个压缩包地址：
（下面的task_id和上面的不一致请忽略，你就认为是同一个就行了，截图没截到）
解析成功的话，state会是done，然后在full_zip_url中会有一个压缩包，把他下载下来，解压后如下图：
这面包含了原始的pdf、解析后的json格式、markdown格式，以及对应的图片也都放到images目录下了。以下是ai关于这些文件的解释：
除了上面的单个文件解析的方式，API中还提供了批量接口，可以提交批量的解析任务和批量查看解析结果。
使用自建服务
除了使用官方api，如果你的处理的任务量很大，对速度有要求，也可以自己部署。或者是，如果你的文档有隐私数据，或者是公司内部数据，不想暴力的，也不建议用api服务方式，建议用自建服务。 安装要求：Python 3.10-3.13, 至少 16GB RAM (32GB 建议), 20GB 磁盘空间
uv init mineru
cd
uv venv
uv pip
不要像官网一样安装"mineru[all]" ，我们只安装core 模块，core是 MinerU 的核心依赖，包含了除vllm/lmdeploy外的所有功能模块。安装此模块可以确保 MinerU 的基本功能正常运行。
（需要安装3.0以上的版本，否则无法处理doc、docx等类型文件）
或者通过源码安装:
git
cd
uv venv
uv pip
使用方式：命令行（最简单） 有 GPU（默认使用 hybrid-auto-engine 后端）：
source
mineru -p input.pdf -o output_dir/ --source modelscope
纯 CPU 环境（使用 pipeline 后端）：
source
mineru -p input.pdf -o output_dir -b pipeline --source modelscope
我运行的是：
--下载一个pdf
wget https://cdn-mineru.openxlab.org.cn/demo/example.pdf
--pdf解析
mineru -p example.pdf -o output_dir -b pipeline --source modelscope
第一次运行的时候，这个过程会下载一些依赖的模型：
运行结束后，会把解析后的文件放在output_dir中：
目录：/output_dir/example/auto
其中的markdown内容如下：
常用参数说明：
| 参数 | 说明 |
| --- | --- |
| -p | 输入 PDF 文件或目录 |
| -o | 输出目录 |
| -b | 后端引擎： |
| -m | 解析方式： |
| -l | 语言代码（如 |
| -s | 起始/结束页码（从 0 开始） |
| -d | 推理设备： |
| -f | 是否启用公式/表格解析（默认 |
| --source | 选择模型源 |
引擎对比 | 后端引擎 | 是否需要 GPU | 最低显存 | 适用场景 | | --- | --- | --- | --- | | pipeline | 否 | 无 | 纯 CPU 环境 | | vlm | 是（Volta架构+） | 10GB | 最高精度 | | hybrid | 是（Volta 架构+） | 8GB | 多语言 OCR +高精度 | | *-auto-engine | 可选 | 3GB | 自动选择最佳引擎 |
常见问题
1.markdown不支持多级标题 如果大家仔细看的话，会发现，解析后的markdown都只有一级标题，并且原来的PDF中的多级标题都会变成一级标题。这个问题github也有很多人提过。 官方的回复是： 也就是说，如果想要识别多级标题，需要用LLM，这。。。我感觉是没啥必要。 2.长时间卡住 本地自建服务做文档解析的时候，如果长时间卡住不动，那么可能是因为默认情况下，mineru会使用huggingface的模型，而可能你的网络并不能访问huggingface，那么就需要使用modelscope的模型，则可以：
mineru -p input.pdf -o output_dir --source modelscope
依赖的模型：
如果都不行，可以考虑先把模型下载到本地，然后使用本地模型运行：
3.python版本不支持
这个也是比较常见的问题，miner目前只支持3.10-3.13的python，比我的电脑最开始3.14，就是不支持的。
还有一种情况，就是可能创建的虚拟环境还是用的升级前的版本，所以需要创建一个基于 Python 3.11 的虚拟环境，激活后，所有的 python 和 pip (以及 uv) 都会自动指向该环境内的 3.11 版本，完全不受系统 3.6 干扰。
## 在当前目录创建一个名为 .venv 的虚拟环境，指定使用 python3.11
uv venv --python python3.11
4.安装报错
在安装mineru的时候，可能会因为各种各样的环境问题导致安装失败，如比如：
这种就借助ai的力量，遇到一个解决一个。上面这个问题ai告诉我运行：brew install pkg-config ffmpeg 就行了。
5.运行报错
我安装的 opencv-python 包依赖于系统的图形库（OpenGL），但你的 Alibaba Cloud Linux 系统（通常是极简安装）缺少这些底层的共享库文件。cv2 (OpenCV) 在初始化时需要加载 libGL.so.1，找不到就报错了。
安装缺失的库：
sudo yum install -y mesa-libGL libglvnd-glx libSM libXext libXrender