BabelDOC PDF 翻译接入统一 API

先说结论:四个参数管住每一次翻译调用

BabelDOC 的命令行直接暴露端点:--openai 启用 LLM 翻译器,--openai-base-url 决定请求发到哪里,--openai-api-key 负责鉴权,--openai-model 选模型 ID。README 自带的示例展示的就是这套参数组合,它的翻译服务说明写得很直白:只支持 OpenAI 兼容的 LLM,这让一个多厂商 OpenAI 兼容网关成为顺理成章的选择,而不是权宜之计。 因为模型 ID 是按纯字符串转发的,端点提供的任何模型都能用:上游文档自己就推荐 GLM 和 DeepSeek 家族作为对 OpenAI 兼容协议友好的模型,经 kkaiapi,它们和 Claude、Gemini 的 ID 就并排待在同一个 base URL 后面。

babeldoc --files paper.pdf \
  --lang-in en --lang-out zh \
  --openai \
  --openai-model "deepseek-v4-flash" \
  --openai-base-url "https://api.kkaiapi.com/v1" \
  --openai-api-key "$KKAIAPI_KEY"

BabelDOC 怎么把一份 PDF 变成模型调用

BabelDOC(GitHub 上的 funstory-ai,约 9K 星标,出自沉浸式翻译团队)是一个保版式的 PDF 文档翻译工具:解析文档结构,保护公式和图表,识别段落,用 LLM 逐段翻译,再重建成一份译文单语版和一份双语对照版。它以 CLI 和 Python API 两种形态提供,是托管版 BabelDOC 服务的自建对应物。 端点真正起作用的是翻译这一步。一份文档会变成许多段落大小的 chat-completions 请求,由 --qps 参数(默认每秒 4 次)节流,由一个 worker 池处理(pool-max-workers 默认跟随 QPS 值)。这个形状带来两个结果。第一,翻译是走量的负载:一份长 PDF 是成百上千次小调用,单价会被迅速放大。第二,和主要靠"读"的检索类负载不同,翻译"写"的量和"读"的量差不多,比较不同 ID 时输出 token 单价和输入单价同样重要。 BabelDOC 还会缓存翻译结果,重跑同一份文档会复用之前的结果,除非传了 --ignore-cache。术语表 CSV(--glossary-files)能在整个流程里锁定专有名词,--max-pages-per-part 能把超大文档拆成几部分,分别翻译再自动合并。

完整配置:命令行参数或 TOML 配置文件

重复使用的场景里,同样的设置可以写进一个 TOML 文件,用 --config 传入。[babeldoc] 表接受完全相同的键,写成短横线格式:openai、openai-model、openai-base-url、openai-api-key,再加上吞吐量和输出选项。这样 Key 不用留在命令行历史里,一份翻译配置也能在不同文档间复用。 下面的配置是一份实用的走量配置:大多数文档用快速 ID,QPS 调高匹配一个有并发能力的网关,单语和双语两种输出都保留。翻译要求更讲究的文档,把 openai-model 换成更强的 ID 就行。

[babeldoc]
lang-in = "en-US"
lang-out = "zh-CN"
qps = 10
pool-max-workers = 10

# 翻译服务
openai = true
openai-model = "deepseek-v4-flash"
openai-base-url = "https://api.kkaiapi.com/v1"
openai-api-key = "sk-你的kkaiapi密钥"

# 输出控制
no-dual = false
no-mono = false
watermark-output-mode = "no_watermark"

怎么选翻译模型

对比流程很具体:用两个 ID 翻译同样十页(按次运行分别缓存不会互相干扰),对照读两份双语版,再看按 Key 的用量日志算每一遍花了多少。多数团队最后落地一个快速默认档加一个高端档,都存成 TOML 文件。

• 走量文档(说明书、只读一次的论文)适合 deepseek-v4-flash:技术性文字的翻译质量能撑住,单页成本几乎可以忽略
• 中文目标语言的翻译是 glm-5.2 和 DeepSeek 家族的主场,上游文档自己也把 GLM 和 DeepSeek 列为表现良好的 OpenAI 兼容选择
• 在意细节的文档(合同、要发表的译文)值得用 claude-sonnet-4-6 或 claude-haiku-4-5-20251001,它们在长文档里对术语和语域的把握更忠实
• 这里输出 token 很要紧。翻译写的量和读的量差不多,比较不同 ID 时也要看输出价格那一列,不只是输入
• 快速 ID 配术语表效果更好。一份术语表 CSV 能锁住快速模型偶尔会漂移的专有名词,补齐技术文本上的质量差距

主力模型价格

价格按 kkaiapi 中文区实时价格计算,单位 ¥/1M tokens(输入/输出)。

翻车点与吞吐量调优

QPS 是和网关互相牵动的参数。默认每秒 4 次很保守,大多数有并发能力的上游能撑住更多,调高 --qps(pool-max-workers 会跟着走)是让一份三百页的文档从一下午缩短到几分钟的关键。边看 429 响应边往上加,不要一上来就跳到一个很大的数字,因为被限流的段落会重试,拖慢整个流程。 这些参数只有在设置了 --openai 时才生效。传了 base URL 但没加 --openai,翻译器就是关闭状态,表现为解析了 PDF 但从未翻译。模型 ID 是精确字符串,以端点 /v1/models 的返回列表为准,拼错字会在第一段翻译时报模型不存在。401 意味着 Key 和 base URL 不属于同一个账户。 版式问题不是端点问题。文字重叠、公式丢失、表格错乱,根源在 PDF 解析这一侧(试试 --enhance-compatibility、扫描件用 --ocr-workaround,或者富文本开关),换模型解决不了。反过来也一样:术语翻译错了是模型或术语表的问题,不是解析器的问题。 缓存可能掩盖变化。换模型之后,如果想让新 ID 重新翻译旧 ID 已经处理过的内容,传 --ignore-cache,否则缓存过的段落维持原样。

哪些人会把 BabelDOC 接到一个网关上

• 批量翻译论文的研究者,一份文档几百次小调用,走量价格和按 Key 的用量可见性是关键
• 标准化双语文档的团队,同一个端点上跑一份快速默认档和一份高端档,只是模型字符串不同
• 所在语言对最强翻译模型分属不同厂商的用户,GLM、DeepSeek、Claude、Gemini 的 ID 都在一个 Key 后面
• 用自建替代托管服务翻译机密文档的用户,解析留在本地,只把段落文字发给一个可审计的端点
• 手头没有某家厂商官方支付渠道的开发者,充值即用不需要海外卡

验证接入与排查首份文档

开始长任务之前先列出你的 Key 能调用的模型;--openai-model 必须和提供的某个 ID 精确匹配。 然后端到端翻译一份很小的文档(一页 PDF,或者在大文档上用 --pages 1)。第一段就 401 说明 Key 和 base URL 不匹配。模型不存在是 ID 拼错了。解析了但从未调用端点的任务是漏了 --openai。频繁卡顿并出现重试提示,说明 QPS 设得比端点能承受的要高,先调低再慢慢往上加。 文档开始流动之后,kkaiapi 控制台会显示每次请求的模型、token 数和花费。翻译成本随文档长度双向增长(输入和输出都算),按 Key 的用量日志是弄清楚每个模型每页真实成本的地方,不用靠估算。

curl -s https://api.kkaiapi.com/v1/models \
  -H "Authorization: Bearer $KKAIAPI_KEY" | head -50

# 再跑一次单页冒烟测试
babeldoc --config babeldoc.toml --files sample.pdf --pages 1

常见问题