【PDF2zh 2.0】三种部署指南与 Zotero 插件配置

写在前面：让 PDF 论文翻译不再是噩梦

还在为密密麻麻的英文 PDF 论文头疼吗？好消息是，PDF2zh 2.0 带着它的全新引擎 BabelDOC 来了！这次升级不仅带来了更优雅、更忠于原文的排版，还让翻译体验丝滑得不像话。
本文将是一份超详细的“保姆级”教程，专为几乎没有编程经验的“代码小白”量身定制。我们将手把手带你走通三种主流部署方案：

1. 懒人福音：Windows .exe 一键启动。
2. 极客之选：使用 uv 搭建本地 Python 虚拟环境，体验飞一般的速度。
3. 省心大法：通过 Docker 容器化部署，一次配置，处处运行。

同时，我们也会讲清楚如何配置 Zotero-PDF2zh 插件，让你的文献管理与翻译工作流无缝衔接。

⚙️ 运行环境示例
• Windows 11 64-bit
• Python 3.12.8
• Docker 28.1.1

传送门：

• PDF2zh 2.0 项目主页：pdf2zh-next.com
• Zotero-PDF2zh 插件仓库：guaguastandup/zotero-pdf2zh
• BabelDOC 引擎仓库：funstory-ai/BabelDOC

本博文视频讲解：【PDF2zh 2.0】三种部署指南与 Zotero 插件配置_哔哩哔哩_bilibili

1. 关键须知：部署前的“排雷”清单

在开始之前，请务必阅读以下关键信息，这能帮你避免 90% 的常见问题。

工具概览

🚨重大兼容性警告：请仔细阅读！

新旧版本服务不互通

PDF2zh 2.0 (pdf2zh_next) 是一个全新的大版本，其服务与 1.x 版本完全不兼容。如果你电脑上安装过旧版，建议在开始前将其卸载，以免冲突。

# 检查是否安装了旧版
pip show pdf2zh
# 如果有，则卸载
pip uninstall pdf2zh

PDF 文件格式要求

用于翻译的 PDF 文档必须是文本可选、可复制的格式。如果你的 PDF 是扫描件（即图片），请在翻译时启用 OCR workaround 选项。为了省心，可以直接在 Web UI 设置中开启 Auto enable OCR workaround，让程序自动探测。

2. 如何选择最适合的路线？

三条大路通罗马，哪条是你的“天选之路”？看这张表就够了。

作者建议：

• “我只想点点鼠标，需求只有GUI” → 路线 A。下载、解压、双击，三步搞定，立即体验核心翻译功能。
• Python 爱好者/开发者 → 路线 B。uv 的速度与优雅，一旦用过就再也回不去了。
• 追求稳定与“一劳永逸” → 路线 C。Docker 是现代开发的黄金标准，帮你屏蔽一切环境差异，今天能用，明天、换台电脑、分享给朋友，照样能用。
• 选择困难症？小白一枚？ → 听我的，直接上 路线 C。Docker 就是你的“环境金钟罩”，能帮你挡掉绝大多数莫名其妙的本地问题。

PDF2zh vs. 沉浸式翻译

• 成本考量: PDF2zh 2.0 自行部署需承担 API调用费用（翻译一页约消耗8,000 Tokens）。作为对比，商业服务“沉浸式翻译”的 Pro 会员提供了按月付费的翻译额度（具体价格请以官方为准）。
• 选择建议: 如果你翻译量巨大、追求极致便利性，或者不想折腾本地环境，付费的商业翻译服务或许是更省心的选择。反之，如果你享受 DIY 的乐趣，并希望对翻译过程有完全的控制权，PDF2zh 是你的不二之选。

3. 部署前准备

根据你选择的路线，按需准备。

4. 路线 A：Windows .exe 极速体验

此路线最为简单，三步搞定，无需任何编程知识。

1. 第一步：下载
   前往 PDF2zh 2.0 Releases 页面。

2. 第二步：选择正确的版本
   找到并下载名为 pdf2zh-<version>-with-assets-win64.zip 的文件。

   下载贴士：

   • 强烈推荐 *-with-assets-* 版本，它已打包所有必需的字体和模型，可完全离线运行。
   • 不带 assets 的版本，首次运行时需在线下载资源，若网络环境不佳极易失败。

3. 第三步：运行
   解压下载的 .zip 文件，找到并双击 pdf2zh.exe。程序启动后，应该会自动在你的默认浏览器中打开 Web UI。
4. 第四步：手动访问 (如果需要)
   如果浏览器没有自动弹出，请手动打开浏览器，在地址栏输入 http://127.0.0.1:7860/ 并访问。

5. 路线 B：本地虚拟环境 + Uvicorn (uv 驱动)

此路线为你提供一个由 uv 管理的、干净且高效的本地 Python 运行环境。这是目前在 pdf2zh 2.0 版本下，唯一支持 Zotero 插件联动的官方推荐路线。

我们将分两步完成：

1. 基础环境搭建：安装并配置 pdf2zh，实现命令行和 Web UI 的基本翻译功能。
2. Zotero 联动配置：搭建一个专门服务于 Zotero 的后台进程，实现“一键翻译”的终极体验。

第一部分：搭建基础 uv 环境并运行 pdf2zh

小贴士
下文默认你已正确安装 Python 与 pip。uv 会利用你已有的 Python，但如果你是完全从零开始，建议先访问 Python 官网 完成基础安装。

步骤 1：安装 uv 并创建虚拟环境

1. 创建项目文件夹：在你的硬盘上选择一个合适的位置，创建一个专门用于本项目的文件夹。

   • win/macOS / Linux:

     mkdir zotero-pdf2zh2.0 && cd zotero-pdf2zh2.0 # 在你喜欢的位置创建项目文件夹并进入

   • 通过图形界面创建: 在任意位置（例如 D:\projects\）右键新建文件夹，命名为 zotero-pdf2zh2.0。

2. 打开终端窗口：

   • Windows 用户: 在刚刚创建的文件夹的地址栏中输入 cmd 或 powershell，然后按回车，即可在当前目录下快速启动终端。
   • macOS / Linux 用户: 在文件夹上右键选择“在终端中打开”，或直接使用 cd 命令导航至该目录。

3. 执行 uv 命令三连：

   # 步骤一：安装 uv (如果网络通畅，推荐此法)
   # 此命令会从官方源下载并执行安装脚本，推荐使用。
   powershell -ExecutionPolicy ByPass -c "irm https://astral.sh/uv/install.ps1 | iex"
   
   # 备用方法：如果已安装 Python 和 pip，也可用 pip 安装 uv
   # pip install uv
   
   # 步骤二：使用 uv 创建一个名为 .venv 的虚拟环境，并指定使用 Python 3.13
   # 编者注：uv 会自动查找你电脑上已安装的 Python 3.13，如果没有则会提示下载。
   uv python install 3.13  # 安装3.13版本python
   uv venv --python 3.13
   
   # 步骤三：激活（进入）这个虚拟环境，成功后命令行前面会出现 (zotero-pdf2zh2.0) 标志
   .\.venv\Scripts\activate

🖼️ 配图示例

Linux / macOS

# 创建并进入项目文件夹
mkdir -p ~/projects/pdf2zh
cd ~/projects/pdf2zh

# 步骤一：安装 uv
curl -LsSf https://astral.sh/uv/install.sh | sh

# 备用方法：如果已安装 Python 和 pip，也可用 pip 安装 uv
# pip install uv

# 步骤二：创建虚拟环境
uv python install 3.13  # 安装3.13版本python
uv venv --python 3.13

# 步骤三：激活虚拟环境
source .venv/bin/activate

✨ PyCharm 用户？ > > 新版 PyCharm (≥ 2023.3) 已原生支持 uv。在新建项目时，可以直接选择 uv 作为虚拟环境工具，IDE 会自动完成上述步骤。

PyCharm 2024.3.2 及更高版本已支持直接创建 uv 虚拟环境：

1. 新建项目。
2. 位置 选择虚拟环境目录。
3. 解释器类型 选 自定义环境
4. 环境 → uv。
5. 基础 Python 指定所需版本（示例：Python 3.13）。
6. 如本机未装 uv，可点击 安装 uv via pip 自动安装。

🖼️ 配图示例

步骤 2：安装pdf2zh

在已激活虚拟环境的终端中，执行以下命令：

# 使用 uv 安装 依赖，如果只有Gui需求那么只安装 pdf2zh_next
uv pip install pdf2zh_next pypdf flask

编者注： uv pip 命令与原生 pip 几乎完全兼容，但速度快得多。

如何更新 pdf2zh_next ？
同样在激活的虚拟环境中，运行：

uv pip install -U pdf2zh_next

步骤 3：日常使用方式

• 方式 1 ：Web UI

pdf2zh_next --gui         # 启动 Web UI 服务，默认监听 7860 端口

服务启动后，在浏览器访问 http://127.0.0.1:7860/ 即可看到熟悉的 Web 界面。保持这个命令行窗口不要关闭，服务才能持续运行。

• 方式 2 ：命令行翻译

# 示例：直接翻译一个位于桌面、文件名带空格的 PDF
# 编者注：带空格的文件路径最好用引号括起来
pdf2zh_next "C:\Users\YourName\Desktop\my test paper.pdf"

特别提示：

• 安装 pdf2zh_next 后，可通过命令 pdf2zh、pdf2zh2 或 pdf2zh_next 调用同一 CLI，三者等价；例如：

  pdf2zh example.pdf --pages 1-3

• 执行后，译文文件会直接输出在当前工作目录。
• 更多高级用法，请参阅 官方文档-高级用法。

第二部分：解锁 Zotero 联动终极形态

现在，让我们在已搭建好的环境基础上，配置 Zotero 插件，实现从文献管理到一键翻译的无缝工作流。

核心原理：Zotero 插件本身不执行复杂的翻译任务，它更像一个“调度员”。它会向本地的 8888 端口发送翻译请求。因此，我们需要启动一个专门的 server.py 脚本，让它作为“翻译管家”在该端口监听并响应 Zotero 的指令。

步骤 1：安装 Zotero-PDF2zh 插件

1. 前往 Zotero 插件市场 (中文社区) 或 GitHub Releases 下载最新版的插件 .xpi 文件。
2. 打开 Zotero，依次点击菜单栏 工具 → 插件。
3. 将下载的 .xpi 文件直接拖入弹出的插件窗口，即可自动安装。安装后重启 Zotero。

步骤 2：准备服务端文件

1. 准备必要文件
   回到我们最开始创建的文件夹下面，打开命令行窗口

# --- 第 1 步：确保你位于正确的项目目录 ---
cd "/path/to/your/zotero-pdf2zh2.0" # 你的文件夹路径

# --- 第 2 步：下载作为“翻译中介”的 server.py 脚本 ---
# 使用 curl 下载脚本到当前目录，并命名为 server.py
curl -o server.py "https://raw.githubusercontent.com/guaguastandup/zotero-pdf2zh/main/server.py"
# Windows 备用（powershell）
# powershell -command "Invoke-WebRequest -Uri 'https://raw.githubusercontent.com/guaguastandup/zotero-pdf2zh/main/server.py' -OutFile 'server.py'"

# [备用“笨办法”]
# 如果以上命令因网络问题失败，请手动：
# 1. 在浏览器中打开 "https://raw.githubusercontent.com/guaguastandup/zotero-pdf2zh/main/server.py"
# 2. 在打开的页面上右键 -> "另存为..."，将文件保存到你刚刚创建的 zotero-pdf2zh2.0 文件夹中。

# --- 第 3 步：创建一个用于存放翻译结果的文件夹 ---
mkdir translated         # 创建名为 translated 的文件夹，用于存放 Zotero 调用后生成的翻译 PDF

2. 生成并配置 config.toml

Zotero 服务端需要一个配置文件来读取你的 API Key 和翻译偏好。

• 生成配置：先在终端运行一次 pdf2zh_next --gui 启动 Web UI。在网页上配置好你的翻译服务（如填入 API Key）、模型等，并成功翻译一份任意小文档以确保配置生效并保存。

• 复制配置：关闭 Web UI，执行以下命令将生成的全局配置文件复制到我们当前的服务目录中。

  # 复制生成的 config.v3.toml 到当前目录并重命名为 config.toml
  # Windows (cmd):
  copy "%USERPROFILE%\.config\pdf2zh\config.v3.toml" config.toml
  # Windows (PowerShell):
  Copy-Item "$env:USERPROFILE\.config\pdf2zh\config.v3.toml" -Destination "config.toml"
  # macOS / Linux:
  cp ~/.config/pdf2zh/config.v3.toml ./config.toml

3. 启动 Zotero 专用服务

# 直接用虚拟环境的python解释器运行 server.py
uv run python server.py

此时，你的项目文件夹结构应该如下所示，非常清晰：

zotero-pdf2zh2.0/
├── .venv/         # uv 创建的虚拟环境
├── config.toml    # 你的翻译配置文件
├── server.py      # Zotero 监听服务脚本
└── translated/    # 存放翻译结果的文件夹

步骤 3：配置 Zotero 插件

1. 回到 Zotero，编辑 -> 首选项 -> PDF2zh。
2. 翻译引擎：选择 pdf2zh-next。
   
3. 配置文件路径：改为: ./config.toml
4. 翻译文件输出路径：改为./translated/或者留空
5. 其他选项按需配置即可。

在zotero插件中，pdf2zh-next可以配置字段:

• 翻译服务
• 线程数 (对应pdf2zh_next里的qps)
• 翻译文件输出路径
• 配置文件路径(格式为toml)
• 跳过最后几页不翻译
• 重命名条目为短标题
• 默认生成文件(不支持生成双语对照文件-单栏PDF)

支持的服务商自查方法：

想知道在 Zotero 中你的 pdf2zh_next 版本具体支持哪些翻译服务吗？可以查看以下路径：
zotero-pdf2zh2.0\.venv\Lib\site-packages\pdf2zh_next\translator\translator_impl (Windows)
或
zotero-pdf2zh2.0/.venv/lib/python3.13/site-packages/pdf2zh_next/translator/translator_impl (macOS/Linux)

文件夹内的 xx.py 文件名就对应着一个可用的翻译服务。例如，看到 openai.py 就意味着支持 OpenAI。动手能力强的用户甚至可以参照现有文件，自行编写新的翻译服务适配器。

懒人福音：一键启动本地翻译服务

每次启动本地翻译服务，都要打开黑乎乎的窗口，输入一长串记不住的命令，是不是感觉又麻烦又容易出错？别担心，下面这个“一键启动”脚本就是为你准备的！只需设置一次，之后双击一下就能搞定。

我们为 Windows 和 macOS / Linux 系统分别准备了脚本，请根据你的电脑系统选择对应的指南。

Windows 用户指南：创建 .bat 魔法脚本

这个脚本会自动帮你完成所有步骤：进入项目目录、激活“虚拟环境”、再运行服务程序。

@echo off
rem 设置窗口编码为 UTF-8，防止中文路径或提示语变成乱码
chcp 65001

rem ===【新手必读：请修改这里！】===
rem 下面这行路径需要换成你自己的！
set "PROJECT_PATH=D:\python_project\zotero-pdf2zh2.0"
rem ===【修改结束】===

echo.
echo ========================================================
echo               Zotero 翻译服务一键启动脚本
echo ========================================================
echo.

rem [步骤 1/3] 进入项目目录，若失败则退出
cd /d "%PROJECT_PATH%" >nul 2>&1
if errorlevel 1 (
    echo 错误：无法进入项目目录！请检查 PROJECT_PATH 设置是否正确。
    echo    你的路径设置是: %PROJECT_PATH%
    pause
    exit /b 1
)
echo [步骤 1/3] 已成功进入项目目录: %cd%
echo.

rem [步骤 2/3] 激活 Python 虚拟环境
echo [步骤 2/3] 正在激活 Python 虚拟环境...
call .\.venv\Scripts\activate
echo    - 虚拟环境已激活！
echo.

rem [步骤 3/3] 启动翻译服务
echo [步骤 3/3] 准备启动翻译服务...
uv run python server.py
echo    - 服务已启动！请勿关闭此窗口。
echo.

echo ========================================================
echo.
rem 为了能看到脚本输出，保持窗口开启
pause

手把手教你用：

1. 找到项目路径（关键一步！）

   • 打开你的“文件资源管理器”。
   • 找到你存放 zotero-pdf2zh2.0 的那个文件夹。
   • 单击文件夹顶部的地址栏（如下图所示），路径就会被完整选中。
   • 按下 Ctrl + C 复制这个路径。

2. 创建并编辑脚本文件

   • 在桌面或任何你喜欢的地方，右键单击 -> 新建 -> 文本文档。
   • 打开这个新建的文本文档，将上面灰色代码块里的全部代码复制粘贴进去。
   • 找到 set "PROJECT_PATH=..." 这一行，把你刚刚复制的路径粘贴进去，替换掉原来的 D:\... 路径。确保路径被英文双引号"包围。

3. 正确保存文件

   • 在记事本里，点击左上角 文件 -> 另存为。
   • 在弹出的窗口中，将底部的“保存类型”从 文本文档(*.txt) 改为 所有文件(*.*)。
   • 将“文件名”修改为 启动翻译服务.bat。
   • 点击“保存”。现在，一个带齿轮图标的脚本文件就创建好了。

4. 运行！

   • 找到你保存的 启动翻译服务.bat 文件，直接双击它。一个黑色的命令窗口会弹出，并自动执行所有操作。看到 pause 提示的“请按任意键继续...”时，就说明服务已成功运行！

友情提示：只要服务在运行，这个黑色窗口就不能关闭。用完翻译功能后，直接关掉它即可。

macOS / Linux 用户指南：创建 .sh 高效脚本

#!/bin/bash

# ===【新手必读：请修改这里！】===
# 下面这行路径需要换成你自己的！
PROJECT_PATH="/Users/your_username/Documents/zotero-pdf2zh2.0"
# ===【修改结束】===

echo ""
echo "========================================================"
echo "          Zotero 翻译服务一键启动脚本 (macOS/Linux)"
echo "========================================================"
echo ""

# 切换到项目目录，如果失败则会提示并退出
cd "$PROJECT_PATH" || { echo "错误：无法找到项目目录！请检查 PROJECT_PATH 设置是否正确。"; echo "你的路径设置是: $PROJECT_PATH"; exit 1; }

echo "[步骤 1/3] 已成功进入项目目录: $(pwd)"
echo ""

# 激活 Python 虚拟环境
echo "[步骤 2/3] 正在激活 Python 虚拟环境..."
source ./.venv/bin/activate
echo "   - 虚拟环境已激活！"
echo ""

# 运行 Python 服务器
echo "[步骤 3/3] 准备启动翻译服务..."
uv run python server.py
echo "   - 服务已启动！关闭此终端窗口即可终止服务。"
echo ""
echo "========================================================"

手把手教你用：

1. 找到项目路径（Mac 用户有妙招！）

   • macOS 妙招：打开“访达 (Finder)”，找到 zotero-pdf2zh2.0 文件夹。然后打开“终端 (Terminal)” App（你可以在“启动台”里找到它）。在终端里输入 cd (注意 cd 后面有个空格)，然后直接用鼠标把文件夹从访达拖到终端窗口里，松开鼠标，完整的路径就会自动出现在终端里了！按下 Ctrl + C 复制它。
   • Linux 用户：通常可以在文件管理器中右键点击文件夹，选择“复制路径”或“属性”来查看。或者在终端中进入该目录后，使用 pwd 命令查看当前路径。

2. 创建并编辑脚本文件

   • 打开任意文本编辑器（如 VS Code 或系统自带的“文本编辑”）。
   • 将上面灰色代码块的全部内容复制粘贴进去。
   • 找到 PROJECT_PATH="..." 这一行，用你刚刚获取的路径替换掉引号里的示例路径。

3. 保存文件

   • 将文件保存为 start_server.sh。请确保它是纯文本格式。

4. 给脚本“授权”（只需一次）

   • 在“终端”里，使用 cd 命令进入你保存 start_server.sh 的目录（例如 cd Desktop）。

   • 运行以下命令，给脚本执行的“许可”：

     chmod +x start_server.sh

   • 这行命令的意思是“允许这个文件被执行”，是安全措施，只需在第一次使用时运行。

5. 运行！

   • 在终端中，确保你位于脚本所在的目录，然后输入以下命令并按回车：

     ./start_server.sh

现在，你的翻译服务已经启动。享受高效的文献翻译体验吧！

6. 路线 C：Docker 一键容器化 (省心之选)

把整套 PDF 翻译工具“打包”进 Docker 镜像，是目前最省心、最具可复现性的方案。你无需折腾 Python 依赖或虚拟环境，在任何安装了 Docker 的操作系统上（Windows/macOS/Linux），体验都完全一致：拉取 → 运行 → 浏览器访问，三步搞定。

准备工作：安装 Docker

在开始之前，请确保你的电脑已经安装了 Docker Desktop 并已成功启动：

# 验证版本，能看到版本号即可，如：Docker version 28.1.1, build 4eba377
docker -v
# 查看 Docker 运行信息，若无报错，说明 Docker 引擎已就绪 
docker info

如果尚未安装，请参考以下资源：

• 官方文档 & 安装指南：Docker Desktop 下载
• 博文【Docker】告别环境配置噩梦：从零到一的安装指南 - 她笑中藏泪花
• 视频【Docker】告别环境配置噩梦：从零到一的安装指南_哔哩哔哩_bilibili

6.1 第一步：选择镜像源

在开始之前，我们需要告诉 Docker 从哪里去下载这个工具的“安装包”（在 Docker 的世界里，这叫镜像 Image）。

把它想象成一个应用商店：

• 官方源 (Docker Hub)：这是全球官方商店，通常速度最快、最可靠。
  镜像地址：awwaawwa/pdfmathtranslate-next
• GitHub Container Registry（备用）：当官方源网络不佳时可选
  ghcr.io/pdfmathtranslate/pdfmathtranslate-next:latest

• 国内源 (镜像加速器)：如果访问官方商店很慢或被“墙”，这些就是开在国内的“分店”或“代购点”，能帮你更快地拿到货。

  • 常见镜像地址格式（任选其一即可）：

    • hub.xdark.top/awwaawwa/pdfmathtranslate-next:latest
    • docker.xuanyuan.me/awwaawwa/pdfmathtranslate-next:latest
    • docker.1ms.run/awwaawwa/pdfmathtranslate-next:latest

6.2 第二步：拉取镜像 —— 把“安装包”下载到本地

选好了商店，我们现在就用 docker pull 命令把“安装包”下载到你的电脑里。

首选：从官方源拉取

docker pull awwaawwa/pdfmathtranslate-next:latest

小贴士

• 镜像末尾的 :latest 是一个“标签 (Tag)”，代表最新版本。你也可以换成具体的版本号，例如 :2.0.10，以使用特定版本。
• 拉取一次后，再次运行同样命令会检查更新；若本地已有最新镜像，将直接跳过下载。
• 如果拉取过程中速度过慢或卡住，可以按 Ctrl + C 中断。

备选：当官方源访问受限时

如果 Docker Hub（官方源）访问困难，可以尝试项目在 GitHub 的官方容器仓库 (GHCR)：

docker pull ghcr.io/pdfmathtranslate/pdfmathtranslate-next:latest

最后的选择：使用国内加速镜像

如果以上两种方式都非常缓慢，可以尝试由社区或第三方提供的国内镜像源。请注意，这些源的更新可能不及时。使用时，需将完整的镜像地址替换掉。

# 示例：使用 dislabaiot.xyz 源 (请将此地址替换为你信任的、可用的加速器地址)
docker pull dislabaiot.xyz/awwaawwa/pdfmathtranslate-next:latest

新手小贴士

• docker pull 是一个一次性动作。镜像下载到本地后，就像软件安装好了，以后随时可以运行，无需重复下载。
• 如果下载进度条卡住不动，可以按 Ctrl + C 中断它，然后换一个国内源地址再试一次。

6.3 第三步：运行容器 —— 启动你的翻译服务！

镜像下载完毕，现在我们用 docker run 命令来启动它。运行中的镜像实例，就叫做“容器 (Container)”。它是一个隔离的、包含了我们所需服务的小型“虚拟机”。

docker run -d --name pdf2zh -p 7860:7860 awwaawwa/pdfmathtranslate-next

一句话解释：
这条命令会让容器在 后台 安静地跑起来，把你电脑的 7860 端口映射到容器的 7860 端口，然后启动名为 awwaawwa/pdfmathtranslate-next 的镜像。

参数“人话”解析

• docker run: “Docker，给我跑起来这个东西！”
• -d (detach): 让容器在后台安靜工作，不占用你当前的终端窗口。
• --name pdf2zh: 给你的容器起一个独一无二的名字叫 pdf2zh，就像给宠物起名，方便以后按名字找它（停止、重启等）。
• -p 7860:7860: 这是最关键的端口映射。它像一个电话转接员，把访问你电脑本机 7860 端口的请求，全部转接给容器内部的 7860 端口来处理。格式是 -p <本机端口>:<容器端口>。
• awwaawwa/pdfmathtranslate-next: 告诉 Docker 你要运行哪个镜像。

6.4 第四步：访问翻译服务

见证奇迹的时刻！

1. 打开你的任意网页浏览器（如 Chrome, Edge, Firefox）。

2. 在地址栏输入：http://127.0.0.1:7860/

   127.0.0.1 是一个特殊的地址，就代表“我这台电脑自己”。

3. 如果一切顺利，你应该能看到 PDF 翻译工具的界面了。现在，可以上传 PDF 文件开始使用了！

管理你的容器

记住你给容器起的名字 pdf2zh，后续就可以像遥控器一样，用以下命令来管理这个在后台运行的服务：

小白必看：如何替换成国内镜像

1. 先“拉取”国内镜像（只要做一次）：

   docker pull hub.xdark.top/awwaawwa/pdfmathtranslate-next:latest

2. 运行时用国内镜像名：

   docker run -d --name pdf2zh -p 7860:7860 hub.xdark.top/awwaawwa/pdfmathtranslate-next:latest

3. 确认

   • 打开浏览器访问：http://127.0.0.1:7860/
   • 出现 Web UI，说明替换成功！

Tip：

• 镜像前缀可以换成任意可用源，格式一致。这是一些国内的镜像源：
• 如果不确定完整的镜像名称，可打开 Docker Desktop → Images → 找到你的镜像 → 点击复制图标。

只需将命令末尾的镜像名换成你之前拉取的国内源地址即可。不确定完整的镜像名？

• 打开 Docker Desktop。
• 点击左侧菜单的 Images。
• 找到你下载的镜像，将鼠标悬停在镜像名称上，点击出现的复制图标即可。
  

7. 常见问题与排障

7.1 快速排障指南

7.2 关于“自定义 Prompt”的成本考量

pdf2zh-next 会将 PDF 拆分为许多小片段，并为每个片段发起一次 API 请求。若启用自定义 Prompt，这个 Prompt 会被附加到每一次请求上，其 token 成本也因此被成倍累加。

决策关键：你的 API 服务商是否支持 KV Cache (上下文硬盘缓存) 技术。这是一种上下文记忆机制，能避免对固定 Prompt 的重复计费。

✅ 强烈建议开启： 如果你的 API 服务商支持 KV Cache。此时，自定义 Prompt 的成本几乎可以忽略不计，请放心使用，以换取更稳定、更优质的翻译效果。

❌ 果断建议关闭： 如果你的 API 服务商不支持 KV Cache。在这种情况下，为避免不必要的开销，关闭此功能是最理性的选择。

最新版自定义Prompt参考

7.3 解读 RPS、QPS 与线程数：pdf2zh 是如何工作的？

许多用户在配置 pdf2zh 时，会对“线程数”、“RPS” 或 “QPS”感到困惑，误以为它们能让整个翻译过程“多核并行”。这里，我们用一个生动的比喻来彻底讲清它的工作机制。

一个“单人备菜，多人上菜”的厨房

想象 pdf2zh 是一个高效的翻译厨房：

1. 备菜阶段 (单线程)：厨房里只有一位主厨（CPU 单核心）。他负责所有前期准备工作：接收整本 PDF、逐页拆解、提取段落、清洗文本格式。无论你请多少个服务员，备菜的厨师始终只有一位，所以这个阶段是单线程的。
2. 上菜阶段 (多并发)：一旦主厨把菜（处理好的文本片段）备好放在出餐口（任务队列），你所设置的“线程数”就相当于你雇佣的服务员团队。他们（asyncio + httpx）会一拥而上，以最快速度将菜品并发地送往大模型（LLM）这张“餐桌”进行翻译。

“线程数”的多种“马甲”

请注意，在工具的不同界面中，这个“服务员团队的规模”有不同的叫法，但它们本质上是同一个概念：

• Web UI 中的 RPS (Requests Per Second)
• config.toml 文件中的 qps (Queries Per Second)
• Zotero 插件中的 线程数

它们都共同指向一件事：程序向上游 LLM 发起翻译请求的并发数量。

技术核心：为何备菜是“单线程”？

这背后的技术原因是 Python 的 GIL (全局解释器锁)。GIL 限制了在同一进程中，同一时间只有一个线程能执行 Python 的字节码。因此，对于计算密集型（CPU-bound）的 PDF 解析任务，多线程无法带来真正的并行加速。

编者注：项目未来可能会引入 GPU 加速功能来优化前处理阶段。

核心优化建议

综上所述，pdf2zh 的瓶颈通常不在于前期的“备菜”，而在于后期“上菜”的效率。若想追求极致速度，你的优化重心应该放在：

• 🚀 选择更快的 LLM API：优先使用由 GPU 加速的、响应延迟低的服务。
• 🌐 保证网络质量：程序与 API 服务器之间的网络带宽和延迟至关重要。
• ⚙️ 合理调整并发数：在不触及 API 服务商速率限制（Rate Limit）的前提下，适当调高 线程数 (或 QPS/RPS) 参数，让更多的“服务员”同时工作。

如何确定“合理”的并发数？

这是一个非常关键问题。设置过低会浪费性能，设置过高则会导致 API 报错。你可以遵循以下步骤来确定理论最大值：

1. 查阅官方文档：找到你所用 API Key 对应服务商的官方文档，定位到关于“速率限制 (Rate Limit)”的说明。
2. 关注核心指标：通常需要关注两个限制：RPM (每分钟请求数) 和 TPM (每分钟处理的 token 数)。

3. 计算理论 RPS：

   • 基于请求数：你的 RPS 设置不应超过 RPM / 60。
   • 基于 Token 数：同时也要确保 RPS * 平均每请求的 token 数 < TPM / 60。

简单粗暴的算法：在不考虑 Token 限制的理想情况下，可以直接用 RPM / 60 作为你的 RPS 参考值。

编者注： 若想获得流畅的高速翻译体验，建议选用支持高 RPM（例如 1000 RPM 或更高）的 API 套餐。一个高的 RPM 指标是保证并发能力的基础。

7.4 需要更多帮助？

如果以上指南未能解决你的问题，推荐通过以下官方渠道寻求帮助：

1. 阅读官方文档：首先查阅 官方项目 FAQ，大部分常见问题已有解答。
2. 搜索 GitHub Issues：在 项目 GitHub Issues 区 搜索关键词，你的问题可能已经被他人提出和解决。
3. zotero-pdf2zh：可以查看置顶 Issue，其中包含了大量有价值的排障讨论：🔝【手动置顶】请所有遇到问题的朋友先看这里 · Issue #64

8. 收工

好了，教程到此结束。有了 PDF2zh 这个神器，希望语言不再是你科研道路上的“拦路虎”，而是可以轻松跨越的“小水沟”。

祝你少踩坑，多产出，Happy Researching!