ai-saas / saas-search

README.md 15 KB

Translation Module

translation/ 是当前项目翻译能力的主目录。
如果要开发、部署、联调、压测翻译服务，优先看这份文档。

对应服务：

相关脚本与报告：

1. 设计目标

翻译模块已经从旧的 provider 体系中独立出来，采用：

  • 一个 translator service
  • 多个 capability backend
  • 一个统一外部接口：model + scene

这套设计的目标是：

  • 业务侧不再关心具体翻译 provider 细节
  • 翻译能力可以独立扩展、独立启停
  • scene、语言码、prompt 模板、模型方向约束等翻译域知识集中在 translation/
  • 配置尽量集中在 <code>config/config.yaml</code> 的 services.translation
  • 配置错误应尽早报错，不做静默兼容和隐式回退

2. 目录结构

核心文件：

后端实现：

3. 配置约定

翻译的部署配置统一放在：

示例：

services:
  translation:
    service_url: "http://127.0.0.1:6006"
    default_model: "llm"
    default_scene: "general"
    timeout_sec: 10.0
    cache:
      enabled: true
      key_prefix: "trans:v2"
      ttl_seconds: 62208000
      sliding_expiration: true
      key_include_scene: true
      key_include_source_lang: true
    capabilities:
      qwen-mt:
        enabled: true
        backend: "qwen_mt"
        model: "qwen-mt-flash"
        base_url: "https://dashscope-us.aliyuncs.com/compatible-mode/v1"
        timeout_sec: 10.0
        use_cache: true
      llm:
        enabled: true
        backend: "llm"
        model: "qwen-flash"
        base_url: "https://dashscope-us.aliyuncs.com/compatible-mode/v1"
        timeout_sec: 30.0
      deepl:
        enabled: false
        backend: "deepl"
        api_url: "https://api.deepl.com/v2/translate"
        timeout_sec: 10.0
      nllb-200-distilled-600m:
        enabled: true
        backend: "local_nllb"
        model_id: "facebook/nllb-200-distilled-600M"
        model_dir: "./models/translation/facebook/nllb-200-distilled-600M"
        device: "cuda"
        torch_dtype: "float16"
        batch_size: 8
        max_input_length: 256
        max_new_tokens: 256
        num_beams: 1
      opus-mt-zh-en:
        enabled: true
        backend: "local_marian"
        model_id: "Helsinki-NLP/opus-mt-zh-en"
        model_dir: "./models/translation/Helsinki-NLP/opus-mt-zh-en"
        device: "cuda"
        torch_dtype: "float16"
        batch_size: 16
        max_input_length: 256
        max_new_tokens: 256
        num_beams: 1
      opus-mt-en-zh:
        enabled: true
        backend: "local_marian"
        model_id: "Helsinki-NLP/opus-mt-en-zh"
        model_dir: "./models/translation/Helsinki-NLP/opus-mt-en-zh"
        device: "cuda"
        torch_dtype: "float16"
        batch_size: 16
        max_input_length: 256
        max_new_tokens: 256
        num_beams: 1

配置边界：

  • config.yaml 只放部署和运行参数 例如 service_url、default_model、default_scene、enabled、base_url、api_url、model_dir、device
  • translation 目录内部放翻译静态知识 例如 scene 规则、语言码映射、prompt 模板、Marian 方向约束

说明：

  • service_url、default_model、default_scene 只从 YAML 读取
  • 不再通过环境变量静默覆盖翻译行为配置
  • 密钥仍通过环境变量提供

4. 环境变量

当前翻译模块主要依赖：

# Qwen / LLM
DASHSCOPE_API_KEY=sk-xxx

# DeepL
DEEPL_AUTH_KEY=xxx

服务启动端口仍可以由启动脚本环境控制：

TRANSLATION_HOST=0.0.0.0
TRANSLATION_PORT=6006

5. Scene 规则

当前只支持 3 个标准 scene：

  • general
  • sku_name
  • ecommerce_search_query

定义位置：

约定：

  • scene 是公共接口字段
  • 不再接受旧的 context
  • 不再对外暴露 prompt
  • LLM prompt 在服务内根据 scene 自动生成

6. 对外 HTTP 接口

服务入口在：

默认地址：

  • http://localhost:6006

提供接口：

  • POST /translate
  • GET /health

6.1 POST /translate

请求体：

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

字段说明：

  • text 支持 string 或 string[]
  • target_lang 目标语言
  • source_lang 源语言
  • model 已配置的 capability 名称
  • scene 翻译场景

响应体：

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

批量时：

  • 返回列表和输入等长
  • 单条失败返回 null

6.2 GET /health

返回示例：

{
  "status": "healthy",
  "service": "translation",
  "default_model": "llm",
  "default_scene": "general",
  "available_models": ["qwen-mt", "llm", "nllb-200-distilled-600m", "opus-mt-zh-en", "opus-mt-en-zh"],
  "enabled_capabilities": ["qwen-mt", "llm", "nllb-200-distilled-600m", "opus-mt-zh-en", "opus-mt-en-zh"],
  "loaded_models": ["llm"]
}

7. 代码调用方式

业务侧统一这样调用：

from translation.client import create_translation_client

translator = create_translation_client()
result = translator.translate(
    text="商品名称",
    source_lang="zh",
    target_lang="en",
    model="opus-mt-zh-en",
    scene="sku_name",
)

批量调用：

results = translator.translate(
    text=["商品1", "商品2"],
    source_lang="zh",
    target_lang="en",
    model="opus-mt-zh-en",
    scene="sku_name",
)

8. 具体实现说明

8.1 Qwen-MT

实现文件：

特点：

  • 云端机翻
  • 支持 Redis 翻译缓存
  • 适合质量优先、非超高并发场景

注意：

  • 当前默认 qwen-mt-flash 限速较低
  • 大量重复请求应依赖缓存

8.2 LLM Translation

实现文件：

特点：

  • 通用大模型翻译
  • 根据 scene 生成内部 prompt
  • 更灵活，但成本和稳定性取决于上游模型

8.3 DeepL

实现文件：

特点：

  • 商业翻译 API
  • scene 会映射到内部上下文
  • 当前默认关闭

8.4 facebook/nllb-200-distilled-600M

实现文件：

模型信息：

  • Hugging Face 名称：facebook/nllb-200-distilled-600M
  • 本地目录：models/translation/facebook/nllb-200-distilled-600M
  • 当前磁盘占用：约 2.4G
  • 模型类型：多语种 Seq2Seq 机器翻译模型
  • 结构特点：
    • encoder-decoder 架构
    • 面向多语种互译
    • 通过语言码控制源语言和目标语言

当前实现特点：

适合场景：

  • 需要多语覆盖
  • 需要一个模型处理多语言对

不太适合：

  • 当前共享 GPU 环境下的常驻在线服务

8.5 opus-mt-zh-en

实现文件：

模型信息：

  • Hugging Face 名称：Helsinki-NLP/opus-mt-zh-en
  • 本地目录：models/translation/Helsinki-NLP/opus-mt-zh-en
  • 当前磁盘占用：约 1.2G
  • 模型类型：Marian / OPUS MT 专用双语翻译模型
  • 方向约束：只支持 zh -> en

结构特点：

  • encoder-decoder Seq2Seq
  • 聚焦特定语言对
  • 模型更小、加载更轻、吞吐更高

8.6 opus-mt-en-zh

实现文件：

模型信息：

  • Hugging Face 名称：Helsinki-NLP/opus-mt-en-zh
  • 本地目录：models/translation/Helsinki-NLP/opus-mt-en-zh
  • 当前磁盘占用：约 1.5G
  • 模型类型：Marian / OPUS MT 专用双语翻译模型
  • 方向约束：只支持 en -> zh

结构特点：

  • encoder-decoder Seq2Seq
  • 双语定向模型
  • 更适合中英双向拆分部署

9. 本地模型安装与部署

9.1 准备环境

cd /data/saas-search
./scripts/setup_translator_venv.sh

9.2 下载模型

下载全部本地模型：

./.venv-translator/bin/python scripts/download_translation_models.py --all-local

下载完成后，默认目录应存在：

models/translation/facebook/nllb-200-distilled-600M
models/translation/Helsinki-NLP/opus-mt-zh-en
models/translation/Helsinki-NLP/opus-mt-en-zh

9.3 打开能力

编辑 <code>config/config.yaml</code>，把对应模型的 enabled 改成 true。

9.4 启动服务

./scripts/start_translator.sh

建议：

  • 本地模型服务使用单 worker
  • 避免多 worker 重复加载模型
  • GPU 机器上优先使用 cuda + float16
  • CPU 只建议用于功能验证或离线低频任务

9.5 验证

健康检查：

curl http://127.0.0.1:6006/health

翻译测试：

curl -X POST http://127.0.0.1:6006/translate \
  -H 'Content-Type: application/json' \
  -d '{
    "text": "男士偏光飞行员太阳镜",
    "source_lang": "zh",
    "target_lang": "en",
    "model": "opus-mt-zh-en",
    "scene": "sku_name"
  }'

10. 性能测试与复现

性能脚本：

数据集：

复现命令：

cd /data/saas-search
./.venv-translator/bin/python scripts/benchmark_translation_local_models.py

单模型复现示例：

./.venv-translator/bin/python scripts/benchmark_translation_local_models.py \
  --single \
  --model opus-mt-zh-en \
  --source-lang zh \
  --target-lang en \
  --column title_cn \
  --scene sku_name

当前压测环境：

  • GPU：Tesla T4 16GB
  • Python env：.venv-translator
  • 数据量：18,576 条商品标题

性能结果摘要：

Model Direction Device Rows Load s Translate s Items/s Avg item ms Batch p50 ms Batch p95 ms
opus-mt-zh-en zh -> en cuda 18,576 3.1435 497.7513 37.32 26.795 301.99 1835.81
opus-mt-en-zh en -> zh cuda 18,576 3.1867 987.3994 18.81 53.155 449.14 2012.12
nllb-200-distilled-600m zh -> en cpu 128 4.4589 132.3088 0.97 1033.662 3853.39 6896.14
nllb-200-distilled-600m en -> zh cpu 128 4.5039 317.8845 0.40 2483.473 6138.87 35134.11

关键结论：

  • 当前机器上，opus-mt-zh-en 是三个新增本地模型里最快的
  • opus-mt-en-zh 大约是 opus-mt-zh-en 吞吐的一半
  • nllb-200-distilled-600M 在当前共享 T4 环境下无法完成 GPU 冷启动，会 OOM
  • nllb 的 CPU fallback 可用，但明显更慢，更适合隔离部署或离线任务

更详细的性能说明见：

11. 开发说明

如果要新增翻译 backend，最少需要做这些事：

  1. 在 <code>translation/backends/</code> 下新增实现
  2. 在 <code>translation/service.py</code> 注册 backend 创建逻辑
  3. 在 <code>config/config.yaml</code> 的 services.translation.capabilities 中新增 capability 配置
  4. 如果有新的静态规则：

原则：

  • 不要再引入 translation provider 兼容层
  • 不要把 scene / prompt / 语言方向规则重新散落到别的目录
  • 不要在代码里写隐式默认和静默兼容

12. 常见建议

  • 中英商品标题双向场景，优先考虑 opus-mt-zh-en 和 opus-mt-en-zh
  • 多语种统一方案，可以考虑 nllb-200-distilled-600M
  • 但 nllb 更适合独占资源环境
  • 如果追求更高质量或更复杂语义处理，可使用 qwen-mt 或 llm
  • 如果追求稳定商业 API，可考虑 deepl

13. 相关文档