08 — LLM 翻译模块

源码目录：src/vocal10n/llm/。

职责

LLM 阶段对转写流执行两类任务：

  1. 源文本修正。 对 STT 原始文本进行词汇表/RAG 替换，并可选补标点。
  2. 翻译。 基于修正后的源文本生成目标语言文本，并可利用前 context_window_size 个翻译对提供上下文。

默认由同一个 Qwen3-4B 实例处理两类调用。在 n_ctx=512 下，单次调用开销通常低于 translation.target_latency_ms 预算。

后端

  • engine.py：本地 GGUF（llama-cpp-python）后端。
  • api_backend.py：OpenAI 兼容 HTTP 后端（LM Studio、Ollama OpenAI shim、vLLM、OpenAI 等），使用 translation.api_* 配置。

由 translation.backend 选择当前后端。LLM 页可在运行中切换后端，controller 会热切换实现并保留 prompt 与 KB 状态。

Prompt 格式

采用 ChatML 风格消息，并以 assistant 提示结尾。该格式在 Qwen3-4B-Instruct 上可稳定生成非 JSON 的短翻译输出。构建逻辑位于 translator.py，包含：

  • 系统消息：声明源/目标语言与行为规则（“只翻译不解释、保留专有名词、优先词汇表”）。
  • 可选词汇表块：小词表直接内嵌，大词表由 rag.py 检索后注入。
  • 短上下文窗口：最近若干 (source, target) 对，帮助代词与时态一致。
  • 当前待翻译源文本。

默认生成参数（temperature=0.0、top_k=1、top_p=1.0、max_tokens=64）强调确定性与低延迟。

Corrector

corrector.py 在翻译前执行（启用时）：

  • 将源文本中的词表 key 替换为规范写法。
  • 对少量缺标点 confirmed 片段，可选走一次“补标点并清洗”提示。

将修正流程与翻译流程拆分，可保持翻译调用短而稳定。

RAG

当挂载词汇表条目超过 translation.rag_threshold 时，启用 rag.py：

  • 使用轻量本地 embedding 模型对词条向量化。
  • 每次翻译先对源文本向量化，检索 top-K 相关词条注入 prompt，而非拼接全部词表。

这样在大词库（数千词）下仍可控制上下文长度。

Controller

controller.py 与 dispatcher 的衔接包括：

  • 订阅 STT_CONFIRMED 与（可选）partial 流。
  • 按 pipeline.translation_debounce_ms 对 partial 调用防抖。
  • 按 pipeline.confirmed_batch_delay_ms 聚合 confirmed，减少 Whisper 分段不佳导致的碎片翻译。
  • 维护滚动翻译上下文（source/target pairs）。
  • 发布 TRANSLATION_PARTIAL 与 TRANSLATION_CONFIRMED。
  • 更新 SystemState.current_translation 与 SystemState.accumulated_translation。

手动输入模式（无 STT）也复用该入口；当 STT 关闭时，不再依赖 confirmed 事件门控输出。