ai-saas / saas-search

Blame view

docs/翻译模块说明.md 3.05 KB
Edit Raw Normal View History
42e3aea6   tangwang   tidy 
1
 
  # 翻译模块
3cd09b3b   tangwang   翻译接口改为调用qwen-mt-f... 
2
42e3aea6   tangwang   tidy 
3
 
  **快速上手**：见 `docs/QUICKSTART.md` 第 3.4 节。
3cd09b3b   tangwang   翻译接口改为调用qwen-mt-f... 
4
42e3aea6   tangwang   tidy 
5
 
  ## 环境变量
3cd09b3b   tangwang   翻译接口改为调用qwen-mt-f... 
6
42e3aea6   tangwang   tidy 
7
8
 
  ```bash
  # Qwen（默认）
3cd09b3b   tangwang   翻译接口改为调用qwen-mt-f... 
9
10
11
12
13
 
  DASHSCOPE_API_KEY=sk-xxx
  
  # DeepL
  DEEPL_AUTH_KEY=xxx
42e3aea6   tangwang   tidy 
14
 
  # 可选
3cd09b3b   tangwang   翻译接口改为调用qwen-mt-f... 
15
16
17
 
  TRANSLATION_MODEL=qwen  # 或 deepl
  ```
985752f5   tangwang   1. 前端调试功能 
18
19
20
21
22
23
 
  > **重要限速说明（Qwen 机翻）**  
  > 当前默认的 Qwen 翻译后端使用 `qwen-mt-flash` 云端模型，**官方限速较低，约 RPM=60（每分钟约 60 请求）**。  
  > - 推荐通过 Redis 翻译缓存复用结果，避免对相同文本重复打云端  
  > - 高并发场景需要在调用端做限流 / 去抖，或改为离线批量翻译  
  > - 如需更高吞吐，可考虑 DeepL 或自建翻译服务
42e3aea6   tangwang   tidy 
24
 
  ## Provider 配置
3cd09b3b   tangwang   翻译接口改为调用qwen-mt-f... 
25
0e66a315   tangwang   docs 
26
 
  Provider 与 URL 在 `config/config.yaml` 的 `services.translation`。详见 [QUICKSTART.md](./QUICKSTART.md) §3 与 [DEVELOPER_GUIDE.md](./DEVELOPER_GUIDE.md) §7.2。
6f7840cf   tangwang   refactor: rename ... 
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
 
  
  ## HTTP 接口契约（translator service，端口 6006）
  
  服务默认监听 `http://localhost:6006`，提供：
  
  - `POST /translate`: 文本翻译（支持 `qwen/qwen-mt`、`deepl`、`llm`）
  - `GET /health`: 健康检查
  
  ### `POST /translate`
  
  **请求体**：
  
  ```json
  {
    "text": "商品名称",
    "target_lang": "en",
    "source_lang": "zh",
    "model": "qwen",
    "context": "sku_name",
    "prompt": null
  }
  ```
  
  - `text` 支持两种形式：
    - 单条：`string`
    - 批量：`string[]`（等长返回，顺序对应）
  
  **响应体**（单条）：
  
  ```json
  {
    "text": "商品名称",
    "target_lang": "en",
    "source_lang": "zh",
    "translated_text": "Product name",
    "status": "success",
    "model": "qwen"
  }
  ```
  
  **响应体**（批量）：
  
  ```json
  {
    "text": ["商品名称1", "商品名称2"],
    "target_lang": "en",
    "source_lang": "zh",
    "translated_text": ["Product name 1", null],
    "status": "success",
    "model": "qwen"
  }
  ```
  
  批量模式下，**单条失败用 `null` 占位**（即 `translated_text[i] = null`），保证长度与顺序一一对应，避免部分失败导致整批报错。
  
  ---
  
  ## 开发者接口约定（Provider / 代码调用）
  
  除 HTTP 微服务外，代码侧（如 query/indexer）通常通过 `providers.translation.create_translation_provider()` 获取翻译 provider 实例并调用 `translate()`。
  
  ### 输入输出形状（Shape）
  
  - `translate(text=...)` 支持：
    - **单条**：`text: str` → 返回 `Optional[str]`
    - **批量**：`text: List[str]` → 返回 `List[Optional[str]]`
  - **批量语义**：返回列表必须与输入 **等长且顺序对应**；某条翻译失败时，对应位置为 `None`（HTTP JSON 中表现为 `null`）。
  
  ### 批量能力标识（supports_batch）
  
  不同 provider 对批量的实现方式可能不同（例如：真正一次请求传多条，或内部循环逐条翻译并保持 shape）。
  
  为便于上层（如 `api/translator_app.py`）做最优调用，provider 可暴露：
  
  - `supports_batch: bool`（property）
  
  上层在收到 `text` 为列表时：
  
  - **若 `supports_batch=True`**：可以直接将列表传给 `translate(text=[...])`
  - **若 `supports_batch=False`**：上层会逐条拆分调用（仍保证输出列表一一对应、失败为 `null`）