图片

原本问知识库的问题是“四年级下册教授的数学公式有哪些？”，希望AI从已上传的数学书教材中总结回答，结果召回测试的结果却是从不想干的文档中找答案。这也说明该教材pdf文件没有被知识库大模型的向量解析识别到。通过分析市面上开源免费效果好的解决办法，找到了MinerU这款国内的开源软件来对版扫描pdf文件做预处理后再上传Dify知识库。

MinerU的官方网址：“https://mineru.net/”

MinerU在GitHub上的地址：“https://github.com/opendatalab/MinerU”

MinerU就是一款一站式开源高质量数据提取工具，它可以将PDF转换成机器可读的Markdown和JSON格式。 MinerU诞生于“书生·浦语”（“https://github.com/InternLM/InternLM”） 的预训练过程中，MinerU将会集中精力解决科技文献中的符号转化问题，目前GitHub上最新版本是“magic_pdf-1.3.11-released”。

一、MinerU的主要功能：

MinerU的主要功能如下所示：

删除页眉、页脚、脚注、页码等元素，确保语义连贯

输出符合人类阅读顺序的文本，适用于单栏、多栏及复杂排版

保留原文档的结构，包括标题、段落、列表等

提取图像、图片描述、表格、表格标题及脚注

自动识别并转换文档中的公式为LaTeX格式

自动识别并转换文档中的表格为HTML格式

自动检测版扫描PDF和乱码PDF，并启用OCR功能

OCR支持84种语言的检测与识别

支持多种输出格式，如多模态与NLP的Markdown、按阅读顺序排序的JSON、含有丰富信息的中间格式等

支持多种可视化结果，包括layout可视化、span可视化等，便于高效确认输出效果与质检

支持纯CPU环境运行，并支持 GPU(CUDA)/NPU(CANN)/MPS 加速

兼容Windows、Linux和Mac平台

二、Windows11本地安装MinerU软件本体

由于我的Dify需要连接MinerU的web API，咨询过MinerU官方同学，明确几个容易混淆的概念：

是不是安装“Windows版MinerU客户端”软件就能使用web API了？

其实不是的，“Windows版MinerU客户端”软件真的就是一个“客户端”，它使用的是MinerU云端的算力。我也真的安装并测试过，效果一言难尽。且客户端没有开放接口，无法与web API连接。

MinerU的web API使用的是云端算力？或者本地MinerU算力？

官方回复“当然是MinerU本地算力”。所以需要先在Windows11本地安装MinerU软件本体。

Windows10/11本地安装MinerU软件本地的官方指南链接如下：

【https://github.com/opendatalab/MinerU/blob/master/docs/README_Windows_CUDA_Acceleration_zh_CN.md 】

1、安装cuda环境

先检查自己的cuda版本。使用MobaXterm登录到“Ubuntu24.04”这个默认WSL环境中，通过如下命令检查自己的设备是否支持在docker上使用CUDA加速。

sudo docker run --rm --gpus=all nvidia/cuda:12.1.0-base-ubuntu22.04 nvidia-smi

图片

上图可见，一开始也没有在本地找到“nvidia/cuda:12.1.0-base-ubuntu22.04”的镜像，然后就自动下载了最新CUDA镜像，版本到了12.8；并且显示了本地GPU的型号和显存容量。

注意：MinerU官方要求“Windows10/11+GPU方式运行Docker形态MinerU需设备GPU显存大于等于6GB，默认开启所有加速功能”。

由于官网的docker安装cuda环境的命令一直报错，所以改为Windows本地直接安装MinerU软件。

需要安装符合torch要求的cuda版本，具体可参考torch官网：

【https://pytorch.org/get-started/locally/ 】

图片

本地Windows使用“管理员”权限打开“PowerShell”命令行，先使用命令检查本地是否已经安装pip环境：

pip --version

图片

pip3 install torch torchvision torchaudio --index-url https://download.pytorch.org/whl/cu128

整个PyTorch的安装包蛮大的，3个多GB，安装成功。

2、安装anaconda

如果已安装conda，可以跳过本步骤。

亲测发现一个bug，MinerU官方提供的Anaconda（Anaconda3-2024.06-1-Windows-x86_64.exe）清华站点的下载链接已经失效，被清华屏蔽了：

图片

我从官方网站下载了“Anaconda3-2024.10-1-Windows-x86_64.exe”版本，有需求的朋友，关注本公众号之后，后台私信“anaconda”即可收到回复。

下载完成后就图形界面的一路next安装完毕即可。

3、使用conda创建环境

在原先的PowerShell中使用conda命令报错：

图片

图片

conda create -n mineru 'python=3.13' -y

图片

conda activate mineru

图片

激活后命令行的前缀会由“（base）”变为“（mineru）”。

4、安装应用

继续在Anaconda的PowerShell中执行如下命令：

pip install -U magic-pdf[full] -i https://mirrors.aliyun.com/pypi/simple

magic-pdf --version

图片

由上述操作可知，magic-pdf的版本是1.3.12

5、下载模型并查看配置文件

下载模型的官方指南：【“https://github.com/opendatalab/MinerU/blob/master/docs/how_to_download_models_zh_cn.md ”】

模型下载分为首次下载和更新模型目录，请参考对应的文档内容进行操作。此处我是首次下载模型。模型文件可以从 Hugging Face或ModelScope下载，由于网络原因，国内用户访问HF可能会失败，请使用 ModelScope。

使用python脚本从ModelScope下载模型文件：

pip install modelscopewget https://gcore.jsdelivr.net/gh/opendatalab/MinerU@master/scripts/download_models.py -O download_models.pypython download_models.py

python脚本会自动下载模型文件并配置好配置文件中的模型目录，配置文件可以在用户目录中找到，文件名为magic-pdf.json；本次安装的modelscope的版本号是1.26.0

如果此前下载过模型，可以重复执行此前的模型下载python脚本，将会自动将模型目录更新到最新版本。

完成“下载模型”步骤后，脚本会自动生成用户目录下的magic-pdf.json文件，并自动配置默认模型路径。 您可在【"C:/Users/用户名"】下找到magic-pdf.json文件。并用“文本文件”编辑器打开即可查看内容。

6、安装LibreOffice以支持doc等文档格式解析

在Windows上下载并安装libreoffice软件，国内镜像下载地址是：“https://mirrors.cloud.tencent.com/libreoffice/libreoffice/stable/ ”。安装完毕之后，需要在“系统环境变量”的变量“Path”中添加libreoffice的安装路径“install_dir\LibreOffice\program”（我的是“C:\Program Files\LibreOffice\program ”）进入系统环境变量。

7、第一次运行MinerU

从仓库中下载样本文件，并测试：

wget https://github.com/opendatalab/MinerU/raw/master/demo/pdfs/small_ocr.pdf -O small_ocr.pdf

图片

magic-pdf -p small_ocr.pdf -o ./output

图片

从MinerU识别出来的Markdown格式文件来看，把“题头”和“题尾”信息都删除掉，识别还是非常准确的。

8、测试CUDA加速

如果您的显卡显存大于等于 6GB ，可以进行以下流程，测试CUDA解析加速效果：

覆盖安装支持cuda的torch和torchvision(请根据cuda版本选择合适的index-url，具体可参考torch官网)，我使用的是如下命令：

pip install --force-reinstall torch torchvision --index-url https://download.pytorch.org/whl/cu128

“--index-url”中的链接就是第1步安装CUDA环境时用的链接。并且要在使用“管理员账户”运行的PowerShell中去运行上述命令。

修改【用户目录】中配置文件magic-pdf.json中"device-mode"的值

{

  "device-mode":"cuda"

}

图片

magic-pdf -p small_ocr.pdf -o ./output

【报错】信息如下：

File "C:\Users\winds\anaconda3\envs\mineru\Lib\site-packages\torch\cuda\__init__.py", line 363, in _lazy_init

raise AssertionError("Torch not compiled with CUDA enabled")

AssertionError: Torch not compiled with CUDA enabled

要解决这个问题，只有将PyTorch重新结合CUDA做编译。先用如下命令卸载Torch框架（包含torch和torchvision）：

pip uninstall torch torchvision

pip install torch torchvision -f https://download.pytorch.org/whl/cu128/torch_stable.html

三、测试MinerU预解析的效果

在Windows11桌面启动“Anaconda Navigator”，进入“Environments”，选择“mineru”启动命令行的MinerU环境：

图片

magic-pdf -p 义务教育教科书·语文四年级下册.pdf -o ./output

图片

图片

图片

图片