BabelDOC入门手册一点就通

BabelDOC入门手册一点就通

【#BubbleDOC 震撼发布！科研党的终极翻译神器，PDF翻译从此告别排版灾难！】

你是否经历过翻译PDF时公式错位、图表乱飞、版式崩坏的绝望？传统翻译工具的时代结束了！#BubbleDOC 横空出世，凭借三大革命性突破，成为全球科研、金融、法律从业者的新宠

✨ 核心亮点

1️⃣ 无损解析：精准提取PDF内嵌公式、图表、脚注，误差<0.5mm，翻译后与原版像素级对齐；
2️⃣ 智能翻译：支持GPT-4o/DeepSeek多模态引擎，学术术语翻译准确率高达99.2%；
3️⃣ 工业级排版：一键生成可直接投稿的双语PDF，适配Nature/Science/IEEE等顶级期刊模板！

为什么爆火？

• 免费额度：每月1000页解析+GLM-4-FLASH翻译，学生党狂喜；
• Pro版黑科技：10000页解析+DeepSeek模型，支持命令行批量处理，实验室必备；
• 生态联动：与Zotero/Overleaf无缝集成，论文写作到翻译全链路打通！

用户直呼“真香”

• “翻译速度12页/分钟，公式再也没乱过！”
• “终于不用手动调排版，省下时间多肝两篇论文！”

安装

优先安装UV，进行包管理

pip install uv -i https://pypi.tuna.tsinghua.edu.cn/simple

推荐源码安装：

# clone 项目
git clone https://github.com/funstory-ai/BabelDOC

# 进入项目目录
cd BabelDOC

# 下载依赖并运行babeldoc命令
uv run babeldoc --help

通常情况下是一步到位的，如遇报错还请自行分析

操作列表

安装完成后我们就可以使用uv run babeldoc --xxx命令来执行babeldoc的相关操作了

常规操作如下表：

一、基本选项

参数名称（简写）	功能描述	参数类型	默认值/示例	注意事项
-h, --help	显示帮助信息并退出	无	-	无
-c CONFIG	指定配置文件路径	文件路径	babeldoc.toml	支持 TOML 格式
--version	显示版本号	无	-	无
--files	指定输入的 PDF 文件路径（多个路径用空格分隔）	文件路径列表	必填项	例如：--files doc1.pdf doc2.pdf
--debug	启用调试日志	无	关闭	用于排查问题
--warmup	预加载并验证资源后退出	无	关闭	用于初始化环境

---

二、翻译相关选项

参数名称（简写）	功能描述	参数类型	默认值/示例	注意事项
--pages, -p	指定翻译的页码范围（如 1,2,3-5）	字符串	全部页面	支持格式：单页、范围、-,（从某页到末尾）
--lang-in, -li	源语言代码（如 en）	语言代码	en	支持 ISO 639-1 代码
--lang-out, -lo	目标语言代码（如 zh）	语言代码	zh	支持 ISO 639-1 代码
--output, -o	输出目录路径	文件路径	输入文件同目录	例如：-o ./translated
--qps, -q	翻译服务的 QPS 限制	整数	无限制	用于控制翻译速度
--ignore-cache	忽略翻译缓存	无	关闭	可能降低性能
--no-dual	不输出双语 PDF	无	输出双语 PDF	与 --no-mono 互斥
--no-mono	不输出单语 PDF	无	输出单语 PDF	与 --no-dual 互斥
--split-short-lines	强制拆分短行（可能导致排版问题）	无	关闭	见知识库说明
--short-line-split-factor	短行拆分阈值因子（默认 0.8）	浮点数	0.8	阈值 = 当前页面行中位长度 × 该因子
--skip-clean	跳过 PDF 清理步骤	无	关闭	可能影响兼容性
--dual-translate-first	双语 PDF 中翻译页优先	无	原始页优先	仅在双语模式生效
--disable-rich-text-translate	禁用富文本翻译（提升兼容性）	无	启用	适用于某些 PDF
--enhance-compatibility	启用所有兼容性增强选项	无	关闭	等效于 --skip-clean --dual-translate-first --disable-rich-text-translate
--use-alternating-pages-dual	双语 PDF 交替页模式	无	并排显示	启用后原译页交替排列
--watermark-output-mode	水印模式（watermarked/no_watermark/both）	枚举	watermarked	--no-watermark 已弃用
--max-pages-per-part	拆分翻译时每部分最大页数	整数	不拆分	例如：--max-pages-per-part 10
--translate-table-text	翻译表格文本（实验性）	无	关闭	可能不稳定
--skip-scanned-detection	跳过扫描文档检测（加速非扫描文档）	无	关闭	首部分译时仍会检测

---

三、OpenAI 特定选项

参数名称（简写）	功能描述	参数类型	默认值/示例	注意事项
--openai	使用 OpenAI 翻译器	无	BabelDOC 默认翻译器	需配合 API 配置
--openai-model	指定 OpenAI 模型（如 gpt-3.5-turbo）	字符串	默认模型	例如：--openai-model gpt-4
--openai-base-url	OpenAI API 基础 URL	URL	OpenAI 官方地址	用于自托管或代理
--openai-api-key, -k	OpenAI API 密钥	字符串	无	必填项

本次功能采用火山引擎下的DeepSeek-R1模型接口

名称	API Key	创建时间
api-key-20250417153620	your_own_api_key	2025-04-17 15:36

---

实际调用参考OpenAI SDK调用的方法（对应模型的技术手册）

调用示例：

运行babeldoc命令

–file 表示对文件进行处理

–openai 表示启用openai平台服务

–openai-model 表示openai平台提供的模型

–openai-base-url 表示模型对应的基础链接（这里以豆包的API为例）

–openai-api-key 表示调用所使用的鉴权秘钥（请参考您所调用的模型提供方的技术手册）

uv run babeldoc --files C:\Users\zhiqi\PycharmProjects\AI_DRF\tesseract\asserts\edgar.pdf --openai --openai-model deepseek-r1-250120 --openai-base-url https://ark.cn-beijing.volces.com/api/v3 --openai-api-key your_own_api_key

最终结果就是生成对应PDF文档的双语对照版本与单语翻译版本文件

[04/17/25 16:33:26] INFO     INFO:babeldoc.document_il.backend.pdf_creater:PDF save with clean=True completed successfully                                           pdf_creater.py:606
                    INFO     INFO:babeldoc.high_level:Peak memory usage: 1001.33 MB                                                                                   high_level.py:333
                    INFO     INFO:babeldoc.high_level:finish translate: C:\Users\zhiqi\PycharmProjects\AI_DRF\tesseract\asserts\dolma-page-1.pdf, cost:               high_level.py:512
                             237.49383068084717 s
                    INFO     INFO:babeldoc.main:Translation results:                                                                                                        main.py:393
                                     Original PDF: C:\Users\zhiqi\PycharmProjects\AI_DRF\tesseract\asserts\dolma-page-1.pdf
                                     Total time: 237.49 seconds
                                     Monolingual PDF: C:\Users\zhiqi\PycharmProjects\AI_DRF\BabelDOC\dolma-page-1.zh.mono.pdf
                                     Dual-language PDF: C:\Users\zhiqi\PycharmProjects\AI_DRF\BabelDOC\dolma-page-1.zh.dual.pdf
                                     Peak memory usage: 1001.328125 MB
                    INFO     INFO:babeldoc.translation_config:cleanup temp files: C:\Users\zhiqi\AppData\Local\Temp\tmpr_6rlx25                               translation_config.py:240
translate                                              ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━╸  99/100 0:03:57 0:00:01
Parse PDF and Create Intermediate Representation (1/1) ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━ 1/1     0:00:01 0:00:00
DetectScannedFile (1/1)                                ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━ 1/1     0:00:00 0:00:00
Parse Page Layout (1/1)                                ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━ 1/1     0:00:01 0:00:00
Parse Paragraphs (1/1)                                 ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━ 1/1     0:00:00 0:00:00
Parse Formulas and Styles (1/1)                        ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━ 1/1     0:00:00 0:00:00
Translate Paragraphs (1/1)                             ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━ 16/16   0:03:45 0:00:00
Typesetting (1/1)                                      ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━ 1/1     0:00:01 0:00:00
Add Fonts (1/1)                                        ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━ 95/95   0:00:00 0:00:00
Generate drawing instructions (1/1)                    ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━ 1/1     0:00:00 0:00:00
Subset font (1/1)                                      ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━ 1/1     0:00:01 0:00:00
Save PDF (1/1)                                         ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━ 2/2     0:00:03 0:00:00
                    INFO     INFO:babeldoc.main:Total tokens: 16768                                                                                                         main.py:395
                    INFO     INFO:babeldoc.main:Prompt tokens: 4249                                                                                                         main.py:396
                    INFO     INFO:babeldoc.main:Completion tokens: 12519                                                                                                    main.py:397
                    INFO     INFO:babeldoc.high_level:Waiting for translation to finish...                                                                            high_level.py:287
                    INFO     INFO:babeldoc.document_il.translator.translator:openai translate call count: 5                                                            translator.py:92
                    INFO     INFO:babeldoc.document_il.translator.translator:openai translate cache call count: 0                                                      translator.py:95

这是一个示例输出

还请根据自己的配置情况进行查验

Original PDF: C:\Users\zhiqi\PycharmProjects\AI_DRF\tesseract\asserts\dolma-page-1.pdf
Monolingual PDF: C:\Users\zhiqi\PycharmProjects\AI_DRF\BabelDOC\dolma-page-1.zh.mono.pdf
Dual-language PDF: C:\Users\zhiqi\PycharmProjects\AI_DRF\BabelDOC\dolma-page-1.zh.dual.pdf

总之根据这三条信息就可以得到对应的（原、双语对照、单语翻译）文件

结语：

更多操作可以见操作列表自行研究，在后续，笔者会对其中较常用的方案进行总结、归纳与举例，并尽可能结合实际应用案例进行讲解