1、写在前面

怎么就想聊标题里这三个库了呢？要从下面这个故事说起。

在前几篇文章里，有小伙伴留言说：他在用 PDFMathTranslate-next 时，想把文档布局分析模型 DocLayout-YOLO 换成百度的 PP-DocLayoutV3，想提高翻译效率和精度，但替换过程中遇到了一些问题。所以想让我也尝试搞一搞。

这个公众号是从去年开始写的。我发现一个很有趣的事情——那些评论和私信我的小伙伴，总是能让我开拓眼界，提供一些新的思路和方法。所以我也十分乐意顺着这些话题往下挖。

由于任务比较复杂，这一篇先把三个库各自干什么研究一下。替换方案涉及推理接口、类别体系、坐标约定，我一个周末确实搞不定，就放在下一个礼拜吧。

2、这三个库是啥关系

简单描述就是：

PDFMathTranslate-next（pdf2zh_next）---主要用的是它，入口
    ↓ 依赖
BabelDOC（PDF 翻译后端）
    ↓ 其中版面分析用到
DocLayout-YOLO（布局检测模型，一般以 ONNX 形式接入）

#PDFMathTranslate-next是面向用户的产品，提供命令行、WebUI 和 Windows EXE 等多种使用方式。我们安装的就是它。

#BabelDOC 是真正干活的 PDF 翻译引擎，负责抽字、版面分析、内容重排和写回 PDF 等核心工作。

#DocLayout-YOLO 是一个版面分析算法模型，负责识别标题、正文、公式、图表等文档区域。

工作的主线是：

读 PDF 文字层 → 本机做版面分析 → 把句子丢给翻译服务 → 再按原版面写回 PDF。

所以，它们根本就没有使用传统的OCR模型，不是文字识别而是直接读 PDF 文字层。好吧，你这个狡猾的家伙！

3、PDFMathTranslate

3.1 它是什么

PDFMathTranslate（当前活跃分支多叫 PDFMathTranslate-next，命令一般是 pdf2zh_next）定位：

PDF 科学论文翻译与双语对照。

它的主要任务是：

• 外面一层：安装方式、WebUI、配置、各种翻译服务适配
• 里面一层：BabelDOC 负责 PDF 管线编排，调用 DocLayout-YOLO 做版面分析，调用翻译服务翻译句子。

补充一下，它默认是调用硅基流动的翻译服务的，我们暂时不用账号登录和付费。

仓库地址：

https://github.com/PDFMathTranslate-next/PDFMathTranslate-next

3.2 关于它的安装

官方文档大致给了三条路：

3.3 CPU 能不能跑

能。

官方 FAQ 写得很直白：不需要 GPU。有 GPU 时程序会尽量自动用上，速度更好；没有也能跑。我这次就是在笔记本上用 CPU 跑的。

但要注意：CPU 主要吃的是本机版面分析那段；翻译句子默认还是走网络 API，不是本机大模型。是的，即使是版面分析，我这台笔记本对8页的论文也是跑了几分钟。

4、BabelDOC：真正的 PDF 翻译后端

4.1 它是什么

BabelDOC 是「PDF 怎么被拆开、怎么翻译、怎么拼回去」的核心库。

仓库地址：

https://github.com/funstory-ai/BabelDOC

4.2 它在流水线里干了啥

BabelDOC 流程大致如下：

输入 PDF
    ↓
用 pdfminer / PyMuPDF 抽文字层、页面结构
    ↓
用 DocLayout-YOLO（ONNX）做版面分析
    ↓
按区域决定：哪些要译、哪些跳过（公式/图等）
    ↓
调用翻译引擎（默认云端）翻译句子
    ↓
按原版面写回，生成 mono / dual PDF

• 抽文字：本地，读 PDF 自带文字层
• 版面分析：本地，跑 DocLayout-YOLO 的 ONNX
• 翻译：默认不在本地，走翻译 API

所以 BabelDOC 很强，但它默认并不是「完全离线的本地大模型翻译器」。离线能力主要体现在：解析、布局、字体、重排；翻译引擎你可以换成自己的 API，也可以接 Ollama 之类本地服务。

4.3 和 OCR 的关系

BabelDOC / pdf2zh 不是完整 OCR 套件。

你解压 with-assets 包时，往往会发现预置模型主要是：

doclayout_yolo_docstructbench_imgsz1024.onnx

如果你的 PDF 是纯扫描图、几乎没有文字层，这个工具本身就不擅长；通常要先做成带文字层的 PDF，或者换 OCR 方案。所以我想说，这篇文章乍一看是OCR相关，但是深入进来发现，跟传统OCR关系不大。

5、DocLayout-YOLO：版面分析

5.1 它是什么

DocLayout-YOLO 来自 OpenDataLab，做的是文档版面检测：在一页图上标出标题、正文、公式、表格、图片等区域。

上游仓库：

https://github.com/opendatalab/DocLayout-YOLO

在 PDFMathTranslate / BabelDOC 这条链路里，直接使用的是导出后的 ONNX 模型。本机缓存常见路径类似：

~/.cache/babeldoc/models/doclayout_yolo_docstructbench_imgsz1024.onnx

5.2 它到底解决什么问题

有人会问：既然已经能用 pdfminer / PyMuPDF 直接抽文字，为什么还要版面分析？

因为 PDF 里的字，往往只是「一堆带坐标的字符/span」，程序并不天然知道：

• 哪一块是标题，哪一块是正文
• 阅读顺序怎么排
• 哪些是公式，翻译时应该跳过
• 译文写回去时，该落在哪个框、占多大地方

5.3 核心代码在哪

如果你想读实现，核心代码在 BabelDOC：

doclayout.py 里最关键的几步可以记成：

OnnxModel.from_pretrained()
    ↓ 拿到 onnx 路径
页面渲染成图
    ↓
resize / pad 到固定输入（如 1024）
    ↓
onnxruntime 推理
    ↓
把框从模型坐标缩放回原图 / PDF 坐标
    ↓
交给后续「译不译、怎么排」逻辑

pdf2zh 这边更多是传配置；真正跑 YOLO 的是 BabelDOC。

至于小伙伴提到的「换成 PP-DocLayoutV3」——从工程上看，就是想替换这一环。类别名、框格式、置信度阈值、和 BabelDOC 后处理怎么对齐等一系列动作。

这个库最新的版本是2024.10.25发布的，距离现在确实有些久远了。

6、整条链路里：哪些本地，哪些联网

默认翻译引擎在代码里是 SiliconFlowFree（硅基流动免费通道）。不配 API Key 时，日志里常会看到类似：

No translation engine selected, using SiliconFlow Free
Using translation engine: SiliconFlowFree

7、Windows EXE 上手

7.1 下载哪个包

去 Releases 下载带 assets 的包，名字类似：

pdf2zh-v2.9.0-BabelDOC-v0.6.2-with-assets-win64

和裸包相比，with-assets 会把字体、DocLayout 模型等资源打进去。

7.2 启动

解压后进入 pdf2zh 目录，双击 pdf2zh.exe。

终端会先 warmup / 校验资源，然后拉起本地 WebUI。浏览器没自动打开的话，手动访问：

http://localhost:7860/

如果 exe 起不来，可先装 VC++ 运行库，也都包含在包里了。

7.3 WebUI 使用很简单

1. 上传 PDF（我测的是经典论文 U-NET.pdf）
2. 源语言 / 目标语言：English → Simplified Chinese
3. 点 Translate
4. 下载结果

常见输出：

8、写在后面

回到开头那位小伙伴的问题：想把 DocLayout-YOLO 换成 PP-DocLayoutV3。

经过这一轮梳理，至少清楚了：

1. 用户层是 PDFMathTranslate
2. 管线层是 BabelDOC
3. 要替换的是 BabelDOC 里 DocLayout

我只想说，这位兄弟还是非常有想法的，版面分析目前确实有很多方案，他想把这些方案都集成到 BabelDOC 里，按需使用。我们这些搞技术的，乐趣就在于完成自己的想法，哪怕付出很多，都不算啥。一起加油吧！

欢迎关注公众号「程序员Linc」获取更多技术文章和项目更新！

参考

1. PDFMathTranslate-next：https://github.com/PDFMathTranslate-next/PDFMathTranslate-next
2. BabelDOC：https://github.com/funstory-ai/BabelDOC
3. DocLayout-YOLO：https://github.com/opendatalab/DocLayout-YOLO
4. SiliconFlow 免费翻译说明（项目文档）：PDFMathTranslate-next docs / SiliconFlow