# 翻译模块

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

## 环境变量

```bash
# Qwen（默认）
DASHSCOPE_API_KEY=sk-xxx

# DeepL
DEEPL_AUTH_KEY=xxx
```

> **重要限速说明（Qwen 机翻）**  
> 当前默认的 Qwen 翻译后端使用 `qwen-mt-flash` 云端模型，**官方限速较低，约 RPM=60（每分钟约 60 请求）**。  
> - 推荐通过 Redis 翻译缓存复用结果，避免对相同文本重复打云端  
> - 高并发场景需要在调用端做限流 / 去抖，或改为离线批量翻译  
> - 如需更高吞吐，可考虑 DeepL 或自建翻译服务

## 配置模型

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

- 业务侧（`QueryParser` / indexer）统一调用 `http://127.0.0.1:6006`
- 服务内按 `services.translation.capabilities` 加载并管理各翻译能力
- 已启用 capability 统一注册，后端实例按首次调用懒加载，避免多个本地模型在启动阶段一次性占满显存
- `config.yaml` 只保留部署相关配置；scene 规则、语言码映射、prompt 模板、模型方向约束等翻译域知识统一收口在 `translation/` 内部
- 每种能力独立配置 `enabled`、`model`、`base_url/api_url`、`timeout`、本地模型运行参数等部署项
- 每种能力显式声明 `backend` 类型，例如 `qwen_mt`、`llm`、`deepl`、`local_nllb`、`local_marian`
- `service_url`、`default_model`、`default_scene` 只从 `config/config.yaml` 读取，不再接受环境变量静默覆盖
- 外部接口通过 `model + scene` 指定本次使用哪种能力、哪个场景

配置入口在 `config/config.yaml -> services.translation`

## 本地模型部署

本仓库已内置 3 个本地机翻 capability：

- `nllb-200-distilled-600m`
- `opus-mt-zh-en`
- `opus-mt-en-zh`

推荐流程：

1. 创建独立运行环境：`./scripts/setup_translator_venv.sh`
2. 下载本地模型：`./.venv-translator/bin/python scripts/download_translation_models.py --all-local`
3. 在 `config/config.yaml` 中把对应 capability 的 `enabled` 改为 `true`
4. 启动服务：`./scripts/start_translator.sh`

默认模型目录：

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

说明：

- 目前只支持 3 个标准 scene：`general`、`sku_name`、`ecommerce_search_query`
- `nllb-200-distilled-600m` 支持多语，但依赖明确的 `source_lang`
- 两个 OPUS 模型分别只支持 `zh -> en` 与 `en -> zh`
- 本地模型建议单 worker 运行，避免重复加载占用显存

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

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

- `POST /translate`: 文本翻译（支持所有已启用 capability）
- `GET /health`: 健康检查

### `POST /translate`

**请求体**：

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

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

**响应体**（单条）：

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

**响应体**（批量）：

```json
{
  "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` 是标准字段
- `prompt` 不属于外部接口；LLM prompt 由 translator service 内部根据 `scene` 生成
- `model` 只能选择已在 `services.translation.capabilities` 中启用的能力
- `/health` 会返回 `default_model`、`default_scene`、`enabled_capabilities` 与 `loaded_models`

---

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

代码侧（如 query/indexer）通过 `translation.create_translation_client()` 获取实例并调用 `translate()`；

### 输入输出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`）做最优调用，client / backend 可暴露：

- `supports_batch: bool`（property）