乐于分享
好东西不私藏
夜雨聆风 > > 办公文件 > 论文翻译自由:把 PDF2zh 部署到本地,中英对照读文献不泄露隐私

论文翻译自由:把 PDF2zh 部署到本地,中英对照读文献不泄露隐私

当前时间： 2026-08-17 18:18:26 分类：办公文件 评论(0)
论文翻译自由:把 PDF2zh 部署到本地,中英对照读文献不泄露隐私

一份面向科研党的本地部署 + Zotero 搭配实操笔记 + 本地文档翻译

导语

读英文文献，是每一个科研人的日常酷刑。

满屏专业术语已经够劝退了，碰到大量数学公式的论文，普通翻译工具一遇到符号就乱码、排版全崩；把 PDF 丢到在线翻译网站吧，又总担心论文内容外流，遇上扫描版还动不动卡死。

有没有一种方法：既能保留公式排版、生成中英对照，又能让文献全程不出本机、保护隐私？

有。把PDF2zh（基于 PDFMathTranslate 的 zotero-pdf2zh）本地部署到自己的电脑上，配合 Zotero，就能实现"选中即翻、双语并排、隐私无忧"。下面这份笔记，从它能干什么、到怎么部署、到避坑，一次讲清。

① 这是什么 / 能干什么

PDF2zh 是一个专门翻译 PDF 的工具，基于 PDFMathTranslate，尤其擅长处理学术论文、含公式的文献。它会在原 PDF 上做双语排版，英文与中文对照呈现，公式、图表的位置尽量保留。

配合 guaguastandup/zotero-pdf2zh 这个服务端，你可以在浏览器网页上传文件翻译，也可以让 Zotero 插件直接调用本机服务翻译文库里的 PDF。

本项目本地版本在官方基础上还加了实用功能：网页上传入口、页码范围选择、以及对 .txt / .md / .markdown 文本的翻译通道（Markdown 会尽量保留标题、列表、引用、代码块、链接、图片、表格等结构）。

② 核心亮点

  • 保留公式排版：数学公式、符号基本不乱码，对照阅读体验远胜普通工具。
  • 双语对照输出：中英并排，原意不易丢失，适合精读。
  • 本地隐私优先：服务跑在你自己的电脑（默认端口 8890），文献不出本机；Flask 自带的是开发服务器，本机自用、Zotero 调用、网页上传都没问题，但不要直接暴露到公网。
  • 不止 PDF：还支持 .txt、.md、.markdown 输入，输出对应格式文本。
  • 灵活翻译后端：默认 SiliconFlow Free（文本通道会回退用 Bing）；想用大模型翻可填 OpenAI / DeepSeek / SiliconFlow / OpenAI Compatible 的 API Key、Base URL、模型。

③ 部署步骤

目标：在 C:\pdf2zh 内部署，尽量不污染系统环境，不改全局 Python / pip / uv。

1. 准备基础软件建议使用Python 3.12；Zotero 用 7 或 8 均可。依赖不要直接装进系统 Python。

2. 建立并固定项目目录推荐固定放在：

C:\pdf2zh

uv 创建的虚拟环境对路径敏感，不要频繁移动这个目录。

3. 放入官方文件项目根目录至少应有：

C:\pdf2zh\server.zipC:\pdf2zh\zotero-pdf-2-zh-v4.0.1.xpi

server.zip 是恢复点，建议保留，不必删。

4. 解压服务端server.zip 解压后得到 server\server.py、server\requirements.txt、server\config\、server\utils\ 等。

5. 创建外层虚拟环境并装依赖外层 .venv 只负责运行 Flask 服务本体：

cd /d C:\pdf2zhpython -m venv .venv.\.venv\Scripts\python.exe -m pip install -r .\server\requirements.txt

依赖含 Flask、toml、pypdf、PyMuPDF 等。网络慢可用镜像源，但优先只影响当前命令，不要改全局 pip 配置。

6. 使用隔离启动脚本（关键）start-pdf2zh.ps1 / start-pdf2zh.bat 会在启动前设置局部变量（HOME、USERPROFILE、XDG_CONFIG_HOME、UV_CACHE_DIR、PIP_CACHE_DIR、TEMP、TMP 等指向 C:\pdf2zh 内的 .home、.config、.uv-cache、.pip-cache、.tmp），把配置/缓存/临时文件关在项目文件夹内，减少干扰别的 Python / uv / pip 项目。

7. 首次启动双击或运行：

C:\pdf2zh\start-pdf2zh.bat

或：

powershell -ExecutionPolicy Bypass -File C:\pdf2zh\start-pdf2zh.ps1

脚本实际进入 C:\pdf2zh\server 执行：

C:\pdf2zh\.venv\Scripts\python.exe server.py --check_update=False --port=8890

首次启动会准备内部虚拟环境（server\zotero-pdf2zh-venv、server\zotero-pdf2zh-next-venv），过程较慢，后续启动会快很多。

8. 验证服务浏览器打开 http://localhost:8890/，健康检查http://localhost:8890/health，网页上传入口http://localhost:8890/upload。终端看到 Running on http://127.0.0.1:8890 即正常。

④ 配合 Zotero 使用

  1. 打开 Zotero → 工具 → 插件。
  2. 将 C:\pdf2zh\zotero-pdf-2-zh-v4.0.1.xpi 拖进去安装。
  3. 重启 Zotero。
  4. 插件设置里确认 Server 地址和端口为 http://127.0.0.1:8890（或 http://localhost:8890）。

日常用法：启动服务 → 打开 http://localhost:8890/upload → 选文件 → 选引擎和翻译服务 → 如需大模型，展开"高级参数"填 API Key / Base URL / 模型 → 可勾"记住 API 配置"→ 填页码范围 → 点"开始翻译"。输出文件在 C:\pdf2zh\server\translated。

⑤ 常见问题 / 避坑

  • 别污染系统 Python：不要执行 pip install pdf2zh pdf2zh_next 这种全局安装；固定用 C:\pdf2zh\.venv\Scripts\python.exe。
  • 别随便移动目录：脚本和 uv 环境都默认 C:\pdf2zh，移动后可能路径失效、依赖找不到。
  • 端口被占用：默认 8890。先关旧服务窗口（Ctrl + C）；若要换端口，启动时改 --port，Zotero 插件设置也要同步改。
  • Flask 警告：看到 This is a development server 是正常提示，本机自用无碍，别上公网即可。
  • 改代码要重启：改了 server.py / upload.html 后需关服务重跑脚本；页面仍旧就 Ctrl + F5 强刷。
  • 翻译慢：限流、免费排队、页数多、扫描版触发 OCR、同时输出过多格式都会变慢。建议只翻需要的页码、只输出必要文件、非扫描 PDF 勾"跳过扫描检测"、合理提高 QPS。
  • GPU 不一定加速：主要耗时在调用在线翻译 API 与服务商响应、PDF 解析重排、OCR；用在线翻译时本机 GPU 基本帮不上忙。
  • 参数名坑：pdf2zh_next 正确参数是 --pool-max-workers（复数），别写成 --pool-max-worker。
  • server.py 改坏：用根目录 server.zip 恢复，先备份当前文件。

⑥ 结语 + 互动

把 PDF2zh 部署到本地，等于给自己配了一个"私密的论文翻译助手"：公式不崩、中英对照、文献不出本机，再接上 Zotero，读文献的效率直接起飞。

你平时翻论文用的是在线工具还是本地部署？本地部署时又踩过哪些坑？欢迎在评论区聊聊，我把完整避坑清单整理出来一起交流 🙌