GHelper 实践指南（免费开源）：一个 exe 搞定华硕笔记本性能控制
2026/9/20 18:40:24
如何快速使用 pdf2zh：保留版式的 PDF 论文翻译完整指南
【免费下载链接】PDFMathTranslate[EMNLP 2025 Demo] PDF scientific paper translation with preserved formats - 基于 AI 完整保留排版的 PDF 文档全文双语翻译，支持 Google/DeepL/Ollama/OpenAI 等服务，提供 CLI/GUI/MCP/Docker/Zotero项目地址: https://gitcode.com/GitHub_Trending/pd/PDFMathTranslate
PDFMathTranslate（命令pdf2zh）是一个只动文字层、排版原样保留的论文翻译工具。公式、图表、目录、双栏结构都不碰，跑完给你纯译文版和中英对照版两份文件。如果你翻论文时经常被散架的公式、漂移的版式折磨，它是照着这个问题做的。
装好 pdf2zh 翻出第一份中文 PDF 📦
环境要求只有一条：Python 版本落在 3.11 和 3.12 之间。项目的pyproject.toml声明requires-python = ">=3.11,<3.13"，3.10、3.13 都会装不上。依赖不用手补，pip install时 onnxruntime、pdfminer-six、gradio 会自动带入。
pip install pdf2zh pdf2zh paper.pdf默认走 Google 翻译，不需要任何 API key。跑完当前目录多出两个文件：paper-mono.pdf是纯译文版，paper-dual.pdf是中英文对照版。首次运行比平时慢，它要先从 Hugging Face 下载版面模型，等就行。Windows 上直接跑 exe 版本、报 DLL 加载失败的，先装 VC++ 2015–2022 运行库再试。
公式和双栏为什么不散架：DocLayout-YOLO 先检测版面
思路是把不该翻译的东西排除掉。ONNX 版 DocLayout-YOLO（模型名wybxc/DocLayout-YOLO-DocStructBench-onnx）逐页扫描，先标出公式、图片、表格、目录，只有文字块会被送去翻译服务，其余一律不动。翻译后的文本按原字体、原位置回填，图编号、脚注、页眉都留在原位。等于对文本层做外科手术，所以你后面不用手动修排版。
想翻检测逻辑，直接看 pdf2zh/doclayout.py。
四种跑法任选：单文件、批量目录、Web GUI、Docker 🐳
按场景挑入口：
| 跑法 | 命令 | 适合 |
|---|---|---|
| 单文件 | pdf2zh paper.pdf | 日常，产物直接落在当前目录 |
| 批量目录 | pdf2zh --dir /path/to/papers/ -o results/ | 一整个论文目录一次翻完，输出归入-o指定目录 |
| Web GUI | pdf2zh -i | 浏览器开 http://localhost:7860/，配服务、选页码、实时预览 |
| Docker | docker pull byaidu/pdf2zh，再docker run -d -p 7860:7860 byaidu/pdf2zh | 不想碰本机环境，同样是 7860 端口的 Web 界面 |
GUI 长这样，选页、换服务、看预览都在浏览器里完成：
还有一个进阶入口：pdf2zh --mcp能把自己注册成 MCP 服务接进 Claude Desktop，在对话里直接让它翻 PDF，配置示例在 docs/ADVANCED.md。
常用 pdf2zh 参数表：页码、服务、语言、线程、输出目录
| 参数 | 作用 | 示例 |
|---|---|---|
-p | 只翻指定页 | pdf2zh paper.pdf -p 1-3,5只翻第 1–3 页和第 5 页 |
-s | 切换翻译服务 | -s deepl、-s openai:gpt-4o-mini |
-li/-lo | 源语言 / 目标语言 | -li en -lo zh |
-t | 翻译线程数 | -t 4四线程并发 |
-o | 输出目录 | 缺省为当前目录 |
--ignore-cache | 忽略翻译缓存，强制重新翻译 | pdf2zh paper.pdf --ignore-cache |
--prompt | 加载自定义 LLM 提示词文件 | pdf2zh paper.pdf --prompt prompt.txt |
--config | 加载 JSON 配置文件 | pdf2zh --config config.json |
翻不动时先查这三个报错 🛠️
扫描件翻不动：你拿到的是纯图片 PDF，没有文本层，而 pdf2zh 解析的就是文本层，自然取不到内容。先 OCR 出文本层再投入翻译，项目自带实验性 OCR 支持，装法pip install 'pdf2zh[ocr]'。
模型下载卡住：首次运行从 Hugging Face 拉版面模型，部分地区访问受限。运行前先设镜像：set HF_ENDPOINT=https://hf-mirror.com；PowerShell 里写$env:HF_ENDPOINT = https://hf-mirror.com。
切换服务后报鉴权错误：DEEPL_AUTH_KEY、OPENAI_API_KEY这类环境变量没提前设置。各服务对应的变量名在 docs/ADVANCED.md 的表格里，设完再跑。
下一步：第一次跑通之后的三件事
- 拿一个论文目录跑
pdf2zh --dir，体验批量模式 - 起
pdf2zh -i，在浏览器里换一套服务，对比翻译质量 - 翻一遍 docs/ADVANCED.md，完整的服务对照表、缓存和字体子集说明都在里面
【免费下载链接】PDFMathTranslate[EMNLP 2025 Demo] PDF scientific paper translation with preserved formats - 基于 AI 完整保留排版的 PDF 文档全文双语翻译，支持 Google/DeepL/Ollama/OpenAI 等服务，提供 CLI/GUI/MCP/Docker/Zotero项目地址: https://gitcode.com/GitHub_Trending/pd/PDFMathTranslate
创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考