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（保留公式与版式的 PDF 论文翻译工具）在本机跑起来，并配置成可供团队访问的网页服务，个人从零到能用大约 10 分钟，配置公网访问再加 20 分钟左右。
30 秒自测，先回答三个问题再往下读：
- 你的机器是什么系统？（Windows / 有 Python 的电脑 / 有 Docker 的服务器）
- 只自己用，还是要给同事用？
- 试一两次就停，还是打算长期挂着？
答案对号入座：自己试 → 去对应路线小节；给别人用 → 先跑起来，再看“局域网分享与公网访问”一节。
一、如何选部署方式：先看对比表
选路线前先看这张表，前提是每种方式对环境的不同要求：
| 方式 | 适合谁 | 最省心的场景 | 常见坑 |
|---|---|---|---|
| Python 安装 | 3.11–3.12 环境，想随时改参数 | 个人电脑试一两篇 | 装依赖和下载模型都要网络顺畅 |
| Docker 容器 | 服务器或长期服务 | 团队共用一个地址 | 7860 端口可能被占用，拉镜像偶尔慢 |
| Windows 绿色版 | 不想装任何环境的 Windows 用户 | 解压双击就走 | 缺 VC++ 运行库时 exe 打不开 |
三种方式最终得到的是同一个东西：一个跑在 7860 端口的网页翻译界面，所以后面的“验证”和“调优”内容对谁都适用。
二、Python 环境：安装后一条命令起网页
前提：Python 3.11 或 3.12。这条路适合要改翻译参数、排查问题的场景。
安装并直接启动网页界面，一条命令搞定：
pip install uv uv tool install --python 3.12 pdf2zh pdf2zh -i✅ 验证：浏览器打开http://localhost:7860/，看到上传框和参数面板即算成功，把 PDF 拖进去点 Translate，产物（单语版example-mono.pdf、双语版example-dual.pdf）生成在当前目录。
⚠️ 出错时：安装报依赖错误，九成是 Python 版本不在 3.11–3.12；首次翻译卡住或报错，是在下载排版检测模型，网络不佳时设置HF_ENDPOINT=https://hf-mirror.com再试，详见 docs/ADVANCED.md。
三、Docker 容器：拉镜像、映射 7860 端口
前提：装好 Docker。镜像自带全部依赖，不用碰 Python，适合服务器长期运行。
docker pull byaidu/pdf2zh docker run -d -p 7860:7860 byaidu/pdf2zh✅ 验证：同样打开http://localhost:7860/。
⚠️ 出错时：curl localhost:7860无响应，先看docker logs里容器有没有在拉模型；7860:7860提示端口被占，就改成-p 8080:7860，改用 8080 访问。镜像构建逻辑见 Dockerfile，想配合其他本地模型跑可以研究 docker-compose.yml。
四、Windows 绿色版：解压双击就能跑
前提：Windows 10/11。从仓库 Release 页下载pdf2zh-version-win64.zip，解压后双击pdf2zh.exe，会自动打开浏览器进入本地 7860 端口的界面，✅ 验证标准与其他路线相同。
⚠️ 最大的坑：双击没反应或闪退，通常是缺 VC++ 运行库（vc_redist.x64），装上再试。首次翻译同样要下载排版模型，慢就设置HF_ENDPOINT=https://hf-mirror.com。
五、局域网分享与公网访问怎么配置
临时分享：只加一个--share参数，启动时会多打印一条 Gradio 公网链接，直接发给同事，适合演示：
pdf2zh -i --share链接是临时的、会过期，不适合长期对外。
长期对外：服务器上用 Docker 跑，映射写成-p 0.0.0.0:7860:7860让外部可达，再用 Nginx 反代加域名和 HTTPS 证书，把 443 指向本机 7860。反代配置有三个要点：转发 Host 和真实 IP 两个请求头；加 WebSocket 升级头（Gradio 界面靠它实时刷新）；client_max_body_size放大到 100M 以上（PDF 上传体积不小）。
多用户鉴权：--authorized users.txt即可，文件每行一个用户名,密码，可选第二个参数传入自定义登录页。对外服务建议同时在配置里设置HIDDEN_GRADIO_DETAILS隐藏服务端 API Key，详见 高级配置文档。
六、按症状调优：慢、异常、质量不达标
| 症状 | 怎么调 |
|---|---|
| 翻译慢 | 加-t线程数，默认 4；确认没在重复翻译相同片段 |
| 相同内容换了引擎却结果不变 | 加了缓存，--ignore-cache强制重翻 |
| 公式字体被当正文翻乱了 | 用-f正则把这些字体排除出翻译范围 |
| 输出 PDF 打开渲染异常 | --skip-subset-fonts跳过字体子集化（文件会变大） |
| 译文风格不合预期 | 写prompt.txt，用--prompt prompt.txt加载 |
自定义提示词文件里可用${lang_in}、${lang_out}、${text}三个占位符，写清“保留公式和术语”这类要求即可，格式细节见 docs/ADVANCED.md。
翻译引擎方面，默认 Google 无需配置；国内网络友好一点的优先试三个：DeepLX（设DEEPLX_ENDPOINT指向自建代理）、Ollama（纯本地，设OLLAMA_HOST、OLLAMA_MODEL）、阿里云百炼qwen-mt（设ALI_API_KEY、ALI_MODEL），启动时-s指定。其余二十多种引擎及环境变量都在 高级配置文档 的表格里。
七、踩坑速查：现象到处理
| 现象 | 先检查什么 | 怎么办 |
|---|---|---|
| 局域网其他电脑打不开 | 服务是不是绑在 127.0.0.1；防火墙 | Docker 映射用 0.0.0.0；放行 7860 |
| 首次启动卡住不动 | 是否在下载排版检测模型 | 设HF_ENDPOINT=https://hf-mirror.com |
| 端口 7860 被占用 | 换端口 | --serverport 8080（Python）或-p 8080:7860（Docker） |
| 鉴权后登录失败 | users.txt 格式 | 每行用户名,密码，不能多空格、不能漏逗号 |
| 浏览器能开、上传报错 | 反代上传体积限制 | 调大 Nginxclient_max_body_size |
八、回顾与进阶资源
三条路线（Python、Docker、Windows 绿色版）跑通后你拿到的都是同一个 7860 端口的网页翻译界面；对外分享用--share临时链接或“域名 + 证书 + 反代”两条路；之后的调优都是对照症状改参数。
想继续深入：
- 高级配置：缓存、字体、配置示例
- Python / HTTP API 文档
- GUI 使用说明
- Docker 镜像配置
【免费下载链接】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），仅供参考
