企业官网建设流程全解析

BabelDOC 离线部署实操指南：把 PDF 翻译能力完整搬进内网的四步流程

【免费下载链接】BabelDOCYet Another Document Translator项目地址: https://gitcode.com/GitHub_Trending/ba/BabelDOC

BabelDOC 是一个开源 PDF 文档翻译工具（AGPL-3.0，当前版本 0.6.2），核心能力是解析 PDF 的版面、文本、公式与表格，翻译后按原版式重新排版，输出双语对照与纯译文两种 PDF。它的离线部署思路很直白：在有网的机器上一条命令导出离线资源包，内网机器恢复后运行时不再触达外网，翻译请求全部打到自建的大模型服务上。

为什么值得把翻译链路搬进内网

运行时对外网的依赖只有两处

先说结论：BabelDOC 部署完成后，真正需要联网的动作只有两个，而且都可以提前消化或替换掉。

1. 资源下载：多语言字体、版面检测模型（YOLO doclayout ONNX）、PDF 字符映射表（CMap）、LLM 分词缓存，首次运行时自动下载并缓存在本地，后续只校验不重下。
2. 翻译请求：所有文本经--openai-base-url指定的 OpenAI 兼容接口发出，这个地址指向哪里完全由你决定。

资源下载交给一台可联网的跳板机完成，LLM 换成内网自建服务，翻译链路对外网的依赖就归零了。这一点在 docs/ImplementationDetails/ 的各阶段实现说明里可以逐段核对。

内网场景下的两个真实用法

• 某高校研究所把历年英文论文存档做中文回译，月均处理几十篇，模型用的是内网部署的 70B 级模型，全程无一份文档出网；
• 某电网公司设备说明书存档回译，扫描件居多，通过 OCR 兜底参数处理后，版面核对基本只抽查个别页面。

共同点：文档敏感、批量稳定、模型自建，这三条同时满足时，离线部署的维护成本通常低于向在线服务反复申请配额。

自托管和在线服务的取舍

在线服务免维护但有配额，且文档经第三方链路；自托管无配额限制、数据不出内网，代价是要自己维护一个可用的 LLM 服务，并承担资源包随版本更新的维护工作。如果内网已经有推理服务（vLLM、Ollama 等任何 OpenAI 兼容网关都行），BabelDOC 侧几乎零额外成本。

部署前先备齐三样东西

硬件与 Python 环境基线

💡 版面模型跑在 GPU 上可换装onnxruntime-gpu（或onnxruntime-directml）可选依赖，但 CPU 对常规页数完全够用，不必为 GPU 单独开机器。

验证自建 LLM 的连通性

翻译引擎走 OpenAI 兼容协议，--openai-base-url直接指向内网网关即可。部署前先用 curl 或任意客户端确认三件事：服务地址可达、/v1/chat/completions能返回、记下模型名与 API key。这三项是后面第一条命令的全部输入。

确定版面模型的运行位置

默认模式下 ONNX 模型随主进程本地推理，单机最简单。如果内网已有 GPU 机器专门跑推理，也可以用--rpc-doclayout把版面识别请求转发给独立的 RPC 服务（实现见 babeldoc/docvision/），主进程只做解析与排版。

在有网机器上生成离线资源包

资源包内容清单

--generate-offline-assets产出的 zip 包含四类资源，每一项都带 sha3_256 指纹，恢复时会逐个复验：

⚠️ 资源包文件名里的那串 tag 是文件清单的哈希值，两端 BabelDOC 版本不一致时，恢复阶段会直接报 tag mismatch 并退出。建议两端锁定同一版本。

一条命令生成并转移

在有网机器上执行，它会先下载并校验全部资源，再压缩成带 tag 的 zip：

# 在 ./offline-pkg/ 目录生成 offline_assets_<tag>.zip babeldoc --generate-offline-assets ./offline-pkg

转移前记录 zip 的sha256sum，随介质一起带入内网，落盘后先比对再恢复，避免传输损坏混进后续排查。

内网机器三步装起来

1. 安装程序本体

内网没有 PyPI 源，先在联网环境把依赖和 BabelDOC 构造成 wheel 一并带进去，再离线安装：

# 不访问 PyPI，仅从本地包目录安装 BabelDOC pip install --no-index --find-links=./local_pkgs BabelDOC

2. 恢复离线资源包

把 zip 放到约定路径后执行恢复，缺失或校验不过的文件会被补齐，已有且校验通过的自动跳过：

# 将字体、版面模型、CMap 等资源恢复到本地缓存 babeldoc --restore-offline-assets /opt/pkgs/offline_assets_<tag>.zip

3. 翻译第一份文档

base-url 指向内网 LLM，一条命令跑通主链路，同时产出单语与双语两个文件：

# 指向内网 LLM 翻译一份 PDF，输出单语与双语结果 babeldoc --files paper.pdf --lang-in en --lang-out zh \ --openai --openai-base-url http://llm.internal:8000/v1 \ --openai-model qwen2.5-72b --openai-api-key sk-internal

部署后的验收清单

先验收输出正确性

挑一份含公式和表格的论文做样张（下图即一篇学术论文的左右双语对照页），按三项逐条核对：

1. 版面还原：译文位置贴合原版式，公式、表格、脚注无丢失或串位；
2. 字体渲染：CJK 字形无缺字方框，连字符与标点换行正常；
3. 产物完整：单语、双语 PDF 均生成，水印行为与--watermark-output-mode设置一致。

再度量性能

• 吞吐：--qps默认 4，按内网模型实测吞吐上调，别拍脑袋翻倍；
• 并发：--pool-max-workers默认跟随 QPS，可结合 CPU 核数单独调；
• 缓存：记录同一文档首跑与二跑耗时，正常二跑应明显更快——翻译缓存命中是离线部署最直观的性能收益。

⚠️ 若二跑耗时没有下降，先检查是否误开了--ignore-cache，再确认缓存目录对运行用户可写。

大文档的处理策略

长文档用--max-pages-per-part 50拆段翻译后自动合并，避免单次上下文过长；只验证链路时用--pages 1-3只翻前三页，成本最低。

出问题先查这里

常见报错速查

用调试参数获取更多线索

--debug打开 debug 级日志，--working-dir指定工作目录可保留中间产物便于复查；每一阶段（解析、找段、排版、建 PDF）的内部流程在 docs/ImplementationDetails/ 都有对应文档，对照日志能快速定位卡在哪个环节。

到这里，BabelDOC 离线部署的全部关键点其实只有两件：有网机器打资源包，内网机器把翻译指向自建 LLM。建议的下一步很具体：在自己的环境里挑一份真实文档，用--pages 1-3先跑通链路，记下耗时与版面偏差点，再回头定 qps 与拆分参数——验收样张跑顺了，剩下的只是批量化的事。

【免费下载链接】BabelDOCYet Another Document Translator项目地址: https://gitcode.com/GitHub_Trending/ba/BabelDOC