# PDFMathTranslate ultrafast 教程：原生文字 PDF 的快速路径与限制

先比较可选中文字 PDF 与无文字层扫描页，再使用主仓库 ultrafast CLI，按官方计时字段记录性能与版面差异。

运行范围：原创 PDF/CSV/EPUB/HTML 材料与本地验收已实际执行。没有调用翻译模型、没有连接 Zotero 库、没有填写凭证。官方截图为官方项目示例，不是本练习运行输出。

依赖：Python 3.11+；PDF 验收需 Poppler 的 pdfinfo/pdftotext；OCR 复现需 tesseract 英文语言数据。安装翻译工具时遵循各自官方 Python 要求。

## 1. 比较两份相同内容的 PDF

练习包 source.pdf 有文字层，scan.pdf 是由该页栅格化后制作的图片 PDF。逐页提取文本，再决定能否用 ultrafast；不是只凭文件扩展名。

```sh
pdftotext source.pdf native.txt
pdftotext scan.pdf scan.txt
python3 verify.py
```

## 2. 核对主仓库而非 Next

ultrafast 是 PDFMathTranslate 主仓库 2026-10-02 记录的新路径。2026-10-14 查询 PyPI 的 pdf2zh 仍为 1.9.11，不能由版本号推断已包含 main 的新功能；本页改为固定官方提交 7b57f11ac04409aaac1aba141d0882619cb689b3。该提交源码已核对，但本机未安装该翻译环境。

```sh
pdf2zh --version
pdf2zh --help
```

## 3. 从功能提交安装对应 extra

官方指定 pdf-inspector>=1.25.2,<2。以下在独立 Python 3.12 环境从固定 Git 提交安装 ultrafast extra；不是承诺 PyPI 1.9.11 含此功能。安装需要 Git 与网络，本教材只核对源码，没有执行依赖安装或模型调用。

```sh
python3.12 -m venv .venv
.venv/bin/python -m pip install "pdf2zh[ultrafast] @ git+https://github.com/PDFMathTranslate/PDFMathTranslate.git@7b57f11ac04409aaac1aba141d0882619cb689b3"
.venv/bin/pdf2zh --version
.venv/bin/pdf2zh --help
```

## 4. 先跑一页原生文字

选已有可用翻译服务，只对 source.pdf 运行。该路径跳过 ONNX 和 OCR，不能与 --mode precise、--babeldoc、GUI、server 或 --onnx 混用。

```sh
mkdir -p output-fast
.venv/bin/pdf2zh source.pdf --ultrafast -li en -lo zh -t 2 -o output-fast
```

## 5. 记录普通路径与快路径

以同一输入、服务、并发和缓存条件运行普通模式。两次 API/模型运行均需自行执行；time-template.csv 只有待填写列，教材未给出编造的速度倍数。

```sh
mkdir -p output-normal
.venv/bin/pdf2zh source.pdf -li en -lo zh -t 2 -o output-normal
```

## 6. 解释计时而非重复相加

记录官方 [ultrafast perf] 日志的 layout_extract、page_scan 和 translation；嵌套的 page_processing 含子阶段，不重复求和。比较整体墙钟、缓存状态、API 重试和页面差异。

## 7. 保存版面与取舍

对齐两个输出的同一页，检查细表格、公式、空格和字体。ultrafast 不做字体子集化，文件可能更大；扫描页会保留，不能由“命令成功”推断已 OCR。

## 来源

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

## 教材

原创输入材料可用于学习练习。官方图片版权归原作者，网页中保留来源；ZIP 不打包这些官方图片。