【Zotero-pdf2zh】快速搞定 PDF 翻译，完美保留原文格式

博主：她笑中藏泪花
发布时间：2025 年 09 月 10 日
4848 次浏览
1 条评论
19774字数
分类：全部文章 Python AI大模型工具资源分享软件安装

引言

在学术研究中，阅读外文文献是常态，而一款能在翻译时保留原文格式的工具则至关重要。PDFMathTranslate Next 借助 BabelDOC 翻译引擎，能轻松实现“结构保持 + 双语对照”的精准翻译，是处理科研文献的理想选择。

目前，Zotero + PDF2zh/PDF2zh_next 的组合已成为一条活跃且广受好评的实现路径。Zotero-pdf2zh 插件现已更新到更为简洁易用的 3.x 版本。接下来，本教程将引导你完成配置，并详细演示如何通过 Python和 Docker 这两种方式来部署翻译服务。

若您只想使用 pdf2zh_next 不使用zotero插件，可参考这篇教程：【PDF2zh 2.0】三种部署指南与 Zotero 插件配置 - 她笑中藏泪花
若觉得 Python 部署有难度，可直接看下方 Docker 方案；
若仍嫌麻烦，建议试用沉浸式翻译 ➡️常用功能➡️Babeldoc ➡️ 登陆账号拖入文件开始翻译

项目资源链接：
Zotero - PDF2zh 插件：guaguastandup/zotero-pdf2zh
PDF2zh_next：PDFMathTranslate/PDFMathTranslate-next

强烈建议该博文配视频一起看【Zotero-pdf2zh】快速搞定 PDF 翻译，完美保留原文格式_哔哩哔哩_bilibili

环境依赖

Python下载链接建议安装 Python 3.12。
- 个人安装教程（仅需安装Python即可，不用安装pycharm）：python和pycharm的下载和安装以及新建项目
插件目前支持 Zotero 7 桌面端，Zotero 8 待适配。Zotero官网下载链接
Docker（可选）：您可以从 Docker 官网下载。
- 个人安装教程：【Docker】告别环境配置噩梦：从零到一的安装指南
模型服务（OpenAI 兼容）：您需要一个大语言模型的 API Key 和 Base URL。
Zotero 插件下载：
zotero-pdf2zh：前往GitHub Releases 下载 .xpi（v3.x.x）在 Zotero 中 “工具 → 插件” 将 .xpi 拖入安装，必要时重启 Zotero；若未生效请重启 Zotero。

Part 1：Python部署

第一步: 安装uv

# 方法一（可选）：用 pip 安装 uv
pip install uv

# 使用中科大镜像源
pip install -i https://mirrors.ustc.edu.cn/pypi/simple uv

# 方法二（推荐）：使用官方独立安装脚本
# macOS / Linux（任选其一）
curl -LsSf https://astral.sh/uv/install.sh | sh
# 或
wget -qO- https://astral.sh/uv/install.sh | sh

# Windows（PowerShell）
powershell -ExecutionPolicy ByPass -c "irm https://astral.sh/uv/install.ps1 | iex"

检查uv安装是否成功(必做)：

uv --version

若检查失败，多半是 PATH 未生效。将 uv 的安装目录加入 PATH 后重启终端：

# Windows PowerShell 
$env:Path = "$env:USERPROFILE\.local\bin;$env:Path"

# macOS / Linux
export PATH="$HOME/.local/bin:$PATH"

手动安装uv

第二步: 下载并解压项目文件

Windows（CMD）

# 1. 创建并进入zotero-pdf2zh文件夹
mkdir zotero-pdf2zh && cd zotero-pdf2zh

# 2. 下载并解压server文件夹
# 如果server.zip下载失败, 可以直接访问: https://raw.githubusercontent.com/guaguastandup/zotero-pdf2zh/main/server.zip 手动下载
curl -L -o server.zip https://raw.githubusercontent.com/guaguastandup/zotero-pdf2zh/main/server.zip
REM 解压（任选一种；如命令行解压失败，可在资源管理器中右键解压到当前目录）
powershell -Command "Expand-Archive -Path '.\server.zip' -DestinationPath '.' -Force"
REM 或者（如果 tar 可用）
REM tar -xf server.zip

# 3. 进入server文件夹
cd server

Mac/Linux

# 1. 创建并进入zotero-pdf2zh文件夹
mkdir zotero-pdf2zh && cd zotero-pdf2zh

# 2. 下载并解压server文件夹
# 如果server.zip下载失败, 可以直接访问: https://raw.githubusercontent.com/guaguastandup/zotero-pdf2zh/main/server.zip 手动下载
curl -L -o server.zip https://raw.githubusercontent.com/guaguastandup/zotero-pdf2zh/main/server.zip
# 解压（任选其一）
unzip -o docker.zip -d .
# 或（若系统支持 bsdtar 解压 zip）
# tar -xf docker.zip

# 3. 进入server文件夹
cd server

解压后的server目录包括：

server.py
requirements.txt
config/
translated/
doc/
utils/

第三步: 安装依赖并启动服务

先做这两件事（降低失败率）
1）确认命令行能访问 Python/uv/conda 之一（python -V / uv --version / conda -V）。
2）若在国内网络，先测试镜像可达性（应返回 pip 的版本清单）：

pip index versions pip -i https://mirrors.ustc.edu.cn/pypi/simple

1进入 server 目录后安装依赖：

pip install -r requirements.txt
# 若网络受限，可临时使用镜像（示例为中科大源）：
# pip install -r requirements.txt -i https://mirrors.ustc.edu.cn/pypi/simple

如果此命令成功返回 flask 的版本列表，则说明镜像可用。

方法一：直接启动

如果您确定本机 uv 或 conda 工作正常，且网络可直接安装依赖（无明显网络问题），可用此法。

启动服务（默认启用虚拟环境与端口 8890，可按需调整）：

python server.py

常用参数（按需）：

# 关闭虚拟环境管理
python server.py --enable_venv=False
# 切换虚拟环境管理工具为 conda
python server.py --env_tool=conda
# 切换端口
python server.py --port={Your Port Num}
# 关闭自动检查更新
python server.py --check_update=False
# 切换自动更新源为 gitee
python server.py --update_source="gitee"
# 关闭包安装时启用镜像(默认为中科大镜像源)
python server.py --enable_mirror=False
# 自定义镜像源（示例为清华源）
python server.py --mirror_source="https://pypi.tuna.tsinghua.edu.cn/simple/"
# 开启 Windows exe 安装模式；将 pdf2zh_next 可执行文件路径传入
#（例如 .\pdf2zh-v2.6.3-BabelDOC-v0.5.7-win64\pdf2zh\pdf2zh.exe）
python server.py --enable_winexe=True --winexe_path="xxxxxxx"

注：首次/更新需要输入两次python server.py来启动，第一次是安装必要依赖；第二次是启动服务。
启动成功的预期：终端会打印服务启动与监听端口信息（默认 8890）。若端口被占用，请改用 --port 指定新端口。

方法二

如果自动安装过程中，由于网络波动或资源文件下载缓慢导致虚拟环境创建失败，可以尝试此方法。

“预热”指提前下载并安装依赖。预热仅首次需要，之后只执行 python server.py。

使用预热uv版本

# 1. 利用uv预热(首次安装)
# Windows用户:
.\install-with-uv.bat --warmup
# MacOS/Linux用户:
./install-with-uv.sh --warmup

# 预热后，您需要检查命令行中是否提示安装成功，如果安装失败，请不要进行下一步

# 2. 首次执行脚本
python server.py --skip_install=True

# install-with-uv.sh有三个选项:
# --warmup 对babeldoc的资源文件进行预热(需要一些时间)
# --upgrade 对当前包进行升级
# --no-mirror 不使用国内镜像源

# 3.以后执行版本
python server.py

使用conda预热版本

# 1. 利用conda预热(首次安装)
# Windows用户:
.\install-with-conda.bat --warmup
# MacOS/Linux用户:
./install-with-conda.sh  --warmup

# 预热后，您需要检查命令行中是否提示安装成功，如果安装失败，请不要进行下一步

# 2. 首次执行脚本
python server.py --env_tool=conda --skip_install=True

# install-with-conda.sh有三个选项:
# --warmup 对babeldoc的资源文件进行预热(需要一些时间)
# --upgrade 对当前包进行升级
# --no-mirror 不使用国内镜像源

# 3.以后执行脚本
# 指定虚拟环境工具为conda
python server.py --env_tool=conda

方法三：手动安装依赖

若上述两个自动安装失败，可手动创建虚拟环境后逐一安装依赖（成功则跳过此节）。

A. 为 pdf2zh_next (2.x) 手动安装

方案 A1：用 uv（推荐）

环境名：zotero-pdf2zh-next-venv

Windows/CMD

:: 进入 server 目录
cd server
:: 1) 创建虚拟环境
uv venv zotero-pdf2zh-next-venv --python 3.12
:: 2) 安装依赖（使用镜像）
uv pip install --python .\zotero-pdf2zh-next-venv\Scripts\python.exe --index-url https://mirrors.ustc.edu.cn/pypi/simple pdf2zh_next pypdf PyMuPDF flask toml

若有打开虚拟环境的需求：

# cmd
zotero-pdf2zh-next-venv\Scripts\activate
# powershell
.\zotero-pdf2zh-next-venv\Scripts\Activate.ps1

macOS / Linux

# 进入 server 目录
cd server
# 1) 创建虚拟环境
uv venv zotero-pdf2zh-next-venv --python 3.12
# 2) 安装依赖（使用镜像）
uv pip install --python ./zotero-pdf2zh-next-venv/bin/python --index-url https://mirrors.ustc.edu.cn/pypi/simple pdf2zh_next pypdf PyMuPDF flask toml

若有打开虚拟环境的需求：

source ./zotero-pdf2zh-next-venv/bin/activate

方案 A2：用 conda

# 进入 server 目录
cd server
# 1) 创建环境
conda create -n zotero-pdf2zh-next-venv python=3.12 -y
# 2) 安装依赖（使用镜像）
conda run -n zotero-pdf2zh-next-venv pip install --index-url https://mirrors.ustc.edu.cn/pypi/simple pdf2zh_next pypdf PyMuPDF flask toml

若有打开虚拟环境的需求：

conda activate zotero-pdf2zh-next-venv

B. 为 pdf2zh (1.x) 手动安装

方案 A1：用 uv（推荐）

环境名：zotero-pdf2zh-venv（与脚本一致）

Windows/CMD

:: 进入 server 目录
cd server
:: 1) 创建虚拟环境（Python 3.12）
uv venv zotero-pdf2zh-venv --python 3.12
:: 2) 安装依赖（使用科大镜像）
uv pip install --python .\zotero-pdf2zh-venv\Scripts\python.exe --index-url https://mirrors.ustc.edu.cn/pypi/simple pdf2zh==1.9.11 pypdf PyMuPDF flask numpy==2.2.0 toml pdfminer.six==20250416

若有打开虚拟环境的需求：

# cmd
zotero-pdf2zh-venv\Scripts\activate
# powershell
.\zotero-pdf2zh-venv\Scripts\Activate.ps1

macOS / Linux

# 进入 server 目录
# 进入 server 目录
cd server
# 1) 创建虚拟环境（Python 3.12）
uv venv zotero-pdf2zh-venv --python 3.12
# 2) 安装依赖（使用科大镜像）
uv pip install --python ./zotero-pdf2zh-venv/bin/python --index-url https://mirrors.ustc.edu.cn/pypi/simple pdf2zh==1.9.11 pypdf PyMuPDF flask numpy==2.2.0 toml pdfminer.six==20250416

若有打开虚拟环境的需求：

source ./zotero-pdf2zh-venv/bin/activate

方案 A2：用 conda

依然使用环境名：zotero-pdf2zh-venv

# 进入 server 目录
# 进入 server 目录
cd server
# 1) 创建环境
conda create -n zotero-pdf2zh-venv python=3.12 -y
# 2) 安装依赖（使用科大镜像）
conda run -n zotero-pdf2zh-venv pip install --index-url https://mirrors.ustc.edu.cn/pypi/simple pdf2zh==1.9.11 pypdf PyMuPDF flask numpy==2.2.0 toml pdfminer.six==20250416

若有打开虚拟环境的需求：

conda activate zotero-pdf2zh-venv

注：若还不行，可以把您使用的代码发给ai，让ai帮您更换一个适合您的镜像源。

使用pdf2zh_next的exe启动服务

python server.py --enable_winexe=True --winexe_path="Your\path\to\pdf2zh\pdf2zh.exe"

第四步：开始翻译

插件设置路径：编辑 → 首选项 → PDF2zh。在此可切换翻译引擎、配置 API 服务（Base URL、API Key、模型名等）与并发/QPS 参数。随后在 Zotero 主界面选中文献，右键选择相关操作即可。

翻译PDF (Translate PDF)：对选中的原文 PDF 生成译文版本（单语/双语取决于插件设置）。
裁剪PDF (Crop PDF)：适用于双语或单语附件。自动裁剪两侧空白，并按页面宽度一分为二后上下拼接，便于小屏阅读。若过裁剪，可在 server/utils/config.py 调整 config.pdf_w_offset。
双语对照 (Compare PDF)：生成“左原右译”的双语 PDF。可在设置中选“Dual 文件翻译页在前”调整顺序。
双语对照（裁剪）(Crop-Compare PDF)：专为双栏论文设计；先沿中缝垂直裁成单栏，再进行左右拼接。

运行提示：若插件调用到服务器失败，请首先确认 server.py 是否在运行、监听端口是否与插件设置一致，防火墙/安全软件是否放行本地端口。

一键启动脚本

第一步：获取 `server.py` 的目录路径

先把终端/命令行打开到 server.py 所在的文件夹
- Windows：打开放有 server.py 的文件夹，在空白处按住 Shift 右键 → 在终端中打开（或地址栏输入 powershell/cmd 回车）。
- macOS：在 Finder 里打开该文件夹，右键空白处 → 服务 → 在文件夹位置打开新终端（没有的话，可先打开“终端”后用 cd 进入这个文件夹）。
- Linux：打开“终端”，用 cd 进入放有 server.py 的文件夹。
复制下面这一行回车执行（这行用的是 Python 自带的 pathlib 库，不需要 pip 安装）：
```
python -c "import pathlib; print(pathlib.Path('server.py').resolve().parent)"
```
- 如果你的电脑只有 python3 命令，把上面的 python 换成 python3。
- Windows 如果 python 不行，试试：
```
py -3 -c "import pathlib; print(pathlib.Path('server.py').resolve().parent)"
```
终端会输出一行目录路径，复制这行：
- Windows 例子：D:\work\myapp\server
- macOS/Linux 例子：/Users/you/work/myapp/server

请复制并保存好这行路径，我们马上就要用它！

第二步：选你的模板并复制

根据你的电脑系统，选择一个对应的模板。

如果你是 Windows 用户，请复制这个：

@echo off
chcp 65001 >nul
set PYTHONUTF8=1
rem ← 只需要修改下面这一行
set "PROJECT_PATH=这里替换成你的路径"
python "%PROJECT_PATH%\server.py"
pause

如果你是 macOS 或 Linux 用户，请复制这个：

#!/usr/bin/env bash
set -euo pipefail
export PYTHONUTF8=1
# ← 只需要修改下面这一行
PROJECT_PATH="这里替换成你的路径"
cd "$PROJECT_PATH"
python3 server.py
read -rp $'完成。按 Enter 退出…' _

若您能看懂该脚本，知道修改哪里，那么请直接到第四步。

第三步：让 AI 帮你生成脚本

现在，我们要请一位的 AI 助手DeepSeek来帮我们生成脚本。

先复制下面这段话：
你好，请你根据我提供的路径和这个模板，生成一个可以直接供我使用的自动化脚本，并告诉我怎么用。
紧接着，粘贴你在第一步获取的路径。
最后，粘贴你在第二步选择的对应模板。

把这三段内容组合在一起，像下面这个样子，然后一次性发给 AI：

发送给AI的完整示例：
你好，请你根据我提供的路径和这个模板，生成一个可以直接供我使用的自动化脚本，并告诉我怎么用。
我的路径是：D:\project\server
我的模板是：
@echo off
chcp 65001 >nul
set PYTHONUTF8=1
rem ← 只需要修改下面这一行
set "PROJECT_PATH=这里替换成你的路径"
python "%PROJECT_PATH%\server.py"
pause

AI 会非常聪明地帮你把路径填好，并生成最终的完美脚本代码。

第四步：运行脚本

AI 已经把最终的脚本代码给你了，现在我们只需要把它保存成一个可执行的文件。

对于 Windows 用户 (.bat 文件):

在电脑任意位置（比如桌面）右键，选择“新建” -> “文本文档”。
打开这个新建的文本文档，把你从 AI 那里复制来的最终代码粘贴进去。
点击左上角的“文件”，选择“另存为”。
在弹出的窗口中，最关键的一步：
- “保存类型”：一定要选择“所有文件 (*.*)”。
- “文件名”：给它取个名字，但后缀必须是 .bat。例如：一键启动.bat。
点击“保存”。现在，桌面上就出现了一个带齿轮图标的文件。

对于 macOS / Linux 用户 (.sh 文件):

打开“文本编辑” (TextEdit) 或任何文本编辑器。
把 AI 生成的最终代码粘贴进去。
- Mac 用户请注意：如果用的是“文本编辑”，请在菜单栏选择“格式” -> “制作纯文本”，确保是纯文本模式。
保存文件。给它取个名字，后缀必须是 .sh。例如：startup.sh，并将它保存在你喜欢的位置（比如桌面）。
最后一步，赋予它运行的权限。打开“终端”，输入 chmod +x （注意 +x 后面有个空格），然后把刚才保存的 .sh 文件从桌面拖到终端窗口里，最后按回车。

Part 2：Docker 部署（Compose）

如果你想使用 pdf2zh（1.x）作为翻译引擎，请直接跳到文末章节：“（可选）切换为 pdf2zh”。

第一步：确认 Docker 环境就绪

docker version
docker compose version

如果显示不了 docker compose，你可能安装的是老版 docker-compose，后续命令把 docker compose 换成 docker-compose 即可。

第二步：下载并准备 Docker 配置文件

Windows（CMD）

mkdir zotero-pdf2zh_docker
cd zotero-pdf2zh_docker

REM 下载
curl -L -o docker.zip https://raw.githubusercontent.com/guaguastandup/zotero-pdf2zh/main/docker.zip

REM 解压（任选一种；如命令行解压失败，可在资源管理器中右键解压到当前目录）
powershell -Command "Expand-Archive -Path '.\docker.zip' -DestinationPath '.' -Force"
REM 或者（如果 tar 可用）
REM tar -xf docker.zip

REM 进入 docker 子目录（里面有 Dockerfile 和 docker-compose.yaml）
cd docker

macOS / Linux（终端）

mkdir -p zotero-pdf2zh_docker
cd zotero-pdf2zh_docker

# 下载
curl -L -o docker.zip https://raw.githubusercontent.com/guaguastandup/zotero-pdf2zh/main/docker.zip

# 解压（任选其一）
unzip -o docker.zip -d .
# 或
# tar -xf docker.zip

# 进入 docker 子目录（里面有官方 Dockerfile 和 docker-compose.yaml）
cd docker

解压后的 docker/ 目录包含：

Dockerfile
docker-compose.yaml
config/         （空文件夹，用于挂载配置）
translated/     （空文件夹，用于挂载输出）

第三步：预拉取核心镜像 (推荐)

为避免首次启动时因网络问题导致超时，建议先手动拉取 pdf2zh_next 的 Docker 镜像。

docker pull awwaawwa/pdfmathtranslate-next:latest

Docker镜像加速

如果你（或你的组织）有可靠的镜像加速端点，可以在 Docker 里配置“registry-mirrors”，让所有 docker pull 走加速：

Docker Desktop（Win/macOS）：Settings → Docker Engine，在 JSON 中加入：

{

  "registry-mirrors": ["https://<your-mirror-endpoint>"]

}

第四步：启动服务

在 zotero-pdf2zh_docker/docker 目录下，执行以下命令：

docker compose up -d --build

当您看到类似下面的日志输出时，代表服务已成功启动：

* Running on http://127.0.0.1:8890
* Running on http://172.18.0.2:8890

常用 Docker 管理命令：

docker start zotero-pdf2zh      # 启动已存在的容器
docker stop zotero-pdf2zh       # 停止容器
docker logs -f zotero-pdf2zh    # 查看实时日志，用于排查问题
docker compose down             # 停止并移除容器

（可选）切换为 `pdf2zh` （1.x）

默认镜像是 pdf2zh_next。如果你只想用 1.x pdf2zh（byaidu/pdf2zh:1.9.6），按下述最小改动即可。

0）预拉取经典镜像

docker pull byaidu/pdf2zh:1.9.6

1) 修改 Dockerfile

A. 更换镜像变量，改为1.x

找到：

ZOTERO_PDF2ZH_FROM_IMAGE=awwaawwa/pdfmathtranslate-next:latest

改为：

ZOTERO_PDF2ZH_FROM_IMAGE=byaidu/pdf2zh:1.9.6

B. 删除“next 包装器”整段

找到

RUN printf '%s\n' \
  '#!/usr/bin/env bash' \
  'set -euo pipefail' \
  'img="${ZOTERO_PDF2ZH_FROM_IMAGE:-awwaawwa/pdfmathtranslate-next:latest}"' \
  'cid="$(cat /etc/hostname)"' \
  'exec docker run --rm --volumes-from "${cid}" -e TZ -e http_proxy -e https_proxy -e HF_ENDPOINT "$img" pdf2zh_next "$@"' \
  > /usr/local/bin/pdf2zh_next && chmod +x /usr/local/bin/pdf2zh_next

整块修改为：

RUN printf '%s\n' \
  '#!/usr/bin/env bash' \
  'set -euo pipefail' \
  'img="${ZOTERO_PDF2ZH_FROM_IMAGE:-byaidu/pdf2zh:1.9.6}"' \
  'cid="$(cat /etc/hostname)"' \
  'exec docker run --rm --volumes-from "${cid}" -e TZ -e http_proxy -e https_proxy -e HF_ENDPOINT "$img" pdf2zh "$@"' \
  > /usr/local/bin/pdf2zh && chmod +x /usr/local/bin/pdf2zh

其它内容（server.zip 下载、requirements 安装、entrypoint）保持不变。

2) 修改 `docker-compose.yaml`

找到

ZOTERO_PDF2ZH_FROM_IMAGE: awwaawwa/pdfmathtranslate-next:latest

改为：

ZOTERO_PDF2ZH_FROM_IMAGE: byaidu/pdf2zh:1.9.6

如需挂字体（可选，字体文件与 docker-compose.yaml 同级）：

volumes:
  - ./translated:/app/server/translated
  - ./config:/app/server/config
  - ./LXGWWenKai-Regular.ttf:/app/LXGWWenKai-Regular.ttf:ro   # 可选
  - /var/run/docker.sock:/var/run/docker.sock

3) 重构启动（在 `docker` 目录）

docker compose down
docker compose up -d --build

常用命令：

docker start zotero-pdf2zh      # 启动已存在的容器
docker stop zotero-pdf2zh       # 停止容器
docker logs -f zotero-pdf2zh    # 查看实时日志，用于排查问题
docker compose down             # 停止并移除容器

插件里把 翻译引擎 选成 pdf2zh。祝您使用愉快！

Docker配置镜像下载的使用教程

本项目在构建镜像时需要从 GitHub 下载 server.zip。默认使用官方源，如果你的网络访问 GitHub 生效较慢或失败，可按需启用以下两种镜像方式（二选一）：

方法 1：给原始链接加“代理前缀”（如 ghproxy.net）
方法 2：直接把下载地址换成 jsDelivr CDN

每次修改构建源后，都请重新构建：
docker compose build --no-cache && docker compose up -d

0. 默认不改（官方源 + pip 自动回退）

默认使用：https://raw.githubusercontent.com/guaguastandup/zotero-pdf2zh/main/server.zip
pip 安装依赖时：先官方 PyPI，失败自动回退 USTC。
（无需任何改动即可工作，适合网络正常时使用。）

1）方法一：开启“代理前缀”镜像

适用：希望保留原始 raw.githubusercontent.com 链接，只在前面加个国内可达的反代前缀（例如 https://ghproxy.net/）。

操作步骤

打开 docker-compose.yml，在 build.args 下取消注释并设置：
```
services:
  pdf2zh-server:
    build:
      args:
        GITHUB_PROXY_PREFIX: "https://ghproxy.net/"
```
你也可以换成你常用的其他前缀域名。

重新构建并启动：

docker compose build --no-cache
docker compose up -d

备注：代理前缀服务通常为第三方社区反代，稳定性与可用性请自评估。无法访问时可更换域名或改用方法二。

2）方法二：改用 jsDelivr（CDN）

适用：公开仓库中的单个文件下载，CDN 稳定缓存，速度通常更好。

操作步骤

打开 docker-compose.yml，在 build.args 下改写 SERVER_ZIP_URL（并且确保 GITHUB_PROXY_PREFIX 留空或注释）：

services:
  pdf2zh-server:
    build:
      args:
        SERVER_ZIP_URL: "https://cdn.jsdelivr.net/gh/guaguastandup/zotero-pdf2zh@main/server.zip"
        # GITHUB_PROXY_PREFIX:  # 留空或注释

重新构建并启动：

docker compose build --no-cache
docker compose up -d

Part 3：连接 Zotero 并开始翻译

无论您选择哪种部署方式，最后一步都是在 Zotero 插件中配置并使用它。

插件设置：在 Zotero 中，导航至 “编辑” -> “首选项” -> “PDF2zh” 选项卡。
服务地址：确保服务地址与您的后端服务一致。默认是 http://127.0.0.1:8890 或 http://localhost:8890。如果您在启动时修改了端口，请在此处同步更新。
模型配置：在此处配置您的翻译引擎（如 pdf2zh_next）、API 服务商的 Base URL 和 API Key。
开始翻译：回到 Zotero 主界面，选中一篇或多篇文献条目，右键单击，在菜单中选择 “开始翻译”。

Part 4：常见问题解答（FAQ）

Q1：第一次翻译进度条卡在 translate 10/100 很久？
A：

建议开启代理/镜像加速首次资源下载；
或直接在 PDFMathTranslate-next Releases 下载 带 assets 的 Windows 压缩包（内置常用字体/资源），解压后双击 pdf2zh.exe，访问 WebUI http://127.0.0.1:7860/ 翻译任意 1 页触发资源释放。

Q2：Windows 报 “DLL 初始化失败/缺少运行库”？
A：安装 Microsoft Visual C++ 2015–2022（x64） 。

Q3：Zotero 无进度条、任务未启动？
A：优先检查 Zotero ↔ 本地服务 连通性（端口/回环地址/代理），并核对插件中的服务地址 http://localhost:8890 是否与后端一致（默认即为 8890）。

Q4：服务端返回 401/403/404/429 或端点不可达？
A：逐项核实 Base URL / API Key / 模型名 / 速率；根据服务商限制临时降低 QPS/并发，观察是否恢复。

Q5：线程/速率如何估算？
A：以服务商 RPM/TPM 为上限，从保守的 QPS 值启动并逐步压测： QPS = ⌊ RPM / 60 ⌋。

Q6：比较推荐哪个服务/大模型？
A：

siliconflowfree（免配置）：硅基流动提供的免费通道（当前为 THUDM/GLM-4-9B-0414），适合入门与临时使用；
火山引擎（开发者/协作计划）：每个模型每日50w额度，具体可见协作奖励计划规则、-火山引擎；
“非思考”模型优先：多数论文/学术 PDF 翻译更看重稳定与速度，尽量使用非思考版；（think模型会带来巨大的token开销，且不稳定）
高性价比口碑：deepseek-v3、qwen-plus-latest 等反馈较好（需自配 API Key）。
不建议使用机翻：BabelDOC是专门为大模型做的服务，bing、google等机翻服务不建议使用。

提示：免费服务策略可能变化，请以各平台控制台实际配额与速率为准。

Q7：我实在是搞不定部署应该怎么办
A：打开网页：沉浸式翻译 ➡️常用功能➡️Babeldoc ➡️ 登陆账号拖入文件开始翻译

获取更多帮助

如果以上内容未能解决您的问题，可以通过以下渠道寻求支持：

阅读更详尽的常见问题文档
在项目的 GitHub Issues 区提交您的问题。
加入用户 QQ 群: 971960014 (入群验证: github)。提问时，请附上：
1）终端的完整报错日志（复制为文本.txt） 2）Zotero 插件的配置截图 3）报错弹窗截图 4）问题 PDF 文件。

若您觉得本博文做的还不错，欢迎支持她笑中藏泪花 | 爱发电

感谢您的支持，祝您使用愉快！！

最后修改：2025 年 10 月 14 日

如果您觉得本文还不错，欢迎打赏支持

1 条评论

【PDF2ZH】谁才是论文翻译之王？新版 vs 旧版深度对决 - 她笑中藏泪花
October 20th, 2025 at 02:46 pm

[...]引言目前开源翻译科研论文的工具有 pdf2zh（1.x）与 pdf2zh-next（2.x）。后者在 2025 年 6 月 4 日迁移到组织仓库并以 “next/2.0” 为主线持续迭代，核心更换为 BabelDOC 翻译内核。本文基于统一环境的实测，对两代引擎在使用体验与综合成本上的差异做纵向对比，并对 pdf2zh-next 下两类主流模型路径做横向讨论。本次评测将围绕以下四个核心维度展开[...]

回复

发表评论取消回复
使用cookie技术保留您的个人信息以便您下次快速评论，继续评论表示您已同意该条款

评论 *

私密评论

名称 *

🎲

邮箱 *

地址

【Zotero-pdf2zh】快速搞定 PDF 翻译，完美保留原文格式

她笑中藏泪花 • 2025 年 09 月 10 日

<h2>引言</h2>在学术研究中，阅读外文文献是常态，而一款能在翻译时保留原文格式的工具则至关重要。<a class="no-external-link" href="https://pdf2zh-next.com/zh/index.html" target="_blank">PDFMathTranslate Next</a> 借助 <a class="no-external-link" href="https://github.com/funstory-ai/BabelDOC" target="_blank">BabelDOC</a> 翻译引擎，能轻松实现“结构保持 + 双语对照”的精准翻译，是处理科研文献的理想选择。目前，Zotero + PDF2zh/PDF2zh_next 的组合已成为一条活跃且广受好评的实现路径。Zotero-pdf2zh 插件现已更新到更为简洁易用的 3.x 版本。接下来，本教程将引导你完成配置，并详细演示如何通过 Python和 Docker 这两种方式来部署翻译服务。若您只想使用 pdf2zh_next 不使用zotero插件，可参考这篇教程：<a href="https://rosetears.cn/archives/53/">【PDF2zh 2.0】三种部署指南与 Zotero 插件配置 - 她笑中藏泪花</a> 若觉得 Python 部署有难度，可直接看下方 Docker 方案； 若仍嫌麻烦，建议试用 <a class="no-external-link" href="https://immersivetranslate.com/?via=4641d7" target="_blank">沉浸式翻译</a> ➡️常用功能➡️Babeldoc ➡️ 登陆账号 拖入文件 开始翻译<blockquote>项目资源链接：<ul><li>Zotero - PDF2zh 插件：<a class="no-external-link" href="https://github.com/guaguastandup/zotero-pdf2zh" target="_blank">guaguastandup/zotero-pdf2zh</a></li><li>PDF2zh_next：<a class="no-external-link" href="https://github.com/PDFMathTranslate/PDFMathTranslate-next" target="_blank">PDFMathTranslate/PDFMathTranslate-next</a></li></ul></blockquote>强烈建议该博文配视频一起看<a class="no-external-link" href="https://www.bilibili.com/video/BV1FnHYzeEfj/" target="_blank">【Zotero-pdf2zh】快速搞定 PDF 翻译，完美保留原文格式_哔哩哔哩_bilibili</a><hr><h2>环境依赖</h2><ul><li><a class="no-external-link" href="https://www.python.org/downloads/" target="_blank">Python下载链接</a> 建议安装 Python 3.12。<ul><li>个人安装教程（仅需安装Python即可，不用安装pycharm）：<a class="no-external-link" href="https://www.bilibili.com/video/BV1arwGenEp7/" target="_blank">python和pycharm的下载和安装以及新建项目</a></li></ul></li><li>插件目前支持 Zotero 7 桌面端，Zotero 8 待适配。<a class="no-external-link" href="https://www.zotero.org" target="_blank">Zotero官网下载链接</a></li><li>Docker（可选）：您可以从 <a class="no-external-link" href="https://www.docker.com/products/docker-desktop/" target="_blank">Docker 官网</a> 下载。<ul><li>个人安装教程：<a href="https://rosetears.cn/archives/54/">【Docker】告别环境配置噩梦：从零到一的安装指南</a></li></ul></li><li>模型服务（OpenAI 兼容）：您需要一个大语言模型的 API Key 和 Base URL。</li><li>Zotero 插件下载： zotero-pdf2zh：前往<a class="no-external-link" href="https://github.com/guaguastandup/zotero-pdf2zh/releases" target="_blank">GitHub Releases</a> 下载 <code>.xpi</code>（v3.x.x）在 Zotero 中 “工具 → 插件” 将 <code>.xpi</code> 拖入安装，必要时重启 Zotero；若未生效请重启 Zotero。</li></ul><hr><h2>Part 1：Python部署</h2><h3>第一步: 安装uv</h3><pre><code class="lang-shell"># 方法一（可选）：用 pip 安装 uv
pip install uv

# 使用中科大镜像源
pip install -i https://mirrors.ustc.edu.cn/pypi/simple uv

# 方法二（推荐）：使用官方独立安装脚本
# macOS / Linux（任选其一）
curl -LsSf https://astral.sh/uv/install.sh | sh
# 或
wget -qO- https://astral.sh/uv/install.sh | sh

# Windows（PowerShell）
powershell -ExecutionPolicy ByPass -c &quot;irm https://astral.sh/uv/install.ps1 | iex&quot;</code></pre>检查uv安装是否成功(必做)：<pre><code class="lang-shell">uv --version</code></pre>若检查失败，多半是 PATH 未生效。将 uv 的安装目录加入 PATH 后重启终端：<pre><code class="lang-bash"># Windows PowerShell 
$env:Path = &quot;$env:USERPROFILE\.local\bin;$env:Path&quot;

# macOS / Linux
export PATH=&quot;$HOME/.local/bin:$PATH&quot;</code></pre><h4>手动安装uv</h4><h3>第二步: 下载并解压项目文件</h3>Windows（CMD）<pre><code class="lang-shell"># 1. 创建并进入zotero-pdf2zh文件夹
mkdir zotero-pdf2zh &amp;&amp; cd zotero-pdf2zh

# 2. 下载并解压server文件夹
# 如果server.zip下载失败, 可以直接访问: https://raw.githubusercontent.com/guaguastandup/zotero-pdf2zh/main/server.zip 手动下载
curl -L -o server.zip https://raw.githubusercontent.com/guaguastandup/zotero-pdf2zh/main/server.zip
REM 解压（任选一种；如命令行解压失败，可在资源管理器中右键解压到当前目录）
powershell -Command &quot;Expand-Archive -Path '.\server.zip' -DestinationPath '.' -Force&quot;
REM 或者（如果 tar 可用）
REM tar -xf server.zip

# 3. 进入server文件夹
cd server</code></pre>Mac/Linux<pre><code class="lang-shell"># 1. 创建并进入zotero-pdf2zh文件夹
mkdir zotero-pdf2zh &amp;&amp; cd zotero-pdf2zh

# 2. 下载并解压server文件夹
# 如果server.zip下载失败, 可以直接访问: https://raw.githubusercontent.com/guaguastandup/zotero-pdf2zh/main/server.zip 手动下载
curl -L -o server.zip https://raw.githubusercontent.com/guaguastandup/zotero-pdf2zh/main/server.zip
# 解压（任选其一）
unzip -o docker.zip -d .
# 或（若系统支持 bsdtar 解压 zip）
# tar -xf docker.zip

# 3. 进入server文件夹
cd server</code></pre>解压后的<code>server</code>目录包括：<pre><code class="lang-txt">server.py
requirements.txt
config/
translated/
doc/
utils/</code></pre><h3>第三步: 安装依赖并启动服务</h3>先做这两件事（降低失败率） 1）确认命令行能访问 Python/uv/conda 之一（<code>python -V</code> / <code>uv --version</code> / <code>conda -V</code>）。 2）若在国内网络，先测试镜像可达性（应返回 <code>pip</code> 的版本清单）：<pre><code class="lang-bash">pip index versions pip -i https://mirrors.ustc.edu.cn/pypi/simple</code></pre>1进入 <code>server</code> 目录后安装依赖：<pre><code class="lang-bash">pip install -r requirements.txt
# 若网络受限，可临时使用镜像（示例为中科大源）：
# pip install -r requirements.txt -i https://mirrors.ustc.edu.cn/pypi/simple</code></pre>如果此命令成功返回 <code>flask</code> 的版本列表，则说明镜像可用。<h4>方法一：直接启动</h4>如果您确定本机 <code>uv</code> 或 <code>conda</code> 工作正常，且网络可直接安装依赖（无明显网络问题），可用此法。启动服务（默认启用虚拟环境与端口 8890，可按需调整）：<pre><code class="lang-bash">python server.py</code></pre>常用参数（按需）：<pre><code class="lang-bash"># 关闭虚拟环境管理
python server.py --enable_venv=False
# 切换虚拟环境管理工具为 conda
python server.py --env_tool=conda
# 切换端口
python server.py --port={Your Port Num}
# 关闭自动检查更新
python server.py --check_update=False
# 切换自动更新源为 gitee
python server.py --update_source=&quot;gitee&quot;
# 关闭包安装时启用镜像(默认为中科大镜像源)
python server.py --enable_mirror=False
# 自定义镜像源（示例为清华源）
python server.py --mirror_source=&quot;https://pypi.tuna.tsinghua.edu.cn/simple/&quot;
# 开启 Windows exe 安装模式；将 pdf2zh_next 可执行文件路径传入
#（例如 .\pdf2zh-v2.6.3-BabelDOC-v0.5.7-win64\pdf2zh\pdf2zh.exe）
python server.py --enable_winexe=True --winexe_path=&quot;xxxxxxx&quot;</code></pre><blockquote>注：首次/更新 需要输入两次<code>python server.py</code>来启动，第一次是安装必要依赖；第二次是启动服务。 启动成功的预期：终端会打印服务启动与监听端口信息（默认 8890）。若端口被占用，请改用 <code>--port</code> 指定新端口。</blockquote><h4>方法二</h4><blockquote>如果自动安装过程中，由于网络波动或资源文件下载缓慢导致虚拟环境创建失败，可以尝试此方法。</blockquote>“预热”指提前下载并安装依赖。预热仅首次需要，之后只执行 <code>python server.py</code>。<ol><li>使用预热uv版本</li></ol><pre><code class="lang-bash"># 1. 利用uv预热(首次安装)
# Windows用户:
.\install-with-uv.bat --warmup
# MacOS/Linux用户:
./install-with-uv.sh --warmup

# 预热后，您需要检查命令行中是否提示安装成功，如果安装失败，请不要进行下一步

# 2. 首次执行脚本
python server.py --skip_install=True

# install-with-uv.sh有三个选项:
# --warmup 对babeldoc的资源文件进行预热(需要一些时间)
# --upgrade 对当前包进行升级
# --no-mirror 不使用国内镜像源

# 3.以后执行版本
python server.py</code></pre><ol start="2"><li>使用conda预热版本</li></ol><pre><code class="lang-bash"># 1. 利用conda预热(首次安装)
# Windows用户:
.\install-with-conda.bat --warmup
# MacOS/Linux用户:
./install-with-conda.sh --warmup

# 预热后，您需要检查命令行中是否提示安装成功，如果安装失败，请不要进行下一步

# 2. 首次执行脚本
python server.py --env_tool=conda --skip_install=True

# install-with-conda.sh有三个选项:
# --warmup 对babeldoc的资源文件进行预热(需要一些时间)
# --upgrade 对当前包进行升级
# --no-mirror 不使用国内镜像源

# 3.以后执行脚本
# 指定虚拟环境工具为conda
python server.py --env_tool=conda</code></pre><h4>方法三：手动安装依赖</h4><blockquote>若上述两个自动安装失败，可手动创建虚拟环境后逐一安装依赖（成功则跳过此节）。</blockquote><h5>A. 为 pdf2zh_next (2.x) 手动安装</h5>方案 A1：用 uv（推荐）<blockquote>环境名：<code>zotero-pdf2zh-next-venv</code></blockquote><ol><li>Windows/CMD</li></ol><pre><code class="lang-bat">:: 进入 server 目录
cd server
:: 1) 创建虚拟环境
uv venv zotero-pdf2zh-next-venv --python 3.12
:: 2) 安装依赖（使用镜像）
uv pip install --python .\zotero-pdf2zh-next-venv\Scripts\python.exe --index-url https://mirrors.ustc.edu.cn/pypi/simple pdf2zh_next pypdf PyMuPDF flask toml</code></pre>若有打开虚拟环境的需求：<pre><code class="lang-bat"># cmd
zotero-pdf2zh-next-venv\Scripts\activate
# powershell
.\zotero-pdf2zh-next-venv\Scripts\Activate.ps1</code></pre><ol start="2"><li>macOS / Linux</li></ol><pre><code class="lang-bash"># 进入 server 目录
cd server
# 1) 创建虚拟环境
uv venv zotero-pdf2zh-next-venv --python 3.12
# 2) 安装依赖（使用镜像）
uv pip install --python ./zotero-pdf2zh-next-venv/bin/python --index-url https://mirrors.ustc.edu.cn/pypi/simple pdf2zh_next pypdf PyMuPDF flask toml</code></pre>若有打开虚拟环境的需求：<pre><code class="lang-bash">source ./zotero-pdf2zh-next-venv/bin/activate</code></pre>方案 A2：用 conda<pre><code class="lang-bash"># 进入 server 目录
cd server
# 1) 创建环境
conda create -n zotero-pdf2zh-next-venv python=3.12 -y
# 2) 安装依赖（使用镜像）
conda run -n zotero-pdf2zh-next-venv pip install --index-url https://mirrors.ustc.edu.cn/pypi/simple pdf2zh_next pypdf PyMuPDF flask toml</code></pre>若有打开虚拟环境的需求：<pre><code class="lang-bash">conda activate zotero-pdf2zh-next-venv</code></pre><h5>B. 为 pdf2zh (1.x) 手动安装</h5>方案 A1：用 uv（推荐）<blockquote>环境名：<code>zotero-pdf2zh-venv</code>（与脚本一致）</blockquote><ol><li>Windows/CMD</li></ol><pre><code class="lang-bat">:: 进入 server 目录
cd server
:: 1) 创建虚拟环境（Python 3.12）
uv venv zotero-pdf2zh-venv --python 3.12
:: 2) 安装依赖（使用科大镜像）
uv pip install --python .\zotero-pdf2zh-venv\Scripts\python.exe --index-url https://mirrors.ustc.edu.cn/pypi/simple pdf2zh==1.9.11 pypdf PyMuPDF flask numpy==2.2.0 toml pdfminer.six==20250416</code></pre>若有打开虚拟环境的需求：<pre><code class="lang-bat"># cmd
zotero-pdf2zh-venv\Scripts\activate
# powershell
.\zotero-pdf2zh-venv\Scripts\Activate.ps1</code></pre><ol start="2"><li>macOS / Linux</li></ol><pre><code class="lang-bash"># 进入 server 目录
# 进入 server 目录
cd server
# 1) 创建虚拟环境（Python 3.12）
uv venv zotero-pdf2zh-venv --python 3.12
# 2) 安装依赖（使用科大镜像）
uv pip install --python ./zotero-pdf2zh-venv/bin/python --index-url https://mirrors.ustc.edu.cn/pypi/simple pdf2zh==1.9.11 pypdf PyMuPDF flask numpy==2.2.0 toml pdfminer.six==20250416</code></pre>若有打开虚拟环境的需求：<pre><code class="lang-bash">source ./zotero-pdf2zh-venv/bin/activate</code></pre>方案 A2：用 conda<blockquote>依然使用环境名：<code>zotero-pdf2zh-venv</code></blockquote><pre><code class="lang-bash"># 进入 server 目录
# 进入 server 目录
cd server
# 1) 创建环境
conda create -n zotero-pdf2zh-venv python=3.12 -y
# 2) 安装依赖（使用科大镜像）
conda run -n zotero-pdf2zh-venv pip install --index-url https://mirrors.ustc.edu.cn/pypi/simple pdf2zh==1.9.11 pypdf PyMuPDF flask numpy==2.2.0 toml pdfminer.six==20250416</code></pre>若有打开虚拟环境的需求：<pre><code class="lang-bash">conda activate zotero-pdf2zh-venv</code></pre><blockquote>注：若还不行，可以把您使用的代码发给ai，让ai帮您更换一个适合您的镜像源。</blockquote><hr><h3>使用pdf2zh_next的exe启动服务</h3><pre><code class="lang-shell">python server.py --enable_winexe=True --winexe_path=&quot;Your\path\to\pdf2zh\pdf2zh.exe&quot;</code></pre><hr><h3>第四步：开始翻译</h3>插件设置路径：编辑 → 首选项 → PDF2zh。在此可切换翻译引擎、配置 API 服务（Base URL、API Key、模型名等）与并发/QPS 参数。随后在 Zotero 主界面选中文献，右键选择相关操作即可。<ul><li>翻译PDF (Translate PDF)：对选中的原文 PDF 生成译文版本（单语/双语取决于插件设置）。</li><li>裁剪PDF (Crop PDF)：适用于双语或单语附件。自动裁剪两侧空白，并按页面宽度一分为二后上下拼接，便于小屏阅读。若过裁剪，可在 <code>server/utils/config.py</code> 调整 <code>config.pdf_w_offset</code>。</li><li>双语对照 (Compare PDF)：生成“左原右译”的双语 PDF。可在设置中选“Dual 文件翻译页在前”调整顺序。</li><li>双语对照（裁剪）(Crop-Compare PDF)：专为双栏论文设计；先沿中缝垂直裁成单栏，再进行左右拼接。</li></ul><blockquote>运行提示：若插件调用到服务器失败，请首先确认 <code>server.py</code> 是否在运行、监听端口是否与插件设置一致，防火墙/安全软件是否放行本地端口。</blockquote><h3>一键启动脚本</h3><h4>第一步：获取 <code>server.py</code> 的目录路径</h4><ol><li>先把终端/命令行打开到 <code>server.py</code> 所在的文件夹<ul><li>Windows：打开放有 <code>server.py</code> 的文件夹，在空白处按住 Shift 右键 → 在终端中打开（或地址栏输入 <code>powershell/cmd</code> 回车）。</li><li>macOS：在 Finder 里打开该文件夹，右键空白处 → 服务 → 在文件夹位置打开新终端（没有的话，可先打开“终端”后用 <code>cd</code> 进入这个文件夹）。</li><li>Linux：打开“终端”，用 <code>cd</code> 进入放有 <code>server.py</code> 的文件夹。</li></ul></li><li>复制下面这一行回车执行（这行用的是 Python 自带的 <code>pathlib</code> 库，不需要 <code>pip</code> 安装）：<pre><code class="lang-bash">python -c &quot;import pathlib; print(pathlib.Path('server.py').resolve().parent)&quot;</code></pre><ul><li>如果你的电脑只有 <code>python3</code> 命令，把上面的 <code>python</code> 换成 <code>python3</code>。</li><li>Windows 如果 <code>python</code> 不行，试试：<pre><code class="lang-powershell">py -3 -c &quot;import pathlib; print(pathlib.Path('server.py').resolve().parent)&quot;</code></pre></li></ul></li><li>终端会输出一行目录路径，复制这行：<ul><li>Windows 例子：<code>D:\work\myapp\server</code></li><li>macOS/Linux 例子：<code>/Users/you/work/myapp/server</code></li></ul></li></ol>请复制并保存好这行路径，我们马上就要用它！<h4>第二步：选你的模板并复制</h4>根据你的电脑系统，选择一个对应的模板。如果你是 Windows 用户，请复制这个：<pre><code class="lang-bat">@echo off
chcp 65001 &gt;nul
set PYTHONUTF8=1
rem ← 只需要修改下面这一行
set &quot;PROJECT_PATH=这里替换成你的路径&quot;
python &quot;%PROJECT_PATH%\server.py&quot;
pause</code></pre>如果你是 macOS 或 Linux 用户，请复制这个：<pre><code class="lang-sh">#!/usr/bin/env bash
set -euo pipefail
export PYTHONUTF8=1
# ← 只需要修改下面这一行
PROJECT_PATH=&quot;这里替换成你的路径&quot;
cd &quot;$PROJECT_PATH&quot;
python3 server.py
read -rp $'完成。按 Enter 退出…' _</code></pre><blockquote>若您能看懂该脚本，知道修改哪里，那么请直接到第四步。</blockquote><h4>第三步：让 AI 帮你生成脚本</h4>现在，我们要请一位的 AI 助手<a class="no-external-link" href="https://deepseek.com/" target="_blank">DeepSeek</a>来帮我们生成脚本。<ol><li>先复制下面这段话：<blockquote>你好，请你根据我提供的路径和这个模板，生成一个可以直接供我使用的自动化脚本，并告诉我怎么用。</blockquote></li><li>紧接着，粘贴你在第一步获取的路径。</li><li>最后，粘贴你在第二步选择的对应模板。</li></ol>把这三段内容组合在一起，像下面这个样子，然后一次性发给 AI：<blockquote>发送给AI的完整示例：你好，请你根据我提供的路径和这个模板，生成一个可以直接供我使用的自动化脚本，并告诉我怎么用。我的路径是：<code>D:\project\server</code>我的模板是：<pre><code class="lang-DOS">@echo off
chcp 65001 &gt;nul
set PYTHONUTF8=1
rem ← 只需要修改下面这一行
set &quot;PROJECT_PATH=这里替换成你的路径&quot;
python &quot;%PROJECT_PATH%\server.py&quot;
pause</code></pre></blockquote>AI 会非常聪明地帮你把路径填好，并生成最终的完美脚本代码。<h4>第四步：运行脚本</h4>AI 已经把最终的脚本代码给你了，现在我们只需要把它保存成一个可执行的文件。对于 Windows 用户 (.bat 文件):<ol><li>在电脑任意位置（比如桌面）右键，选择“新建” -&gt; “文本文档”。</li><li>打开这个新建的文本文档，把你从 AI 那里复制来的最终代码粘贴进去。</li><li>点击左上角的“文件”，选择“另存为”。</li><li>在弹出的窗口中，最关键的一步：<ul><li>“保存类型”：一定要选择“所有文件 (<code>*.*</code>)”。</li><li>“文件名”：给它取个名字，但后缀必须是 <code>.bat</code>。例如：<code>一键启动.bat</code>。</li></ul></li><li>点击“保存”。现在，桌面上就出现了一个带齿轮图标的文件。</li></ol>对于 macOS / Linux 用户 (.sh 文件):<ol><li>打开“文本编辑” (TextEdit) 或任何文本编辑器。</li><li>把 AI 生成的最终代码粘贴进去。<ul><li>Mac 用户请注意：如果用的是“文本编辑”，请在菜单栏选择“格式” -&gt; “制作纯文本”，确保是纯文本模式。</li></ul></li><li>保存文件。给它取个名字，后缀必须是 <code>.sh</code>。例如：<code>startup.sh</code>，并将它保存在你喜欢的位置（比如桌面）。</li><li>最后一步，赋予它运行的权限。打开“终端”，输入 <code>chmod +x</code> （注意 <code>+x</code> 后面有个空格），然后把刚才保存的 <code>.sh</code> 文件从桌面拖到终端窗口里，最后按回车。</li></ol><hr><h2>Part 2：Docker 部署（Compose）</h2><blockquote>如果你想使用 pdf2zh（1.x）作为翻译引擎，请直接跳到文末章节：“（可选）切换为 pdf2zh”。</blockquote><h3>第一步：确认 Docker 环境就绪</h3><pre><code class="lang-bash">docker version
docker compose version</code></pre><blockquote>如果显示不了 <code>docker compose</code>，你可能安装的是老版 <code>docker-compose</code>，后续命令把 <code>docker compose</code> 换成 <code>docker-compose</code> 即可。</blockquote><hr><h3>第二步：下载并准备 Docker 配置文件</h3><h4>Windows（CMD）</h4><pre><code class="lang-cmd">mkdir zotero-pdf2zh_docker
cd zotero-pdf2zh_docker

REM 下载
curl -L -o docker.zip https://raw.githubusercontent.com/guaguastandup/zotero-pdf2zh/main/docker.zip

REM 解压（任选一种；如命令行解压失败，可在资源管理器中右键解压到当前目录）
powershell -Command &quot;Expand-Archive -Path '.\docker.zip' -DestinationPath '.' -Force&quot;
REM 或者（如果 tar 可用）
REM tar -xf docker.zip

REM 进入 docker 子目录（里面有 Dockerfile 和 docker-compose.yaml）
cd docker</code></pre><h4>macOS / Linux（终端）</h4><pre><code class="lang-bash">mkdir -p zotero-pdf2zh_docker
cd zotero-pdf2zh_docker

# 下载
curl -L -o docker.zip https://raw.githubusercontent.com/guaguastandup/zotero-pdf2zh/main/docker.zip

# 解压（任选其一）
unzip -o docker.zip -d .
# 或
# tar -xf docker.zip

# 进入 docker 子目录（里面有官方 Dockerfile 和 docker-compose.yaml）
cd docker</code></pre>解压后的 <code>docker/</code> 目录包含：<pre><code class="lang-txt">Dockerfile
docker-compose.yaml
config/ （空文件夹，用于挂载配置）
translated/ （空文件夹，用于挂载输出）</code></pre><hr><h3>第三步：预拉取核心镜像 (推荐)</h3>为避免首次启动时因网络问题导致超时，建议先手动拉取 <code>pdf2zh_next</code> 的 Docker 镜像。<pre><code class="lang-bash">docker pull awwaawwa/pdfmathtranslate-next:latest</code></pre>Docker镜像加速 如果你（或你的组织）有可靠的镜像加速端点，可以在 Docker 里配置“registry-mirrors”，让所有 docker pull 走加速：Docker Desktop（Win/macOS）：Settings → Docker Engine，在 JSON 中加入：<pre><code class="lang-json">{

&quot;registry-mirrors&quot;: [&quot;https://&lt;your-mirror-endpoint&gt;&quot;]

}</code></pre><hr><h3>第四步：启动服务</h3>在 <code>zotero-pdf2zh_docker/docker</code> 目录下，执行以下命令：<pre><code class="lang-bash">docker compose up -d --build</code></pre>当您看到类似下面的日志输出时，代表服务已成功启动：<pre><code class="lang-cmd">* Running on http://127.0.0.1:8890
* Running on http://172.18.0.2:8890</code></pre>常用 Docker 管理命令：<pre><code class="lang-cmd">docker start zotero-pdf2zh # 启动已存在的容器
docker stop zotero-pdf2zh # 停止容器
docker logs -f zotero-pdf2zh # 查看实时日志，用于排查问题
docker compose down # 停止并移除容器</code></pre><hr><h3>（可选）切换为 <code>pdf2zh</code> （1.x）</h3><blockquote>默认镜像是 <code>pdf2zh_next</code>。如果你只想用 1.x <code>pdf2zh</code>（<code>byaidu/pdf2zh:1.9.6</code>），按下述最小改动即可。</blockquote><h4>0）预拉取经典镜像</h4><pre><code class="lang-bash">docker pull byaidu/pdf2zh:1.9.6</code></pre><hr><h4>1) 修改 Dockerfile</h4>A. 更换镜像变量，改为1.x找到：<pre><code class="lang-dockerfile">ZOTERO_PDF2ZH_FROM_IMAGE=awwaawwa/pdfmathtranslate-next:latest</code></pre>改为：<pre><code class="lang-dockerfile">ZOTERO_PDF2ZH_FROM_IMAGE=byaidu/pdf2zh:1.9.6</code></pre>B. 删除“next 包装器”整段找到<pre><code class="lang-dockerfile">RUN printf '%s\n' \
 '#!/usr/bin/env bash' \
 'set -euo pipefail' \
 'img=&quot;${ZOTERO_PDF2ZH_FROM_IMAGE:-awwaawwa/pdfmathtranslate-next:latest}&quot;' \
 'cid=&quot;$(cat /etc/hostname)&quot;' \
 'exec docker run --rm --volumes-from &quot;${cid}&quot; -e TZ -e http_proxy -e https_proxy -e HF_ENDPOINT &quot;$img&quot; pdf2zh_next &quot;$@&quot;' \
 &gt; /usr/local/bin/pdf2zh_next &amp;&amp; chmod +x /usr/local/bin/pdf2zh_next</code></pre>整块修改为：<pre><code class="lang-dockerfile">RUN printf '%s\n' \
 '#!/usr/bin/env bash' \
 'set -euo pipefail' \
 'img=&quot;${ZOTERO_PDF2ZH_FROM_IMAGE:-byaidu/pdf2zh:1.9.6}&quot;' \
 'cid=&quot;$(cat /etc/hostname)&quot;' \
 'exec docker run --rm --volumes-from &quot;${cid}&quot; -e TZ -e http_proxy -e https_proxy -e HF_ENDPOINT &quot;$img&quot; pdf2zh &quot;$@&quot;' \
 &gt; /usr/local/bin/pdf2zh &amp;&amp; chmod +x /usr/local/bin/pdf2zh</code></pre><blockquote>其它内容（server.zip 下载、requirements 安装、entrypoint）保持不变。</blockquote><h4>2) 修改 <code>docker-compose.yaml</code></h4>找到<pre><code class="lang-yaml">ZOTERO_PDF2ZH_FROM_IMAGE: awwaawwa/pdfmathtranslate-next:latest</code></pre>改为：<pre><code class="lang-yaml">ZOTERO_PDF2ZH_FROM_IMAGE: byaidu/pdf2zh:1.9.6</code></pre>如需挂字体（可选，字体文件与 <code>docker-compose.yaml</code> 同级）：<pre><code class="lang-yaml">volumes:
 - ./translated:/app/server/translated
 - ./config:/app/server/config
 - ./LXGWWenKai-Regular.ttf:/app/LXGWWenKai-Regular.ttf:ro # 可选
 - /var/run/docker.sock:/var/run/docker.sock</code></pre><h4>3) 重构启动（在 <code>docker</code> 目录）</h4><pre><code class="lang-bash">docker compose down
docker compose up -d --build</code></pre>常用命令：<pre><code class="lang-cmd">docker start zotero-pdf2zh # 启动已存在的容器
docker stop zotero-pdf2zh # 停止容器
docker logs -f zotero-pdf2zh # 查看实时日志，用于排查问题
docker compose down # 停止并移除容器</code></pre><blockquote>插件里把 翻译引擎 选成 <code>pdf2zh</code>。祝您使用愉快！</blockquote><h3>Docker配置镜像下载的使用教程</h3>本项目在构建镜像时需要从 GitHub 下载 <code>server.zip</code>。默认使用官方源，如果你的网络访问 GitHub 生效较慢或失败，可按需启用以下两种镜像方式（二选一）：<ul><li>方法 1：给原始链接加“代理前缀”（如 <code>ghproxy.net</code>）</li><li>方法 2：直接把下载地址换成 jsDelivr CDN</li></ul><blockquote>每次修改构建源后，都请重新构建： <code>docker compose build --no-cache &amp;&amp; docker compose up -d</code></blockquote><h4>0. 默认不改（官方源 + pip 自动回退）</h4><ul><li>默认使用：<code>https://raw.githubusercontent.com/guaguastandup/zotero-pdf2zh/main/server.zip</code></li><li><code>pip</code> 安装依赖时：先官方 PyPI，失败自动回退 USTC。 （无需任何改动即可工作，适合网络正常时使用。）</li></ul>1）方法一：开启“代理前缀”镜像适用：希望保留原始 <code>raw.githubusercontent.com</code> 链接，只在前面加个国内可达的反代前缀（例如 <code>https://ghproxy.net/</code>）。操作步骤<ol><li>打开 <code>docker-compose.yml</code>，在 <code>build.args</code> 下取消注释并设置：<pre><code class="lang-yaml">services:
 pdf2zh-server:
 build:
 args:
 GITHUB_PROXY_PREFIX: &quot;https://ghproxy.net/&quot;</code></pre><blockquote>你也可以换成你常用的其他前缀域名。</blockquote></li><li>重新构建并启动：<pre><code class="lang-bash">docker compose build --no-cache
docker compose up -d</code></pre></li></ol><blockquote>备注：代理前缀服务通常为第三方社区反代，稳定性与可用性请自评估。无法访问时可更换域名或改用方法二。</blockquote>2）方法二：改用 jsDelivr（CDN）适用：公开仓库中的单个文件下载，CDN 稳定缓存，速度通常更好。操作步骤<ol><li>打开 <code>docker-compose.yml</code>，在 <code>build.args</code> 下改写 <code>SERVER_ZIP_URL</code>（并且确保 <code>GITHUB_PROXY_PREFIX</code> 留空或注释）：<pre><code class="lang-yaml">services:
 pdf2zh-server:
 build:
 args:
 SERVER_ZIP_URL: &quot;https://cdn.jsdelivr.net/gh/guaguastandup/zotero-pdf2zh@main/server.zip&quot;
 # GITHUB_PROXY_PREFIX: # 留空或注释</code></pre></li><li>重新构建并启动：<pre><code class="lang-bash">docker compose build --no-cache
docker compose up -d</code></pre></li></ol><hr><h2>Part 3：连接 Zotero 并开始翻译</h2>无论您选择哪种部署方式，最后一步都是在 Zotero 插件中配置并使用它。<ol><li>插件设置：在 Zotero 中，导航至 “编辑” -&gt; “首选项” -&gt; “PDF2zh” 选项卡。</li><li>服务地址：确保服务地址与您的后端服务一致。默认是 <code>http://127.0.0.1:8890</code> 或 <code>http://localhost:8890</code>。如果您在启动时修改了端口，请在此处同步更新。</li><li>模型配置：在此处配置您的翻译引擎（如 <code>pdf2zh_next</code>）、API 服务商的 Base URL 和 API Key。</li><li>开始翻译：回到 Zotero 主界面，选中一篇或多篇文献条目，右键单击，在菜单中选择 “开始翻译”。</li></ol><h2>Part 4：常见问题解答（FAQ）</h2>Q1：第一次翻译进度条卡在 <code>translate 10/100</code> 很久？ A：<ul><li>建议开启代理/镜像加速首次资源下载；</li><li>或直接在 <a class="no-external-link" href="https://github.com/PDFMathTranslate/PDFMathTranslate-next/releases" target="_blank">PDFMathTranslate-next Releases</a> 下载 带 <code>assets</code> 的 Windows 压缩包（内置常用字体/资源），解压后双击 <code>pdf2zh.exe</code>，访问 WebUI <code>http://127.0.0.1:7860/</code> 翻译任意 1 页触发资源释放。</li></ul>Q2：Windows 报 “DLL 初始化失败/缺少运行库”？ A：安装 Microsoft Visual C++ 2015–2022（x64） 。Q3：Zotero 无进度条、任务未启动？ A：优先检查 Zotero ↔ 本地服务 连通性（端口/回环地址/代理），并核对插件中的服务地址 <code>http://localhost:8890</code> 是否与后端一致（默认即为 8890）。Q4：服务端返回 401/403/404/429 或端点不可达？ A：逐项核实 Base URL / API Key / 模型名 / 速率；根据服务商限制临时降低 QPS/并发，观察是否恢复。Q5：线程/速率如何估算？ A：以服务商 RPM/TPM 为上限，从保守的 QPS 值启动并逐步压测： <code>QPS = ⌊ RPM / 60 ⌋</code>。Q6：比较推荐哪个服务/大模型？ A：<ol><li>siliconflowfree（免配置）：<a class="no-external-link" href="https://siliconflow.cn/" target="_blank">硅基流动</a>提供的免费通道（当前为 <code>THUDM/GLM-4-9B-0414</code>），适合入门与临时使用；</li><li>火山引擎（开发者/协作计划）：每个模型每日50w额度，具体可见<a class="no-external-link" href="https://www.volcengine.com/docs/82379/1391869" target="_blank">协作奖励计划规则、-火山引擎</a>；</li><li>“非思考”模型优先：多数论文/学术 PDF 翻译更看重稳定与速度，尽量使用非思考版；（think模型会带来巨大的token开销，且不稳定）</li><li>高性价比口碑：<code>deepseek-v3</code>、<code>qwen-plus-latest</code> 等反馈较好（需自配 API Key）。</li><li>不建议使用机翻：BabelDOC是专门为大模型做的服务，bing、google等机翻服务不建议使用。</li></ol><blockquote>提示：免费服务策略可能变化，请以各平台控制台实际配额与速率为准。</blockquote>Q7：我实在是搞不定部署应该怎么办 A：打开网页：<a class="no-external-link" href="https://immersivetranslate.com/?via=4641d7" target="_blank">沉浸式翻译</a> ➡️常用功能➡️Babeldoc ➡️ 登陆账号 拖入文件 开始翻译<h3>获取更多帮助</h3>如果以上内容未能解决您的问题，可以通过以下渠道寻求支持：<ol><li>阅读更详尽的 <a class="no-external-link" href="https://docs.qq.com/markdown/DU0RPQU1vaEV6UXJC" target="_blank">常见问题文档</a></li><li>在项目的 <a class="no-external-link" href="https://github.com/guaguastandup/zotero-pdf2zh/issues" target="_blank">GitHub Issues</a> 区提交您的问题。</li><li>加入用户 QQ 群: 971960014 (入群验证: github)。提问时，请附上： 1）终端的完整报错日志（复制为文本.txt） 2）Zotero 插件的配置截图 3）报错弹窗截图 4）问题 PDF 文件。</li></ol>若您觉得本博文做的还不错，欢迎支持<a class="no-external-link" href="https://afdian.com/a/rosetears" target="_blank">她笑中藏泪花 | 爱发电</a>感谢您的支持，祝您使用愉快！！

引言

环境依赖

Part 1：Python部署

第一步: 安装uv

手动安装uv

第二步: 下载并解压项目文件

第三步: 安装依赖并启动服务

方法一：直接启动

方法二

方法三：手动安装依赖

A. 为 pdf2zh_next (2.x) 手动安装

B. 为 pdf2zh (1.x) 手动安装

使用pdf2zh_next的exe启动服务

第四步：开始翻译

一键启动脚本

第一步：获取 server.py 的目录路径

第二步：选你的模板并复制

第三步：让 AI 帮你生成脚本

第四步：运行脚本

Part 2：Docker 部署（Compose）

第一步：确认 Docker 环境就绪

第二步：下载并准备 Docker 配置文件

Windows（CMD）

macOS / Linux（终端）

第三步：预拉取核心镜像 (推荐)

第四步：启动服务

（可选）切换为 pdf2zh （1.x）

0）预拉取经典镜像

1) 修改 Dockerfile

2) 修改 docker-compose.yaml

3) 重构启动（在 docker 目录）

Docker配置镜像下载的使用教程

0. 默认不改（官方源 + pip 自动回退）

Part 3：连接 Zotero 并开始翻译

Part 4：常见问题解答（FAQ）

获取更多帮助

1 条评论

发表评论 取消回复 使用cookie技术保留您的个人信息以便您下次快速评论，继续评论表示您已同意该条款

【Zotero-pdf2zh】快速搞定 PDF 翻译，完美保留原文格式

第一步：获取 `server.py` 的目录路径

（可选）切换为 `pdf2zh` （1.x）

2) 修改 `docker-compose.yaml`

3) 重构启动（在 `docker` 目录）

发表评论取消回复
使用cookie技术保留您的个人信息以便您下次快速评论，继续评论表示您已同意该条款