引言

在学术研究中，阅读外文文献是常态，而一款能在翻译时保留原文格式的工具则至关重要。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】快速搞定 PDF 翻译，完美保留原文格式_哔哩哔哩_bilibili

环境依赖

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。

  1. 使用预热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
  1. 使用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
  1. 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
  1. 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（与脚本一致）
  1. 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
  1. 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 的目录路径

  1. 先把终端/命令行打开到 server.py 所在的文件夹

    • Windows：打开放有 server.py 的文件夹，在空白处按住 Shift 右键 → 在终端中打开（或地址栏输入 powershell/cmd 回车）。
    • macOS：在 Finder 里打开该文件夹，右键空白处 → 服务 → 在文件夹位置打开新终端（没有的话，可先打开“终端”后用 cd 进入这个文件夹）。
    • Linux：打开“终端”，用 cd 进入放有 server.py 的文件夹。

  2. 复制下面这一行回车执行（这行用的是 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)"

  3. 终端会输出一行目录路径，复制这行：

    • 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来帮我们生成脚本。

  1. 先复制下面这段话：

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

把这三段内容组合在一起，像下面这个样子，然后一次性发给 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 文件):

  1. 在电脑任意位置（比如桌面）右键，选择“新建” -> “文本文档”。
  2. 打开这个新建的文本文档，把你从 AI 那里复制来的最终代码粘贴进去。
  3. 点击左上角的“文件”，选择“另存为”。

  4. 在弹出的窗口中，最关键的一步：

    • “保存类型”：一定要选择“所有文件 (*.*)”。
    • “文件名”：给它取个名字，但后缀必须是 .bat。例如：一键启动.bat。
  5. 点击“保存”。现在，桌面上就出现了一个带齿轮图标的文件。

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

  1. 打开“文本编辑” (TextEdit) 或任何文本编辑器。

  2. 把 AI 生成的最终代码粘贴进去。

    • Mac 用户请注意：如果用的是“文本编辑”，请在菜单栏选择“格式” -> “制作纯文本”，确保是纯文本模式。
  3. 保存文件。给它取个名字，后缀必须是 .sh。例如：startup.sh，并将它保存在你喜欢的位置（比如桌面）。
  4. 最后一步，赋予它运行的权限。打开“终端”，输入 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/）。

操作步骤

  1. 打开 docker-compose.yml，在 build.args 下取消注释并设置：

    services:
  pdf2zh-server:
    build:
      args:
        GITHUB_PROXY_PREFIX: "https://ghproxy.net/"
    你也可以换成你常用的其他前缀域名。

  2. 重新构建并启动：

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

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

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

操作步骤

  1. 打开 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:  # 留空或注释

  2. 重新构建并启动：

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

Part 3：连接 Zotero 并开始翻译

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

  1. 插件设置：在 Zotero 中，导航至 “编辑” -> “首选项” -> “PDF2zh” 选项卡。
  2. 服务地址：确保服务地址与您的后端服务一致。默认是 http://127.0.0.1:8890 或 http://localhost:8890。如果您在启动时修改了端口，请在此处同步更新。
  3. 模型配置：在此处配置您的翻译引擎（如 pdf2zh_next）、API 服务商的 Base URL 和 API Key。
  4. 开始翻译：回到 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：

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

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

获取更多帮助

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

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

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

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

最后修改：2025 年 10 月 14 日
© 允许规范转载
如果您觉得本文还不错，欢迎打赏支持