翻译模块

快速上手：见 docs/QUICKSTART.md 第 3.4 节。

环境变量

# Qwen（默认）
DASHSCOPE_API_KEY=sk-xxx

# DeepL
DEEPL_AUTH_KEY=xxx

# 可选
TRANSLATION_SERVICE_URL=http://127.0.0.1:6006
TRANSLATION_MODEL=llm   # 默认能力；也可传 qwen-mt / deepl
TRANSLATION_SCENE=general

重要限速说明（Qwen 机翻）
当前默认的 Qwen 翻译后端使用 qwen-mt-flash 云端模型，官方限速较低，约 RPM=60（每分钟约 60 请求）。

• 推荐通过 Redis 翻译缓存复用结果，避免对相同文本重复打云端
  
• 高并发场景需要在调用端做限流 / 去抖，或改为离线批量翻译
  
• 如需更高吞吐，可考虑 DeepL 或自建翻译服务

配置模型

翻译已改为“一个翻译服务 + 多种翻译能力”的结构：

• 业务侧（QueryParser / indexer）统一调用 http://127.0.0.1:6006
• 服务内按 services.translation.capabilities 加载并管理各翻译能力
• 每种能力独立配置 enabled、model、timeout 等参数
• 外部接口通过 model + scene 指定本次使用哪种能力、哪个场景

配置入口在 config/config.yaml -> services.translation，核心字段示例：

services:
  translation:
    service_url: "http://127.0.0.1:6006"
    default_model: "llm"
    default_scene: "general"
    timeout_sec: 10.0
    capabilities:
      qwen-mt:
        enabled: true
        model: "qwen-mt-flash"
      llm:
        enabled: true
        model: "qwen-flash"
      deepl:
        enabled: false

HTTP 接口契约（translator service，端口 6006）

服务默认监听 http://localhost:6006，提供：

• POST /translate: 文本翻译（支持 qwen/qwen-mt、deepl、llm）
• GET /health: 健康检查

POST /translate

请求体：

{
  "text": "商品名称",
  "target_lang": "en",
  "source_lang": "zh",
  "model": "qwen-mt",
  "scene": "sku_name",
  "prompt": null
}

• text 支持两种形式：
  • 单条：string
  • 批量：string[]（等长返回，顺序对应）

响应体（单条）：

{
  "text": "商品名称",
  "target_lang": "en",
  "source_lang": "zh",
  "translated_text": "Product name",
  "status": "success",
  "model": "qwen-mt",
  "scene": "sku_name"
}

响应体（批量）：

{
  "text": ["商品名称1", "商品名称2"],
  "target_lang": "en",
  "source_lang": "zh",
  "translated_text": ["Product name 1", null],
  "status": "success",
  "model": "qwen-mt",
  "scene": "sku_name"
}

批量模式下，单条失败用 null 占位（即 translated_text[i] = null），保证长度与顺序一一对应，避免部分失败导致整批报错。

说明：

• scene 是标准字段，context 仅保留为兼容别名
• model 只能选择已在 services.translation.capabilities 中启用的能力
• /health 会返回 default_model、default_scene 与 enabled_capabilities

---

开发者接口约定（代码调用）

代码侧（如 query/indexer）仍通过 providers.translation.create_translation_provider() 获取实例并调用 translate()，但该实例现在固定是 translator service client，不再在业务侧做翻译 provider 选择。

输入输出形状（Shape）

• translate(text=...) 支持：
  • 单条：text: str → 返回 Optional[str]
  • 批量：text: List[str] → 返回 List[Optional[str]]
• 批量语义：返回列表必须与输入 等长且顺序对应；某条翻译失败时，对应位置为 None（HTTP JSON 中表现为 null）。

批量能力标识（supports_batch）

服务客户端与服务内后端都可以暴露 supports_batch。若后端不支持批量，服务端会逐条拆分并保持 shape。

为便于上层（如 api/translator_app.py）做最优调用，provider 可暴露：

• supports_batch: bool（property）