如何从零搭建PDF翻译网页服务：PDFMathTranslate部署与公网访问配置指南

如何从零搭建PDF翻译网页服务：PDFMathTranslate部署与公网访问配置指南

【免费下载链接】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 翻译服务，自己用、团队内网共享都行。

三步命令，先把网页服务跑起来

先说结论：开发测试、个人使用推荐 Python 安装方式，一条命令装好、报错好定位；如果你是要在服务器上长期跑，直接跳到 Dockerfile 部分用容器部署。

Python 方式需要 Python 3.11–3.12 环境，然后执行：

pip install pdf2zh # 安装 pdf2zh 命令行工具 pdf2zh -i # 启动网页版界面

启动后等命令行出现 Running on local URL 之类的提示，浏览器打开http://localhost:7860就是翻译界面了。

验证标准：浏览器能打开页面、能看到文件上传框，说明服务已经跑起来了。页面里可以选翻译服务、设置语言，上传 PDF 后点击开始即可。

主流程：从本机可用到局域网、公网访问

1. 先完成一次完整翻译，确认效果

目标：产出一份排版完好的译文，确认工具链没问题。

操作：网页里上传一篇英文论文 PDF，翻译服务默认用 Google，也可以选 DeepL、Ollama 等。如果习惯命令行，装好后直接pdf2zh 文档.pdf也行，译文会生成在当前目录。

验证：翻译完成后你会得到两个文件——纯译文版和双语对照版。打开译文 PDF，重点看公式区和表格区，公式应该保持原样。

2. 开放局域网访问

目标：同一网络下的其他电脑、手机都能打开这个翻译服务。

操作：其实什么都不用改——服务默认就绑定在0.0.0.0，也就是说它本来就允许外部访问。你只需要把访问地址里的localhost换成这台机器的局域网 IP：

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

如果 7860 端口被占了，用pdf2zh -i --serverport 8080换个端口再启动，后面的地址也要跟着改端口。

验证：手机连同一 Wi-Fi，或另一台电脑，用上面的 IP 地址访问，能打开页面就算成功。

3. 公网访问怎么配

两条路，按需求选：

• 临时演示：启动时加--share（pdf2zh -i --share），会自动生成一个临时公网链接，发给别人就能用。为什么这么设计——它走的是第三方隧道，适合一次性演示，不适合长期挂着。
• 长期服务（推荐）：用 Nginx 之类的反向代理把域名指到本机 7860 端口，加上 SSL 证书。这样链接稳定、可控制访问来源，而且配合下面要讲的授权功能，才是安全的团队共享方案。

验证：在另一台不与你同网段、或断开 Wi-Fi 的设备上访问，能打开页面即成功。

部署方式怎么选

Docker 方式就两条命令：

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

镜像里已经默认执行pdf2zh -i，所以容器起来就是网页服务。如果启动时想追加参数（比如授权文件），把参数写在镜像名后面追加即可。

关键点详解

端口冲突与换端口

现象：启动时报端口被占用，或者换了启动方式后页面打不开。原因：7860 端口已被其他程序占用，或地址里还写着旧端口。解决：--serverport指定新端口；Docker 侧则把-p 8080:7860这样映射——左边是你访问的端口，右边是容器内固定端口。两边端口要一致地记在心里，后面配反向代理时代理到的也是这个端口。

公网开放前，先配授权

现象：服务一旦上了公网，任何知道地址的人都能用，翻译额度、机器资源全被消耗。原因：网页版默认没有登录门槛。解决：准备一个users.txt，每行一个用户，格式是用户名,密码：

admin,123456 user1,password1

启动时加上--authorized users.txt，访问页面就会先弹登录框。还可以把第二个参数换成自定义的auth.html，改登录页样式。具体说明见 docs/ADVANCED.md 的 Authorization 一节。

验证：用 users.txt 里的账号能登录、用错误密码会被拒绝。

翻译服务与性能怎么调

现象：默认服务不稳定、翻译速度慢，或想用自己的模型。原因：默认翻译服务是 Google；线程数默认较低；不同服务依赖各自的环境变量。解决：

• 换服务：-s deepl、-s ollama等，各服务需要配的环境变量（如DEEPL_AUTH_KEY）都在 docs/ADVANCED.md 的服务列表里有对照表；
• 加线程：-t 4提高并发，一般设成 CPU 核心数的一半起步；
• 集中管理：用--config config.json指定配置文件，默认存在~/.config/PDFMathTranslate/config.json，环境变量优先于文件，改一处就能固定下来。

首次启动卡在模型下载

现象：第一次运行长时间卡住或报错，日志里指向模型下载。原因：程序需要下载版面检测模型wybxc/DocLayout-YOLO-DocStructBench-onnx，部分地区访问源站慢。解决：启动前设置镜像环境变量：

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

下载成功后模型会被缓存，之后的启动就不会再卡这一步。

排坑指南

本机能打开，局域网却打不开？

• 先看这台机器的系统防火墙/安全组是否放行了 7860 端口——云服务器最常见的是云控制台的"安全组"没加规则；
• 确认访问地址用的是局域网 IP 而不是localhost；
• 如果机器有多网卡，确认 IP 取的是同一网络下的那个。

上传大文件失败或没反应？

• 网页版基于 Gradio，上传大小默认限制在 5MB，超限会直接失败；
• 大文件建议改走命令行pdf2zh 文件.pdf，它不走网页上传通道；
• 一批文件可以用pdf2zh --dir 目录批量翻译。

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

• 优先加--skip-subset-fonts跳过字体子集化，这是字体相关渲染问题的常见开关；
• 检查是否改过保留规则-f/-c，默认会保留数学类字体，改动后需要按 docs/ADVANCED.md 的 exceptions 一节核对正则；
• 换一篇结构简单的 PDF 复测，先排除是源文件本身的问题。

换了翻译服务没生效？

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

进阶入口

网页服务搭好之后，下面三份文档可以直接接着看：

• docs/ADVANCED.md：全部翻译服务列表、自定义提示词（--prompt）、配置文件详解；
• docs/README_GUI.md：网页界面的完整功能说明；
• docs/APIS.md：Python API 与 HTTP 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