README.md

---
language:
- en
- zh
base_model: openbmb/MiniCPM5-1B
library_name: transformers
pipeline_tag: translation
tags:
- minicpm
- translation
- english-to-chinese
- immersive-translate
- lora
- fine-tuned
- text-generation
license: apache-2.0
datasets:
- Variable65536/immersive_translate_en-zh
---

# MiniCPM5-1B Immersive Translate

英译中专用翻译模型，基于 [`MiniCPM5-1B-Base`](https://huggingface.co/openbmb/MiniCPM5-1B) 微调，面向 [沉浸式翻译](https://immersivetranslate.com/) 插件场景优化。已合并 LoRA 权重，可直接使用 Transformers 加载。

## 模型概览

| 项目 | 说明 |
|---|---|
| 基座模型 | `openbmb/MiniCPM5-1B-Base` |
| 微调数据 | [`Variable65536/immersive_translate_en-zh`](https://huggingface.co/datasets/Variable65536/immersive_translate_en-zh)（18,228 条 SFT 样本） |
| 微调方法 | LoRA（r=16, alpha=32, target=all） |
| 训练轮数 | 2 epoch |
| 最终 eval_loss | 1.1135 |
| 硬件 | Tesla P100 16GB |
| 权重格式 | safetensors（LoRA 已合并） |
| 量化版本 | 见 [`Variable65536/minicpm5-1b-immersive-translate-gguf`](https://huggingface.co/Variable65536/minicpm5-1b-immersive-translate-gguf) |

## 快速开始

### 安装依赖

```bash
pip install transformers torch accelerate
```

### 加载模型

```python
import torch
from transformers import AutoModelForCausalLM, AutoTokenizer

model_path = "Variable65536/minicpm5-immersive-translate"

model = AutoModelForCausalLM.from_pretrained(
    model_path,
    torch_dtype=torch.float16,
    device_map="auto",
)
tokenizer = AutoTokenizer.from_pretrained(model_path)
```

### 推理示例

模型训练时使用与沉浸式翻译插件完全对齐的 system prompt 和 user prompt 格式，推理时需保持一致。

```python
SYSTEM_PROMPT = """You are a professional Chinese native translator who needs to fluently translate text into Chinese.

## Translation Rules
1. Output only the translated content, without explanations or additional content (such as "Here's the translation:" or "Translation as follows:")
2. The returned translation must maintain exactly the same number of paragraphs and format as the original text
3. If the text contains HTML tags, consider where the tags should be placed in the translation while maintaining fluency
4. For content that should not be translated (such as proper nouns, code, etc.), keep the original text.
5. If input contains %%, use %% in your output, if input has no %%, don't use %% in your output

## OUTPUT FORMAT:
- **Single paragraph input** → Output translation directly (no separators, no extra text)
- **Multi-paragraph input** → Use %% as paragraph separator between translations
"""

# 单段输入
user_input = "Translate to Chinese (output translation only):\n\nThe committee approved the proposal after extensive deliberation."

messages = [
    {"role": "system", "content": SYSTEM_PROMPT},
    {"role": "user", "content": user_input},
]

input_ids = tokenizer.apply_chat_template(
    messages,
    tokenize=True,
    add_generation_prompt=True,
    return_tensors="pt",
    return_dict=False,
).to(model.device)

outputs = model.generate(
    input_ids,
    max_new_tokens=512,
    temperature=0.2,
    top_p=0.9,
    do_sample=True,
)

result = tokenizer.decode(outputs[0][input_ids.shape[-1]:], skip_special_tokens=True)
print(result)
# 输出：委员会经过充分讨论后批准了该提案。
```

### 多段输入示例

```python
user_input = """Translate to Chinese:

## Installation

Run `pip install minicpm` to install the package.

%%

## Usage

See the <a href="https://github.com/OpenBMB/MiniCPM">repo</a> for examples.
"""
```

模型会输出对应中文译文，并保留 `%%` 分隔符、代码块和 HTML 标签。

## 提示词格式

### System Prompt

```
You are a professional Chinese native translator who needs to fluently translate text into Chinese.

## Translation Rules
1. Output only the translated content, without explanations or additional content (such as "Here's the translation:" or "Translation as follows:")
2. The returned translation must maintain exactly the same number of paragraphs and format as the original text
3. If the text contains HTML tags, consider where the tags should be placed in the translation while maintaining fluency
4. For content that should not be translated (such as proper nouns, code, etc.), keep the original text.
5. If input contains %%, use %% in your output, if input has no %%, don't use %% in your output

## OUTPUT FORMAT:
- **Single paragraph input** → Output translation directly (no separators, no extra text)
- **Multi-paragraph input** → Use %% as paragraph separator between translations
```

### 单段 User Prompt

```
Translate to Chinese (output translation only):

{英文原文}
```

### 多段 User Prompt

```
Translate to Chinese:

{英文段落 1}

%%

{英文段落 2}
```

### 推荐推理参数

| 参数 | 值 |
|---|---|
| temperature | 0.2 |
| top_p | 0.9 |
| max_new_tokens | 512 |
| repetition_penalty | 1.0 |

温度建议设在 **0.1~0.3** 之间，翻译任务不需要高随机性。

## 模型能力

训练数据覆盖以下场景，模型在这些任务上表现良好：

- **技术文档**：GitHub README、Hugging Face 模型卡片、软件文档
- **学术摘要**：arXiv 论文摘要英译中
- **格式保留**：代码块（` ``` `）、行内代码（`` `code` ``）、HTML 标签、URL、Markdown 标题
- **多段翻译**：使用 `%%` 分隔段落，输入输出段落数严格一致
- **专有名词**：GitHub、Git、Microsoft 等保留原文不译

## 与沉浸式翻译插件配合使用

推荐通过 **vLLM** 部署为 OpenAI 兼容 API：

```bash
pip install vllm
python -m vllm.entrypoints.openai.api_server \
    --model Variable65536/minicpm5-immersive-translate \
    --served-model-name minicpm5-immersive \
    --port 8000 \
    --dtype float16 \
    --max-model-len 4096
```

然后在沉浸式翻译插件中配置：

| 字段 | 值 |
|---|---|
| API URL | `http://localhost:8000/v1/chat/completions` |
| API Key | 任意值（本地服务不校验） |
| 模型 | `minicpm5-immersive` |

插件会自动发送其内置的 system prompt，与本模型训练时使用的格式一致。

## 已知限制

- **纯代码块段落**：当多段输入中存在仅含代码块的段落时，模型可能将其与相邻段落合并，导致 `%%` 数量不一致。实际使用中插件通常会剥离代码块，影响较小。
- **维基百科信息框字段**：如 `Parent`、`Founded`、`Industry` 等字段的翻译可能不准确，训练数据未覆盖此类结构化字段。
- **复杂从句语序**：个别 `after`、`before` 等时间状语从句的语序可能出错。
- **合成数据风险**：训练数据中 BiST 部分的中文译文为 LLM 合成，可能继承源模型的翻译偏好。

## 引用

如果使用本模型，请同时引用原始数据源及 MiniCPM5：

```bibtex
@misc{minicpm5,
  title={MiniCPM5},
  author={OpenBMB},
  year={2025},
  howpublished={\url{https://huggingface.co/openbmb/MiniCPM5-1B}}
}
```

## 致谢

- [OpenBMB](https://github.com/OpenBMB) 提供 MiniCPM5-1B 基座模型
- [LLaMA-Factory](https://github.com/hiyouga/LLaMA-Factory) 提供微调框架
- 各源数据集作者与维护者