如何从零部署 PDFMathTranslate：2 条命令跑通 PDF 翻译网页服务并开放公网-平芜编程栈

如何从零部署 PDFMathTranslate：2 条命令跑通 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 是一款基于 AI 的 PDF 翻译工具，能把学术论文全文翻译成中文的同时，完整保留公式、图表、目录和批注的原有排版。跟着这篇指南操作完，你会在自己的机器上跑起一个浏览器里直接能用的 PDF 翻译网页服务，既能个人使用，也能开放给局域网甚至公网共享。它适合想快速部署一个排版不跑样的 PDF 翻译服务、又不想折腾复杂环境的开发者；如果你只是要命令行批量处理、完全不需要网页界面，直接看命令行用法即可。

环境准备：2 条命令启动 PDF 翻译网页服务

选型一句话：个人试水、开发调试用 Python 安装，报错好定位；服务器上长期跑、要重启即恢复，直接用 Docker 容器。

Python 方式要求环境是 Python 3.11–3.12。先装命令行工具，装完看到Successfully installed pdf2zh即成功：

pip install pdf2zh # 安装 pdf2zh 命令行工具

接着启动网页版界面，命令行出现Running on local URL: http://0.0.0.0:7860之类的提示就说明启动成功：

pdf2zh -i # 启动网页版界面

浏览器打开http://localhost:7860，页面出现文件上传框，就说明服务已经跑起来了。

服务器长期跑的话，Docker 就两条命令，容器起来后浏览器打开同一地址即可：

docker pull byaidu/pdf2zh docker run -d -p 7860:7860 byaidu/pdf2zh # 后台运行并映射 7860 端口

✅ 镜像里默认执行pdf2zh -i，所以容器一启动就是网页服务。

由内到外：让 PDF 翻译服务被更多人访问

本机自测：先完成一次完整 PDF 翻译并核对公式排版

这一步要确认工具链本身没问题——排版最容易坏的地方就是公式区和表格区。在网页里上传一篇英文论文 PDF，翻译服务默认用 Google，也可以选 DeepL、Ollama 等；如果习惯命令行，装好后直接pdf2zh 文档.pdf也行，译文会生成在当前目录。

翻译完成后你会得到两个文件：纯译文版文档名-mono.pdf和双语对照版文档名-dual.pdf。打开译文，重点看公式和表格——公式应保持原样、表格没有错位、目录还能正常跳转，这三点都过关就说明没坏。

同一局域网：把地址里的 localhost 换成局域网 IP

这一步要达成：同一网络下的其他电脑、手机也能打开这个翻译服务。其实服务默认就绑定在0.0.0.0，本来就允许外部访问，你只需要把访问地址里的localhost换成这台机器的局域网 IP：

http://192.168.1.10:7860 # 换成你机器的实际局域网 IP

如果 7860 端口被占用导致起不来，就换个端口再启动，后面所有访问地址也要跟着改端口：

pdf2zh -i --serverport 8080 # 改用 8080 端口启动

用另一台连同一 Wi-Fi 的设备打开上面的 IP 地址，能打开页面就说明局域网访问通了。

公网访问：临时隧道或反向代理二选一

这一步要把服务开放到外网。两条路，按需求选。

临时演示：启动时加--share，会自动生成一个临时公网链接，发给别人就能用。

pdf2zh -i --share # 生成临时公网隧道链接

它走的是第三方隧道，适合一次性演示，不适合长期挂着。验证：在一台和你不同网段、或断开 Wi-Fi 的设备上打开该临时链接，能打开即成功。

长期服务（推荐）：用 Nginx 这类反向代理把域名指到本机 7860 端口，再配上 SSL 证书。这样链接稳定、能控制访问来源，配合下一节的登录授权，才是安全的团队共享方案。验证：用外网设备通过你的域名访问，能打开页面即成功。

部署方式怎么选

方式	优点	局限	适合谁
Python 安装	一条命令装好、方便调试定位	需要自备 Python 环境	开发测试、个人使用
Docker 容器	环境自带、重启即恢复	需要装 Docker	服务器长期运行
Windows 绿色版	不用装环境，解压双击即用	仅限 Windows 平台	个人电脑、临时使用

高频问题速查：PDF 翻译部署踩坑怎么办

本机浏览器能打开，局域网别的设备却打不开？

通常是这台机器的系统防火墙或云服务器安全组没放行 7860 端口，或是地址里还写着localhost。把防火墙/安全组放行 7860 端口、确认访问地址用的是局域网 IP 而不是localhost，多网卡机器再确认 IP 取的是同一网络下那个即可。

第一次运行长时间卡住，日志指向模型下载？

程序首次运行要下载版面检测模型wybxc/DocLayout-YOLO-DocStructBench-onnx，部分地区访问源站很慢会一直卡住。启动前设置镜像环境变量即可，下载成功后模型会被缓存，之后启动不再卡这步：

export HF_ENDPOINT=https://hf-mirror.com # 指定模型镜像源

译文里公式或特殊字符丢了、乱了？

最常见的原因是字体子集化（font subsetting）导致某些字符渲染异常。优先加--skip-subset-fonts跳过字体子集化；如果改过保留规则-f/-c，按 docs/ADVANCED.md 的 exceptions 一节核对正则，必要时换一篇结构简单的 PDF 复测，先排除源文件本身的问题。

换了翻译服务没生效，或接口报 404？

指定了-s的服务如果环境变量没 export、变量名拼错，就会静默回退或报错。对照 docs/ADVANCED.md 的服务列表逐项检查环境变量；用 OpenAI 兼容接口时，Base URL 必须以/v1结尾，漏掉会直接报 404。把配置写进 config.json 再启动，能避免"临时设的环境变量忘了带"这类问题。

服务上了公网谁都能用，怎么加登录门槛？

⚠️ 网页版默认没有登录门槛，一旦上公网，任何知道地址的人都能用，翻译额度和机器资源全被消耗。准备一个 users.txt（每行用户名,密码），启动时加上--authorized users.txt，访问页面就会先弹登录框；还能把第二个参数换成自定义的 auth.html 改登录页样式。用 users.txt 里的账号能登录、错误密码被拒绝，即验证通过。