PDFMathTranslate 完整使用指南科学论文 PDF 排版保留翻译的安装、CLI 参数与高级配置详解【免费下载链接】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本文以 PDFMathTranslatePython 包名pdf2zh的 README.md 为主线系统讲解这款面向科研场景的开源 PDF 翻译工具如何在本地安装、如何用一条命令把英文论文翻译成保留公式、图表、目录与注释排版的译文以及如何通过命令行高级参数、翻译服务配置、实验性 OCR 与 fast/precise 双内核等能力进行深度定制。读完本文你将掌握从零部署到生产级参数调优的完整实操路径并能直接对照本仓库源码理解每一步背后的实现原理。一、项目定位什么是 PDFMathTranslatePDFMathTranslate 是一个开源的科学文献 PDF 翻译工具核心目标是「翻译科学文档时完整保留排版」。与普通全文翻译工具不同它在翻译英文或其他语言论文时会保留公式、图表、目录与批注公式以{v*}占位符保护图表区域通过版面检测跳过保证翻译后数学符号与排版不被破坏多语言与多翻译服务默认 Google另支持 DeepL、Ollama、OpenAI、DeepLX、Bing、Gemini 等数十种服务详见 docs/ADVANCED.md多种使用形态命令行工具、浏览器交互界面GUI、Docker 容器部署并支持作为 MCP 服务器供 Claude 等 Agent 调用。该工作已被EMNLP 2025 System DemonstrationsProceedings of the 2025 Conference on Empirical Methods in Natural Language Processing: System Demonstrations, pp. 918–924接收论文题目为PDFMathTranslate: Scientific Document Translation Preserving Layouts官方 BibTeX 引用信息见 README.md 第 5.1 节。从源码结构看翻译管线由 pdf2zh/pdf2zh.pyCLI 入口→ pdf2zh/high_level.pytranslate/translate_stream/translate_patch核心流程→ pdf2zh/converter.pyPDF 内容级转换逐层驱动最终同时产出单语译文与双语对照两份 PDF。二、快速开始先试用在线服务不想在本机装任何东西可以先通过官方在线服务体验效果注意 demo 计算资源有限请勿滥用公共免费服务 pdf2zh.com无需安装官方推荐Immersive Translate 的 BabelDOC提供免费额度HuggingFace 与 ModelScope 上托管的 Docker Demo。上述入口的具体链接均维护在 README.md 第 3.1 节中可自行查阅。在线试用确认效果后再进入本地安装环节。三、本地安装五种方式按需选择3.1 使用 uv 安装推荐先安装 Python版本需满足3.11 ≤ version ≤ 3.12与 pyproject.toml 中requires-python 3.11,3.13一致然后pip install uv uv tool install --python 3.12 pdf2zh执行翻译输出文件生成在当前工作目录pdf2zh document.pdf3.2 使用 pip 安装pip install pdf2zh pdf2zh document.pdf3.3 图形界面GUI安装后以浏览器界面启动pdf2zh -i若浏览器未自动打开访问http://localhost:7860/GUI 的详细使用说明见 docs/README_GUI.md。从 pdf2zh/pdf2zh.py 的源码可以看到-i会调用pdf2zh.gui.setup_gui并支持--serverport指定端口、--share生成公网链接、--authorized设置登录鉴权。3.4 Windows 桌面版从项目的 release 页面下载pdf2zh-version-win64.zip解压后双击pdf2zh.exe即可运行若下载后无法打开需要先安装微软 VC 运行库vc_redist.x64.exe再重试。3.5 文献管理插件ZoteroZotero 用户可借助 Zotero PDF2zh 插件在文献管理器中直接触发翻译详见其独立项目文档。3.6 Docker 容器化部署docker pull byaidu/pdf2zh docker run -d -p 7860:7860 byaidu/pdf2zh浏览器访问http://localhost:7860/。若无法访问 Docker Hub可改用 GitHub Container Registry 镜像docker pull ghcr.io/byaidu/pdfmathtranslate docker run -d -p 7860:7860 ghcr.io/byaidu/pdfmathtranslate此外README 还提供 Heroku、Render、Zeabur、Sealos、Koyeb 等云平台的模板化部署按钮。本仓库的 Dockerfile 与 docker-compose.yml 可作为自定义构建的参考。3.7 安装期网络问题处理程序依赖版面检测模型wybxc/DocLayout-YOLO-DocStructBench-onnx部分网络环境下载失败时可通过镜像端点绕过# CMD set HF_ENDPOINThttps://hf-mirror.com # PowerShell $env:HF_ENDPOINT https://hf-mirror.com四、命令行高级参数全表在命令行执行翻译后当前目录会生成两个文件example-mono.pdf单语译文 PDFexample-dual.pdf原文与译文对照的双语 PDF。默认翻译服务为 Google。pdf2zh example.pdf一次调用内部经历「下载字体 → PyMuPDF 打开并复制文档 → DocLayout-YOLO 版面检测 → 逐页提取文本 → 翻译 → 回填 → 生成 mono/dual 两份文件」对应源码位于 pdf2zh/high_level.py。下表汇总 README 中列出的全部高级选项并补充了来自 pdf2zh/pdf2zh.pycreate_parser的默认值与参数细节选项功能示例默认值源码确认files本地文件支持 PDF/Wordpdf2zh ~/local.pdf必填links在线文件自动下载后翻译pdf2zh http://arxiv.org/paper.pdf—-i进入 GUI 交互界面pdf2zh -i关闭-p部分页面翻译pdf2zh example.pdf -p 1-3,5全部页面-li源语言代码pdf2zh example.pdf -li enen-lo目标语言代码pdf2zh example.pdf -lo zhzh-s翻译服务pdf2zh example.pdf -s deeplgoogle-t翻译线程数pdf2zh example.pdf -t 14-o输出目录pdf2zh example.pdf -o output当前目录-f,-c公式字体/字符豁免正则pdf2zh example.pdf -f (MS.*)空-cp/--compatible兼容模式转 PDF/Apdf2zh example.pdf --compatible关闭--skip-subset-fonts跳过字体子集化pdf2zh example.pdf --skip-subset-fonts关闭默认子集化--ignore-cache忽略翻译缓存强制重译pdf2zh example.pdf --ignore-cache关闭--shareGUI 生成 Gradio 公网链接pdf2zh -i --share关闭--authorizedGUI 登录鉴权pdf2zh -i --authorized users.txt [auth.html]关闭--prompt自定义 LLM 提示词文件pdf2zh --prompt [prompt.txt]内置默认提示词--onnx自定义 DocLayout-YOLO ONNX 模型pdf2zh --onnx [onnx/model/path]自动加载可用模型--serverport自定义 WebUI 端口pdf2zh --serverport 7860Gradio 默认端口--dir目录批量翻译递归扫描 PDF/doc/docxpdf2zh --dir /path/to/translate/关闭--config指定配置文件pdf2zh --config /path/to/config/config.json~/.config/PDFMathTranslate/config.json--mode翻译内核fastv1默认或precisev2实验pdf2zh --mode precise example.pdffast--babeldoc使用实验性 BabelDOC 后端pdf2zh --babeldoc -s openai example.pdf关闭--mcp以 MCP STDIO 模式启动服务器pdf2zh --mcp关闭--sse以 MCP SSE 模式启动服务器pdf2zh --mcp --sse关闭-v/--version打印版本号pdf2zh -v—-d/--debug开启调试日志pdf2zh -d example.pdf关闭--backendONNX Runtime 执行后端pdf2zh --backend cuda example.pdfauto可选auto/cpu/cuda/dml关于-p的页码语法parse_args中支持1-3,5这种逗号连字符混用写法连字符会展开为连续区间最终转换为 0 起始的内部页索引见 pdf2zh/pdf2zh.py。-f/-c的典型用法用正则保护公式字体与字符避免被当作正文翻译# 保护指定字体名与数学符号 pdf2zh example.pdf -f (CM[^RT].*|MS.*|.*Ital) -c (\(|\||\)|\||\d|[\u0080-\ufaff])默认已保护Latex、Mono、Code、Italic、Symbol、Math类字体pdf2zh example.pdf -f (CM[^R]|MS.M|XY|MT|BL|RM|EU|LA|RS|LINE|LCIRCLE|TeX-|rsfs|txsy|wasy|stmary|.*Mono|.*Code|.*Ital|.*Sym|.*Math)五、翻译服务与语言环境变量与配置文件5.1 支持的翻译服务README 与 docs/ADVANCED.md 维护了完整服务清单及所需环境变量核心摘录如下翻译服务-s取值环境变量默认值Google默认google无—Bingbing无—OpenAIopenaiOPENAI_BASE_URL、OPENAI_API_KEY、OPENAI_MODEL等https://api.openai.com/v1、gpt-4o-miniDeepLdeeplDEEPL_AUTH_KEY—DeepLXdeeplxDEEPLX_ENDPOINThttps://api.deepl.com/translateOllamaollamaOLLAMA_HOST、OLLAMA_MODELhttp://127.0.0.1:11434、gemma2XinferencexinferenceXINFERENCE_HOST、XINFERENCE_MODELhttp://127.0.0.1:9997Azure OpenAIazure-openaiAZURE_OPENAI_BASE_URL等gpt-4o-miniZhipuzhipuZHIPU_API_KEY、ZHIPU_MODELglm-4-flashModelScopemodelscopeMODELSCOPE_API_KEY、MODELSCOPE_MODELQwen/Qwen2.5-Coder-32B-InstructSiliconsiliconSILICON_API_KEY、SILICON_MODELQwen/Qwen2.5-7B-InstructGeminigeminiGEMINI_API_KEY、GEMINI_MODELgemini-1.5-flashAzureazureAZURE_ENDPOINT、AZURE_API_KEYhttps://api.translator.azure.cnTencenttencentTENCENTCLOUD_SECRET_ID、TENCENTCLOUD_SECRET_KEY—DifydifyDIFY_API_URL、DIFY_API_KEY—AnythingLLManythingllmAnythingLLM_URL、AnythingLLM_APIKEY—GrokgrokGROK_API_KEY、GROK_MODEL、GROK_BASE_URLgrok-2-1212GroqgroqGROQ_API_KEY、GROQ_MODELllama-3-3-70b-versatileDeepSeekdeepseekDEEPSEEK_API_KEY、DEEPSEEK_MODELdeepseek-chatMiniMaxminimaxMINIMAX_API_KEY、MINIMAX_MODELMiniMax-M2.7OpenAI-LikedopenailikedOPENAILIKED_BASE_URL、OPENAILIKED_API_KEY、OPENAILIKED_MODEL等—阿里 Qwen 翻译qwen-mtALI_MODEL、ALI_API_KEY、ALI_DOMAINSqwen-mt-turbo、scientific paperArgos Translateargos—本地离线模型各翻译器类均在 pdf2zh/translator.py 中继承自BaseTranslator实现如GoogleTranslator直接请求translate.google.com/m端点BingTranslator会先解析params_AbusePreventionHelper获取签名。凡是兼容 OpenAI API 的模型都可以按 OpenAI 的环境变量方式接入。指定服务-s service或-s service:model两种写法pdf2zh example.pdf -s openai:gpt-4o-mini或用环境变量指定模型以set与 PowerShell$env:两种语法为例set OPENAI_MODELgpt-4o-mini pdf2zh example.pdf -s openai$env:OPENAI_MODEL gpt-4o-mini pdf2zh example.pdf -s openai5.2 源语言与目标语言pdf2zh example.pdf -li en -lo ja语言代码以各翻译服务的官方代码为准Google 语言代码、DeepL 语言代码链接见 docs/ADVANCED.md。注意部分服务内置了语言映射例如 Google 将zh映射为zh-CN、Bing 将zh映射为zh-Hans见 pdf2zh/translator.py。5.3 自定义配置文件配置文件有两种来源命令行--config指定或默认读取~/.config/PDFMathTranslate/config.json。配置读取顺序为先读配置文件再叠加环境变量环境变量存在时优先使用环境变量并回写更新配置文件对应 pdf2zh/config.py 中ConfigManager.get的实现逻辑。示例配置 config.json{ USE_MODELSCOPE: 0, PDF2ZH_LANG_FROM: English, PDF2ZH_LANG_TO: Simplified Chinese, NOTO_FONT_PATH: /app/SourceHanSerifCN-Regular.ttf, translators: [ { name: deeplx, envs: { DEEPLX_ENDPOINT: http://localhost:1188/translate/, DEEPLX_ACCESS_TOKEN: null } }, { name: ollama, envs: { OLLAMA_HOST: http://127.0.0.1:11434, OLLAMA_MODEL: gemma2 } }, { name: grok, envs: { GROK_BASE_URL: https://api.x.ai/v1, GROK_API_KEY: your-api-key, GROK_MODEL: grok-2-1212 } } ] }⚠️ 重要提醒使用 OpenAI 兼容 API 或自定义代理时BASE_URL必须以/v1结尾如https://api.openai.com/v1、http://your-proxy:8000/v1否则会返回 404。使用方式pdf2zh example.pdf --config config.json pdf2zh -i --config config.json5.4 作为公共服务部署若把 GUI 部署为对外公共翻译服务可在配置文件中增加两项能力ENABLED_SERVICES只开放白名单内的翻译服务HIDDEN_GRADIO_DETAILS在 Web 界面隐藏真实 API Key防止他人窃取服务端密钥。组合配置示例完整 JSON 见 docs/ADVANCED.md{ USE_MODELSCOPE: 0, translators: [/* 服务密钥配置 */], ENABLED_SERVICES: [OpenAI, Grok], HIDDEN_GRADIO_DETAILS: true, PDF2ZH_LANG_FROM: English, PDF2ZH_LANG_TO: Simplified Chinese, NOTO_FONT_PATH: /app/SourceHanSerifCN-Regular.ttf }六、实验性特性自动 OCRfast 模式README 当前主线版本1.x新增了实验性自动 OCR 快速模式用于处理扫描版/纯图片型 PDF工作原理翻译前先对「仅含图片的页面」自动执行本地 OCR原生文本页、已有 OCR 层、空白页会被跳过双语输出的原页面保持不变安装方式pip install pdf2zh[ocr]从本仓库源码安装则为pip install -e .[ocr]。该可选依赖仅新增pooch用于缓存下载OCR 引擎由 PyMuPDF 内置提供无需单独安装 Tesseract 可执行文件见 pyproject.toml 与 pdf2zh/high_level.py语言数据首个扫描页会从 Tesseract 的tessdata_fast4.1.0 release 下载对应语言数据到~/.cache/pdf2zh/tessdata/4.1.0之后离线复用原生文本 PDF 不会触发下载语言选择默认使用输入语言-li对应的 Tesseract 代码如en→eng、zh→chi_sim、ja→jpn可用环境变量PDF2ZH_OCR_LANGUAGEengdeu覆盖设置TESSDATA_PREFIX可改用自有语言数据、跳过自动下载版面处理OCR 词元会在检测到的版面区域内重新分组为段落连接折行与软连字符译文段落以源文字号的中位数起步并自适应收缩回原文本框检测到的图、表、独立公式保持原样已知限制当前实现面向白底扫描件——已含文本页上的局部扫描会被跳过手写文字与行内公式可能识别错误precise 模式不受影响。七、fast 与 precise双翻译内核架构自 2026 年 3 月起项目引入实验性的v2.0 翻译内核通过隔离环境运行--mode precise与默认 v1 内核fast并存pdf2zh --mode precise example.pdf从源码看模式切换通过 pdf2zh/kernel/registry.py 的线程安全注册表KernelRegistry.switch()完成precise 内核会先ensure_venv()校验隔离虚拟环境再检查可用性对应 pdf2zh/kernel/precise.py。安装后需运行pdf2zh-setup-precise准备隔离环境该入口声明于 pyproject.toml。v2 的正式版已发布在独立仓库 PDFMathTranslate/PDFMathTranslate-next 下两分支定位差异详见 README.md 第 4.3 节——主分支面向稳定发布与社区贡献next 分支侧重 Web UI 与边角场景处理、跨栏跨页语义一致性等质量优化但不保证兼容性、不面向社区贡献。八、翻译缓存机制为加速重复翻译并节省 API 调用pdf2zh 默认启用翻译缓存以「翻译引擎 引擎参数语言对、模型 原文」三元组为唯一键命中则直接复用结果需要强制重译时加--ignore-cache。缓存底层为 SQLite~/.cache/pdf2zh/cache.v1.dbWAL 模式实现见 pdf2zh/cache.py翻译入口的缓存读写封装在BaseTranslator.translate()pdf2zh/translator.py。九、自定义提示词LLM 服务--prompt可传入提示词文件覆盖内置默认提示词内置默认内容与自定义格式保持一致见 pdf2zh/translator.pypdf2zh example.pdf --prompt prompt.txt提示词模板支持三个变量${lang_in}源语言、${lang_out}目标语言、${text}待翻译文本。示例You are a professional, authentic machine translation engine. Only Output the translated text, do not include any other text. Translate the following markdown source text to ${lang_out}. Keep the formula notation {v*} unchanged. Output translation directly without any additional text. Source Text: ${text} Translated Text:注意当前版本不支持 System PromptREADME 明确注明了这一点。十、GUI 鉴权与 MCP 集成10.1 登录鉴权--authorized可指定 Web UI 用户列表与自定义登录页pdf2zh -i --authorized users.txt auth.htmlusers.txt每行一个用户格式为用户名,密码admin,123456 user1,password1 user2,abc123 guest,guest123 test,test123auth.html为自定义登录页面 HTML任意合法 HTML 即可。10.2 作为 MCP 服务器pdf2zh 支持以 MCPModel Context Protocol方式供 AI 客户端调用配置claude_desktop_config.json需先通过uv pip install pdf2zh安装{ mcpServers: { filesystem: { command: npx, args: [-y, modelcontextprotocol/server-filesystem, /path/to/Document] }, translate_pdf: { command: uv, args: [run, pdf2zh, --mcp] } } }其中filesystem服务器用于定位 PDF 文件必需translate_pdf即翻译服务。配置完成后可直接在 Claude Desktop 中发出自然语言指令例如「在 Document 文件夹中找到test.pdf并翻译成中文」。MCP 服务器实现位于 pdf2zh/mcp_server.pySTDIO 模式由--mcp触发SSE 模式加--sse基于 uvicorn 启动 Starlette 应用。十一、下游开发Python API 与 HTTP APIREADME 第 4.2 节指向 docs/APIS.md 提供了两类二次开发接口Python APIdocs/APIS.md在自有 Python 程序中调用pdf2zh.high_level.translate()直接获得 mono/dual 两份文件路径列表核心签名见 pdf2zh/high_level.pyHTTP APIdocs/APIS.md与已部署该服务的服务器进行 HTTP 通信可用于构建 Web 前端或远程翻译服务。十二、字体处理与兼容性细节多语言字体pdf2zh 会根据目标语言自动下载远程字体——非 CJK 语言用GoNotoKurrent-Regular.ttf中文简/繁、日文、韩文分别映射SourceHanSerifCN/TW/JP/KR-Regular.ttf映射表见 pdf2zh/high_level.py并注入到译文的每页字体资源中字体子集化默认开启字体子集化以压缩输出体积遇到兼容性问题可--skip-subset-fonts关闭代价是输出文件变大兼容模式-cp/--compatible会先将输入转换为 PDF/A-2B 格式再翻译提高部分阅读器下的兼容性转换逻辑基于 pikepdf 实现pdf2zh/high_level.py。十三、引用与致谢如果你在论文或项目中使用了 PDFMathTranslate请按 README 第 5.1 节给出的 BibTeX 引用inproceedings{ouyang-etal-2025-pdfmathtranslate, ...}完整条目见 README.md。项目致谢了 PyMuPDF文档合并、Pdfminer.six文档解析、MinerU文档抽取、DocLayout-YOLO版面解析、MathTranslate多线程翻译思路、Go Noto Universal多语言字体等上游项目README.md 第 5.2 节。十四、技术路线小结本文给出的完整上手路径可以概括为四步① 按需选择安装方式uv/pip/GUI/Windows/Zotero/Docker→ ② 一行命令pdf2zh document.pdf产出 mono/dual 双语 PDF → ③ 用-s、-li/-lo、-p、-t等参数切换到目标服务与翻译范围 → ④ 进阶时通过--config配置文件、--prompt自定义提示词、--mode precise实验内核与 OCR 功能进一步调优。每一步所对应的源码文件CLI 入口 pdf2zh/pdf2zh.py、核心流程 pdf2zh/high_level.py、翻译服务 pdf2zh/translator.py、缓存 pdf2zh/cache.py、内核注册表 pdf2zh/kernel/registry.py、高级文档 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），仅供参考