Update README.md

README.md

@@ -1,3 +1,238 @@
+
 ---
-license: apache-2.0
+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: other
+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) 提供微调框架
+- 各源数据集作者与维护者