Name	Last Update	Last Commit 00471f80 – trans History
..
backends	Loading commit data...
README.md	Loading commit data...
__init__.py	Loading commit data...
client.py	Loading commit data...
languages.py	Loading commit data...
prompts.py	Loading commit data...
protocols.py	Loading commit data...
scenes.py	Loading commit data...
service.py	Loading commit data...
settings.py	Loading commit data...

README.md

Translation Module

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

对应服务：

translator service：http://127.0.0.1:6006
业务侧统一通过 <code>translation/client.py</code> 调用
服务内统一通过 <code>translation/service.py</code> 路由到具体翻译实现

1. 设计目标

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

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

这套设计的目标是：

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

2. 目录结构

核心文件：

<code>translation/client.py</code> 业务侧 HTTP client，供 query/indexer 等模块调用
<code>translation/service.py</code> translator service 内部的统一编排层
<code>translation/settings.py</code> 翻译配置的规范化与校验辅助函数
<code>translation/scenes.py</code> scene 规范和值校验
<code>translation/languages.py</code> 语言码映射、Marian 方向映射等静态知识
<code>translation/prompts.py</code> LLM 翻译 prompt 模板
<code>translation/protocols.py</code> 输入输出协议类型

后端实现：

<code>translation/backends/qwen_mt.py</code> Qwen-MT 云端翻译
<code>translation/backends/llm.py</code> 通用 LLM 翻译
<code>translation/backends/deepl.py</code> DeepL 翻译
<code>translation/backends/local_seq2seq.py</code> 本地 Hugging Face Seq2Seq 模型，包括 NLLB 和 Marian/OPUS MT

3. 配置约定

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

<code>config/config.yaml</code> -> services.translation

示例：

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

定义位置：

<code>translation/scenes.py</code>

约定：

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

6. 对外 HTTP 接口

服务入口在：

<code>api/translator_app.py</code>

默认地址：

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

实现文件：

<code>translation/backends/qwen_mt.py</code>

特点：

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

注意：

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

8.2 LLM Translation

实现文件：

<code>translation/backends/llm.py</code>

特点：

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

8.3 DeepL

实现文件：

<code>translation/backends/deepl.py</code>

特点：

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

8.4 `facebook/nllb-200-distilled-600M`

实现文件：

<code>translation/backends/local_seq2seq.py</code>

模型信息：

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

当前实现特点：

backend 类型：local_nllb
支持多语
调用时必须显式传 source_lang
语言码映射定义在 <code>translation/languages.py</code>

适合场景：

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

不太适合：

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

8.5 `opus-mt-zh-en`

实现文件：

<code>translation/backends/local_seq2seq.py</code>

模型信息：

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`

实现文件：

<code>translation/backends/local_seq2seq.py</code>

模型信息：

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. 性能测试与复现

性能脚本：

<code>scripts/benchmark_translation_local_models.py</code>

数据集：

<code>products_analyzed.csv</code>

复现命令：

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 可用，但明显更慢，更适合隔离部署或离线任务

更详细的性能说明见：

<code>perf_reports/20260317/translation_local_models/README.md</code>

11. 开发说明

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

在 <code>translation/backends/</code> 下新增实现
在 <code>translation/service.py</code> 注册 backend 创建逻辑
在 <code>config/config.yaml</code> 的 services.translation.capabilities 中新增 capability 配置
如果有新的静态规则：
- scene 规则放到 <code>translation/scenes.py</code>
- 语言映射放到 <code>translation/languages.py</code>
- prompt 模板放到 <code>translation/prompts.py</code>

原则：

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

12. 常见建议

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

GITLAB

ai-saas / saas-search

README.md

Translation Module

1. 设计目标

2. 目录结构

3. 配置约定

4. 环境变量

5. Scene 规则

6. 对外 HTTP 接口

6.1 POST /translate

6.2 GET /health

7. 代码调用方式

8. 具体实现说明

8.1 Qwen-MT

8.2 LLM Translation

8.3 DeepL

8.4 `facebook/nllb-200-distilled-600M`

8.5 `opus-mt-zh-en`

8.6 `opus-mt-en-zh`

9. 本地模型安装与部署

9.1 准备环境

9.2 下载模型

9.3 打开能力

9.4 启动服务

9.5 验证

10. 性能测试与复现

11. 开发说明

12. 常见建议

13. 相关文档

README.md

Translation Module

1. 设计目标

2. 目录结构

3. 配置约定

4. 环境变量

5. Scene 规则

6. 对外 HTTP 接口

6.1 POST /translate

6.2 GET /health

7. 代码调用方式

8. 具体实现说明

8.1 Qwen-MT

8.2 LLM Translation

8.3 DeepL

8.4 facebook/nllb-200-distilled-600M

8.5 opus-mt-zh-en

8.6 opus-mt-en-zh

9. 本地模型安装与部署

9.1 准备环境

9.2 下载模型

9.3 打开能力

9.4 启动服务

9.5 验证

10. 性能测试与复现

11. 开发说明

12. 常见建议

13. 相关文档

8.4 `facebook/nllb-200-distilled-600M`

8.5 `opus-mt-zh-en`

8.6 `opus-mt-en-zh`