Name	Last Update	Last Commit 3eff49b7 – trans nllb-200-distilled-600M性能提升 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. 设计目标

翻译模块采用：

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

这套设计的目标是：

翻译能力可以独立扩展、独立启停
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: 16
        max_input_length: 256
        max_new_tokens: 64
        num_beams: 1
        attn_implementation: "sdpa"
      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 机器翻译模型
来源：Meta NLLB（No Language Left Behind）系列的 600M 蒸馏版
目标：用一个模型覆盖大规模多语言互译，而不是只服务某一个固定语言对
结构特点：
- Transformer encoder-decoder 架构
- 12 层 encoder + 12 层 decoder
- d_model=1024
- 多头注意力，适合多语统一建模
- 通过 source_lang + forced_bos_token_id 控制翻译方向
- 语言标识采用 language_script 形式，例如 eng_Latn、zho_Hans

模型定位：

优势是多语覆盖面广，一个模型可以支撑很多语言方向
劣势是相较于 Marian 这种双语专用模型，推理更重、延迟更高
在我们当前业务里，它更适合“多语覆盖优先”的场景，不适合拿来和专用中英模型拼极致吞吐

显存占用情况：

600M模型半float16权重约1.25G，推理时会叠加 CUDA context、allocator reserve、激活张量、batch、输入长度、生成长度等开销
当前这台 Tesla T4 上，优化后的实际运行峰值大约在 2.8-3.0 GiB

当前实现特点：

backend 类型：local_nllb
支持多语
调用时必须显式传 source_lang
语言码映射定义在 <code>translation/languages.py</code>
当前 T4 推荐配置：device=cuda、torch_dtype=float16、batch_size=16、max_new_tokens=64、attn_implementation=sdpa

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 只建议用于功能验证或离线低频任务
对 NLLB，T4 上优先采用 batch_size=16 + max_new_tokens=64 + attn_implementation=sdpa

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`	`cuda`	500	7.3397	25.9577	19.26	51.915	832.64	1263.01
`nllb-200-distilled-600m`	`en -> zh`	`cuda`	500	7.4152	42.0405	11.89	84.081	1093.87	2107.44

NLLB 性能优化经验：

起作用的优化点 1：float16 + cuda
- 模型确认以 torch.float16 实际加载到 cuda:0
- 优化后在 T4 上的峰值显存约 2.8-3.0 GiB
起作用的优化点 2：batch_size=16
- 相比 batch_size=8，吞吐提升明显
- 继续提升到 32 虽然还能增吞吐，但 batch p95 和 batch max 会恶化很多
起作用的优化点 3：max_new_tokens=64
- 商品标题翻译通常不需要 256 的生成上限
- 收紧生成长度后，zh->en 与 en->zh 都有明显收益
起作用的优化点 4：attn_implementation=sdpa
- 对当前 PyTorch + T4 环境有效
- 配合半精度和较合理 batch size 后，整体延迟进一步下降

为什么最终没有采用其它方案：

当前 HF 原生方案已经能在 T4 上稳定跑通
在 10G+ 可用显存下，原生 float16 已足够支撑 NLLB-600M
因此暂时不需要为这个模型额外引入 GGUF 或 CT2 的新运行栈
如果未来目标变成“继续压缩显存”或“进一步追求更低延迟”，再评估 ct2-int8 会更合适

关键结论：

当前机器上，opus-mt-zh-en 是三个新增本地模型里最快的
opus-mt-en-zh 大约是 opus-mt-zh-en 吞吐的一半
nllb-200-distilled-600M 在显存充足时可以用 cuda + float16 + batch_size=16 + max_new_tokens=64 + sdpa 正常运行
nllb 最终可用，但吞吐仍明显低于两个 Marian 模型，更适合多语覆盖或独立资源环境

最终推荐部署方案：

模型：facebook/nllb-200-distilled-600M
设备：cuda
精度：float16
推荐卡型：至少 Tesla T4 16GB 这一级别
推荐 batch：16
推荐 max_input_length：256
推荐 max_new_tokens：64
推荐 num_beams：1
推荐注意力实现：sdpa
运行方式：单 worker，避免重复加载

更详细的性能说明见：

<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`