翻译模块说明.md 6.23 KB
Edit Raw Blame History


翻译模块说明（Qwen / DeepL）
本文档汇总翻译模块的接口使用说明与Python 模块用法，对应代码：


HTTP 服务：api/translator_app.py
Python 模块：query/translator.py


1. 功能概述
当前翻译模块支持两种后端：


Qwen（默认）：通过阿里云百炼 DashScope 的 OpenAI 兼容接口调用 qwen-mt-flash
DeepL：通过 DeepL API 调用翻译（保留原有能力）


两种方式均支持：


Redis 缓存（如启用）：同文案同目标语言命中缓存直接返回
source_lang 自动检测：当 source_lang 为空或 "auto" 时启用自动检测（Qwen 使用 "auto"）


2. 环境变量与配置
项目会在 config/env_config.py 中加载项目根目录的 .env，常用变量如下：
# Qwen / DashScope
DASHSCOPE_API_KEY=sk-xxx

# DeepL
DEEPL_AUTH_KEY=xxx

# 可选：翻译服务默认模型（HTTP 服务启动后若请求不传 model，则使用此默认值）
TRANSLATION_MODEL=qwen  # 或 deepl


说明：


Qwen 使用 DASHSCOPE_API_KEY
DeepL 使用 DEEPL_AUTH_KEY
.env 中的 OPENAI_API_KEY 不是本翻译模块必须项（当前实现用的是 DASHSCOPE_API_KEY）


3. HTTP 翻译服务（api/translator_app.py）
3.1 启动命令
推荐（热更新）：
cd /data/saas-search
uvicorn api.translator_app:app --host 0.0.0.0 --port 6006 --reload


指定默认模型（不传请求 model 时生效）：
cd /data/saas-search
export TRANSLATION_MODEL=qwen   # 或 deepl
uvicorn api.translator_app:app --host 0.0.0.0 --port 6006 --reload

3.2 接口列表

GET /health：健康检查（返回默认模型、已初始化模型列表等）
POST /translate：翻译文本
GET /docs：Swagger UI

3.3 /translate 请求参数
请求体（JSON）：
{
  "text": "要翻译的文本",
  "target_lang": "en",
  "source_lang": "auto",
  "model": "qwen"
}


text：必填，待翻译文本
target_lang：必填，目标语言代码（见“语言支持”）
source_lang：可选，源语言代码；不传或传 "auto" 时自动检测
model：可选，"qwen" 或 "deepl"；默认 "qwen"

3.4 /translate 返回参数
响应体（JSON，成功时）：
{
  "text": "商品名称",
  "target_lang": "en",
  "source_lang": "zh",
  "translated_text": "Product name",
  "status": "success",
  "model": "qwen"
}

3.5 请求示例（curl）
健康检查：
curl http://localhost:6006/health


默认（qwen）中文 → 英文：
curl -X POST http://localhost:6006/translate \
  -H "Content-Type: application/json" \
  -d '{"text":"我看到这个视频后没有笑","target_lang":"en","source_lang":"auto"}'


显式指定 qwen，英文 → 简体中文：
curl -X POST http://localhost:6006/translate \
  -H "Content-Type: application/json" \
  -d '{"text":"Product name","target_lang":"zh","source_lang":"en","model":"qwen"}'


繁体中文（zh_tw）测试：
curl -X POST http://localhost:6006/translate \
  -H "Content-Type: application/json" \
  -d '{"text":"商品名稱","target_lang":"zh_tw","source_lang":"auto","model":"qwen"}'


切换 DeepL：
curl -X POST http://localhost:6006/translate \
  -H "Content-Type: application/json" \
  -d '{"text":"商品名称","target_lang":"en","source_lang":"zh","model":"deepl"}'

3.6 关于提示词（Prompt）
HTTP 服务内部使用了固定提示词 TRANSLATION_PROMPT（适用于“商品 SKU 英文名”场景），并通过 prompt 参数传入 Translator.translate()。


DeepL：prompt 会作为 DeepL 的 context 使用（影响翻译但不被翻译）
Qwen：当前实现未将 prompt/context 传给 Qwen 的 translation_options（即对 Qwen 不生效）


4. Python 翻译模块（query/translator.py）
4.1 基本用法
from query.translator import Translator

# 默认使用 qwen
translator = Translator()

result = translator.translate(
    text="我看到这个视频后没有笑",
    target_lang="en",
    source_lang="auto",
)
print(result)


显式选择模型：
translator_qwen = Translator(model="qwen")
translator_deepl = Translator(model="deepl")

4.2 关键参数

Translator(model="qwen" | "deepl")：选择翻译模型，默认 "qwen"
translate(text, target_lang, source_lang=None, context=None, prompt=None)：


target_lang / source_lang：语言代码（见“语言支持”）
source_lang 为空或 "auto"：自动检测
prompt：
DeepL：作为 context 使用
Qwen：当前未使用


4.3 缓存（Redis）
Translator(use_cache=True) 时会连接 Redis 并缓存翻译结果。


Redis 连接配置来自 config/env_config.py 的 REDIS_CONFIG
缓存 key 前缀默认 trans（可用 REDIS_TRANSLATION_CACHE_PREFIX 覆盖）


5. Qwen 语言支持（按 qwen-mt-plus/flash/turbo 标准）

以下为 Qwen 翻译模型支持的语言（代码 → 英文名），并已用于 query/translator.py 的映射。


代码
英文名


en
English


zh
Chinese


zh_tw
Traditional Chinese


ru
Russian


ja
Japanese


ko
Korean


es
Spanish


fr
French


pt
Portuguese


de
German


it
Italian


th
Thai


vi
Vietnamese


id
Indonesian


ms
Malay


ar
Arabic


hi
Hindi


he
Hebrew


my
Burmese


ta
Tamil


ur
Urdu


bn
Bengali


pl
Polish


nl
Dutch


ro
Romanian


tr
Turkish


km
Khmer


lo
Lao


yue
Cantonese


cs
Czech


el
Greek


sv
Swedish


hu
Hungarian


da
Danish


fi
Finnish


uk
Ukrainian


bg
Bulgarian


6. 常见问题（FAQ）
6.1 Qwen 调用报错 / 无法初始化

确认 .env 中已配置 DASHSCOPE_API_KEY
确认安装依赖：openai（Python 包）
如在海外地域使用模型，将 base_url 切换为 https://dashscope-intl.aliyuncs.com/compatible-mode/v1

6.2 DeepL 返回 403 / 翻译失败

确认 .env 中已配置 DEEPL_AUTH_KEY
若使用的是 Pro key，请使用 https://api.deepl.com/v2/translate（当前代码即为该地址）