BabelDOC 异步翻译 API 完全指南async_translate 的事件流、进度上报与取消机制【免费下载链接】BabelDOCYet Another Document Translator项目地址: https://gitcode.com/GitHub_Trending/ba/BabelDOC导读yadt.high_level.async_translate当前仓库中为babeldoc.format.pdf.high_level.async_translate为 PDF 翻译提供了一个基于 Pythonasyncio的异步接口以**事件流event stream**的方式实时上报翻译进度方便上层 UI进度条、任务面板与 CLI 消费。读完本文你将掌握如何用async for消费翻译过程中的全部事件类型、五种事件的数据结构与语义、八个核心翻译阶段与真实权重、三种取消方式CancelledError、KeyboardInterrupt、cancel_translation()以及底层ProgressMonitor与AsyncCallback的实现原理。本文所有结论均可对应到 async_translate 实现 与 ProgressMonitor 实现 的源码。一、异步翻译 API 概览1.1 函数签名与设计定位async_translate是一个异步生成器async generator定义在 babeldoc/format/pdf/high_level.py。它接收一个TranslationConfig对象并在翻译过程中持续yield描述进度的字典事件async def async_translate(translation_config: TranslationConfig): Asynchronously translate a PDF file with real-time progress reporting.同步版本translate()与异步版本共用同一套底层流程两者最终都会进入do_translate()high_level.py区别在于异步版本把进度回调包装成跨线程的 asyncio 事件队列从而让调用方能够以async for逐条接收进度事件而不是阻塞等待一个最终结果。1.2 与同步翻译的区别维度同步translate(config)异步async_translate(config)返回值直接返回TranslateResult异步生成器yield 事件字典进度获取通过ProgressMonitor回调/进度条事件流中的progress_start/progress_update/progress_end取消依赖配置与回调支持asyncio原生取消与cancel_translation()典型场景CLI、脚本批量处理GUI/Web 任务面板、需要实时进度反馈的应用注意仓库中实际的导入路径为babeldoc.format.pdf.high_level.async_translate见 CLI 调用处 与 executor 适配器文档中的yadt.high_level为历史包名。二、快速上手消费事件流文档给出的基本用法可以直接照搬完整可运行的形态如下import asyncio async def translate_with_progress(): config TranslationConfig( input_fileexample.pdf, translatoryour_translator, # 一个 BaseTranslator 实例如 OpenAITranslator lang_inen, lang_outzh, doc_layout_modelyour_layout_model, # DocLayoutModel用于版面分析 # ... 其他配置项见下文参数小节 ) try: async for event in async_translate(config): if event[type] progress_update: print(fProgress: {event[overall_progress]}%) elif event[type] finish: result event[translate_result] print(fTranslation completed: {result.original_pdf_path}) elif event[type] error: print(fError occurred: {event[error]}) break except asyncio.CancelledError: print(Translation was cancelled) except KeyboardInterrupt: print(Translation was interrupted)从源码看事件流在收到error事件后就会停止迭代high_level.py因此在error分支break是安全且必要的而finish事件则由ProgressMonitor.translate_done()触发progress_monitor.py。2.1 构造 TranslationConfig 的关键参数TranslationConfig的完整签名见 translation_config.py以下是构造异步翻译配置时的常用参数参数类型默认值说明translatorBaseTranslator必填翻译引擎实现do_translate/do_llm_translateinput_filestr \| Path必填输入 PDF 路径lang_in/lang_outstr必填源语言 / 目标语言代码doc_layout_modelDocLayoutModel自动加载版面分析模型不传时调用DocLayoutModel.load_available()pagesstrNone页码范围形如1-,2,-3,4由parse_pages()解析为(start, end)列表report_intervalfloat0.1进度上报最小时间间隔秒控制progress_update的发送频率output_dirstr \| Path当前目录输出 PDF 存放目录working_dirstr \| Path临时目录中间文件工作目录debug 模式固定为缓存目录下working/输入文件名qpsint1翻译请求速率限制每秒请求数同时作为线程池pool_max_workers的默认值no_dual/no_monoboolFalse是否不生成双语 / 单语 PDFwatermark_output_modeWatermarkOutputModeWatermarkedwatermarked/no_watermark/both三选一debugboolFalse开启后保留中间 IL JSON、输出更详细日志skip_scanned_detectionboolFalse跳过扫描件检测阶段auto_extract_glossaryboolTrue是否启用术语自动抽取skip_translationboolFalse跳过翻译仅排版split_strategyBaseSplitStrategyNone大文件分片策略可用create_max_pages_per_part_split_strategy()创建依赖说明translate_with_progress运行在asyncio事件循环中底层翻译工作通过loop.run_in_executor(None, do_translate, pm, config)投递到线程池执行high_level.py所以即使翻译引擎是同步实现也不会阻塞事件循环。三、事件类型详解async_translate一共产出五种事件所有事件都以type字段区分。以下字段定义与 high_level.py 的 docstring 以及 ProgressMonitor 的发送点 完全一致。3.1 progress_start —— 阶段开始事件某个翻译阶段开始时发出stage_progress恒为0.0stage_current恒为0{ type: progress_start, stage: str, # 当前阶段名称 stage_progress: float, # 恒为 0.0 stage_current: int, # 当前进度计数0 stage_total: int # 本阶段待处理的总条目数 }源码出处ProgressMonitor.stage_start()progress_monitor.py其中stage_total由各阶段在启动时上报例如翻译段落阶段的total是待翻译段落数。3.2 progress_update —— 进度更新事件翻译过程中周期性发出发送频率由TranslationConfig.report_interval控制默认0.1秒。这是消费端最常用的事件用于驱动进度条{ type: progress_update, stage: str, # 当前阶段名称 stage_progress: float, # 当前阶段进度百分比0-100 stage_current: int, # 本阶段已处理的条目数 stage_total: int, # 本阶段总条目数 overall_progress: float # 整体翻译进度0-100 }源码出处ProgressMonitor.stage_update()progress_monitor.py。注意两点实现细节节流逻辑当time.time() - last_report_time report_interval且stage.total 3时直接跳过上报避免高频小步进刷屏阶段总条目数不大于 3 时则每次都上报。整体进度overall_progress由calculate_current_progress()progress_monitor.py基于阶段权重加权计算而不是简单平均——权重见下一节。3.3 progress_end —— 阶段结束事件阶段完成时发出stage_progress恒为100.0stage_current等于stage_total{ type: progress_end, stage: str, # 已完成的阶段名称 stage_progress: float, # 恒为 100.0 stage_current: int, # 等于 stage_total stage_total: int, # 本阶段处理的总条目数 overall_progress: float # 整体翻译进度0-100 }源码出处ProgressMonitor.stage_done()progress_monitor.py。它由TranslationStage.__exit__在阶段上下文管理器退出时触发如果阶段提前结束current ! total且未取消会先记录一条 warning 日志再上报结束事件。3.4 finish —— 完成事件整份文档翻译成功时发出携带TranslateResult{ type: finish, translate_result: TranslateResult # 包含产物文件路径与耗时等信息 }TranslateResult定义在 translation_config.py主要字段包括字段含义original_pdf_path原始输入 PDF 路径mono_pdf_path/dual_pdf_path单语 / 双语 PDF 产物路径含水印no_watermark_mono_pdf_path/no_watermark_dual_pdf_path无水印产物路径total_seconds翻译总耗时秒peak_memory_usage峰值内存占用MB含子进程total_valid_character_count全文件有效字符数统计total_valid_text_token_count全文件有效文本 token 数统计按 gpt-4o 口径auto_extracted_glossary_path自动抽取术语表导出路径可选3.5 error —— 错误事件翻译过程中任何异常都会先被记录日志再以错误事件上报{ type: error, error: str # 错误信息 }源码出处ProgressMonitor.translate_error()progress_monitor.py由do_translate()的异常分支调用high_level.py。错误事件之后事件流随即终止。error字段在取消场景下可能携带asyncio.CancelledError对象见第五节。四、翻译阶段与整体进度权重4.1 八个核心阶段含子阶段文档列出的 8 个阶段对应真实流水线。在 high_level.py 的 TRANSLATE_STAGES 中阶段被展开为 14 项并配有经验权重权重之和为 100用于计算整体进度阶段文档名 → 真实 stage 名权重对应实现ILCreater →Parse PDF and Create Intermediate Representation14.12il_creater.py / il_creater_active.py扫描件检测→DetectScannedFile2.45detect_scanned_file.pyLayoutParser →Parse Page Layout14.03layout_parser.py表格解析→Parse Table1.0table_parser.pyParagraphFinder →Parse Paragraphs6.26paragraph_finder.pyStylesAndFormulas →Parse Formulas and Styles1.66styles_and_formulas.py术语抽取→Automatic Term Extraction30.0automatic_term_extractor.pyILTranslator →Translate Paragraphs46.96il_translator.py / il_translator_llm_only.pyTypesetting →Typesetting4.71typesetting.pyFontMapper →Add Fonts0.61fontmap.pyPDFCreater →Generate drawing instructions1.96pdf_creater.py子集化字体→Subset font0.92pdf_creater.py保存 PDF→Save PDF6.34pdf_creater.py每个阶段都会按上文三种progress_*事件上报自己的进度overall_progress由ProgressMonitor将各阶段权重归一化后累加得到。4.2 阶段裁剪按配置动态调整流水线get_translation_stage()high_level.py会根据配置裁剪阶段进而影响事件流中出现的stage名称only_parse_generate_pdfTrue跳过检测、版面、表格、段落、公式、术语抽取、翻译、排版等全部中间阶段只保留解析与生成skip_scanned_detectionTrue移除DetectScannedFiletable_model为空移除Parse Table注意当前版本table_model已弃用并强制置None见 translation_config.pyauto_extract_glossaryFalse移除Automatic Term Extractionskip_translationTrue移除Translate Paragraphs。理解这一点对消费端很重要不要硬编码假设事件流一定包含某个阶段应始终以事件中的stage字段为准。五、取消机制文档列出了三种取消途径源码全部支持5.1 方式一抛出CancelledErrorasyncio.Task.cancel()在async_translate内部async for event in callback循环若收到CancelledError会立刻cancel_event.set()high_level.py随后future.cancel()尝试终止线程池中的翻译任务并等待finish_event确认收尾high_level.py。5.2 方式二KeyboardInterruptCtrlC事件循环捕获KeyboardInterrupt时同样会设置取消事件并记录日志Translation cancelled by user through keyboard interrupthigh_level.py。5.3 方式三TranslationConfig.cancel_translation()这是推荐的程序化取消方式。cancel_translation()会调用progress_monitor.cancel()最终cancel_event.set()translation_config.py、progress_monitor.py。各翻译阶段内部通过raise_if_cancelled()translation_config.py在关键点检查取消标记并抛出asyncio.CancelledError从而优雅中断。文档中的完整示例单独任务 延时取消async def translate_with_cancellation(): config TranslationConfig( input_fileexample.pdf, translatoryour_translator, # ... 其他配置 ) try: # 在另一个任务中启动翻译 translation_task asyncio.create_task(process_translation(config)) # 模拟某个需要取消的条件 await asyncio.sleep(5) config.cancel_translation() # 触发取消 await translation_task # 等待任务结束 except asyncio.CancelledError: print(Translation was cancelled) async def process_translation(config): async for event in async_translate(config): if event[type] error: if isinstance(event[error], asyncio.CancelledError): print(Translation was cancelled) break print(fError occurred: {event[error]}) break # ... 处理其他事件 ...提示取消时error事件的error字段可能不是字符串而是asyncio.CancelledError对象示例中isinstance判断正是为此设计对应 progress_monitor.py 中on_finish()的行为。5.4 取消后的行为保证对照源码取消或任何终止发生后取消原因会被记录到日志do_translate()的finally分支会调用pm.on_finish()并执行translation_config.cleanup_temp_files()清理临时文件high_level.py正在进行的翻译任务通过future.cancel()与各阶段raise_if_cancelled()停止若取消标记已设置会补发一个携带CancelledError的error事件progress_monitor.pyasync_translate等待finish_event后优雅退出high_level.py。六、错误处理文档要求与源码行为一致记录日志异常在do_translate()中被捕获debugTrue时记录完整 tracebacklogger.exception否则仅记录错误摘要high_level.py上报错误事件pm.translate_error(e)发送{type: error, error: e}终止事件流async_translate收到error事件后break事件流停止high_level.py清理资源finally中执行on_finish()与cleanup_temp_files()。此外do_translate()在进入正式流程前还会做一次元数据校验若输入 PDF 的 producer 字段含BabelDOC与Translation_generated_by_AI,please_carefully_discern会直接抛出InputFileGeneratedByBabelDOCError拒绝翻译已被 BabelDOC 处理过的文件high_level.py。七、底层实现原理7.1 事件流的跨线程桥梁AsyncCallback翻译工作运行在线程池中而事件循环在另一个线程。两者通过AsyncCallbackbabeldoc/asynchronize/init.py桥接step_callback()每个进度回调通过loop.call_soon_threadsafe(self.queue.put_nowait, args)将事件安全地投递进asyncio.Queue并time.sleep(0.01)让出 GIL保证事件循环有机会消费消息finished_callback()投递最终事件后置finished True__aiter__/__anext__实现异步迭代器语义——只要finished为假或队列非空就持续产出事件队列清空且finished为真时抛出StopAsyncIteration结束迭代。这解释了为什么async for event in callback能够一边等待一边消费线程池里的进度更新。7.2 进度计算的权重模型ProgressMonitorProgressMonitorbabeldoc/progress_monitor.py将阶段列表按权重归一化weight / total_weightoverall_progress由已完成阶段的权重百分比累加、加上当前阶段stage.current / stage.total的加权值得到全部阶段完成时精确返回100。它还支持分片翻译split_strategy每个分片通过create_part_monitor()创建子监视器calculate_current_progress()再按part_index / total_parts折算整体进度事件中也会附带part_index、total_parts字段。7.3 生产环境中的消费范式仓库自身提供了两个可直接参考的消费端CLIbabeldoc/main.py 中async for event in async_translate(config)finish时打印str(result)并退出Executor 服务babeldoc/tools/executor/babeldoc_adapter.py 的_run_async_translate()用asyncio.run(run())包装将finish事件中的TranslateResult转为返回值、将error事件包装为BabelDocReportedError其余事件原样透传给调用方如 IDE 插件的任务面板。如果你的应用需要把进度同步到 WebSocket/IPC直接参照 executor 的做法收到progress_update时转发overall_progress收到finish时交付产物路径收到error时上报错误信息即可。八、最佳实践清单始终按event[type]分派不要假设事件顺序与阶段集合固定阶段可被配置裁剪使用overall_progress驱动全局进度条stage_progress只用于阶段内细节展示error事件后必须break事件流不会自行继续优先用config.cancel_translation()做程序化取消并兼容error事件中error字段为CancelledError对象的情况取消/异常后无需手动清理cleanup_temp_files()会自动回收临时目录除非设置了working_dir且非 debug 模式需要阶段明细时开启debugTrue会额外在working_dir中输出各阶段的 IL JSON如layout_generator.json、il_translated.json便于排查排版与翻译问题。相关源码索引异步翻译入口与事件定义babeldoc/format/pdf/high_level.py阶段流水线与权重表babeldoc/format/pdf/high_level.py配置与结果对象babeldoc/format/pdf/translation_config.py进度监视器阶段/权重/分片/取消babeldoc/progress_monitor.py跨线程事件桥接babeldoc/asynchronize/init.pyCLI 消费示例babeldoc/main.pyExecutor 消费示例babeldoc/tools/executor/babeldoc_adapter.py【免费下载链接】BabelDOCYet Another Document Translator项目地址: https://gitcode.com/GitHub_Trending/ba/BabelDOC创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考