Atomgit-Ascend/translategemma-4b-it
模型介绍文件和版本Pull Requests讨论分析
下载使用量0

TranslateGemma-4B-IT 模型部署文档

本文档提供了 TranslateGemma-4B-IT 翻译模型在昇腾 NPU 环境下的完整部署指南。

模型介绍

TranslateGemma 是 Google 基于 Gemma 3 系列模型开发的轻量级、最先进的开源翻译模型。TranslateGemma-4B-IT 支持 55 种语言的翻译任务,可以处理文本翻译和图像文本提取与翻译。

主要特性

  • 支持 55 种语言的互译
  • 支持文本翻译(单个和批量)
  • 支持图像文本提取和翻译(图像输入)
  • 支持流式响应(Server-Sent Events)
  • 支持昇腾 NPU 加速
  • 支持 CUDA 和 CPU 推理
  • 使用特殊的 chat template,支持 ISO 639-1 语言代码和区域化变体

目录结构

translategemma-4b-it/
├── api/
│   ├── __init__.py
│   ├── model_loader.py      # 模型加载器(支持NPU)
│   ├── inference.py          # 推理引擎
│   └── main.py               # FastAPI 服务
├── config/
│   └── config.yaml           # 配置文件
├── requirements.txt
├── Dockerfile
├── deploy.sh
└── README.md

环境要求

  • Python 3.8+
  • transformers>=4.40.0
  • torch>=2.0.0
  • fastapi>=0.100.0
  • 昇腾 910B NPU(可选,支持 NPU 加速)
  • CANN 7.0+(NPU 环境)

安装依赖

pip install -r requirements.txt

使用方法

1. 启动服务

cd translategemma-4b-it/api
python main.py

服务默认在 http://localhost:8000 启动(容器内端口)。通过 Docker 部署时,映射到宿主机端口 18002。

2. API 接口

健康检查

curl http://localhost:18002/health

文本翻译

curl -X POST http://localhost:18002/v1/translate \
  -H "Content-Type: application/json" \
  -d '{
    "source_text": "Hello, world!",
    "source_language": "en",
    "target_language": "zh"
  }'

批量文本翻译

curl -X POST http://localhost:18002/v1/translate \
  -H "Content-Type: application/json" \
  -d '{
    "source_text": ["Hello", "World"],
    "source_language": "en",
    "target_language": "zh"
  }'

流式文本翻译

curl -X POST http://localhost:18002/v1/translate \
  -H "Content-Type: application/json" \
  -d '{
    "source_text": "你好,世界!该数据在2026-01-08进行处理,其有效日期也为2026-01-08。该数据已于2026-01-08发布。请使用下方的按钮来了解有关您的存款的更多信息.",
    "source_language": "zh",
    "target_language": "en",
    "stream": true,
    "temperature": 0.3
  }'

流式响应格式为 Server-Sent Events (SSE),每行格式为:

data: {"delta": "片段", "translated_text": "累积文本", "source_language": "en", "target_language": "zh"}

data: [DONE]

注意:流式返回模式只支持单个文本,不支持批量文本。

图像文本提取和翻译

curl -X POST http://localhost:18002/v1/translate \
  -H "Content-Type: application/json" \
  -d '{
    "image_url": "https://c7.alamy.com/comp/2YAX36N/traffic-signs-in-czech-republic-pedestrian-zone-2YAX36N.jpg",
    "source_language": "cs",
    "target_language": "zh",
    "stream": true,
    "temperature": 0.3
  }'

流式图像文本提取和翻译

curl -X POST http://localhost:18002/v1/translate \
  -H "Content-Type: application/json" \
  -d '{
    "image_url": "https://c7.alamy.com/comp/2YAX36N/traffic-signs-in-czech-republic-pedestrian-zone-2YAX36N.jpg",
    "source_language": "cs",
    "target_language": "zh",
    "stream": true,
    "temperature": 0.3
  }'

注意:source_text 和 image_url 参数必须提供其中一个,不能同时提供。流式响应支持文本翻译和图像翻译。

3. 统一翻译接口

/v1/translate 接口支持两种输入模式和流式响应:

  1. 文本翻译模式:提供 source_text 参数(可以是单个字符串或字符串列表)
  2. 图像翻译模式:提供 image_url 参数
  3. 流式响应模式:设置 stream=true 时,返回 Server-Sent Events 格式的流式响应

4. 支持的参数

统一翻译接口支持以下参数:

必需参数:

  • source_language: 源语言代码(如 "en", "zh", "en-US")
  • target_language: 目标语言代码(如 "zh", "de-DE")
  • source_text 或 image_url: 必须提供其中一个

可选参数:

  • stream: 是否流式返回(默认:false)。流式模式支持单个文本翻译和图像翻译,不支持批量文本
  • max_new_tokens: 最大生成 token 数(默认:200)
  • do_sample: 是否使用采样(默认:false)
  • temperature: 采样温度(默认:1.0)
  • top_p: Top-p 采样参数(默认:1.0)
  • top_k: Top-k 采样参数(默认:50)

4. 语言代码格式

模型支持两种语言代码格式:

  1. ISO 639-1 Alpha-2 语言代码:如 en, zh, de
  2. 区域化变体:ISO 639-1 语言代码 + ISO 3166-1 Alpha-2 国家代码,如 en-US, en-GB, de-DE

示例:

  • en → zh:英语到中文
  • cs → de-DE:捷克语到德语(德国变体)
  • en-US → zh:美式英语到中文

5. 支持的语言

模型支持 55 种语言,完整列表如下:

序号语言名称语言代码
1南非荷兰语 (Afrikaans)af
2阿尔巴尼亚语 (Albanian)sq
3阿拉伯语 (Arabic)ar
4亚美尼亚语 (Armenian)hy
5阿塞拜疆语 (Azerbaijani)az
6巴斯克语 (Basque)eu
7白俄罗斯语 (Belarusian)be
8孟加拉语 (Bengali)bn
9波斯尼亚语 (Bosnian)bs
10保加利亚语 (Bulgarian)bg
11缅甸语 (Burmese)my
12加泰罗尼亚语 (Catalan)ca
13中文 (Chinese)zh
14克罗地亚语 (Croatian)hr
15捷克语 (Czech)cs
16丹麦语 (Danish)da
17荷兰语 (Dutch)nl
18英语 (English)en, en-US, en-GB
19爱沙尼亚语 (Estonian)et
20芬兰语 (Finnish)fi
21法语 (French)fr
22德语 (German)de, de-DE
23希腊语 (Greek)el
24古吉拉特语 (Gujarati)gu
25希伯来语 (Hebrew)he
26印地语 (Hindi)hi
27匈牙利语 (Hungarian)hu
28印度尼西亚语 (Indonesian)id
29意大利语 (Italian)it
30日语 (Japanese)ja
31卡纳达语 (Kannada)kn
32韩语 (Korean)ko
33拉脱维亚语 (Latvian)lv
34立陶宛语 (Lithuanian)lt
35马来语 (Malay)ms
36马拉雅拉姆语 (Malayalam)ml
37马拉地语 (Marathi)mr
38挪威语 (Norwegian)no
39波斯语 (Persian)fa
40波兰语 (Polish)pl
41葡萄牙语 (Portuguese)pt
42旁遮普语 (Punjabi)pa
43罗马尼亚语 (Romanian)ro
44俄语 (Russian)ru
45斯洛伐克语 (Slovak)sk
46斯洛文尼亚语 (Slovenian)sl
47西班牙语 (Spanish)es
48斯瓦希里语 (Swahili)sw
49瑞典语 (Swedish)sv
50泰米尔语 (Tamil)ta
51泰卢固语 (Telugu)te
52泰语 (Thai)th
53土耳其语 (Turkish)tr
54乌克兰语 (Ukrainian)uk
55越南语 (Vietnamese)vi

注意:

  • 模型支持 ISO 639-1 Alpha-2 语言代码(如 en, zh, de)
  • 部分语言支持区域化变体(如 en-US, en-GB, de-DE)
  • 完整语言列表和详细信息请参考 模型官方文档

Docker 部署

构建镜像

cd translategemma-4b-it
docker build -t translategemma-4b-it:latest .

启动容器(NPU 环境)

docker run -d \
  --name translategemma-4b-it \
  --privileged \
  --device=/dev/davinci2 \
  --device=/dev/davinci_manager \
  --device=/dev/devmm_svm \
  --device=/dev/hisi_hdc \
  -v /usr/local/Ascend/driver:/usr/local/Ascend/driver \
  -v /usr/local/Ascend/add-ons:/usr/local/Ascend/add-ons \
  -v /data/models:/app/models \
  -p 18002:8000 \
  --restart unless-stopped \
  translategemma-4b-it:latest

使用部署脚本

cd translategemma-4b-it
./deploy.sh

部署脚本会自动:

  • 检查 NPU 环境
  • 构建 Docker 镜像
  • 启动容器并配置 NPU 设备(davinci2)
  • 映射端口 18002

环境变量

  • MODEL_CACHE_DIR: 模型缓存目录(默认:/app/models)
  • LOCAL_MODEL_PATH: 本地模型路径(可选)
  • PORT: 服务端口(默认:8000)
  • WORKERS: 工作进程数(默认:1)
  • LOG_LEVEL: 日志级别(默认:INFO)
  • ASCEND_RT_VISIBLE_DEVICES: 物理 NPU 设备 ID
  • NPU_VISIBLE_DEVICES: 容器内逻辑 NPU 设备 ID

模型下载

模型会在首次启动时自动从 AtomGit 下载,也可以手动下载:

pip install atomgit-hub
# 使用 atomgit 下载
pip install -U atomgit
python -c "from atomgit_hub import snapshot_download; snapshot_download('hf_mirrors/google/translategemma-4b-it', local_dir='/data/models/translategemma-4b-it')"

注意:访问 Gemma 模型需要先登录 AtomGit 并同意 Google 的使用许可。

性能优化

  • 使用 NPU 加速可以显著提升推理速度
  • 批量翻译时,建议批量大小不超过 10
  • 根据实际需求调整 max_new_tokens 参数
  • 图像输入会被归一化到 896x896 分辨率并编码为 256 个 token

常见问题

  1. 模型加载失败

    • 检查网络连接(首次下载需要)
    • 检查是否已登录 AtomGit 并同意许可协议
    • 检查磁盘空间是否充足
    • 检查模型路径是否正确
  2. NPU 不可用

    • 检查 CANN 环境是否正确安装
    • 检查 torch_npu 是否正确安装
    • 服务会自动降级到 CUDA 或 CPU
  3. 翻译结果不准确

    • 确保使用正确的语言代码格式
    • 尝试使用区域化变体(如 de-DE 而不是 de)
    • 调整生成参数(temperature, top_p 等)
  4. 图像翻译失败

    • 检查图像 URL 是否可访问
    • 确保图像格式支持(JPG, PNG 等)
    • 检查网络连接(需要下载图像)

技术支持

如遇到问题,请查看:

  1. Docker 容器日志:docker logs translategemma-4b-it-api
  2. 服务健康检查:curl http://localhost:18002/health
  3. Prometheus 指标:curl http://localhost:18002/metrics

API 使用示例

Python 客户端示例

非流式翻译

import requests

url = "http://localhost:18002/v1/translate"
payload = {
    "source_text": "Hello, world!",
    "source_language": "en",
    "target_language": "zh"
}
response = requests.post(url, json=payload)
result = response.json()
print(result["translated_text"])

流式文本翻译

import requests
import json

url = "http://localhost:18002/v1/translate"
payload = {
    "source_text": "Hello, world!",
    "source_language": "en",
    "target_language": "zh",
    "stream": True
}

response = requests.post(url, json=payload, stream=True)

for line in response.iter_lines():
    if line:
        line_str = line.decode('utf-8')
        if line_str.startswith('data: '):
            data_str = line_str[6:]  # 移除 "data: " 前缀
            if data_str == '[DONE]':
                break
            try:
                data = json.loads(data_str)
                print(data.get('delta', '), end=', flush=True)
            except json.JSONDecodeError:
                pass
print()  # 换行

流式图像翻译

import requests
import json

url = "http://localhost:18002/v1/translate"
payload = {
    "image_url": "https://c7.alamy.com/comp/2YAX36N/traffic-signs-in-czech-republic-pedestrian-zone-2YAX36N.jpg",
    "source_language": "cs",
    "target_language": "zh",
    "stream": True,
    "temperature": 0.3
}

response = requests.post(url, json=payload, stream=True)

for line in response.iter_lines():
    if line:
        line_str = line.decode('utf-8')
        if line_str.startswith('data: '):
            data_str = line_str[6:]  # 移除 "data: " 前缀
            if data_str == '[DONE]':
                break
            try:
                data = json.loads(data_str)
                print(data.get('delta', '), end=', flush=True)
            except json.JSONDecodeError:
                pass
print()  # 换行

版本信息

  • API 版本:1.0.0
  • 模型版本:google/translategemma-4b-it
  • transformers 版本:>=4.40.0

参考链接

  • HuggingFace 模型页面
  • 技术报告
  • Gemma 3 技术报告
  • Google AI 负责任使用工具包

许可证

本模型遵循 Gemma 许可证。使用前请仔细阅读 Gemma 使用条款。