尧图网站建设 
PDFMathTranslate 完整使用指南pdf2zh 安装、CLI 高级选项、翻译服务与 API 实战【免费下载链接】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本文基于仓库文档 docs/README_ja-JP.md 展开并结合源码如 pdf2zh/pdf2zh.py、pdf2zh/translator.py、pdf2zh/high_level.py、pdf2zh/backend.py进行深度扩充。全文以当前仓库实际内容为准。PDFMathTranslatePyPI 包名为pdf2zh是一款面向科学文献场景的 PDF 翻译工具其核心目标是在翻译全文的同时完整保留原文档的版式——包括数学公式、图表、目录与注释。本文将从安装入手系统讲解命令行CLI的全部高级选项、20 余种翻译服务的接入方式、局部翻译与正则例外规则、自定义提示词与配置文件以及 Python / HTTP 两种 API 的调用方式并辅以源码级原理说明帮助你把它部署为本地工具、GUI 服务或公共翻译后端。一、项目定位保留版式的科学 PDF 翻译在科研阅读场景中直接翻译 PDF 往往会破坏公式与排版导致翻译完看不懂、看版式又找不到原文。PDFMathTranslate 的设计目标正是解决这一痛点 保留数式公式、图表、目录与注释等元素 支持多种源语言 / 目标语言以及多样化的翻译服务Google、DeepL、Ollama、OpenAI、DeepSeek、MiniMax 等 提供命令行工具、交互式图形界面GUI与 Docker 三种使用形态另有便携版Windows可选。从源码结构看其核心处理链路大致为对应 pdf2zh/high_level.py 中的translate_stream→translate_patch布局解析使用 ONNX 格式的 DocLayout-YOLO 模型wybxc/DocLayout-YOLO-DocStructBench-onnx对每页渲染出的图像做版面检测识别正文、图表、公式等区域见 pdf2zh/high_level.py 中的model.predict(...)调用vcls [abandon, figure, table, isolate_formula, formula_caption]等类别会被排除在翻译区域之外文本解析基于 pdfminer.six 解析页面内容流PDFParser/PDFDocument/PDFPageInterpreterEx逐段翻译按线程池并发调用所选翻译服务版式重排用 PyMuPDF 将翻译文本按原位置写回生成-mono.pdf纯译文与-dual.pdf双语对照两个文件。项目相关的更完整说明可继续阅读 README.md英文主文档、docs/ADVANCED.md高级用法与 docs/APIS.mdAPI 细节。二、安装与四种使用方式项目提供 4 种使用方式命令行、便携版Windows、GUI与Docker。安装前请确认 Python 版本满足3.11 版本 3.12。2.1 方法一命令行pip 安装pip install pdf2zh然后在当前工作目录下直接翻译pdf2zh document.pdf命令执行后会在当前目录生成document-mono.pdf单语译文与document-dual.pdf双语对照两个文件。2.2 方法二便携版Windows免 Python 环境如果不想预先安装 Python 环境可以下载仓库 script/setup.bat双击运行即可完成环境准备与安装适合在不熟悉 Python 的机器上快速使用。2.3 方法三GUI浏览器交互界面安装包pip install pdf2zh以交互模式启动pdf2zh -i若浏览器未自动打开手动访问http://localhost:7860/将 PDF 文件拖入窗口点击Translate即可开始翻译。GUI 更多细节支持的语言列表、环境变量等参见 docs/README_GUI.md。2.4 方法四Docker 容器化部署docker pull byaidu/pdf2zh docker run -d -p 7860:7860 byaidu/pdf2zh然后浏览器打开http://localhost:7860/即可使用。2.5 模型下载问题的解决方案网络受限场景pdf2zh 启动时需要额外下载布局检测模型wybxc/DocLayout-YOLO-DocStructBench-onnx该模型在 ModelScope 上也有镜像。如果因网络问题无法下载可通过设置 HuggingFace 镜像端点环境变量解决# CMD set HF_ENDPOINThttps://hf-mirror.com# PowerShell $env:HF_ENDPOINT https://hf-mirror.com若该方案仍无法解决可参考仓库 Wiki 中的 FAQ 章节获取更多排查建议。三、命令行高级选项速查在命令行执行翻译时默认使用 Google 翻译服务并在当前工作目录生成example-mono.pdf与example-dual.pdf。下图直观展示了各参数在命令行中的位置与含义以下表格汇总了全部高级选项参数定义可在 pdf2zh/pdf2zh.py 的create_parser()中逐一核对选项功能示例files本地文件pdf2zh ~/local.pdflinks在线文件自动下载pdf2zh http://arxiv.org/paper.pdf-i进入 GUIpdf2zh -i-p部分文档翻译pdf2zh example.pdf -p 1-li源语言pdf2zh example.pdf -li en-lo目标语言pdf2zh example.pdf -lo zh-s翻译服务pdf2zh example.pdf -s deepl-t多线程数量pdf2zh example.pdf -t 1-o输出目录pdf2zh example.pdf -o output-f,-c翻译例外正则pdf2zh example.pdf -f (MS.*)-cp/--compatible兼容模式转为 PDF/A 提升兼容性pdf2zh example.pdf --compatible--skip-subset-fonts跳过字体子集化提高兼容性但增大文件pdf2zh example.pdf --skip-subset-fonts--ignore-cache忽略翻译缓存、强制重译pdf2zh example.pdf --ignore-cache--share生成 Gradio 公网分享链接pdf2zh -i --share--authorized添加 Web 认证与自定义认证页pdf2zh -i --authorized users.txt [auth.html]--prompt使用自定义大模型提示词pdf2zh --prompt [prompt.txt]--onnx使用自定义 DocLayout-YOLO ONNX 模型pdf2zh --onnx [onnx/model/path]--serverport自定义 WebUI 端口pdf2zh --serverport 7860--dir批量翻译目录下所有 PDF/Word 文件pdf2zh --dir /path/to/translate/--config指定配置文件pdf2zh --config /path/to/config/config.json--mode翻译模式fast默认v1或precisev2 实验性pdf2zh --mode precise example.pdf--babeldoc使用实验性后端 BabelDOCpdf2zh --babeldoc -s openai example.pdf--mcp以 MCP STDIO 模式启动pdf2zh --mcp--sse以 MCP SSE 模式启动pdf2zh --mcp --sse其中--dir的实现可在 pdf2zh/pdf2zh.py 的find_all_files_in_directory()中看到它会递归遍历目录收集所有.pdf、.doc、.docx文件后逐一翻译--compatible会调用 pdf2zh/high_level.py 中的convert_to_pdfa()通过 pikepdf 写入 PDF/A-2B 元数据与输出意图从而改善兼容性。四、全文翻译与部分翻译全文翻译默认行为pdf2zh example.pdf部分翻译使用-p指定页范围支持逗号分隔与连字符区间pdf2zh example.pdf -p 1-3,5该命令只翻译第 1、2、3、5 页。从 pdf2zh/pdf2zh.py 的parse_args()可以看到-p参数会被解析为 0 起始的页索引列表如1-3展开为[0,1,2]再传入翻译内核按页过滤。五、指定源语言与目标语言使用-lisource与-lotarget指定语言代码pdf2zh example.pdf -li en -lo ja语言代码可参考 Google 与 DeepL 官方支持的语言代码列表分别对应 Google Translate 与 DeepL API 的语言枚举。CLI 中语言参数的默认值分别为en源与zh目标定义于 pdf2zh/pdf2zh.py 的--lang-in/--lang-out参数。另外GUI 模式可通过环境变量预设语言PDF2ZH_LANG_FROM源语言默认 EnglishPDF2ZH_LANG_TO目标语言默认 Simplified Chinese。详见 docs/README_GUI.md。六、使用不同翻译服务6.1 服务与环境变量总表下表列出了各翻译服务所需的环境变量与默认值。使用对应服务前务必先设置好这些变量变量读取逻辑见 pdf2zh/translator.py 中BaseTranslator.set_envs()程序会优先使用操作系统环境变量并将其写回本地配置文件。TranslatorServiceEnvironment VariablesDefault ValuesNotesGoogle默认google无N/A免费无需密钥Bingbing无N/A免费无需密钥DeepLdeeplDEEPL_AUTH_KEY[Your Key]需 DeepL API KeyDeepLXdeeplxDEEPLX_ENDPOINThttps://api.deepl.com/translate自建 DeepL 代理OllamaollamaOLLAMA_HOST,OLLAMA_MODELhttp://127.0.0.1:11434,gemma2本地大模型OpenAIopenaiOPENAI_BASE_URL,OPENAI_API_KEY,OPENAI_MODEL,OPENAI_STOP_TOKENS,OPENAI_MAX_TOKENShttps://api.openai.com/v1,[Your Key],gpt-4o-mini, 空格,-1兼容 OpenAI API 的服务均可参考此项AzureOpenAIazure-openaiAZURE_OPENAI_BASE_URL,AZURE_OPENAI_API_KEY,AZURE_OPENAI_MODEL[Your Endpoint],[Your Key],gpt-4o-miniAzure 上的 OpenAI 服务Zhipu智谱zhipuZHIPU_API_KEY,ZHIPU_MODEL[Your Key],glm-4-flash智谱 GLM 系列ModelScopemodelscopeMODELSCOPE_API_KEY,MODELSCOPE_MODEL[Your Key],Qwen/Qwen2.5-Coder-32B-Instruct魔搭社区模型服务SiliconsiliconSILICON_API_KEY,SILICON_MODEL[Your Key],Qwen/Qwen2.5-7B-InstructSiliconCloud 平台GeminigeminiGEMINI_API_KEY,GEMINI_MODEL[Your Key],gemini-1.5-flashGoogle Gemini APIAzureazureAZURE_ENDPOINT,AZURE_API_KEYhttps://api.translator.azure.cn,[Your Key]Azure 文本翻译服务Tencent腾讯tencentTENCENTCLOUD_SECRET_ID,TENCENTCLOUD_SECRET_KEY[Your ID],[Your Key]腾讯云机器翻译 TMTDifydifyDIFY_API_URL,DIFY_API_KEY[Your DIFY URL],[Your Key]需在 Dify 工作流输入中定义lang_out、lang_in、text三个变量AnythingLLManythingllmAnythingLLM_URL,AnythingLLM_APIKEY[Your AnythingLLM URL],[Your Key]AnythingLLM 后端Argos Translateargos无N/A开源离线翻译引擎GrokgrokGROK_API_KEY,GROK_MODEL[Your GROK_API_KEY],grok-2-1212xAI 的 GrokDeepSeekdeepseekDEEPSEEK_API_KEY,DEEPSEEK_MODEL[Your DEEPSEEK_API_KEY],deepseek-chatDeepSeek 大模型MiniMaxminimaxMINIMAX_API_KEY,MINIMAX_MODEL[Your MINIMAX_API_KEY],MiniMax-M2.7MiniMax 大模型OpenAI-LikedopenailikedOPENAILIKED_BASE_URL,OPENAILIKED_API_KEY,OPENAILIKED_MODEL可选OPENAILIKED_STOP_TOKENS,OPENAILIKED_MAX_TOKENSurl,[Your Key],model name任意 OpenAI 兼容接口补充说明上表中未列出、但兼容 OpenAI API 的大语言模型服务可完全照搬 OpenAI 一行的环境变量设置方式接入从源码看OpenAI 系列还支持OPENAI_STREAM默认true以流式方式取回翻译结果并可设置temperature: 0以避免随机采样打断公式占位符见 pdf2zh/translator.py 中OpenAITranslator的实现含速率限制自动重试与think过滤逻辑仓库 docs/ADVANCED.md 中还收录了 302.AI、Xinference、Groq、Qwen-MT 等更多服务可一并查阅。6.2 指定服务与模型使用-s service或-s service:model指定服务与模型pdf2zh example.pdf -s openai:gpt-4o-mini也可以用环境变量指定模型# CMD set OPENAI_MODELgpt-4o-mini pdf2zh example.pdf -s openai# PowerShell $env:OPENAI_MODEL gpt-4o-mini pdf2zh example.pdf -s openai七、翻译例外用正则保留公式字体与字符在科学文档中公式字体与特殊字符不应被翻译。使用-f字体名正则与-c字符正则指定需要保留的内容pdf2zh example.pdf -f (CM[^RT].*|MS.*|.*Ital) -c (\(|\||\)|\||\d|[\u0080-\ufaff])默认情况下pdf2zh 会保留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)这两个正则分别对应 CLI 的--vfont与--vchar参数见 pdf2zh/pdf2zh.py它们最终会传递给TranslateConverter在解析 PDF 内容流时按字体与字符判断是否跳过翻译。八、指定线程数使用-t指定翻译时的并发线程数默认值为 4pdf2zh example.pdf -t 1多线程翻译的实现位于 pdf2zh/converter.py它基于concurrent.futures线程池并发提交翻译请求以显著缩短整篇文档的翻译耗时在线程不足或服务端限流时可调小该值。九、自定义提示词--prompt对于 LLM 类翻译服务可以用--prompt指定自定义提示词文件pdf2zh example.pdf -pr prompt.txt说明-pr为文档中出现的写法实际参数名为--prompt即pdf2zh example.pdf --prompt prompt.txt。prompt.txt示例JSON 消息数组格式对应BaseTranslator.prompt()中按 role/content 构造消息的逻辑[ { role: system, content: You are a professional,authentic machine translation engine., }, { role: user, content: Translate the following markdown source text to ${lang_out}. Keep the formula notation {{v*}} unchanged. Output translation directly without any additional text.\nSource Text: ${text}\nTranslated Text:, }, ]自定义提示词文件中可使用以下 3 个变量由string.Template.safe_substitute注入见 pdf2zh/translator.py变量内容lang_in源语言lang_out目标语言text待翻译文本注意--prompt主要面向支持自定义提示词的 LLM 服务源码中以CustomPrompt True标记如 OpenAI、AzureOpenAI 等。若不提供自定义提示词BaseTranslator.prompt()会使用内置默认提示词要求模型只输出译文、保持公式占位符{v*}不变。十、自定义配置文件--config除环境变量外还可用--config指定 JSON 配置文件pdf2zh example.pdf --config config.jsonpdf2zh -i --config 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 } } ] }配置加载优先级默认配置文件位于~/.config/PDFMathTranslate/config.json。程序先读取该文件内容再读取环境变量当环境变量存在时以环境变量为准并同步更新配置文件对应 pdf2zh/config.py 中ConfigManager的实现单例模式 可重入锁保证线程安全get()在命中环境变量或默认值时自动写回配置文件。⚠️ 使用 OpenAI 兼容 API 或自定义代理如 Grok、OpenAI-liked 等时请确保BASE_URL以/v1结尾例如https://api.openai.com/v1或http://your-proxy:8000/v1否则会返回 404。十一、其他实用进阶能力11.1 字体子集化与跳过默认启用字体子集化font subsetting以减小输出文件体积。遇到兼容性问题时可跳过子集化代价是输出文件变大pdf2zh example.pdf --skip-subset-fonts11.2 翻译缓存pdf2zh 会缓存已翻译文本以加快重复内容处理并避免产生不必要的 API 调用缓存实现见 pdf2zh/cache.py缓存键包含服务名、语言对与模型名并额外记录 temperature、stop、max_tokens、prompt 等影响翻译质量的参数。需要强制重译时pdf2zh example.pdf --ignore-cache11.3 GUI 认证与公网分享--share为 GUI 生成 Gradio 公网分享链接--authorized为 Web UI 添加用户名/密码认证与自定义登录页。users.txt每行一个用户格式为用户名,密码admin,123456 user1,password1自定义auth.html将被用作登录页。11.4 MCP 集成pdf2zh 可以作为 MCP 服务器运行pdf2zh --mcp或--mcp --sse切换 SSE 模式从而让 Claude Desktop 等 MCP 客户端直接调用翻译能力。配合 filesystem MCP 服务器即可实现找到某 PDF 并翻译成中文这类自然语言指令详见 docs/ADVANCED.md 的 MCP 一节。十二、API在程序与服务器中集成12.1 Python APIpdf2zh 作为 Python 模块对外暴露translate与translate_stream两个函数定义见 pdf2zh/high_level.pyfrom pdf2zh import translate, translate_stream params {lang_in: en, lang_out: zh, service: google, thread: 4} file_mono, file_dual translate(files[example.pdf], **params)[0] with open(example.pdf, rb) as f: stream_mono, stream_dual translate_stream(streamf.read(), **params)translate(files[...], ...)传入本地文件路径也支持http(s)://在线文件会自动下载到临时目录后翻译见check_files()与在线下载分支返回(单语文件路径, 双语文件路径)元组列表translate_stream(streambytes, ...)直接传入 PDF 二进制流返回两个 PDF 字节流mono 与 dual适合在 Web 服务等内存场景中使用。12.2 HTTP API更灵活的集成方式是部署 Flask Celery 后端通过 HTTP 协议通信实现见 pdf2zh/backend.py所有接口均依赖 Redis 作为 Celery 的 broker 与结果后端pip install pdf2zh[backend] pdf2zh --flask pdf2zh --celery worker然后即可使用如下接口1. 提交翻译任务curl http://localhost:11008/v1/translate -F fileexample.pdf -F data{\lang_in\:\en\,\lang_out\:\zh\,\service\:\google\,\thread\:4} # 返回任务 ID {id:d9894125-2f4e-45ea-9d93-1a9068d2045a}2. 查询进度进行中curl http://localhost:11008/v1/translate/d9894125-2f4e-45ea-9d93-1a9068d2045a {info:{n:13,total:506},state:PROGRESS}3. 查询状态已完成curl http://localhost:11008/v1/translate/d9894125-2f4e-45ea-9d93-1a9068d2045a {state:SUCCESS}4. 下载单语文件curl http://localhost:11008/v1/translate/d9894125-2f4e-45ea-9d93-1a9068d2045a/mono --output example-mono.pdf5. 下载双语文件curl http://localhost:11008/v1/translate/d9894125-2f4e-45ea-9d93-1a9068d2045a/dual --output example-dual.pdf6. 中断任务并删除curl http://localhost:11008/v1/translate/d9894125-2f4e-45ea-9d93-1a9068d2045a -X DELETE说明GET /v1/translate/id在任务进行中返回{state:PROGRESS,info:{...}}完成后返回{state:SUCCESS}/mono与/dual只有在任务成功后才会返回 PDF 内容。Celery 的 broker/结果后端地址可通过环境变量CELERY_BROKER与CELERY_RESULT配置默认redis://127.0.0.1:6379/0。十三、GUI 界面在浏览器中启动的 GUIpdf2zh -i支持拖拽上传 PDF 并一键翻译GUI 支持的默认语言包括English、简体中文、繁体中文、French、German、Japanese、Korean、Russian、Spanish、Italian 等并可通过环境变量PDF2ZH_LANG_FROM/PDF2ZH_LANG_TO预设默认源语言与目标语言。更多细节参见 docs/README_GUI.md。十四、公共在线服务无需安装即可在线体验免费公共服务https://pdf2zh.com/无需注册HuggingFace 在线 Demo 与 ModelScope 在线 Demo计算资源有限请勿滥用。十五、底层原理补充为了帮助你判断什么时候该用哪个参数这里把源码中可确认的实现事实补充如下均为当前仓库可验证的内容版面检测翻译前每页会被 PyMuPDF 渲染为图像交由 DocLayout-YOLO ONNX 模型wybxc/DocLayout-YOLO-DocStructBench-onnx做版面检测figure、table、isolate_formula、formula_caption等区域被排除在翻译之外见 pdf2zh/high_level.pytranslate_patch()。可通过--onnx指定自定义模型用--backend选择 ONNX Runtime 执行后端auto/cpu/cuda/dml。文档解析基于 pdfminer.six 的PDFParser/PDFDocument/PDFPageInterpreterEx解析内容流翻译后的文本通过 PyMuPDF 的 xref/流机制回写最终用insert_filemove_page交错合并出双语版见translate_stream()。字体与重排根据目标语言自动选择远程字体中文/日文/韩文使用 Source Han Serif 系列其余语言使用 Go Noto 系列见download_remote_fonts()默认对输出做字体子集化以减小体积。多线程翻译TranslateConverter通过线程池并发调用翻译服务见 pdf2zh/converter.py。翻译缓存TranslationCache以服务名 语言对 模型 影响质量的参数为键缓存结果--ignore-cache可跳过见 pdf2zh/cache.py。实验性能力--mode precise走 v2 翻译内核依赖pdf2zh_next子模块--babeldoc使用实验性后端 BabelDOCREADME 还提到实验性 OCR 支持pip install pdf2zh[ocr]仅对纯图像页自动 OCR 后再翻译。结语PDFMathTranslatepdf2zh把科学文献翻译从丢掉排版的纯文本翻译推进到了保留公式、图表与版式的双语排版。通过本文介绍的四种安装方式、完整 CLI 参数、20 余种翻译服务接入、正则例外、自定义提示词与配置、以及 Python / HTTP 两种 API你可以把它落地为个人翻译工具、团队 Web 服务甚至公共翻译后端。后续更完整的参数解释可继续查阅 docs/ADVANCED.md 与 docs/APIS.mdGUI 细节见 docs/README_GUI.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），仅供参考 PDFMathTranslate 完整使用指南：pdf2zh 安装、CLI 高级选项、翻译服务与 API 实战
PDFMathTranslate 完整使用指南pdf2zh 安装、CLI 高级选项、翻译服务与 API 实战【免费下载链接】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本文基于仓库文档 docs/README_ja-JP.md 展开并结合源码如 pdf2zh/pdf2zh.py、pdf2zh/translator.py、pdf2zh/high_level.py、pdf2zh/backend.py进行深度扩充。全文以当前仓库实际内容为准。PDFMathTranslatePyPI 包名为pdf2zh是一款面向科学文献场景的 PDF 翻译工具其核心目标是在翻译全文的同时完整保留原文档的版式——包括数学公式、图表、目录与注释。本文将从安装入手系统讲解命令行CLI的全部高级选项、20 余种翻译服务的接入方式、局部翻译与正则例外规则、自定义提示词与配置文件以及 Python / HTTP 两种 API 的调用方式并辅以源码级原理说明帮助你把它部署为本地工具、GUI 服务或公共翻译后端。一、项目定位保留版式的科学 PDF 翻译在科研阅读场景中直接翻译 PDF 往往会破坏公式与排版导致翻译完看不懂、看版式又找不到原文。PDFMathTranslate 的设计目标正是解决这一痛点 保留数式公式、图表、目录与注释等元素 支持多种源语言 / 目标语言以及多样化的翻译服务Google、DeepL、Ollama、OpenAI、DeepSeek、MiniMax 等 提供命令行工具、交互式图形界面GUI与 Docker 三种使用形态另有便携版Windows可选。从源码结构看其核心处理链路大致为对应 pdf2zh/high_level.py 中的translate_stream→translate_patch布局解析使用 ONNX 格式的 DocLayout-YOLO 模型wybxc/DocLayout-YOLO-DocStructBench-onnx对每页渲染出的图像做版面检测识别正文、图表、公式等区域见 pdf2zh/high_level.py 中的model.predict(...)调用vcls [abandon, figure, table, isolate_formula, formula_caption]等类别会被排除在翻译区域之外文本解析基于 pdfminer.six 解析页面内容流PDFParser/PDFDocument/PDFPageInterpreterEx逐段翻译按线程池并发调用所选翻译服务版式重排用 PyMuPDF 将翻译文本按原位置写回生成-mono.pdf纯译文与-dual.pdf双语对照两个文件。项目相关的更完整说明可继续阅读 README.md英文主文档、docs/ADVANCED.md高级用法与 docs/APIS.mdAPI 细节。二、安装与四种使用方式项目提供 4 种使用方式命令行、便携版Windows、GUI与Docker。安装前请确认 Python 版本满足3.11 版本 3.12。2.1 方法一命令行pip 安装pip install pdf2zh然后在当前工作目录下直接翻译pdf2zh document.pdf命令执行后会在当前目录生成document-mono.pdf单语译文与document-dual.pdf双语对照两个文件。2.2 方法二便携版Windows免 Python 环境如果不想预先安装 Python 环境可以下载仓库 script/setup.bat双击运行即可完成环境准备与安装适合在不熟悉 Python 的机器上快速使用。2.3 方法三GUI浏览器交互界面安装包pip install pdf2zh以交互模式启动pdf2zh -i若浏览器未自动打开手动访问http://localhost:7860/将 PDF 文件拖入窗口点击Translate即可开始翻译。GUI 更多细节支持的语言列表、环境变量等参见 docs/README_GUI.md。2.4 方法四Docker 容器化部署docker pull byaidu/pdf2zh docker run -d -p 7860:7860 byaidu/pdf2zh然后浏览器打开http://localhost:7860/即可使用。2.5 模型下载问题的解决方案网络受限场景pdf2zh 启动时需要额外下载布局检测模型wybxc/DocLayout-YOLO-DocStructBench-onnx该模型在 ModelScope 上也有镜像。如果因网络问题无法下载可通过设置 HuggingFace 镜像端点环境变量解决# CMD set HF_ENDPOINThttps://hf-mirror.com# PowerShell $env:HF_ENDPOINT https://hf-mirror.com若该方案仍无法解决可参考仓库 Wiki 中的 FAQ 章节获取更多排查建议。三、命令行高级选项速查在命令行执行翻译时默认使用 Google 翻译服务并在当前工作目录生成example-mono.pdf与example-dual.pdf。下图直观展示了各参数在命令行中的位置与含义以下表格汇总了全部高级选项参数定义可在 pdf2zh/pdf2zh.py 的create_parser()中逐一核对选项功能示例files本地文件pdf2zh ~/local.pdflinks在线文件自动下载pdf2zh http://arxiv.org/paper.pdf-i进入 GUIpdf2zh -i-p部分文档翻译pdf2zh example.pdf -p 1-li源语言pdf2zh example.pdf -li en-lo目标语言pdf2zh example.pdf -lo zh-s翻译服务pdf2zh example.pdf -s deepl-t多线程数量pdf2zh example.pdf -t 1-o输出目录pdf2zh example.pdf -o output-f,-c翻译例外正则pdf2zh example.pdf -f (MS.*)-cp/--compatible兼容模式转为 PDF/A 提升兼容性pdf2zh example.pdf --compatible--skip-subset-fonts跳过字体子集化提高兼容性但增大文件pdf2zh example.pdf --skip-subset-fonts--ignore-cache忽略翻译缓存、强制重译pdf2zh example.pdf --ignore-cache--share生成 Gradio 公网分享链接pdf2zh -i --share--authorized添加 Web 认证与自定义认证页pdf2zh -i --authorized users.txt [auth.html]--prompt使用自定义大模型提示词pdf2zh --prompt [prompt.txt]--onnx使用自定义 DocLayout-YOLO ONNX 模型pdf2zh --onnx [onnx/model/path]--serverport自定义 WebUI 端口pdf2zh --serverport 7860--dir批量翻译目录下所有 PDF/Word 文件pdf2zh --dir /path/to/translate/--config指定配置文件pdf2zh --config /path/to/config/config.json--mode翻译模式fast默认v1或precisev2 实验性pdf2zh --mode precise example.pdf--babeldoc使用实验性后端 BabelDOCpdf2zh --babeldoc -s openai example.pdf--mcp以 MCP STDIO 模式启动pdf2zh --mcp--sse以 MCP SSE 模式启动pdf2zh --mcp --sse其中--dir的实现可在 pdf2zh/pdf2zh.py 的find_all_files_in_directory()中看到它会递归遍历目录收集所有.pdf、.doc、.docx文件后逐一翻译--compatible会调用 pdf2zh/high_level.py 中的convert_to_pdfa()通过 pikepdf 写入 PDF/A-2B 元数据与输出意图从而改善兼容性。四、全文翻译与部分翻译全文翻译默认行为pdf2zh example.pdf部分翻译使用-p指定页范围支持逗号分隔与连字符区间pdf2zh example.pdf -p 1-3,5该命令只翻译第 1、2、3、5 页。从 pdf2zh/pdf2zh.py 的parse_args()可以看到-p参数会被解析为 0 起始的页索引列表如1-3展开为[0,1,2]再传入翻译内核按页过滤。五、指定源语言与目标语言使用-lisource与-lotarget指定语言代码pdf2zh example.pdf -li en -lo ja语言代码可参考 Google 与 DeepL 官方支持的语言代码列表分别对应 Google Translate 与 DeepL API 的语言枚举。CLI 中语言参数的默认值分别为en源与zh目标定义于 pdf2zh/pdf2zh.py 的--lang-in/--lang-out参数。另外GUI 模式可通过环境变量预设语言PDF2ZH_LANG_FROM源语言默认 EnglishPDF2ZH_LANG_TO目标语言默认 Simplified Chinese。详见 docs/README_GUI.md。六、使用不同翻译服务6.1 服务与环境变量总表下表列出了各翻译服务所需的环境变量与默认值。使用对应服务前务必先设置好这些变量变量读取逻辑见 pdf2zh/translator.py 中BaseTranslator.set_envs()程序会优先使用操作系统环境变量并将其写回本地配置文件。TranslatorServiceEnvironment VariablesDefault ValuesNotesGoogle默认google无N/A免费无需密钥Bingbing无N/A免费无需密钥DeepLdeeplDEEPL_AUTH_KEY[Your Key]需 DeepL API KeyDeepLXdeeplxDEEPLX_ENDPOINThttps://api.deepl.com/translate自建 DeepL 代理OllamaollamaOLLAMA_HOST,OLLAMA_MODELhttp://127.0.0.1:11434,gemma2本地大模型OpenAIopenaiOPENAI_BASE_URL,OPENAI_API_KEY,OPENAI_MODEL,OPENAI_STOP_TOKENS,OPENAI_MAX_TOKENShttps://api.openai.com/v1,[Your Key],gpt-4o-mini, 空格,-1兼容 OpenAI API 的服务均可参考此项AzureOpenAIazure-openaiAZURE_OPENAI_BASE_URL,AZURE_OPENAI_API_KEY,AZURE_OPENAI_MODEL[Your Endpoint],[Your Key],gpt-4o-miniAzure 上的 OpenAI 服务Zhipu智谱zhipuZHIPU_API_KEY,ZHIPU_MODEL[Your Key],glm-4-flash智谱 GLM 系列ModelScopemodelscopeMODELSCOPE_API_KEY,MODELSCOPE_MODEL[Your Key],Qwen/Qwen2.5-Coder-32B-Instruct魔搭社区模型服务SiliconsiliconSILICON_API_KEY,SILICON_MODEL[Your Key],Qwen/Qwen2.5-7B-InstructSiliconCloud 平台GeminigeminiGEMINI_API_KEY,GEMINI_MODEL[Your Key],gemini-1.5-flashGoogle Gemini APIAzureazureAZURE_ENDPOINT,AZURE_API_KEYhttps://api.translator.azure.cn,[Your Key]Azure 文本翻译服务Tencent腾讯tencentTENCENTCLOUD_SECRET_ID,TENCENTCLOUD_SECRET_KEY[Your ID],[Your Key]腾讯云机器翻译 TMTDifydifyDIFY_API_URL,DIFY_API_KEY[Your DIFY URL],[Your Key]需在 Dify 工作流输入中定义lang_out、lang_in、text三个变量AnythingLLManythingllmAnythingLLM_URL,AnythingLLM_APIKEY[Your AnythingLLM URL],[Your Key]AnythingLLM 后端Argos Translateargos无N/A开源离线翻译引擎GrokgrokGROK_API_KEY,GROK_MODEL[Your GROK_API_KEY],grok-2-1212xAI 的 GrokDeepSeekdeepseekDEEPSEEK_API_KEY,DEEPSEEK_MODEL[Your DEEPSEEK_API_KEY],deepseek-chatDeepSeek 大模型MiniMaxminimaxMINIMAX_API_KEY,MINIMAX_MODEL[Your MINIMAX_API_KEY],MiniMax-M2.7MiniMax 大模型OpenAI-LikedopenailikedOPENAILIKED_BASE_URL,OPENAILIKED_API_KEY,OPENAILIKED_MODEL可选OPENAILIKED_STOP_TOKENS,OPENAILIKED_MAX_TOKENSurl,[Your Key],model name任意 OpenAI 兼容接口补充说明上表中未列出、但兼容 OpenAI API 的大语言模型服务可完全照搬 OpenAI 一行的环境变量设置方式接入从源码看OpenAI 系列还支持OPENAI_STREAM默认true以流式方式取回翻译结果并可设置temperature: 0以避免随机采样打断公式占位符见 pdf2zh/translator.py 中OpenAITranslator的实现含速率限制自动重试与think过滤逻辑仓库 docs/ADVANCED.md 中还收录了 302.AI、Xinference、Groq、Qwen-MT 等更多服务可一并查阅。6.2 指定服务与模型使用-s service或-s service:model指定服务与模型pdf2zh example.pdf -s openai:gpt-4o-mini也可以用环境变量指定模型# CMD set OPENAI_MODELgpt-4o-mini pdf2zh example.pdf -s openai# PowerShell $env:OPENAI_MODEL gpt-4o-mini pdf2zh example.pdf -s openai七、翻译例外用正则保留公式字体与字符在科学文档中公式字体与特殊字符不应被翻译。使用-f字体名正则与-c字符正则指定需要保留的内容pdf2zh example.pdf -f (CM[^RT].*|MS.*|.*Ital) -c (\(|\||\)|\||\d|[\u0080-\ufaff])默认情况下pdf2zh 会保留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)这两个正则分别对应 CLI 的--vfont与--vchar参数见 pdf2zh/pdf2zh.py它们最终会传递给TranslateConverter在解析 PDF 内容流时按字体与字符判断是否跳过翻译。八、指定线程数使用-t指定翻译时的并发线程数默认值为 4pdf2zh example.pdf -t 1多线程翻译的实现位于 pdf2zh/converter.py它基于concurrent.futures线程池并发提交翻译请求以显著缩短整篇文档的翻译耗时在线程不足或服务端限流时可调小该值。九、自定义提示词--prompt对于 LLM 类翻译服务可以用--prompt指定自定义提示词文件pdf2zh example.pdf -pr prompt.txt说明-pr为文档中出现的写法实际参数名为--prompt即pdf2zh example.pdf --prompt prompt.txt。prompt.txt示例JSON 消息数组格式对应BaseTranslator.prompt()中按 role/content 构造消息的逻辑[ { role: system, content: You are a professional,authentic machine translation engine., }, { role: user, content: Translate the following markdown source text to ${lang_out}. Keep the formula notation {{v*}} unchanged. Output translation directly without any additional text.\nSource Text: ${text}\nTranslated Text:, }, ]自定义提示词文件中可使用以下 3 个变量由string.Template.safe_substitute注入见 pdf2zh/translator.py变量内容lang_in源语言lang_out目标语言text待翻译文本注意--prompt主要面向支持自定义提示词的 LLM 服务源码中以CustomPrompt True标记如 OpenAI、AzureOpenAI 等。若不提供自定义提示词BaseTranslator.prompt()会使用内置默认提示词要求模型只输出译文、保持公式占位符{v*}不变。十、自定义配置文件--config除环境变量外还可用--config指定 JSON 配置文件pdf2zh example.pdf --config config.jsonpdf2zh -i --config 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 } } ] }配置加载优先级默认配置文件位于~/.config/PDFMathTranslate/config.json。程序先读取该文件内容再读取环境变量当环境变量存在时以环境变量为准并同步更新配置文件对应 pdf2zh/config.py 中ConfigManager的实现单例模式 可重入锁保证线程安全get()在命中环境变量或默认值时自动写回配置文件。⚠️ 使用 OpenAI 兼容 API 或自定义代理如 Grok、OpenAI-liked 等时请确保BASE_URL以/v1结尾例如https://api.openai.com/v1或http://your-proxy:8000/v1否则会返回 404。十一、其他实用进阶能力11.1 字体子集化与跳过默认启用字体子集化font subsetting以减小输出文件体积。遇到兼容性问题时可跳过子集化代价是输出文件变大pdf2zh example.pdf --skip-subset-fonts11.2 翻译缓存pdf2zh 会缓存已翻译文本以加快重复内容处理并避免产生不必要的 API 调用缓存实现见 pdf2zh/cache.py缓存键包含服务名、语言对与模型名并额外记录 temperature、stop、max_tokens、prompt 等影响翻译质量的参数。需要强制重译时pdf2zh example.pdf --ignore-cache11.3 GUI 认证与公网分享--share为 GUI 生成 Gradio 公网分享链接--authorized为 Web UI 添加用户名/密码认证与自定义登录页。users.txt每行一个用户格式为用户名,密码admin,123456 user1,password1自定义auth.html将被用作登录页。11.4 MCP 集成pdf2zh 可以作为 MCP 服务器运行pdf2zh --mcp或--mcp --sse切换 SSE 模式从而让 Claude Desktop 等 MCP 客户端直接调用翻译能力。配合 filesystem MCP 服务器即可实现找到某 PDF 并翻译成中文这类自然语言指令详见 docs/ADVANCED.md 的 MCP 一节。十二、API在程序与服务器中集成12.1 Python APIpdf2zh 作为 Python 模块对外暴露translate与translate_stream两个函数定义见 pdf2zh/high_level.pyfrom pdf2zh import translate, translate_stream params {lang_in: en, lang_out: zh, service: google, thread: 4} file_mono, file_dual translate(files[example.pdf], **params)[0] with open(example.pdf, rb) as f: stream_mono, stream_dual translate_stream(streamf.read(), **params)translate(files[...], ...)传入本地文件路径也支持http(s)://在线文件会自动下载到临时目录后翻译见check_files()与在线下载分支返回(单语文件路径, 双语文件路径)元组列表translate_stream(streambytes, ...)直接传入 PDF 二进制流返回两个 PDF 字节流mono 与 dual适合在 Web 服务等内存场景中使用。12.2 HTTP API更灵活的集成方式是部署 Flask Celery 后端通过 HTTP 协议通信实现见 pdf2zh/backend.py所有接口均依赖 Redis 作为 Celery 的 broker 与结果后端pip install pdf2zh[backend] pdf2zh --flask pdf2zh --celery worker然后即可使用如下接口1. 提交翻译任务curl http://localhost:11008/v1/translate -F fileexample.pdf -F data{\lang_in\:\en\,\lang_out\:\zh\,\service\:\google\,\thread\:4} # 返回任务 ID {id:d9894125-2f4e-45ea-9d93-1a9068d2045a}2. 查询进度进行中curl http://localhost:11008/v1/translate/d9894125-2f4e-45ea-9d93-1a9068d2045a {info:{n:13,total:506},state:PROGRESS}3. 查询状态已完成curl http://localhost:11008/v1/translate/d9894125-2f4e-45ea-9d93-1a9068d2045a {state:SUCCESS}4. 下载单语文件curl http://localhost:11008/v1/translate/d9894125-2f4e-45ea-9d93-1a9068d2045a/mono --output example-mono.pdf5. 下载双语文件curl http://localhost:11008/v1/translate/d9894125-2f4e-45ea-9d93-1a9068d2045a/dual --output example-dual.pdf6. 中断任务并删除curl http://localhost:11008/v1/translate/d9894125-2f4e-45ea-9d93-1a9068d2045a -X DELETE说明GET /v1/translate/id在任务进行中返回{state:PROGRESS,info:{...}}完成后返回{state:SUCCESS}/mono与/dual只有在任务成功后才会返回 PDF 内容。Celery 的 broker/结果后端地址可通过环境变量CELERY_BROKER与CELERY_RESULT配置默认redis://127.0.0.1:6379/0。十三、GUI 界面在浏览器中启动的 GUIpdf2zh -i支持拖拽上传 PDF 并一键翻译GUI 支持的默认语言包括English、简体中文、繁体中文、French、German、Japanese、Korean、Russian、Spanish、Italian 等并可通过环境变量PDF2ZH_LANG_FROM/PDF2ZH_LANG_TO预设默认源语言与目标语言。更多细节参见 docs/README_GUI.md。十四、公共在线服务无需安装即可在线体验免费公共服务https://pdf2zh.com/无需注册HuggingFace 在线 Demo 与 ModelScope 在线 Demo计算资源有限请勿滥用。十五、底层原理补充为了帮助你判断什么时候该用哪个参数这里把源码中可确认的实现事实补充如下均为当前仓库可验证的内容版面检测翻译前每页会被 PyMuPDF 渲染为图像交由 DocLayout-YOLO ONNX 模型wybxc/DocLayout-YOLO-DocStructBench-onnx做版面检测figure、table、isolate_formula、formula_caption等区域被排除在翻译之外见 pdf2zh/high_level.pytranslate_patch()。可通过--onnx指定自定义模型用--backend选择 ONNX Runtime 执行后端auto/cpu/cuda/dml。文档解析基于 pdfminer.six 的PDFParser/PDFDocument/PDFPageInterpreterEx解析内容流翻译后的文本通过 PyMuPDF 的 xref/流机制回写最终用insert_filemove_page交错合并出双语版见translate_stream()。字体与重排根据目标语言自动选择远程字体中文/日文/韩文使用 Source Han Serif 系列其余语言使用 Go Noto 系列见download_remote_fonts()默认对输出做字体子集化以减小体积。多线程翻译TranslateConverter通过线程池并发调用翻译服务见 pdf2zh/converter.py。翻译缓存TranslationCache以服务名 语言对 模型 影响质量的参数为键缓存结果--ignore-cache可跳过见 pdf2zh/cache.py。实验性能力--mode precise走 v2 翻译内核依赖pdf2zh_next子模块--babeldoc使用实验性后端 BabelDOCREADME 还提到实验性 OCR 支持pip install pdf2zh[ocr]仅对纯图像页自动 OCR 后再翻译。结语PDFMathTranslatepdf2zh把科学文献翻译从丢掉排版的纯文本翻译推进到了保留公式、图表与版式的双语排版。通过本文介绍的四种安装方式、完整 CLI 参数、20 余种翻译服务接入、正则例外、自定义提示词与配置、以及 Python / HTTP 两种 API你可以把它落地为个人翻译工具、团队 Web 服务甚至公共翻译后端。后续更完整的参数解释可继续查阅 docs/ADVANCED.md 与 docs/APIS.mdGUI 细节见 docs/README_GUI.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），仅供参考