# MSLite-Translator

**Repository Path**: ybf521/mslite-translator

## Basic Information

- **Project Name**: MSLite-Translator
- **Description**: MSLite-Translator实现了在鸿蒙Next设备端部署中英机器互译能力，实现隐私安全的高性能离线实时翻译。
- **Primary Language**: Unknown
- **License**: AGPL-3.0
- **Default Branch**: master
- **Homepage**: None
- **GVP Project**: No

## Statistics

- **Stars**: 1
- **Forks**: 0
- **Created**: 2025-06-19
- **Last Updated**: 2026-07-10

## Categories & Tags

**Categories**: Uncategorized

**Tags**: None

## README

# MSLite-Translator

### 介绍
MSLite-Translator实现了在鸿蒙Next设备端部署中英/英俄机器互译能力，实现隐私安全的高性能离线实时翻译。

[English](README_EN.md)

### 效果预览

![img.png](entry/src/main/resources/base/media/img0.png)

### 核心挑战：

•	模型需从PyTorch（Hugging Face）→ ONNX → MindSpore Lite（.ms）跨框架转换

•	鸿蒙Next端侧资源受限（CPU/内存），需优化推理性能

•	适配Helsinki-NLP模型的动态输入长度与子词分词逻辑

### 技术栈：

•	模型：Helsinki-NLP/opus-mt-zh-en、opus-mt-en-zh、opus-mt-en-ru、opus-mt-ru-en

•	推理框架：MindSpore Lite 2.3+

•	设备：HarmonyOS Next（API Version 10+）

•	语言：ArkTS/C++

### 软件架构

![img.png](entry/src/main/resources/base/media/img.png)

### C++ 源码结构

```
entry/src/main/cpp/
├── CMakeLists.txt              # 构建配置
├── napi_init.cpp               # NAPI 接口层（JS ↔ C++ 桥接）
├── include/                    # 头文件
│   ├── common.h                # 公共定义（日志宏、路径常量）
│   ├── config_loader.h         # 配置加载器（单例模式）
│   ├── opus_mt_tokenizer.h     # Marian 分词器（分词/解码/语言检测）
│   ├── ms_model.h              # MindSpore Lite 模型封装
│   ├── translator.h            # 翻译器（编解码流水线）
│   ├── beam_search_decoder.h   # Beam Search 解码器
│   └── thread_safe_queue.h     # 线程安全队列
├── src/                        # 源文件
│   ├── config_loader.cpp       # 配置加载实现
│   ├── opus_mt_tokenizer.cpp   # 分词器实现
│   ├── ms_model.cpp            # 模型推理实现
│   ├── translator.cpp          # 翻译流水线实现
│   └── beam_search_decoder.cpp # Beam Search 实现
└── thirdparty/                 # 第三方库
    ├── jsoncpp/                # JSON 解析
    └── sentencepiece/          # 子词分词
```

### NAPI 接口

| 接口 | 参数 | 返回值 | 说明 |
|:-----|:-----|:------|:-----|
| `init` | 无 | void | 初始化翻译器，加载默认模型 |
| `destroy` | 无 | void | 销毁翻译器，释放资源 |
| `translate` | text: string | {resCode, translateText, translateTime} | 贪心解码翻译 |
| `translateBeamSearch` | text: string | {resCode, translateText, translateTime} | Beam Search 解码翻译 |
| `translateSync` | text: string | void | 异步流式翻译（配合 getNextWord） |
| `getNextWord` | 无 | {resCode, outputString} | 获取下一个输出词 |
| `getWordEnd` | 无 | void | 等待流式翻译完成 |
| `getTargetLanguage` | 无 | string | 获取当前目标语言 |
| `switchTranslateModel` | mode: number | void | 切换翻译方向（0=ZH2EN, 1=EN2ZH, 2=EN2RU, 3=RU2EN） |

### 项目实现

#### 模型导出

模型信息参考：https://huggingface.co/Helsinki-NLP/opus-mt-zh-en

    # python
    
    from optimum.onnxruntime import ORTModelForSeq2SeqLM
    from transformers import MarianTokenizer  # 关键导入
    # 导出模型
    model = ORTModelForSeq2SeqLM.from_pretrained(
    "Helsinki-NLP/opus-mt-zh-en",
    export=True,
    #use_merged=True,  # 关键参数：合并所有组件
    provider="CPUExecutionProvider" # 或CUDAExecutionProvider
    )
    
    # 保存模型
    model.save_pretrained("opus-mt-zh-en-onnx-optimum")

#### 模型转换

安装MindSpore Lite：参考：https://www.mindspore.cn/lite/docs/zh-CN/r2.6.0/converter/converter_tool.html

    ./converter_lite --fmk=ONNX --inputDataFormat=NCHW --modelFile=encoder_model.onnx --outputFile=encoder_model_dyn_shape
    ./converter_lite --fmk=ONNX --inputDataFormat=NCHW --modelFile=decoder_model.onnx --outputFile=decoder_model_dyn_shape
    ./converter_lite --fmk=ONNX --inputDataFormat=NCHW --modelFile=decoder_model_with_past.onnx --outputFile=decoder_with_past_model_dyn_shape
    
    注：需要把转换后的模型放在resources/resfile/model的对应目录下，如中->英，则放在zh2en目录下。
    
    量化版本：
    ./converter_lite --fmk=ONNX --modelFile=decoder_model.onnx --outputFile=decoder_model_quant0p16 --configFile=mix_bit_weight_quant.cfg

#### 用例设计

![img_1.png](entry/src/main/resources/base/media/img_1.png)

实时翻译用例： 用户输入源语言文本，系统返回目标语言翻译结果

翻译方向切换用例： 用户切换中→英或英→中翻译模式

资源管理用例： 应用启动时按需加载模型资源

#### 时序设计

![img_3.png](entry/src/main/resources/base/media/img_3.png)

关键时序优化

•	KV缓存预热：首次解码后保留缓存

•	流水线处理：分段翻译中编码与解码并行

•	懒加载：解码器在首次使用时加载

时序设计针对移动端特性优化：
1.	减少主线程阻塞：分词/编码/解码异步执行
2.	缓存复用：KV缓存避免重复计算，提升解码速度3-5倍
3.	分段流水线：长文本处理时隐藏加载延迟
4.	按需加载：解码器模型仅在使用时加载，节省内存

#### 类设计

![img_5.png](entry/src/main/resources/base/media/img_5.png)

##### 类图说明

类名|     核心职责     |    设计目的    |
:-----:|:------------:|:----------:
MarianTokenizer|    双语分词处理    | cpp实现python的分词逻辑
Encoder|     编码器      | 实现文本编码 
Decoder|   首次/无缓存解码   | 分离首次和后续迭代解码以优化性能 
ModelDecoderWithPast| 带KVCache的解码器 | 优化自回归生成的性能 
PastKV|    缓存键值对     | 显示管理Transformer缓存 

模型分层：

o	基类MSModel处理通用模型操作

o	派生类实现编解码器具体功能

o	ModelDecoderWithPast支持KV缓存优化

内存管理：

o	PastKV结构体显式管理Key/Value缓存，支持深拷贝

o	析构函数确保资源释放

扩展性：

o	TranslateMode支持中英/英俄双向翻译

o	分词器与模型解耦设计

推理优化：

o	支持同步/异步模型加载

o	KV缓存减少重复计算


#### 后续演进方向
1.	量化压缩：INT8量化进一步减小模型体积
2.	知识蒸馏：小模型适配低端设备
3.	端云协同：超长文本自动切换云端处理
4.	多模态扩展：支持语音/图像输入

### License

[Apache License 2.0](LICENSE)