三行命令快速启动 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/PDFMathTranslate

组会前夜，你想把刚下载的一篇英文论文转成中文分享给同事，却发现普通机器翻译要么把公式打碎，要么排版全乱。PDFMathTranslate 就是为学术论文 PDF 翻译设计的工具：公式、图表、目录、注释原样保留，只翻译文字，并且提供命令行、网页界面、MCP 服务器多种用法，可接 Google、DeepL、Ollama、OpenAI 等翻译服务。

本文是照做即通的手把手教程，按顺序走完，你可以完成这几个可验证的动作：

在浏览器打开http://localhost:7860，把第一篇 PDF 翻译成保留排版的中文版；
让同一局域网内的同事打开服务，各自翻译自己的文件；
用--authorized加用户鉴权、用配置文件隐藏服务器 API Key，把服务放到服务器上长期跑；
处理首次运行模型下载失败、Windows 版打不开等高频问题。

1. 第一步：本地启动 PDFMathTranslate 网页界面

这一章的目标很具体：浏览器打开 7860 端口，翻译成功一份文档。三条路线，先对号入座再动手。

路线	适用场景	特点
Python（pip 安装）	本机已有 Python 环境，开发调试	配置最灵活，参数随手加
Windows 绿色版	个人电脑，不想装任何环境	解压即用，无需 Python
Docker	服务器长期运行、多人共享	一个镜像带齐所有依赖

⚠️ Python 路线要求3.11 ≤ 版本 ≤ 3.12（见 Dockerfile 同款的 3.12 基础镜像）。系统只有 3.13 或更低版本时，建议直接走 Docker。

1.1 Python：两条命令装好并启动

先在当前目录安装，再启动网页界面：

pip install pdf2zh # 安装 pdf2zh pdf2zh -i # 启动 Web 界面（GUI）

浏览器会打开http://localhost:7860/，没自动打开就手动访问；把 PDF 拖进窗口、点 Translate 即可开始。如果端口被占用，换端口启动：

pdf2zh -i --serverport 8080 # 把端口改成 8080

不想要界面的话，命令行直接翻，产物生成在当前工作目录：

pdf2zh paper.pdf # 翻译 paper.pdf

运行结束后你会拿到两个文件：paper-mono.pdf（纯中文版）和paper-dual.pdf（双语对照版）。

-i：进入交互界面，不加则走命令行模式
--serverport：指定 Web 界面端口，默认 7860
-o：指定输出目录，例如pdf2zh paper.pdf -o out

1.2 Windows 绿色版：解压即用

从项目的 release 页面下载pdf2zh-version-win64.zip，解压后双击pdf2zh.exe运行。

⚠️ 若双击后无反应，先安装 VC++ 运行库vc_redist.x64.exe再重试，这是仓库文档明确提到的常见原因。

1.3 Docker：拉取镜像并运行容器

docker pull byaidu/pdf2zh # 拉取官方镜像 docker run -d -p 7860:7860 byaidu/pdf2zh # 后台运行并映射 7860 端口

-d：后台运行
-p 7860:7860：容器端口映射到宿主机，浏览器访问http://localhost:7860/

仓库根目录还有一个 docker-compose.yml：一次性构建自包含镜像（含系统依赖安装和babeldoc --warmup预热），command已写死为pdf2zh -i，适合想要可控构建流程的场景。

小结：能在 7860 端口翻出一份文档，本章就达标了。下一步，把服务开放给局域网里的人。

2. 第二步：配置局域网与临时公网访问

2.1 局域网访问：两条路径

Docker 路线：-p 7860:7860默认绑定宿主机所有网卡，同一局域网的设备直接打开http://<服务器IP>:7860即可，不需要额外参数。
Python 路线：如果办公网内直连不通（通常是防火墙拦了 7860 端口），最快的办法是生成临时公网链接：

pdf2zh -i --share # 启动并生成 Gradio Share 临时公网链接

拿到链接直接发给同事，用完即弃，适合临时协作。

2.2 用户鉴权：每行一个用户

服务开放后，建议立刻加上账号密码，防止别人拿着你的 API Key 白嫖：

pdf2zh -i --authorized users.txt

users.txt格式：每行一个用户，用户名和密码用英文逗号分隔：

admin,123456 user1,password1

第二个参数可选，传一个auth.html（如--authorized users.txt auth.html）就能定制登录页样式，详见 docs/ADVANCED.md 的 Authorization 一节。

⚠️ 一旦端口对外，--authorized是必选项，不要依赖"端口没人知道"这种安全。

小结：验证标准是——同事设备能打开页面、且必须先登录才能翻译。

3. 第三步：长期稳定运行——固定配置与安全保障

这一章把"能跑"升级成"能长期跑"，核心是固定翻译服务、锁住密钥、微调质量。

3.1 固定翻译服务

默认走 Google 免费服务，长期运行建议显式指定：

export DEEPL_AUTH_KEY=你的Key # 设置 DeepL 密钥 pdf2zh -i -s deepl # 用 DeepL 启动

本地离线可用 Ollama，默认连接http://127.0.0.1:11434、模型gemma2，加-s ollama即可。常用服务与所需环境变量对照：

服务	开关	需要的环境变量
google（默认）	无需设置	无
deepl	`-s deepl`	`DEEPL_AUTH_KEY`
openai	`-s openai`	`OPENAI_BASE_URL`、`OPENAI_API_KEY`、`OPENAI_MODEL`
ollama（本地）	`-s ollama`	`OLLAMA_HOST`、`OLLAMA_MODEL`（可选）

完整服务列表（20+ 家）及默认值见 docs/ADVANCED.md 的 Services 表格。

3.2 配置文件锁住公开服务的安全面

用--config config.json指定配置，默认位置是~/.config/PDFMathTranslate/config.json。面向公网时，仓库文档专门给出两个公开服务开关：

ENABLED_SERVICES：只暴露白名单里的翻译服务，其余选项在页面上不可见
HIDDEN_GRADIO_DETAILS：设为true，隐藏页面上的真实 API Key，防止使用方直接看到服务端密钥

⚠️ 用 OpenAI 兼容接口或自定义代理时，BASE_URL必须以/v1结尾，否则报 404——这是仓库文档里用加粗标注的高频错误。

3.3 微调翻译质量

三个参数按需组合：

--prompt prompt.txt：自定义提示词，文件内可用${lang_in}、${lang_out}、${text}三个变量，适合约束"保留公式与术语"这类风格
-t：翻译线程数，默认 4，机器强可适当调大
--mode precise：切换到实验性 v2 翻译内核（默认fast为 v1），需要 pdf2zh_next 子模块，适合尝鲜

小结：重启服务后确认三件事——用户必须登录、页面上看不到密钥、-s指定的服务生效，长期运行配置就算落地。

4. 踩坑清单：四个高频问题的处理方式

4.1 首次启动模型下载失败或很慢？

首次运行会下载版面检测模型wybxc/DocLayout-YOLO-DocStructBench-onnx，网络不通 Hugging Face 就会卡住或报错
启动前设置镜像变量：cmd 下执行set HF_ENDPOINT=https://hf-mirror.com，PowerShell 下执行$env:HF_ENDPOINT = https://hf-mirror.com
设置后重新运行启动命令，一般即可成功

4.2 Windows 绿色版双击没反应？

安装 VC++ 运行库vc_redist.x64.exe后重试（仓库文档明确提示）
仍无反应时，先跑一遍pdf2zh --version确认 Python 组件是否完整

4.3 中文版个别版面错位、缺字？

加--skip-subset-fonts跳过字体子集化，兼容性更好，代价是输出文件变大：pdf2zh paper.pdf --skip-subset-fonts
怀疑源文件本身兼容性差时，加-cp（--compatible）先转成 PDF/A 再翻译

4.4 同一篇文档反复翻译，会一直消耗额度吗？

默认开启翻译缓存，相同文本再次翻译不会再调 API
确实需要强制重翻（比如换了服务想对比效果）时，加--ignore-cache

4.5 拉不到 Docker Hub 的镜像？

改用仓库 README 提供的 Container Registry 镜像：

docker pull ghcr.io/byaidu/pdfmathtranslate # 拉取 ghcr 镜像 docker run -d -p 7860:7860 ghcr.io/byaidu/pdfmathtranslate # 同样映射 7860

到这里，"本地能翻 → 局域网能共享 → 长期安全运行 → 常见报错有解法"这条线就闭环了。还想继续深入的话，建议按这个顺序读：中文文档（总览）、docs/ADVANCED.md（全部高级参数）、docs/README_GUI.md（界面与语言支持列表）、docs/APIS.md（把翻译能力用 HTTP/Python API 接进自己的工作流）。

创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考