PDFMathTranslate 中文使用指南保留公式与排版的科学 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/PDFMathTranslatePDFMathTranslate 是一款面向科学文献的 PDF 翻译工具其核心能力是在翻译过程中完整保留原始排版——公式、图表、目录与注释均不被破坏最终同时输出单语译文-mono与双语对照-dual两份 PDF。本文以仓库内中文文档 docs/README_zh-CN.md 为主体结合源码与高级配置文档系统讲解从安装、命令行翻译、GUI 与 Docker 部署到翻译服务选择、自定义配置与翻译内核机制的完整实战方案。读完本文你将能够独立完成科学 PDF 的本地翻译部署并根据自己的翻译服务与环境灵活调整参数。项目概览科学 PDF 翻译与双语对照PDFMathTranslate 定位为科学 PDF 文档翻译及双语对照工具面向论文、技术手册等排版复杂的科学文档解决了传统 PDF 翻译工具翻译后格式崩坏、公式乱码的痛点保留公式、图表、目录和注释支持多种语言和诸多翻译服务Google、DeepL、OpenAI、Ollama 等提供命令行工具、图形交互界面GUI以及容器化部署Docker三种使用形态。从仓库结构看翻译能力由 pdf2zh/ 包承载命令行入口定义在 pdf2zh/pdf2zh.py布局解析依赖 DocLayout-YOLO 的 ONNX 模型见 pdf2zh/doclayout.py文档合并与解析则基于 PyMuPDF 与 pdfminer.six声明于 pyproject.toml 的依赖列表。在线演示服务在本地安装之前可以通过以下在线服务快速体验翻译效果注意演示资源有限请勿滥用公共免费服务在线使用无需安装沉浸式翻译 BabelDOC每月免费 1000 页HuggingFace 托管的 Docker 演示ModelScope 托管的演示无需安装。安装与使用六种方式中文文档针对不同使用场景提供了六种安装与使用方式。1. uv 安装推荐uv 提供独立的工具环境不会污染系统 Pythonpip install uv uv tool install --python 3.12 pdf2zh安装后执行翻译译文文件生成在当前工作目录pdf2zh document.pdf需要 Python 版本满足3.11 版本 3.12该约束与 pyproject.toml 中的requires-python 3.11,3.13一致。2. Windows exe从发布页面下载pdf2zh-version-win64.zip解压后双击pdf2zh.exe即可运行适合无需 Python 环境的 Windows 用户。3. 图形用户界面GUIpip install pdf2zh pdf2zh -i命令执行后会在浏览器中打开 Web 界面若浏览器未自动启动访问http://localhost:7860/。GUI 模式下支持拖拽 PDF 上传并点击 Translate 完成翻译详细交互说明见 docs/README_GUI.md。GUI 中源语言与目标语言也可通过环境变量控制PDF2ZH_LANG_FROM源语言默认EnglishPDF2ZH_LANG_TO目标语言默认Simplified Chinese。支持的界面语言包括英文、简体中文、繁体中文、法文、德文、日文、韩文、俄文、西班牙文、意大利文。从源码看-i参数在 pdf2zh/pdf2zh.py 中触发setup_gui()底层基于 Gradio 构建依赖gradio5.36并支持--share生成公网链接、--authorized配置登录鉴权。4. Docker 容器化部署docker pull byaidu/pdf2zh docker run -d -p 7860:7860 byaidu/pdf2zh随后在浏览器打开http://localhost:7860/即可。若无法访问 Docker Hub可使用 GitHub 容器注册中心的镜像docker pull ghcr.io/byaidu/pdfmathtranslate docker run -d -p 7860:7860 ghcr.io/byaidu/pdfmathtranslate仓库根目录的 docker-compose.yml 与 Dockerfile 也提供了可参考的自建镜像配置。云服务部署方面文档提供了 Heroku、Render、Zeabur、Sealos、Koyeb 等平台的部署入口。5. Zotero 插件面向文献管理场景可通过 Zotero 插件在文献库中直接触发翻译详见 Zotero PDF2zh 插件项目。6. 命令行pip install pdf2zh pdf2zh document.pdf执行后会在当前工作目录生成example-mono.pdf单语译文与example-dual.pdf双语对照默认使用 Google 翻译服务。无法安装模型下载的网络问题程序运行前需要加载 AI 布局模型wybxc/DocLayout-YOLO-DocStructBench-onnx用于识别文档中的公式、图表、目录等区域加载逻辑见 pdf2zh/doclayout.py。部分用户因网络原因无法从 Hugging Face 下载该模型可通过设置镜像环境变量解决set HF_ENDPOINThttps://hf-mirror.comPowerShell 用户$env:HF_ENDPOINT https://hf-mirror.com若仍无法解决可查阅项目 Wiki 的常见问题解答FAQ。此外Windows 用户若下载后无法打开程序需先安装vc_redist.x64.exeMicrosoft Visual C 运行库再重试——这与 pdf2zh/doclayout.py 中对 ONNX Runtime DLL 加载失败的显式提示一致。高级选项命令行参数全解pdf2zh的命令行参数在 pdf2zh/pdf2zh.py 中通过 argparse 定义。中文 README 列出了全部高级选项下表在保留原文基础上补充了各参数的默认值取自源码选项功能示例files本地文件支持 PDF/Wordpdf2zh ~/local.pdflinks在线文件pdf2zh http://arxiv.org/paper.pdf-i进入 GUIpdf2zh -i-p部分文档翻译pdf2zh example.pdf -p 1-li源语言默认enpdf2zh example.pdf -li en-lo目标语言默认zhpdf2zh example.pdf -lo zh-s翻译服务默认googlepdf2zh example.pdf -s deepl-t多线程数默认4pdf2zh example.pdf -t 1-o输出目录pdf2zh example.pdf -o output-f,-c公式字体/字符异常正则pdf2zh example.pdf -f (MS.*)-cp兼容模式转换 PDF/Apdf2zh example.pdf --compatible--skip-subset-fonts跳过字体子集化pdf2zh example.pdf --skip-subset-fonts--ignore-cache忽略翻译缓存强制重译pdf2zh example.pdf --ignore-cache--share生成 Gradio 公网链接pdf2zh -i --share--authorizedGUI 登录授权pdf2zh -i --authorized users.txt [auth.html]--prompt自定义翻译提示词pdf2zh --prompt [prompt.txt]--onnx自定义 DocLayout-YOLO ONNX 模型pdf2zh --onnx [onnx/model/path]--backendONNX Runtime 执行后端auto/cpu/cuda/dmlpdf2zh --backend cuda--serverport自定义 WebUI 端口pdf2zh --serverport 7860--dir批量翻译目录内全部 PDF/Wordpdf2zh --dir /path/to/translate/--config指定配置文件pdf2zh --config /path/to/config/config.json--mode翻译模式fast默认v1或precisev2 实验性pdf2zh --mode precise example.pdf--babeldoc使用实验性 BabelDOC 后端pdf2zh --babeldoc -s openai example.pdf--mcp以 MCP STDIO 模式启动服务pdf2zh --mcp--sse以 MCP SSE 模式启动服务pdf2zh --mcp --sse完整选项说明可查阅 docs/ADVANCED.md。下面对几个高频参数做源码级展开。部分翻译-p支持页码范围与列表例如-p 1-3,5表示翻译第 1 至 3 页与第 5 页。源码 pdf2zh/pdf2zh.py 会将1-3展开为页索引列表注意页码在内部被转换为从 0 开始的索引。语言与翻译服务-li/-lo/-s默认源语言为英文、目标语言为简体中文、服务为 Google分别对应源码中的默认值en、zh、google。Google 翻译器实现在 pdf2zh/translator.py其单次请求上限为 5000 字符text[:5000]。语言代码遵循各服务的规范如 Google 使用zh-CNBing 使用zh-Hanslang_map映射同样定义在 pdf2zh/translator.py。公式异常处理-f/-c科学 PDF 中公式往往使用特殊字体渲染默认情况下程序会保留 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)-c用于按字符正则保留公式中的特殊符号pdf2zh example.pdf -f (CM[^RT].*|MS.*|.*Ital) -c (\(|\||\)|\||\d|[\u0080-\ufaff])在源码中这两个正则分别对应--vfont公式字体名匹配与--vchar公式字符匹配作用于 PDF 解析阶段见 pdf2zh/pdf2zh.py。翻译服务与环境变量-s指定翻译服务通用格式为-s service或-s service:model。例如指定 OpenAI 及具体模型pdf2zh example.pdf -s openai:gpt-4o-mini也可通过环境变量指定模型set OPENAI_MODELgpt-4o-mini pdf2zh example.pdf -s openaiPowerShell 用户$env:OPENAI_MODEL gpt-4o-mini pdf2zh example.pdf -s openai主要服务及其所需环境变量来自 docs/ADVANCED.md 的对照表翻译器Service 名环境变量默认值Google默认google无-Bingbing无-302.AI302aiX302AI_API_KEY,X302AI_MODEL[Your Key],Gemma-7BOpenAIopenaiOPENAI_BASE_URL,OPENAI_API_KEY,OPENAI_MODEL,OPENAI_STOP_TOKENS,OPENAI_MAX_TOKENShttps://api.openai.com/v1,[Your Key],gpt-4o-mini, ,-1DeepLdeeplDEEPL_AUTH_KEY[Your Key]DeepLXdeeplxDEEPLX_ENDPOINThttps://api.deepl.com/translateOllamaollamaOLLAMA_HOST,OLLAMA_MODELhttp://127.0.0.1:11434,gemma2XinferencexinferenceXINFERENCE_HOST,XINFERENCE_MODELhttp://127.0.0.1:9997,gemma-2-itAzureOpenAIazure-openaiAZURE_OPENAI_BASE_URL,AZURE_OPENAI_API_KEY,AZURE_OPENAI_MODEL[Your Endpoint],[Your Key],gpt-4o-mini智谱 ZhipuzhipuZHIPU_API_KEY,ZHIPU_MODEL[Your Key],glm-4-flashModelScopemodelscopeMODELSCOPE_API_KEY,MODELSCOPE_MODEL[Your Key],Qwen/Qwen2.5-Coder-32B-Instruct硅基流动 SiliconsiliconSILICON_API_KEY,SILICON_MODEL[Your Key],Qwen/Qwen2.5-7B-InstructGeminigeminiGEMINI_API_KEY,GEMINI_MODEL[Your Key],gemini-1.5-flashAzureazureAZURE_ENDPOINT,AZURE_API_KEYhttps://api.translator.azure.cn,[Your Key]腾讯 TencenttencentTENCENTCLOUD_SECRET_ID,TENCENTCLOUD_SECRET_KEY[Your ID],[Your Key]DifydifyDIFY_API_URL,DIFY_API_KEY[Your DIFY URL],[Your Key]AnythingLLManythingllmAnythingLLM_URL,AnythingLLM_APIKEY[Your AnythingLLM URL],[Your Key]Argos Translateargos无-GrokgrokGROK_API_KEY,GROK_MODEL,GROK_BASE_URL[Your GROK_API_KEY],grok-2-1212,https://api.x.ai/v1GroqgroqGROQ_API_KEY,GROQ_MODEL[Your GROQ_API_KEY],llama-3-3-70b-versatileDeepSeekdeepseekDEEPSEEK_API_KEY,DEEPSEEK_MODEL[Your DEEPSEEK_API_KEY],deepseek-chatMiniMaxminimaxMINIMAX_API_KEY,MINIMAX_MODEL[Your MINIMAX_API_KEY],MiniMax-M2.7OpenAI-LikedopenailikedOPENAILIKED_BASE_URL,OPENAILIKED_API_KEY,OPENAILIKED_MODEL,OPENAILIKED_STOP_TOKENS,OPENAILIKED_MAX_TOKENSurl,[Your Key],model name, ,-1阿里通义 Qwen MTqwen-mtALI_MODEL,ALI_API_KEY,ALI_DOMAINSqwen-mt-turbo,[Your Key],scientific paper注意事项凡兼容 OpenAI API 但未列入上表的 LLM 服务均可按 OpenAI 的方式设置环境变量接入使用 OpenAI 兼容 API 或自定义代理时BASE_URL必须以/v1结尾如https://api.openai.com/v1或http://your-proxy:8000/v1否则会产生 404 错误Qwen MT 暂不支持繁体中文繁体会被翻译为简体中文。配置文件集中管理服务与密钥通过--config可指定 JSON 配置文件同时适用于 CLI 与 GUIpdf2zh example.pdf --config config.json pdf2zh -i --config config.json示例配置文件来自 docs/ADVANCED.md{ 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 } } ] }配置加载顺序程序默认读取~/.config/PDFMathTranslate/config.json随后读取环境变量当环境变量可用时环境变量优先生效并写回配置文件。该机制由 pdf2zh/config.py 中的ConfigManager实现翻译器初始化时也会通过set_envs将环境变量与配置文件中的密钥合并见 pdf2zh/translator.py。面向公开服务的配置若要将 GUI 部署为公开服务可通过ENABLED_SERVICES限制可选翻译服务、通过HIDDEN_GRADIO_DETAILS隐藏真实 API Key防止用户从网页端窃取服务端密钥{ USE_MODELSCOPE: 0, translators: [ { name: grok, envs: { GROK_BASE_URL: https://api.x.ai/v1, GROK_API_KEY: your-api-key, GROK_MODEL: grok-2-1212 } }, { name: openai, envs: { OPENAI_BASE_URL: https://api.openai.com/v1, OPENAI_API_KEY: sk-xxxx, OPENAI_MODEL: gpt-4o-mini } } ], ENABLED_SERVICES: [OpenAI, Grok], HIDDEN_GRADIO_DETAILS: true, PDF2ZH_LANG_FROM: English, PDF2ZH_LANG_TO: Simplified Chinese, NOTO_FONT_PATH: /app/SourceHanSerifCN-Regular.ttf }自定义翻译提示词--prompt针对 LLM 类服务可通过--prompt传入提示词文件注意系统提示词暂不支持pdf2zh example.pdf --prompt prompt.txt提示词模板示例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:模板支持三个变量lang_in输入语言、lang_out输出语言、text待翻译文本。在源码 pdf2zh/translator.py 中默认提示词同样使用这组变量并要求保持公式记号{v*}不变这正是翻译结果中公式不损坏的关键约定--prompt文件会被读取为string.Template进行安全替换见 pdf2zh/pdf2zh.py。GUI 授权登录--authorized为 Web UI 配置账号密码与自定义登录页pdf2zh example.pdf --authorized users.txt auth.htmlusers.txt每行包含用户名,密码admin,123456 user1,password1 user2,abc123 guest,guest123 test,test123auth.html为自定义登录页面!DOCTYPE html html head titleSimple HTML/title /head body h1Hello, World!/h1 pWelcome to my simple HTML page./p /body /html字体子集化与翻译缓存字体子集化--skip-subset-fonts默认启用字体子集化以减小输出文件体积但当遇到兼容性问题时可用--skip-subset-fonts关闭pdf2zh example.pdf --skip-subset-fonts源码注释pdf2zh/pdf2zh.py说明该选项会提升兼容性但增大输出文件体积。翻译缓存--ignore-cache程序会对已翻译文本建立本地缓存以提升重复翻译速度、避免相同的 API 调用。缓存实现在 pdf2zh/cache.py基于 peewee SQLite数据库文件位于~/.cache/pdf2zh/cache.v1.db以翻译引擎 引擎参数 原文为唯一键翻译器基类BaseTranslator.translate会先查缓存、未命中才调用do_translate并回写见 pdf2zh/translator.py。如需强制重新翻译pdf2zh example.pdf --ignore-cache翻译模式fast 与 precise--mode支持两种翻译内核fast默认v1传统内核即 pdf2zh 1.x 的完整解析-翻译-重组管线precisev2实验性调用 PDFMathTranslate-next 内核在隔离的虚拟环境中以子进程运行需要先初始化PDFMathTranslate-next.git子模块。内核切换由 pdf2zh/kernel/registry.py 的KernelRegistry完成线程安全的热插拔注册表precise内核适配器实现在 pdf2zh/kernel/precise.py它会校验子模块目录与 venv 是否存在缺失时提示执行git submodule update --init pdf2zh/kernel/PDFMathTranslate-next.git。安装后可运行pdf2zh-setup-precise命令完成隔离环境的初始化入口声明于 pyproject.toml 的[project.scripts]。子模块与工作脚本位于 pdf2zh/kernel/PDFMathTranslate-next.git/ 与 pdf2zh/kernel/v2_worker.py。多线程与批量翻译-t指定翻译线程数默认 4源码 pdf2zh/pdf2zh.py。GUI 中同样提供该参数--dir批量翻译递归扫描目录下全部.pdf、.doc、.docx文件见find_all_files_in_directorypdf2zh/pdf2zh.pyWord 文档会先转换为 PDF 再翻译见 pdf2zh/converter_docx.py。二次开发与 API 说明当前 pdf2zh 的 Python/HTTP API 已暂时弃用相关代码不会移除但不再提供技术支持与 bug 修复。API 将在 pdf2zh 2.0 发布后重新提供需要程序化访问的用户可改用 BabelDOC 的babeldoc.high_level.async_translate函数。仓库中的 docs/APIS.md 保留了对 Python API 与 HTTP API 的历史说明。若需以 MCPModel Context Protocol方式将翻译能力接入 AI 助手可用--mcp启动 STDIO 模式、--mcp --sse启动 SSE 模式见 pdf2zh/mcp_server.py并在客户端配置如claude_desktop_config.json中声明translate_pdf服务示例配置见 docs/ADVANCED.md。工作原理与实现要点从源码结构可以梳理出 fast 模式的基本流程布局解析加载 DocLayout-YOLO ONNX 模型pdf2zh/doclayout.py通过OnnxModel.predict识别每页的标题、正文、公式、表格、图表等区域--backend可选择 ONNX Runtime 的 CPU/CUDA/DirectML 执行提供方GPU 加速需安装cudaonnxruntime-gpu或dmlonnxruntime-directml可选依赖见 pyproject.toml文本解析基于 pdfminer.six 解析页面文本流与字体信息pdf2zh/converter.py、pdf2zh/pdfinterp.py按-f/-c正则识别公式字体与字符将其替换为占位符以保护公式并行翻译多线程调用所选翻译服务pdf2zh/translator.pyLLM 类服务通过自定义/默认提示词保持公式记号{v*}不变结果写入 SQLite 缓存重组输出基于 PyMuPDF 将译文按原始坐标回填生成-mono单语与-dual双语 PDF-cp兼容模式则额外转换 PDF/A 格式提升兼容性。小结PDFMathTranslate 通过布局识别 公式保护 多服务翻译 排版回填的完整管线实现了科学 PDF 的保排版全文翻译。本文覆盖了中文 README 中全部安装方式uv、Windows exe、GUI、Docker、Zotero、CLI、高级参数、翻译服务配置与网络问题解法并结合 docs/ADVANCED.md 与 pdf2zh/ 源码补充了配置文件、缓存、字体子集化与 fast/precise 双内核的底层机制。你可以根据实际环境选择最合适的安装方式并参照服务对照表配置自己的翻译服务后立即投入使用。【免费下载链接】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），仅供参考 PDFMathTranslate 中文使用指南：保留公式与排版的科学 PDF 全文双语翻译
PDFMathTranslate 中文使用指南保留公式与排版的科学 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/PDFMathTranslatePDFMathTranslate 是一款面向科学文献的 PDF 翻译工具其核心能力是在翻译过程中完整保留原始排版——公式、图表、目录与注释均不被破坏最终同时输出单语译文-mono与双语对照-dual两份 PDF。本文以仓库内中文文档 docs/README_zh-CN.md 为主体结合源码与高级配置文档系统讲解从安装、命令行翻译、GUI 与 Docker 部署到翻译服务选择、自定义配置与翻译内核机制的完整实战方案。读完本文你将能够独立完成科学 PDF 的本地翻译部署并根据自己的翻译服务与环境灵活调整参数。项目概览科学 PDF 翻译与双语对照PDFMathTranslate 定位为科学 PDF 文档翻译及双语对照工具面向论文、技术手册等排版复杂的科学文档解决了传统 PDF 翻译工具翻译后格式崩坏、公式乱码的痛点保留公式、图表、目录和注释支持多种语言和诸多翻译服务Google、DeepL、OpenAI、Ollama 等提供命令行工具、图形交互界面GUI以及容器化部署Docker三种使用形态。从仓库结构看翻译能力由 pdf2zh/ 包承载命令行入口定义在 pdf2zh/pdf2zh.py布局解析依赖 DocLayout-YOLO 的 ONNX 模型见 pdf2zh/doclayout.py文档合并与解析则基于 PyMuPDF 与 pdfminer.six声明于 pyproject.toml 的依赖列表。在线演示服务在本地安装之前可以通过以下在线服务快速体验翻译效果注意演示资源有限请勿滥用公共免费服务在线使用无需安装沉浸式翻译 BabelDOC每月免费 1000 页HuggingFace 托管的 Docker 演示ModelScope 托管的演示无需安装。安装与使用六种方式中文文档针对不同使用场景提供了六种安装与使用方式。1. uv 安装推荐uv 提供独立的工具环境不会污染系统 Pythonpip install uv uv tool install --python 3.12 pdf2zh安装后执行翻译译文文件生成在当前工作目录pdf2zh document.pdf需要 Python 版本满足3.11 版本 3.12该约束与 pyproject.toml 中的requires-python 3.11,3.13一致。2. Windows exe从发布页面下载pdf2zh-version-win64.zip解压后双击pdf2zh.exe即可运行适合无需 Python 环境的 Windows 用户。3. 图形用户界面GUIpip install pdf2zh pdf2zh -i命令执行后会在浏览器中打开 Web 界面若浏览器未自动启动访问http://localhost:7860/。GUI 模式下支持拖拽 PDF 上传并点击 Translate 完成翻译详细交互说明见 docs/README_GUI.md。GUI 中源语言与目标语言也可通过环境变量控制PDF2ZH_LANG_FROM源语言默认EnglishPDF2ZH_LANG_TO目标语言默认Simplified Chinese。支持的界面语言包括英文、简体中文、繁体中文、法文、德文、日文、韩文、俄文、西班牙文、意大利文。从源码看-i参数在 pdf2zh/pdf2zh.py 中触发setup_gui()底层基于 Gradio 构建依赖gradio5.36并支持--share生成公网链接、--authorized配置登录鉴权。4. Docker 容器化部署docker pull byaidu/pdf2zh docker run -d -p 7860:7860 byaidu/pdf2zh随后在浏览器打开http://localhost:7860/即可。若无法访问 Docker Hub可使用 GitHub 容器注册中心的镜像docker pull ghcr.io/byaidu/pdfmathtranslate docker run -d -p 7860:7860 ghcr.io/byaidu/pdfmathtranslate仓库根目录的 docker-compose.yml 与 Dockerfile 也提供了可参考的自建镜像配置。云服务部署方面文档提供了 Heroku、Render、Zeabur、Sealos、Koyeb 等平台的部署入口。5. Zotero 插件面向文献管理场景可通过 Zotero 插件在文献库中直接触发翻译详见 Zotero PDF2zh 插件项目。6. 命令行pip install pdf2zh pdf2zh document.pdf执行后会在当前工作目录生成example-mono.pdf单语译文与example-dual.pdf双语对照默认使用 Google 翻译服务。无法安装模型下载的网络问题程序运行前需要加载 AI 布局模型wybxc/DocLayout-YOLO-DocStructBench-onnx用于识别文档中的公式、图表、目录等区域加载逻辑见 pdf2zh/doclayout.py。部分用户因网络原因无法从 Hugging Face 下载该模型可通过设置镜像环境变量解决set HF_ENDPOINThttps://hf-mirror.comPowerShell 用户$env:HF_ENDPOINT https://hf-mirror.com若仍无法解决可查阅项目 Wiki 的常见问题解答FAQ。此外Windows 用户若下载后无法打开程序需先安装vc_redist.x64.exeMicrosoft Visual C 运行库再重试——这与 pdf2zh/doclayout.py 中对 ONNX Runtime DLL 加载失败的显式提示一致。高级选项命令行参数全解pdf2zh的命令行参数在 pdf2zh/pdf2zh.py 中通过 argparse 定义。中文 README 列出了全部高级选项下表在保留原文基础上补充了各参数的默认值取自源码选项功能示例files本地文件支持 PDF/Wordpdf2zh ~/local.pdflinks在线文件pdf2zh http://arxiv.org/paper.pdf-i进入 GUIpdf2zh -i-p部分文档翻译pdf2zh example.pdf -p 1-li源语言默认enpdf2zh example.pdf -li en-lo目标语言默认zhpdf2zh example.pdf -lo zh-s翻译服务默认googlepdf2zh example.pdf -s deepl-t多线程数默认4pdf2zh example.pdf -t 1-o输出目录pdf2zh example.pdf -o output-f,-c公式字体/字符异常正则pdf2zh example.pdf -f (MS.*)-cp兼容模式转换 PDF/Apdf2zh example.pdf --compatible--skip-subset-fonts跳过字体子集化pdf2zh example.pdf --skip-subset-fonts--ignore-cache忽略翻译缓存强制重译pdf2zh example.pdf --ignore-cache--share生成 Gradio 公网链接pdf2zh -i --share--authorizedGUI 登录授权pdf2zh -i --authorized users.txt [auth.html]--prompt自定义翻译提示词pdf2zh --prompt [prompt.txt]--onnx自定义 DocLayout-YOLO ONNX 模型pdf2zh --onnx [onnx/model/path]--backendONNX Runtime 执行后端auto/cpu/cuda/dmlpdf2zh --backend cuda--serverport自定义 WebUI 端口pdf2zh --serverport 7860--dir批量翻译目录内全部 PDF/Wordpdf2zh --dir /path/to/translate/--config指定配置文件pdf2zh --config /path/to/config/config.json--mode翻译模式fast默认v1或precisev2 实验性pdf2zh --mode precise example.pdf--babeldoc使用实验性 BabelDOC 后端pdf2zh --babeldoc -s openai example.pdf--mcp以 MCP STDIO 模式启动服务pdf2zh --mcp--sse以 MCP SSE 模式启动服务pdf2zh --mcp --sse完整选项说明可查阅 docs/ADVANCED.md。下面对几个高频参数做源码级展开。部分翻译-p支持页码范围与列表例如-p 1-3,5表示翻译第 1 至 3 页与第 5 页。源码 pdf2zh/pdf2zh.py 会将1-3展开为页索引列表注意页码在内部被转换为从 0 开始的索引。语言与翻译服务-li/-lo/-s默认源语言为英文、目标语言为简体中文、服务为 Google分别对应源码中的默认值en、zh、google。Google 翻译器实现在 pdf2zh/translator.py其单次请求上限为 5000 字符text[:5000]。语言代码遵循各服务的规范如 Google 使用zh-CNBing 使用zh-Hanslang_map映射同样定义在 pdf2zh/translator.py。公式异常处理-f/-c科学 PDF 中公式往往使用特殊字体渲染默认情况下程序会保留 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)-c用于按字符正则保留公式中的特殊符号pdf2zh example.pdf -f (CM[^RT].*|MS.*|.*Ital) -c (\(|\||\)|\||\d|[\u0080-\ufaff])在源码中这两个正则分别对应--vfont公式字体名匹配与--vchar公式字符匹配作用于 PDF 解析阶段见 pdf2zh/pdf2zh.py。翻译服务与环境变量-s指定翻译服务通用格式为-s service或-s service:model。例如指定 OpenAI 及具体模型pdf2zh example.pdf -s openai:gpt-4o-mini也可通过环境变量指定模型set OPENAI_MODELgpt-4o-mini pdf2zh example.pdf -s openaiPowerShell 用户$env:OPENAI_MODEL gpt-4o-mini pdf2zh example.pdf -s openai主要服务及其所需环境变量来自 docs/ADVANCED.md 的对照表翻译器Service 名环境变量默认值Google默认google无-Bingbing无-302.AI302aiX302AI_API_KEY,X302AI_MODEL[Your Key],Gemma-7BOpenAIopenaiOPENAI_BASE_URL,OPENAI_API_KEY,OPENAI_MODEL,OPENAI_STOP_TOKENS,OPENAI_MAX_TOKENShttps://api.openai.com/v1,[Your Key],gpt-4o-mini, ,-1DeepLdeeplDEEPL_AUTH_KEY[Your Key]DeepLXdeeplxDEEPLX_ENDPOINThttps://api.deepl.com/translateOllamaollamaOLLAMA_HOST,OLLAMA_MODELhttp://127.0.0.1:11434,gemma2XinferencexinferenceXINFERENCE_HOST,XINFERENCE_MODELhttp://127.0.0.1:9997,gemma-2-itAzureOpenAIazure-openaiAZURE_OPENAI_BASE_URL,AZURE_OPENAI_API_KEY,AZURE_OPENAI_MODEL[Your Endpoint],[Your Key],gpt-4o-mini智谱 ZhipuzhipuZHIPU_API_KEY,ZHIPU_MODEL[Your Key],glm-4-flashModelScopemodelscopeMODELSCOPE_API_KEY,MODELSCOPE_MODEL[Your Key],Qwen/Qwen2.5-Coder-32B-Instruct硅基流动 SiliconsiliconSILICON_API_KEY,SILICON_MODEL[Your Key],Qwen/Qwen2.5-7B-InstructGeminigeminiGEMINI_API_KEY,GEMINI_MODEL[Your Key],gemini-1.5-flashAzureazureAZURE_ENDPOINT,AZURE_API_KEYhttps://api.translator.azure.cn,[Your Key]腾讯 TencenttencentTENCENTCLOUD_SECRET_ID,TENCENTCLOUD_SECRET_KEY[Your ID],[Your Key]DifydifyDIFY_API_URL,DIFY_API_KEY[Your DIFY URL],[Your Key]AnythingLLManythingllmAnythingLLM_URL,AnythingLLM_APIKEY[Your AnythingLLM URL],[Your Key]Argos Translateargos无-GrokgrokGROK_API_KEY,GROK_MODEL,GROK_BASE_URL[Your GROK_API_KEY],grok-2-1212,https://api.x.ai/v1GroqgroqGROQ_API_KEY,GROQ_MODEL[Your GROQ_API_KEY],llama-3-3-70b-versatileDeepSeekdeepseekDEEPSEEK_API_KEY,DEEPSEEK_MODEL[Your DEEPSEEK_API_KEY],deepseek-chatMiniMaxminimaxMINIMAX_API_KEY,MINIMAX_MODEL[Your MINIMAX_API_KEY],MiniMax-M2.7OpenAI-LikedopenailikedOPENAILIKED_BASE_URL,OPENAILIKED_API_KEY,OPENAILIKED_MODEL,OPENAILIKED_STOP_TOKENS,OPENAILIKED_MAX_TOKENSurl,[Your Key],model name, ,-1阿里通义 Qwen MTqwen-mtALI_MODEL,ALI_API_KEY,ALI_DOMAINSqwen-mt-turbo,[Your Key],scientific paper注意事项凡兼容 OpenAI API 但未列入上表的 LLM 服务均可按 OpenAI 的方式设置环境变量接入使用 OpenAI 兼容 API 或自定义代理时BASE_URL必须以/v1结尾如https://api.openai.com/v1或http://your-proxy:8000/v1否则会产生 404 错误Qwen MT 暂不支持繁体中文繁体会被翻译为简体中文。配置文件集中管理服务与密钥通过--config可指定 JSON 配置文件同时适用于 CLI 与 GUIpdf2zh example.pdf --config config.json pdf2zh -i --config config.json示例配置文件来自 docs/ADVANCED.md{ 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 } } ] }配置加载顺序程序默认读取~/.config/PDFMathTranslate/config.json随后读取环境变量当环境变量可用时环境变量优先生效并写回配置文件。该机制由 pdf2zh/config.py 中的ConfigManager实现翻译器初始化时也会通过set_envs将环境变量与配置文件中的密钥合并见 pdf2zh/translator.py。面向公开服务的配置若要将 GUI 部署为公开服务可通过ENABLED_SERVICES限制可选翻译服务、通过HIDDEN_GRADIO_DETAILS隐藏真实 API Key防止用户从网页端窃取服务端密钥{ USE_MODELSCOPE: 0, translators: [ { name: grok, envs: { GROK_BASE_URL: https://api.x.ai/v1, GROK_API_KEY: your-api-key, GROK_MODEL: grok-2-1212 } }, { name: openai, envs: { OPENAI_BASE_URL: https://api.openai.com/v1, OPENAI_API_KEY: sk-xxxx, OPENAI_MODEL: gpt-4o-mini } } ], ENABLED_SERVICES: [OpenAI, Grok], HIDDEN_GRADIO_DETAILS: true, PDF2ZH_LANG_FROM: English, PDF2ZH_LANG_TO: Simplified Chinese, NOTO_FONT_PATH: /app/SourceHanSerifCN-Regular.ttf }自定义翻译提示词--prompt针对 LLM 类服务可通过--prompt传入提示词文件注意系统提示词暂不支持pdf2zh example.pdf --prompt prompt.txt提示词模板示例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:模板支持三个变量lang_in输入语言、lang_out输出语言、text待翻译文本。在源码 pdf2zh/translator.py 中默认提示词同样使用这组变量并要求保持公式记号{v*}不变这正是翻译结果中公式不损坏的关键约定--prompt文件会被读取为string.Template进行安全替换见 pdf2zh/pdf2zh.py。GUI 授权登录--authorized为 Web UI 配置账号密码与自定义登录页pdf2zh example.pdf --authorized users.txt auth.htmlusers.txt每行包含用户名,密码admin,123456 user1,password1 user2,abc123 guest,guest123 test,test123auth.html为自定义登录页面!DOCTYPE html html head titleSimple HTML/title /head body h1Hello, World!/h1 pWelcome to my simple HTML page./p /body /html字体子集化与翻译缓存字体子集化--skip-subset-fonts默认启用字体子集化以减小输出文件体积但当遇到兼容性问题时可用--skip-subset-fonts关闭pdf2zh example.pdf --skip-subset-fonts源码注释pdf2zh/pdf2zh.py说明该选项会提升兼容性但增大输出文件体积。翻译缓存--ignore-cache程序会对已翻译文本建立本地缓存以提升重复翻译速度、避免相同的 API 调用。缓存实现在 pdf2zh/cache.py基于 peewee SQLite数据库文件位于~/.cache/pdf2zh/cache.v1.db以翻译引擎 引擎参数 原文为唯一键翻译器基类BaseTranslator.translate会先查缓存、未命中才调用do_translate并回写见 pdf2zh/translator.py。如需强制重新翻译pdf2zh example.pdf --ignore-cache翻译模式fast 与 precise--mode支持两种翻译内核fast默认v1传统内核即 pdf2zh 1.x 的完整解析-翻译-重组管线precisev2实验性调用 PDFMathTranslate-next 内核在隔离的虚拟环境中以子进程运行需要先初始化PDFMathTranslate-next.git子模块。内核切换由 pdf2zh/kernel/registry.py 的KernelRegistry完成线程安全的热插拔注册表precise内核适配器实现在 pdf2zh/kernel/precise.py它会校验子模块目录与 venv 是否存在缺失时提示执行git submodule update --init pdf2zh/kernel/PDFMathTranslate-next.git。安装后可运行pdf2zh-setup-precise命令完成隔离环境的初始化入口声明于 pyproject.toml 的[project.scripts]。子模块与工作脚本位于 pdf2zh/kernel/PDFMathTranslate-next.git/ 与 pdf2zh/kernel/v2_worker.py。多线程与批量翻译-t指定翻译线程数默认 4源码 pdf2zh/pdf2zh.py。GUI 中同样提供该参数--dir批量翻译递归扫描目录下全部.pdf、.doc、.docx文件见find_all_files_in_directorypdf2zh/pdf2zh.pyWord 文档会先转换为 PDF 再翻译见 pdf2zh/converter_docx.py。二次开发与 API 说明当前 pdf2zh 的 Python/HTTP API 已暂时弃用相关代码不会移除但不再提供技术支持与 bug 修复。API 将在 pdf2zh 2.0 发布后重新提供需要程序化访问的用户可改用 BabelDOC 的babeldoc.high_level.async_translate函数。仓库中的 docs/APIS.md 保留了对 Python API 与 HTTP API 的历史说明。若需以 MCPModel Context Protocol方式将翻译能力接入 AI 助手可用--mcp启动 STDIO 模式、--mcp --sse启动 SSE 模式见 pdf2zh/mcp_server.py并在客户端配置如claude_desktop_config.json中声明translate_pdf服务示例配置见 docs/ADVANCED.md。工作原理与实现要点从源码结构可以梳理出 fast 模式的基本流程布局解析加载 DocLayout-YOLO ONNX 模型pdf2zh/doclayout.py通过OnnxModel.predict识别每页的标题、正文、公式、表格、图表等区域--backend可选择 ONNX Runtime 的 CPU/CUDA/DirectML 执行提供方GPU 加速需安装cudaonnxruntime-gpu或dmlonnxruntime-directml可选依赖见 pyproject.toml文本解析基于 pdfminer.six 解析页面文本流与字体信息pdf2zh/converter.py、pdf2zh/pdfinterp.py按-f/-c正则识别公式字体与字符将其替换为占位符以保护公式并行翻译多线程调用所选翻译服务pdf2zh/translator.pyLLM 类服务通过自定义/默认提示词保持公式记号{v*}不变结果写入 SQLite 缓存重组输出基于 PyMuPDF 将译文按原始坐标回填生成-mono单语与-dual双语 PDF-cp兼容模式则额外转换 PDF/A 格式提升兼容性。小结PDFMathTranslate 通过布局识别 公式保护 多服务翻译 排版回填的完整管线实现了科学 PDF 的保排版全文翻译。本文覆盖了中文 README 中全部安装方式uv、Windows exe、GUI、Docker、Zotero、CLI、高级参数、翻译服务配置与网络问题解法并结合 docs/ADVANCED.md 与 pdf2zh/ 源码补充了配置文件、缓存、字体子集化与 fast/precise 双内核的底层机制。你可以根据实际环境选择最合适的安装方式并参照服务对照表配置自己的翻译服务后立即投入使用。【免费下载链接】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），仅供参考