介绍一款基于MinerU的PDF翻译工具

一。简介

Fast pdf translate是一款pdf翻译软件，基于MinerU实现pdf转markdown的功能，接着对markdown进行分割，
送给大模型翻译，最后组装翻译结果并由pypandoc生成结果pdf。

git地址：
https://github.com/kv1830/fast_pdf_trans
gitee地址：
https://gitee.com/daibaitu170/fast_pdf_trans

二。主要功能

pdf解析功能

• 支持由pdf书签生成markdown标题（分级），魔改MinerU实现
• 支持移除markdown代码块的非标题#号，魔改MinerU实现
• 支持由大模型对MinerU生成的标题进行分级和过滤(无书签的场景)
• 支持由大模型移除误识别的公式，魔改MinerU实现

翻译功能

• 支持所有兼容openai api的大模型
• 支持流控限制、多线程、多个大模型同时翻译
• 支持缓存，任务中断后再次执行时，问过的问题直接从缓存读取
• 支持对大模型返回的代码块进行自动换行处理

生成结果pdf

• 基于pypandoc加prince引擎实现

三。系统要求

完整的系统要求可以参照MinerU的系统要求，简言之：

• windows/linux均可
• 有英伟达显卡则可以使用显卡加速，显存8G以上最好（6G也可以）
• 内存最好在16G以上

四。安装

建议使用conda安装，尤其是如果用gpu进行pdf解析的话。

1.创建conda环境

conda create -n fast_pdf_trans python=3.10
conda activate fast_pdf_trans

2.安装MinerU

pip install "magic-pdf[full]==1.2.0" --extra-index-url https://wheels.myhloli.com

如果要使用本软件魔改MinerU的相关功能（pdf书签等），就要严格使用上面指定的1.2.0版本，否则可以使用最新版本。
如果要使用英伟达gpu加速推理，请移步MinerU cuda环境安装文档（主要是重装cuda版的pytorch和paddlepaddle-gpu），也可以参照文本后面的七。MinerU cuda环境安装:
Windows 10/11 + GPU
Ubuntu 22.04 LTS + GPU

3.安装依赖

cd到fast_pdf_trans项目目录下

pip install -r requirements.txt

4.下载模型

注意：如果你已经参照MinerU官方的cuda环境文档安装过了，你可能已经把下载模型的步骤执行过了，
不用再重新下载模型了。

执行如下脚本

python tools\download_models.py

模型会下载到C:\Users\你的用户名.cache\modelscope\hub\models目录下，并且脚本会自动当该目录保存到
C:\Users\你的用户名\magic-pdf.json文件中

注意，在linux中就用你的当前用户来执行这个脚本，不要用root用户去执行，否则模型会下载到/root/.cache/modelscope中， 而你普通用户是访问不了/root这个目录的。

5.安装Prince

如果你只需要将pdf解析为markdown并翻译成中文markdown，那就不需要安装Prince了。但是如果你还需要将它转换成中文pdf，则需要Prince。
请移步Prince官网下载对应系统的版本。下面分别以windows和ubuntu为例：

windows

下载prince-16-win64.zip，解压到任意目录，比如D:\program，然后把"D:\program\prince-16-win64\bin"添加到系统环境变量PATH中。
以windows11为例(win10应该也差不多，顶多是找环境变量的过程可能稍有区别)，在文件浏览器中右击"此电脑"–“属性”–“高级系统设置”–“环境变量”–下面的"系统变量"，在里面找到Path，双击它打开，
在里面新建一项填"D:\program\prince-16-win64\bin"即可(填的时候并不需要双引号)。
修改完环境变量后，需要重新打开cmd命令行才有效(如果你用的是pycharm也是同理，需要重新打开pycharm)，执行where prince，看到如下结果表示Path加成功了

(fast_pdf_trans) D:\workPython\llm\fast_pdf_trans>where prince
D:\program\prince-16-win64\bin\prince.exe

ubuntu20.04

下载prince_16-1_ubuntu20.04_amd64.deb，参考Prince Installation Guide

点到ubuntu的安装部分，其实就一条命令，如果是root用户，直接执行：

gdebi prince_16-1_ubuntu20.04_amd64.deb

否则执行：

sudo gdebi prince_16-1_ubuntu20.04_amd64.deb

如果你没有安装gdebi，那就先用apt安装一下就好啦

apt update
apt install gdebi

非root用户还是注意加上sudo

sudo apt update
sudo apt install gdebi

安装完prince之后执行which prince，看到如下结果表示成功安装了：

(fast_pdf_trans) root@DESKTOP-U5878VE:/home/kv183# which prince
/usr/bin/prince

6.配置大模型

本项目自身要用的配置都在conf.yaml中，里面各项都做了详细说明，不要被它们吓到！ 接下来演示的功能，唯一要配置的就是一个大模型的api-key。
即如下这段，搜索ds_llm_agent即可找到，把里面的api_key的值sk-xxxxxxxxxx换成你自己的api_key：

ds_llm_agent: # deepseek官方api，这里的'ds_llm_agent'是在别的配置中引用的名字，随便起什么都可以。更多的llm_agent示例见conf_llm_example.yaml
  base_url: https://api.deepseek.com/
  model_name: deepseek-chat
  api_key: sk-xxxxxxxxxx # api_key需要到对应平台创建
  timeout: 120
  max_retries: 2 # 开启流控的话则把这一项置0，否则会影响流控的计算
  use_cache: true # 开启缓存，会把大模型的响应缓存在文件中，下次同样的问题直接从缓存文件中读取，不会重复调用大模型
  cache_file_name: deepseek-chat # 缓存文件名。缓存目录就是项目目录的cache文件夹
  rate_control: # 没有明确说明流控的，可以不配置。也可以通过相关任务的线程数来控制访问频繁。
  streaming: false # 流式输出，没有强制要求流式输出的，可以指定为false

你如果没有api_key，请移步deepseek官网注册并充值~~

• 你如果不想用deepseek，只要是兼容openai-api的大模型，都可以配置在这里。
• 也可以另外新建一段大模型的配置并且在翻译配置中引用它。
• 或者你有多个deepseek的帐号，你想在翻译中一起用。

具体用法参见README 6配置大模型

至此，所有准备工作就都完成了！

五。运行

现在我有一本"Hands-On Generative AI with Transformers and Diffusion Models.pdf"，现在测试一下，让它翻译21页到27页，cd到fast_pdf_trans项目目录下，执行：

python translate.py "D:\学习\机器学习\GAN、扩散模型\Hands-On Generative AI with Transformers and Diffusion Models.pdf"  --start-page 21 --end-page 27

注意这里的–start-page，–end-page的值都是从1开始计数的。如果这两个参数都不传，则会翻译整个pdf。各命令行参数的含义可以执行python translate.py -h进行查看。

本次运行的条件是这是一个文字版pdf（非扫描版），有书签，无公式，其它场景后面会再详细例举。

最后看到

2025-03-21 02:14:01,684 llm_translate.translator translate 30 INFO     finish all step, result_pdf_path: D:\workPython\llm\fast_pdf_trans\output\Hands-On Generative AI with Transformers and Diffusion Models\Hands-On Generative AI with Transformers and Diffusion Models_correct_trans_format.pdf

表示结果pdf路径就是：D:\workPython\llm\fast_pdf_trans\output\Hands-On Generative AI with Transformers and Diffusion Models\Hands-On Generative AI with Transformers and Diffusion Models_correct_trans_format.pdf

本次没有指定输出文件的目录，所以默认是在项目目录的output文件夹下。

如上图：

• 绿框是通过MinerU解析pdf后生成的markdown文件，但是本次使用了pdf书签生成markdown标题（在conf.yaml中有默认配置，后面详述），
  所以这个markdown文件里的标题看起来会有点奇怪，是我做了特殊记号的（用于标记标题级别）。
• 黄框是在MinerU生成的markdown的基础上，进行一些修改操作，比如把上面的标题级别的标记还原成实际的markdown标题级别。
  或者在没有使用pdf书签的情况下，通过大模型修正markdown标题级别，也会在本文件中完成。
• 蓝框就是翻译后的中文markdown了。
• 红框是MinerU解析pdf后我保存的一些调试数据，比如layout.pdf, spans.pdf可以直接去看看。
• 没有框起来的那两个文件，_correct_trans_format.md是在翻译完的markdown的基础上又进行了一些修正操作，比如将代码段中超长的代码行自动换行。_correct_trans_format.pdf就是最终的翻译结果啦。

所以如果已经完成了pdf到markdown的解析步骤，在翻译的过程中，手动中断了翻译任务（或者产生未知的异常中断了翻译任务），
可以再次运行相同的命令，pdf解析这一步是不会再重复执行的，因为相关的markdown已经存在了。
而已经翻译过的段落，实际上已经保存在缓存文件中了，所以会直接从缓存文件读取，不会再去调api。

是否开启缓存也是配置在conf.yaml的大模型配置中的，如下只展示缓存配置

ds_llm_agent: # deepseek官方api，这里的'ds_llm_agent'是在别的配置中引用的名字，随便起什么都可以。更多的llm_agent示例见conf_llm_example.yaml
  use_cache: true # 开启缓存，会把大模型的响应缓存在文件中，下次同样的问题直接从缓存文件中读取，不会重复调用大模型
  cache_file_name: deepseek-chat # 缓存文件名。缓存目录就是项目目录的cache文件夹

所以缓存文件名就是deepseek-chat.txt，它就在本项目的cache文件夹下：

其实通过这个文件来检查大模型的回答还挺方便。如果不想再用过去的缓存，可以自行删除这些文件。

六。更多翻译场景

比如

• pdf有公式
• pdf无书签
• pdf页数过多导致内存不够
• 翻译结果pdf有问题
• 想使用命令行参数代替conf.yaml

见how_to_translate_different_pdfs_zh-CN.md

七。MinerU cuda环境安装

如二。安装–2.安装MinerU中所说，可以参照MinerU官方的安装指南，也可以参照我这里的。其实MinerU的cuda环境稍微有点麻烦的是，它既要用到pytorch2.3.1又要用到paddlepaddle-gpu2.6.1，但这两者依赖的cuda版本还不一样。
另外，先完成二。安装里的步骤，然后再执行本节的步骤。

windows

安装显卡驱动

首先说明一下，cuda环境必然得是英伟达的显卡，如果你是amd显卡，那就不在本文讨论范围之内。MinerU也支持华为Ascend NPU，请参照MinerU官方文档 。

接下就是安装英伟达的显卡驱动了，其实一般情况下你多半已经安装过显卡驱动了（不然你显卡咋用来打游戏~~），但是我们得确认一下你的驱动版本是否过老（太老了可能不适用于cuda11.8），执行如下命令：

nvidia-smi

看右上角的CUDA Version，只要它大于等于11.8，就OK。注意，上图这里并不是说你安装了cuda12.6，而是你的显卡驱动最高支持cuda12.6。

• 如果你压根就没这个命令(nvidia-smi)，那你多半没装显卡驱动，去英伟达官网装一个nvidia驱动 。
• 如果你CUDA Version小于11.8，那你还是得装一个新的驱动。

卸载pip安装的cpu版的pytorch

pip uninstall torch torchvision

输入Y回车。

使用conda安装pytorch

conda install pytorch==2.3.1 torchvision==0.18.1 pytorch-cuda=11.8 -c pytorch -c nvidia

如上命令安装的是cuda11.8版本的pytorch。
可能需要等待片刻，然后解析出所有要安装的包，输入Y回车。

可以检查一下pytorch安装好了没

conda list | findstr torch

上图的pytorch已经是cuda版的pytorch了。至于pytorch-cuda是啥，其实它就是conda里面的各种cuda文件的依赖打包。
可以执行如下命令查看安装好的cuda运行时：

conda list | findstr nvidia

cuda11.8运行时已经装好了，其实这并不是完整的cuda，它缺少nvcc编译器，不过只有要编译pytorch扩展时才会用到nvcc编译器。MinerU并不需要用到nvcc。

安装cudnn

conda install "cudnn==8.9.*[build=cuda11_0]"  -c nvidia --no-deps

可能需要等待片刻，然后解析出所有要安装的包，不过这次其实只有一个包，输入Y回车。

之所以只有一个包，是因为我们加了–no-deps，加它的原因是因为cudnn8.9依赖cuda-toolkit11.5，但我们已经有cuda11.8啦。其实安装的这个cudnn并不是给pytorch用的，pytorch自己就带上了cudnn的库文件。这里安装的是给paddlepaddle-gpu用的。

安装paddlepaddle-gpu

用pip安装，因为如果用conda安装的话，它会依赖cuda-toolkit11.7，而我们装的是pytorch-cuda11.8，它们依赖的cuda版本不一样，那就会装两个cuda进来，有可能会冲突。而cuda11.8一般是兼容基于cuda11.7开发的软件的。而用pip装paddlepaddle-gpu2.6.1的话，它并不会装cuda和cudnn相关的东西

pip install paddlepaddle-gpu==2.6.1

一切安装完毕！

修改MinerU配置

接下来把MinerU的配置文件修改一下
C:\Users\你的用户名\magic-pdf.json
把device-mode的值由cpu改为cuda

测试

还是跑之前的用例：

python translate.py "D:\学习\机器学习\GAN、扩散模型\Hands-On Generative AI with Transformers and Diffusion Models.pdf"  --start-page 21 --end-page 27

显存大于等于8G，则会进行批量推理（文档布局识别、文字行识别），上图红线处即表示用cuda推理，红框里显示文档布局识别用时1.83秒，文字行检测用时1.3秒，这是7页的总时间。
下面对比一下cpu推理的耗时：

cpu推理耗时明显比gpu慢很多，单页就要3到4秒。

linux

在linux下，在执行如下命令的时候，就已经安装了cuda版的pytorch，并且把cuda12.1和cudnn8.9都装好了。

pip install "magic-pdf[full]==1.2.0" --extra-index-url https://wheels.myhloli.com

接下来只要安装paddlepaddle-gpu就行了

python -m pip install paddlepaddle-gpu==3.0.0rc1 -i https://www.paddlepaddle.org.cn/packages/stable/cu118/

然后把MinerU配置文件修改一下就行了参照上面的windows一节中的修改MinerU配置。
不过其实pytorch装的是cuda12.1，paddlepaddle装的是cuda11.8，这两者分别对应不同的cudnn，都通过pip装进来了，如下图：

em…，不过我运行了一下，是没有问题的，cuda11.8和cuda12.1共存，可能关系不太大，因为cuda11和cuda12的相关库文件名不同，pytorch和paddle在加载cuda库文件时可以通过文件名区分: