尧图网站建设 
BabelDOC 完整配置指南兼容性、本地模型与术语表一次调通【免费下载链接】BabelDOCYet Another Document Translator项目地址: https://gitcode.com/GitHub_Trending/ba/BabelDOCBabelDOC 是一款开源的 PDF 文档翻译工具能把英文 PDF 翻成中英双语且尽量不破坏原版式。这份指南面向真正要跑 BabelDOC 的人你会看到最小可用的命令长什么样、翻完后阅读器显示异常或扫描件发虚时该拧哪个参数以及怎么接入本地模型、管好术语表。一、最小可用配置30 秒跑通一次 PDF 翻译 命令行一把梭用 uv 装好后一条命令就能完成翻译。只要你的模型服务是 OpenAI 兼容接口--openai开关加模型参数就够了uv tool install --python 3.12 BabelDOC babeldoc --openai --openai-api-key sk-xxx \ --openai-model gpt-4o-mini \ --lang-in en --lang-out zh \ --files input.pdf跑完会在输入目录旁得到双语和纯译文两个 PDF。用 TOML 固化配置参数多了命令行会失控。把常用项写进配置文件再用-c指定即可以后只改模型和文件名[babeldoc] openai true openai-model gpt-4o-mini openai-api-key sk-xxx lang-in en lang-out zh qps 4二、按症状修配置翻完不对劲时怎么调每个兼容参数都对应一个具体症状。先认症状再开药方最后掂量代价。症状药方参数作用代价阅读器显示异常、乱码--enhance-compatibility一次开启三个兼容开关文件略大译文页在前富格式信息丢失扫描件翻完文字发虚--ocr-workaround给字符垫白色底盖住扫描噪声只对黑白扫描件有效体积略增不想逐篇判断是否扫描件--auto-enable-ocr-workaround检出大量扫描页后自动开启绕过多一步检测耗时大文档处理太慢、内存吃紧--max-pages-per-part 100按页数切片分批翻译多部分调度开销确定不是扫描件--skip-scanned-detection跳过扫描检测若误判为纯电子文档会省掉该有的兜底阅读器显示异常开兼容三件套--enhance-compatibility等价于同时打开--skip-clean跳过清理压缩保留原始结构老阅读器更认、--dual-translate-first双语版译文页放前面和--disable-rich-text-translate不保留富文本标记换取最大兼容性。如果你只遇到其中一种问题也可以单独开对应开关代价更小。扫描件翻完一片乱OCR 绕过如果你的扫描件翻完文字发虚、和背景噪声混在一起通常是原图太脏。--ocr-workaround会给每个字符下方垫一块白色底矩形把噪声盖住。注意它是绕过而非识别文字只改善显示。开了它之后扫描检测会被自动跳过用--auto-enable-ocr-workaround则让 BabelDOC 自己判断检出大量扫描页才启用并对该文档跳过后续检测。大文档处理太慢分页加跳过检测页数上百时给--max-pages-per-part一个值如 100文档会被切片处理单批内存占用更稳。如果你百分之百确定文档是电子版再加--skip-scanned-detection省掉检测时间——这就是何时可以跳过检测的答案只有当文档明显不是扫描件时才跳否则可能漏掉本该启用的兜底处理。三、接上你的翻译引擎云端 API 与本地模型云端任何 OpenAI 兼容接口BabelDOC 只认 OpenAI 风格的 chat completions 接口所以官方 OpenAI、Azure OpenAI 的兼容端点、各家开源模型网关都能接区别只是--openai-base-url和 key。模型可写gpt-4o-mini、glm-4-flash、deepseek-chat等网关支持的任意名称。命令行和 TOML 两种方式等价长项目建议用 TOML临时试模型用命令行。本地Ollama 与 vLLM 接入对比 本地模型走同一套 OpenAI 兼容协议只是地址换成 localhostbabeldoc --openai --openai-base-url http://localhost:11434/v1 \ --openai-api-key ollama --openai-model llama3.1 \ --files input.pdfvLLM 同理把地址换成http://localhost:8000/v1。两者怎么选方案上手成本吞吐适合Ollama极低一条命令拉起一般CPU/单卡为主小模型、低并发、快速验证vLLM较高需 GPU 环境高批量解码强大模型、整本书级别任务本地部署后建议把--qps调到 1~2别按云端配额设。限流、缓存、重试与自定义提示词限流漏桶限流--qps默认 4意思就是每秒最多放 4 个请求出门防止打爆配额。--pool-max-workers控制并发线程不填默认等于 QPS术语提取线程另有--term-pool-max-workers。缓存翻译结果存本地 SQLite命中条件按模型 温度 提示词 源/目标语言整组匹配——换模型或改提示词都会让缓存失效这是设计使然。想强制重新翻译就加--ignore-cache。重试遇到限流错误自动指数退避重试等待从 1 秒起、翻倍到 15 秒封顶最多 100 次所以你看到卡住几秒多半是退避在起作用不用手动干预。自定义提示词--custom-system-prompt可整段替换系统指令适合对学术腔或文风有要求的场景。提醒一句提示词参与缓存键改完首次跑会更慢。四、术语只说一种话术语表管理与自动提取术语表 CSV 怎么写术语表是标准 CSV三列tgt_lng可选source,target,tgt_lng Machine Learning,机器学习,zh-CN LLM,大语言模型,zh-CNtgt_lng填了就会做目标语言过滤这份表只在你输出zh-CN时生效换目标语言时自动忽略。匹配由 hyperscan 引擎承担大小写不敏感、多术语取最长匹配所以Neural Network不会被Neural抢先截走。多个文件用--glossary-files a.csv,b.csv逗号分隔传入示例文件 可以参考。自动提取与三级优先级 翻译过程中 BabelDOC 默认还会让 LLM 自动提取术语把段落发给模型要求返回原文-译文JSON 对去重后并入术语库。嫌费 token 可以--no-auto-extract-glossary关掉想让提取走更便宜的模型用--openai-term-extraction-model单独指定--save-auto-extracted-glossary能把提取结果落盘成 CSV下一轮直接当人工术语表用。优先级规则从高到低你手动维护的术语表——绝对权威自动提取的术语——本次任务内动态生效LLM 自由发挥——兜底。冲突时永远以你写的 CSV 为准所以值得花半小时把核心术语固化下来。五、进阶调优与排查清单公式识别参数数学公式默认按字体和字符模式识别--formular-font-pattern CM*匹配 Computer Modern 字体--formular-char-pattern补抓特殊符号。公式会被占位符保护不参与翻译排版原样保留。--add-formula-placehold-hint官方标注目前不推荐会向模型暴露占位符可能反而拉低翻译质量别急着开。分页、短行与其他旋钮--max-pages-per-part大文档切片配合--pages 1-5先小范围验证。--min-text-length默认 5太短的文本直接跳过减少碎片请求。--split-short-lines强制拆短行官方提示可能引起排版变差属调试项。token 统计与排查任务结束时日志会汇总总 token、prompt token、completion token、缓存命中 token 以及术语提取各阶段的消耗——对账费用和定位为什么这么慢就看这几行。排查顺序建议先--pages 1,2试翻一两页再--debug开调试日志最后才怀疑参数。六、这套配置适合谁下一步做什么H3 占位/输出文章Let me finish the last section properly — Ill rewrite the ending section with a proper H3.输出文章BabelDOC 完整配置指南兼容性、本地模型与术语表一次调通BabelDOC 是一款开源的 PDF 文档翻译工具能把英文 PDF 翻成中英双语且尽量不破坏原版式。这份指南面向真正要跑 BabelDOC 的人你会看到最小可用的命令长什么样、翻完后阅读器显示异常或扫描件发虚时该拧哪个参数以及怎么接入本地模型、管好术语表。一、最小可用配置30 秒跑通一次 PDF 翻译 命令行一把梭用 uv 装好后一条命令就能完成翻译。只要你的模型服务是 OpenAI 兼容接口--openai开关加模型参数就够了uv tool install --python 3.12 BabelDOC babeldoc --openai --openai-api-key sk-xxx \ --openai-model gpt-4o-mini \ --lang-in en --lang-out zh \ --files input.pdf跑完会在输入目录旁得到双语和纯译文两个 PDF。用 TOML 固化配置参数多了命令行会失控。把常用项写进配置文件再用-c指定即可以后只改模型和文件名[babeldoc] openai true openai-model gpt-4o-mini openai-api-key sk-xxx lang-in en lang-out zh qps 4二、按症状修配置翻完不对劲时怎么调每个兼容参数都对应一个具体症状。先认症状再开药方最后掂量代价。症状药方参数作用代价阅读器显示异常、乱码--enhance-compatibility一次开启三个兼容开关文件略大译文页在前富格式信息丢失扫描件翻完文字发虚--ocr-workaround给字符垫白色底盖住扫描噪声只对黑白扫描件有效体积略增不想逐篇判断是否扫描件--auto-enable-ocr-workaround检出大量扫描页后自动开启绕过多一步检测耗时大文档处理太慢、内存吃紧--max-pages-per-part 100按页数切片分批翻译多部分调度开销确定不是扫描件--skip-scanned-detection跳过扫描检测若误判会漏掉该启用的兜底处理阅读器显示异常开兼容三件套--enhance-compatibility等价于同时打开--skip-clean跳过清理压缩保留原始结构老阅读器更认、--dual-translate-first双语版译文页放前面和--disable-rich-text-translate不保留富文本标记换取最大兼容性。如果你只遇到其中一种问题也可以单独开对应开关代价更小。扫描件翻完一片乱OCR 绕过如果你的扫描件翻完文字发虚、和背景噪声混在一起通常是原图太脏。--ocr-workaround会给每个字符下方垫一块白色底矩形把噪声盖住。注意它是绕过而非识别文字只改善显示。手动开了它之后扫描检测会被自动跳过用--auto-enable-ocr-workaround则让 BabelDOC 自己判断检出大量扫描页才启用并对该文档跳过后续检测。大文档处理太慢分页加跳过检测页数上百时给--max-pages-per-part一个值如 100文档会被切片处理单批内存占用更稳。如果你百分之百确定文档是电子版再加--skip-scanned-detection省掉检测时间——何时可以跳过检测的答案就一句话只有当文档明显不是扫描件时才跳否则可能漏掉本该启用的兜底。三、接上你的翻译引擎云端 API 与本地模型云端任何 OpenAI 兼容接口BabelDOC 只认 OpenAI 风格的 chat completions 接口所以官方 OpenAI、Azure OpenAI 的兼容端点、各家开源模型网关都能接区别只是--openai-base-url和 key。模型可写gpt-4o-mini、glm-4-flash、deepseek-chat等网关支持的任意名称。命令行和 TOML 两种方式等价长项目建议用 TOML临时试模型用命令行。本地Ollama 与 vLLM 接入对比 本地模型走同一套 OpenAI 兼容协议只是地址换成 localhostbabeldoc --openai --openai-base-url http://localhost:11434/v1 \ --openai-api-key ollama --openai-model llama3.1 \ --files input.pdfvLLM 同理把地址换成http://localhost:8000/v1。两者怎么选方案上手成本吞吐适合Ollama极低一条命令拉起一般CPU/单卡为主小模型、低并发、快速验证vLLM较高需 GPU 环境高批量解码强大模型、整本书级别任务本地部署后建议把--qps调到 1~2别按云端配额设。限流、缓存、重试与自定义提示词限流漏桶限流--qps默认 4意思就是每秒最多放 4 个请求出门防止打爆配额。--pool-max-workers控制并发线程不填默认等于 QPS术语提取线程另有--term-pool-max-workers。缓存翻译结果存本地 SQLite命中条件按模型 温度 提示词 源/目标语言整组匹配——换模型或改提示词都会让缓存失效这是设计使然。想强制重新翻译就加--ignore-cache。重试遇到限流错误自动指数退避重试等待从 1 秒起、翻倍到 15 秒封顶最多 100 次所以看到卡住几秒多半是退避在起作用不用手动干预。自定义提示词--custom-system-prompt可整段替换系统指令适合对学术腔或文风有要求的场景。提醒一句提示词参与缓存键改完首次跑会更慢。四、术语只说一种话术语表管理与自动提取术语表 CSV 怎么写术语表是标准 CSV三列tgt_lng可选source,target,tgt_lng Machine Learning,机器学习,zh-CN LLM,大语言模型,zh-CNtgt_lng填了就会做目标语言过滤这份表只在你输出zh-CN时生效换目标语言时自动忽略。匹配由 hyperscan 引擎承担大小写不敏感、多术语取最长匹配所以Neural Network不会被Neural抢先截走。多个文件用--glossary-files a.csv,b.csv逗号分隔传入示例文件 可以参考。自动提取与三级优先级 翻译过程中 BabelDOC 默认还会让 LLM 自动提取术语把段落发给模型要求返回原文-译文JSON 对去重后并入术语库。嫌费 token 可以--no-auto-extract-glossary关掉想让提取走更便宜的模型用--openai-term-extraction-model单独指定--save-auto-extracted-glossary能把提取结果落盘成 CSV下一轮直接当人工术语表用。优先级规则从高到低你手动维护的术语表——绝对权威自动提取的术语——本次任务内动态生效LLM 自由发挥——兜底。冲突时永远以你写的 CSV 为准所以值得花半小时把核心术语固化下来。五、进阶调优与排查清单公式识别参数数学公式默认按字体和字符模式识别--formular-font-pattern CM*匹配 Computer Modern 字体--formular-char-pattern补抓特殊符号。公式会被占位符保护不参与翻译排版原样保留。--add-formula-placehold-hint官方标注目前不推荐会向模型暴露占位符可能反而拉低翻译质量别急着开。分页、短行与其他旋钮--max-pages-per-part大文档切片配合--pages 1,2先小范围验证。--min-text-length默认 5太短的文本直接跳过减少碎片请求。--split-short-lines强制拆短行官方提示可能引起排版变差属调试项。token 统计与排查任务结束时日志会汇总总 token、prompt token、completion token、缓存命中 token 以及术语提取各阶段的消耗——对账费用和定位为什么这么慢就看这几行。排查顺序建议先--pages 1,2试翻一两页再--debug开调试日志最后才怀疑参数配置。六、这套配置适合谁下一步做什么适用场景与行动清单这套组合适合三类人用云端 API 批量翻论文的配好 TOML 加术语表即可本地 GPU 跑开源模型做离线文档翻译的Ollama/vLLM 加低 QPS以及处理扫描件、老阅读器这种疑难杂症的症状表加兼容三件套。你的下一步拿一份真实文档跑一遍最小配置翻完对照症状表逐条核对再按 官方实现细节文档 深入你想调的那一环。参数不用背症状表记住就够了。【免费下载链接】BabelDOCYet Another Document Translator项目地址: https://gitcode.com/GitHub_Trending/ba/BabelDOC创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考 BabelDOC 完整配置指南：兼容性、本地模型与术语表一次调通
BabelDOC 完整配置指南兼容性、本地模型与术语表一次调通【免费下载链接】BabelDOCYet Another Document Translator项目地址: https://gitcode.com/GitHub_Trending/ba/BabelDOCBabelDOC 是一款开源的 PDF 文档翻译工具能把英文 PDF 翻成中英双语且尽量不破坏原版式。这份指南面向真正要跑 BabelDOC 的人你会看到最小可用的命令长什么样、翻完后阅读器显示异常或扫描件发虚时该拧哪个参数以及怎么接入本地模型、管好术语表。一、最小可用配置30 秒跑通一次 PDF 翻译 命令行一把梭用 uv 装好后一条命令就能完成翻译。只要你的模型服务是 OpenAI 兼容接口--openai开关加模型参数就够了uv tool install --python 3.12 BabelDOC babeldoc --openai --openai-api-key sk-xxx \ --openai-model gpt-4o-mini \ --lang-in en --lang-out zh \ --files input.pdf跑完会在输入目录旁得到双语和纯译文两个 PDF。用 TOML 固化配置参数多了命令行会失控。把常用项写进配置文件再用-c指定即可以后只改模型和文件名[babeldoc] openai true openai-model gpt-4o-mini openai-api-key sk-xxx lang-in en lang-out zh qps 4二、按症状修配置翻完不对劲时怎么调每个兼容参数都对应一个具体症状。先认症状再开药方最后掂量代价。症状药方参数作用代价阅读器显示异常、乱码--enhance-compatibility一次开启三个兼容开关文件略大译文页在前富格式信息丢失扫描件翻完文字发虚--ocr-workaround给字符垫白色底盖住扫描噪声只对黑白扫描件有效体积略增不想逐篇判断是否扫描件--auto-enable-ocr-workaround检出大量扫描页后自动开启绕过多一步检测耗时大文档处理太慢、内存吃紧--max-pages-per-part 100按页数切片分批翻译多部分调度开销确定不是扫描件--skip-scanned-detection跳过扫描检测若误判为纯电子文档会省掉该有的兜底阅读器显示异常开兼容三件套--enhance-compatibility等价于同时打开--skip-clean跳过清理压缩保留原始结构老阅读器更认、--dual-translate-first双语版译文页放前面和--disable-rich-text-translate不保留富文本标记换取最大兼容性。如果你只遇到其中一种问题也可以单独开对应开关代价更小。扫描件翻完一片乱OCR 绕过如果你的扫描件翻完文字发虚、和背景噪声混在一起通常是原图太脏。--ocr-workaround会给每个字符下方垫一块白色底矩形把噪声盖住。注意它是绕过而非识别文字只改善显示。开了它之后扫描检测会被自动跳过用--auto-enable-ocr-workaround则让 BabelDOC 自己判断检出大量扫描页才启用并对该文档跳过后续检测。大文档处理太慢分页加跳过检测页数上百时给--max-pages-per-part一个值如 100文档会被切片处理单批内存占用更稳。如果你百分之百确定文档是电子版再加--skip-scanned-detection省掉检测时间——这就是何时可以跳过检测的答案只有当文档明显不是扫描件时才跳否则可能漏掉本该启用的兜底处理。三、接上你的翻译引擎云端 API 与本地模型云端任何 OpenAI 兼容接口BabelDOC 只认 OpenAI 风格的 chat completions 接口所以官方 OpenAI、Azure OpenAI 的兼容端点、各家开源模型网关都能接区别只是--openai-base-url和 key。模型可写gpt-4o-mini、glm-4-flash、deepseek-chat等网关支持的任意名称。命令行和 TOML 两种方式等价长项目建议用 TOML临时试模型用命令行。本地Ollama 与 vLLM 接入对比 本地模型走同一套 OpenAI 兼容协议只是地址换成 localhostbabeldoc --openai --openai-base-url http://localhost:11434/v1 \ --openai-api-key ollama --openai-model llama3.1 \ --files input.pdfvLLM 同理把地址换成http://localhost:8000/v1。两者怎么选方案上手成本吞吐适合Ollama极低一条命令拉起一般CPU/单卡为主小模型、低并发、快速验证vLLM较高需 GPU 环境高批量解码强大模型、整本书级别任务本地部署后建议把--qps调到 1~2别按云端配额设。限流、缓存、重试与自定义提示词限流漏桶限流--qps默认 4意思就是每秒最多放 4 个请求出门防止打爆配额。--pool-max-workers控制并发线程不填默认等于 QPS术语提取线程另有--term-pool-max-workers。缓存翻译结果存本地 SQLite命中条件按模型 温度 提示词 源/目标语言整组匹配——换模型或改提示词都会让缓存失效这是设计使然。想强制重新翻译就加--ignore-cache。重试遇到限流错误自动指数退避重试等待从 1 秒起、翻倍到 15 秒封顶最多 100 次所以你看到卡住几秒多半是退避在起作用不用手动干预。自定义提示词--custom-system-prompt可整段替换系统指令适合对学术腔或文风有要求的场景。提醒一句提示词参与缓存键改完首次跑会更慢。四、术语只说一种话术语表管理与自动提取术语表 CSV 怎么写术语表是标准 CSV三列tgt_lng可选source,target,tgt_lng Machine Learning,机器学习,zh-CN LLM,大语言模型,zh-CNtgt_lng填了就会做目标语言过滤这份表只在你输出zh-CN时生效换目标语言时自动忽略。匹配由 hyperscan 引擎承担大小写不敏感、多术语取最长匹配所以Neural Network不会被Neural抢先截走。多个文件用--glossary-files a.csv,b.csv逗号分隔传入示例文件 可以参考。自动提取与三级优先级 翻译过程中 BabelDOC 默认还会让 LLM 自动提取术语把段落发给模型要求返回原文-译文JSON 对去重后并入术语库。嫌费 token 可以--no-auto-extract-glossary关掉想让提取走更便宜的模型用--openai-term-extraction-model单独指定--save-auto-extracted-glossary能把提取结果落盘成 CSV下一轮直接当人工术语表用。优先级规则从高到低你手动维护的术语表——绝对权威自动提取的术语——本次任务内动态生效LLM 自由发挥——兜底。冲突时永远以你写的 CSV 为准所以值得花半小时把核心术语固化下来。五、进阶调优与排查清单公式识别参数数学公式默认按字体和字符模式识别--formular-font-pattern CM*匹配 Computer Modern 字体--formular-char-pattern补抓特殊符号。公式会被占位符保护不参与翻译排版原样保留。--add-formula-placehold-hint官方标注目前不推荐会向模型暴露占位符可能反而拉低翻译质量别急着开。分页、短行与其他旋钮--max-pages-per-part大文档切片配合--pages 1-5先小范围验证。--min-text-length默认 5太短的文本直接跳过减少碎片请求。--split-short-lines强制拆短行官方提示可能引起排版变差属调试项。token 统计与排查任务结束时日志会汇总总 token、prompt token、completion token、缓存命中 token 以及术语提取各阶段的消耗——对账费用和定位为什么这么慢就看这几行。排查顺序建议先--pages 1,2试翻一两页再--debug开调试日志最后才怀疑参数。六、这套配置适合谁下一步做什么H3 占位/输出文章Let me finish the last section properly — Ill rewrite the ending section with a proper H3.输出文章BabelDOC 完整配置指南兼容性、本地模型与术语表一次调通BabelDOC 是一款开源的 PDF 文档翻译工具能把英文 PDF 翻成中英双语且尽量不破坏原版式。这份指南面向真正要跑 BabelDOC 的人你会看到最小可用的命令长什么样、翻完后阅读器显示异常或扫描件发虚时该拧哪个参数以及怎么接入本地模型、管好术语表。一、最小可用配置30 秒跑通一次 PDF 翻译 命令行一把梭用 uv 装好后一条命令就能完成翻译。只要你的模型服务是 OpenAI 兼容接口--openai开关加模型参数就够了uv tool install --python 3.12 BabelDOC babeldoc --openai --openai-api-key sk-xxx \ --openai-model gpt-4o-mini \ --lang-in en --lang-out zh \ --files input.pdf跑完会在输入目录旁得到双语和纯译文两个 PDF。用 TOML 固化配置参数多了命令行会失控。把常用项写进配置文件再用-c指定即可以后只改模型和文件名[babeldoc] openai true openai-model gpt-4o-mini openai-api-key sk-xxx lang-in en lang-out zh qps 4二、按症状修配置翻完不对劲时怎么调每个兼容参数都对应一个具体症状。先认症状再开药方最后掂量代价。症状药方参数作用代价阅读器显示异常、乱码--enhance-compatibility一次开启三个兼容开关文件略大译文页在前富格式信息丢失扫描件翻完文字发虚--ocr-workaround给字符垫白色底盖住扫描噪声只对黑白扫描件有效体积略增不想逐篇判断是否扫描件--auto-enable-ocr-workaround检出大量扫描页后自动开启绕过多一步检测耗时大文档处理太慢、内存吃紧--max-pages-per-part 100按页数切片分批翻译多部分调度开销确定不是扫描件--skip-scanned-detection跳过扫描检测若误判会漏掉该启用的兜底处理阅读器显示异常开兼容三件套--enhance-compatibility等价于同时打开--skip-clean跳过清理压缩保留原始结构老阅读器更认、--dual-translate-first双语版译文页放前面和--disable-rich-text-translate不保留富文本标记换取最大兼容性。如果你只遇到其中一种问题也可以单独开对应开关代价更小。扫描件翻完一片乱OCR 绕过如果你的扫描件翻完文字发虚、和背景噪声混在一起通常是原图太脏。--ocr-workaround会给每个字符下方垫一块白色底矩形把噪声盖住。注意它是绕过而非识别文字只改善显示。手动开了它之后扫描检测会被自动跳过用--auto-enable-ocr-workaround则让 BabelDOC 自己判断检出大量扫描页才启用并对该文档跳过后续检测。大文档处理太慢分页加跳过检测页数上百时给--max-pages-per-part一个值如 100文档会被切片处理单批内存占用更稳。如果你百分之百确定文档是电子版再加--skip-scanned-detection省掉检测时间——何时可以跳过检测的答案就一句话只有当文档明显不是扫描件时才跳否则可能漏掉本该启用的兜底。三、接上你的翻译引擎云端 API 与本地模型云端任何 OpenAI 兼容接口BabelDOC 只认 OpenAI 风格的 chat completions 接口所以官方 OpenAI、Azure OpenAI 的兼容端点、各家开源模型网关都能接区别只是--openai-base-url和 key。模型可写gpt-4o-mini、glm-4-flash、deepseek-chat等网关支持的任意名称。命令行和 TOML 两种方式等价长项目建议用 TOML临时试模型用命令行。本地Ollama 与 vLLM 接入对比 本地模型走同一套 OpenAI 兼容协议只是地址换成 localhostbabeldoc --openai --openai-base-url http://localhost:11434/v1 \ --openai-api-key ollama --openai-model llama3.1 \ --files input.pdfvLLM 同理把地址换成http://localhost:8000/v1。两者怎么选方案上手成本吞吐适合Ollama极低一条命令拉起一般CPU/单卡为主小模型、低并发、快速验证vLLM较高需 GPU 环境高批量解码强大模型、整本书级别任务本地部署后建议把--qps调到 1~2别按云端配额设。限流、缓存、重试与自定义提示词限流漏桶限流--qps默认 4意思就是每秒最多放 4 个请求出门防止打爆配额。--pool-max-workers控制并发线程不填默认等于 QPS术语提取线程另有--term-pool-max-workers。缓存翻译结果存本地 SQLite命中条件按模型 温度 提示词 源/目标语言整组匹配——换模型或改提示词都会让缓存失效这是设计使然。想强制重新翻译就加--ignore-cache。重试遇到限流错误自动指数退避重试等待从 1 秒起、翻倍到 15 秒封顶最多 100 次所以看到卡住几秒多半是退避在起作用不用手动干预。自定义提示词--custom-system-prompt可整段替换系统指令适合对学术腔或文风有要求的场景。提醒一句提示词参与缓存键改完首次跑会更慢。四、术语只说一种话术语表管理与自动提取术语表 CSV 怎么写术语表是标准 CSV三列tgt_lng可选source,target,tgt_lng Machine Learning,机器学习,zh-CN LLM,大语言模型,zh-CNtgt_lng填了就会做目标语言过滤这份表只在你输出zh-CN时生效换目标语言时自动忽略。匹配由 hyperscan 引擎承担大小写不敏感、多术语取最长匹配所以Neural Network不会被Neural抢先截走。多个文件用--glossary-files a.csv,b.csv逗号分隔传入示例文件 可以参考。自动提取与三级优先级 翻译过程中 BabelDOC 默认还会让 LLM 自动提取术语把段落发给模型要求返回原文-译文JSON 对去重后并入术语库。嫌费 token 可以--no-auto-extract-glossary关掉想让提取走更便宜的模型用--openai-term-extraction-model单独指定--save-auto-extracted-glossary能把提取结果落盘成 CSV下一轮直接当人工术语表用。优先级规则从高到低你手动维护的术语表——绝对权威自动提取的术语——本次任务内动态生效LLM 自由发挥——兜底。冲突时永远以你写的 CSV 为准所以值得花半小时把核心术语固化下来。五、进阶调优与排查清单公式识别参数数学公式默认按字体和字符模式识别--formular-font-pattern CM*匹配 Computer Modern 字体--formular-char-pattern补抓特殊符号。公式会被占位符保护不参与翻译排版原样保留。--add-formula-placehold-hint官方标注目前不推荐会向模型暴露占位符可能反而拉低翻译质量别急着开。分页、短行与其他旋钮--max-pages-per-part大文档切片配合--pages 1,2先小范围验证。--min-text-length默认 5太短的文本直接跳过减少碎片请求。--split-short-lines强制拆短行官方提示可能引起排版变差属调试项。token 统计与排查任务结束时日志会汇总总 token、prompt token、completion token、缓存命中 token 以及术语提取各阶段的消耗——对账费用和定位为什么这么慢就看这几行。排查顺序建议先--pages 1,2试翻一两页再--debug开调试日志最后才怀疑参数配置。六、这套配置适合谁下一步做什么适用场景与行动清单这套组合适合三类人用云端 API 批量翻论文的配好 TOML 加术语表即可本地 GPU 跑开源模型做离线文档翻译的Ollama/vLLM 加低 QPS以及处理扫描件、老阅读器这种疑难杂症的症状表加兼容三件套。你的下一步拿一份真实文档跑一遍最小配置翻完对照症状表逐条核对再按 官方实现细节文档 深入你想调的那一环。参数不用背症状表记住就够了。【免费下载链接】BabelDOCYet Another Document Translator项目地址: https://gitcode.com/GitHub_Trending/ba/BabelDOC创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考