RetainPDF v4.2.6：Windows、macOS、Linux PDF 翻译的 API 配置与任务排查
RetainPDF 的安装包准备好之后，还不能直接把它理解为一个完全离线的 PDF 翻译器。官方链路涉及 OCR、语言模型和页面排版，遇到失败时需要分别检查输入文件、服务配置和任务状态。本文根据 v4.2.6 对应官方文档整理配置与验证顺序，未安装或运行程序，也不提供性能测试结论。
概念封面表达处理步骤，不是实际控制台截图。
1. 区分桌面包与 Docker 部署
官方发行附件包含 Windows Setup.exe、macOS dmg 和 Linux deb。选择桌面包时按操作系统匹配；已读资料未明确这些包各自的 CPU 架构和最低系统版本，不能仅凭文件名继续推断。
Docker 部署文档则给出了另一组条件：建议 Linux Ubuntu 22.04 或 24.04，4 核 CPU、8GB 内存、至少 10GB 可用空间；镜像支持 linux/amd64 与 linux/arm64，不要求独立显卡。这些条件属于容器部署，不能用来证明桌面包兼容性。
对于已经按官方交付目录准备 Docker 环境的读者，在 ops/deployment/docker/delivery 目录执行 docker compose up -d 后，默认前端入口为 http://127.0.0.1:40001。该入口包含同源 API 代理。文档中的完整后端与扁平提交接口有其他端口，不应把它们直接当作前端页面地址。
本次整理以 v4.2.6 为版本基准。容器镜像的标签和拉取时间需另行记录，使用滚动标签并不自动得到同一版本，后续排查时也应把镜像身份与桌面安装包身份分开。
2. 配置 OCR，再配置模型
在页面右上角打开"API 配置"。OCR provider 默认建议 paddle，也可选择 mineru；填写所选 provider 对应的 token。不要因为页面上有多种识别入口，就把所有凭据混在一个字段里。
语言模型部分需要 API key、模型名称和 base URL。建议按服务后台提供的信息逐项核对：密钥是否有效，模型是否在该账号权限范围内，地址是否指向该服务要求的接口入口。OCR 可以访问，不等于模型一定可以调用；两段链路要分别判断。
MIT 许可解决的是软件代码的使用与分发条件。OCR 和模型服务的额度、网络访问和计费由各服务决定。部署到本地服务器，也仍需要访问所配置的外部接口，不能以此推断文档处理全部发生在本机。
标准 Docker 代理方案把后端 API key 留在 NGINX 代理层，由代理注入 RETAINPDF_PROXY_API_KEY，浏览器可读的 FRONT_X_API_KEY 保持为空。配置自己的实例时，应沿用这种层次区分，避免把后端访问凭据写进前端可读配置。模型凭据与后端鉴权 key 的用途也不同。
3. 用可检查的 PDF 验证完整链路
第一次验证可以选一份页数较少、含一段正文和一处公式的普通 PDF。先确认文件能够正常打开，记录页数，然后提交。这样一旦出现问题，既能检查输入，也能核对结果，不必从整本扫描资料里定位第一处错误。
官方接口采用异步任务方式。上传文件获得 upload_id，创建翻译任务获得 job_id，之后查询任务状态；只有任务成功，才进入结果下载。提交接口返回任务身份与初始状态，不表示已经得到 ZIP。
部署文档中的接口顺序可以概括为：/api/v1/uploads 上传，/api/v1/jobs 创建任务，/api/v1/jobs/{job_id} 查询状态，再访问对应的 PDF、Markdown 或下载入口。记录自己这次的任务编号，排查时查询同一个任务，避免反复创建任务后混淆结果。
状态检查应同时看阶段和详细说明。识别阶段失败时优先检查 OCR 配置与输入质量；模型阶段失败时检查模型服务和参数。页面重排后的结果仍要阅读验证，单看任务成功只能说明程序流程完成。
排查时可以保留一份不含密钥的记录：输入文件页数、所选 OCR provider、模型名称、任务编号、失败阶段，以及本轮实际修改了哪项配置。如果一次同时换 OCR、模型和文件，就很难判断哪项变化解决了问题。每轮只改变与当前错误有关的一项，更便于比较。
4. 将输入限制与服务故障分开
运行配置控制文件大小、页数与并发。官方文档的示例使用 209715200 字节和 300 页，但这些是可调整的配置示例，不是所有部署都固定采用的极限。遇到超限提示，先检查当前实例配置，再决定缩小输入或调整部署参数。
网络错误与额度错误也应分别处理。服务不可达时，检查部署所在环境到该接口的访问情况；账号额度不足时，查看服务后台用量；鉴权失败时，核对所用 key 和账号权限。记录提示的原始信息，不把所有错误都笼统归为 PDF 不兼容。
扫描 PDF 还需要关注页面方向和清晰度。识别输出如果已经把段落顺序弄错，后面的翻译很难恢复准确语义。可以先查看一页对应的文本，分清是字形识别问题还是语言转换问题，再处理原稿或修改 OCR 配置。
复杂表格也要单独检查。表格翻译控制属于官方说明的能力，开启或调整相关策略后，应核对行列对应关系、数字和单位。不能仅凭译文出现中文，就判断表格已经可用于计算或引用。
5. 成功任务仍需要结果验收
左侧保留 PDF 页面，右侧查看 Markdown；截图拍摄版本未单独标明。
先打开译文 PDF，检查页数、段落顺序以及公式和图注；再查看 Markdown，检查可编辑内容中的上下标、图片位置和段落划分。两种格式用途不同，不能只验证其中一种就替另一种下结论。
公式较多的论文建议同时保留原稿。检查对象包括变量字母、正负号、上下标、单位和公式编号，结论段还要注意否定与适用条件。发现异常时记录原稿页码与结果位置，便于后续重试或人工修订。
需要提取文档信息时，可使用带页码和原文引用的 AI 问答，再沿引用回查。官方将阅读问答与 PDF Agent 修改入口区分开；只做定位和阅读时，无需进入修改模式。
导出 PDF、Markdown 或 ZIP 后，再打开实际文件确认完整性。归档时把输入、输出、服务配置说明和任务编号关联起来，但不要把密钥写进笔记或故障记录。这样的记录能解释某次结果的来历，也便于以后只调整一个变量进行比较。
v4.2.6 发布于 2026 年 10 月 6 日，发行记录没有详细变更正文。本文介绍对应官方资料中的工作方式，不将这些功能称为该版新增。项目资料见 RetainPDF 官方仓库；图片引用用于软件说明，仓库标注 MIT，图中论文内容权利需分别判断。
软件界面 © 2026 RetainPDF contributors，MIT 许可；版权与许可文本随软件保留。
下载与获取
按自己的桌面系统选择 v4.2.6 安装包，保留同目录的 LICENSE 和 SHA256SUMS.txt。