Update README.md

README.md

@@ -1,11 +1,177 @@
 ---
-license: mit
-language: ru
-pipeline_tag: text-generation
-base_model: RefalMachine/RuadaptQwen3-4B-Instruct
+license: apache-2.0
+language:
+- ru
+base_model:
+- RefalMachine/RuadaptQwen3-4B-Instruct
 datasets:
 - melsmm/spell-correction-ru
+- ai-forever/spellcheck_punctuation_benchmark
+pipeline_tag: text-generation
+library_name: transformers
 tags:
 - spell-correction
+- spelling-correction
+- punctuation-restoration
+- grammatical-error-correction
 - russian
----
+- qwen3
+- lora
+---
+
+# Spell-Corrector-RU-4B
+
+**Spell-Corrector-RU-4B** — языковая модель для **автоматического исправления орфографических, пунктуационных и регистровых ошибок** в русскоязычных текстах.
+
+Модель дообучена на базе [`RefalMachine/RuadaptQwen3-4B-Instruct`](https://huggingface.co/RefalMachine/RuadaptQwen3-4B-Instruct) (адаптированная под русский язык версия [`Qwen/Qwen3-4B-Instruct-2507`](https://huggingface.co/Qwen/Qwen3-4B-Instruct-2507)) методом **LoRA** в фреймворке [LLaMA-Factory](https://github.com/hiyouga/LLaMA-Factory). LoRA-адаптер уже **смержен** с базовой моделью — её можно использовать напрямую.
+
+📦 **Код, ноутбуки и полное описание проекта:** [github.com/melsmm/llm-spell-corrector](https://github.com/melsmm/llm-spell-corrector)
+📚 **Датасеты для обучения:** [`melsmm/spell-correction-ru`](https://huggingface.co/datasets/melsmm/spell-correction-ru)
+
+## Для чего модель
+
+Модель принимает текст с ошибками и возвращает его исправленную версию. Она умеет:
+
+- 🔤 исправлять **орфографические** ошибки и опечатки;
+- ❓ восстанавливать и исправлять **пунктуацию**;
+- 🔠 восстанавливать **регистр** букв (заглавные/строчные) и букву «ё».
+
+Основное преимущество перед существующими решениями (например, [SAGE](https://github.com/ai-forever/sage) на архитектуре T5) — **высокая скорость инференса** (через [vLLM](https://github.com/vllm-project/vllm), ~в 6 раз быстрее), простота внедрения в продакшен через OpenAI-совместимый API и лёгкость дообучения под новые домены с помощью LoRA.
+
+## На чём обучалась
+
+Обучение проходило в **две стадии**:
+
+| Стадия | Датасет | Объём | Описание |
+| --- | --- | --- | --- |
+| **Stage 1** | `synth_spell_correction_1m` | ~1 млн | Синтетические ошибки, внесённые в чистые корпусы (`nerus`, `gazeta`, `wikipedia`) с помощью [SAGE](https://github.com/ai-forever/sage) (`SBSC`, `CharAug`, `WordAug`) и собственного алгоритма пунктуационной порчи. |
+| **Stage 2** | `spell_correction_30k` | ~30 тыс. | Объединение готовых пар «ошибка → исправление» из открытых датасетов (RUSpellRU, MultidomainGold, GEC). |
+
+Сначала модель учится на большом объёме разнообразных синтетических ошибок, затем «дошлифовывается» на меньшем, но более качественном наборе реальных пар. Оба датасета доступны в репозитории [`melsmm/spell-correction-ru`](https://huggingface.co/datasets/melsmm/spell-correction-ru).
+
+**Гиперпараметры LoRA:** rank=32, alpha=64, dropout=0, bf16, cutoff length=4000.
+
+## Использование
+
+### Промпт
+
+Модель ожидает следующий формат запроса:
+
+```
+Исходный текст:
+{текст с ошибками}
+
+Отредактируй исходный текст, исправив ошибки.
+```
+
+Рекомендуемые параметры генерации: `temperature=0.1`, `top_p=0.7`.
+
+### Через `transformers`
+
+```python
+from transformers import AutoModelForCausalLM, AutoTokenizer
+
+model_name = "melsmm/Spell-Corrector-RU-4B"
+tokenizer = AutoTokenizer.from_pretrained(model_name)
+model = AutoModelForCausalLM.from_pretrained(model_name, torch_dtype="auto", device_map="auto")
+
+text = "привет как дила, что делаеш севодня"
+prompt = f"Исходный текст:\n{text}\n\nОтредактируй исходный текст, исправив ошибки."
+
+messages = [{"role": "user", "content": prompt}]
+inputs = tokenizer.apply_chat_template(
+    messages, add_generation_prompt=True, return_tensors="pt"
+).to(model.device)
+
+outputs = model.generate(inputs, max_new_tokens=512, temperature=0.1, top_p=0.7, do_sample=True)
+print(tokenizer.decode(outputs[0][inputs.shape[1]:], skip_special_tokens=True))
+```
+
+### Через vLLM (рекомендуется для продакшена)
+
+Запуск OpenAI-совместимого сервера:
+
+```bash
+vllm serve melsmm/Spell-Corrector-RU-4B \
+    --gpu-memory-utilization 0.95 \
+    --host 0.0.0.0 \
+    --port 9900 \
+    --served-model-name spell_correction \
+    --max-model-len 4096
+```
+
+Обращение к серверу:
+
+```python
+from openai import OpenAI
+
+client = OpenAI(base_url="http://localhost:9900/v1", api_key="EMPTY")
+
+text = "привет как дила"
+resp = client.chat.completions.create(
+    model="spell_correction",
+    messages=[{"role": "user", "content":
+        f"Исходный текст:\n{text}\n\nОтредактируй исходный текст, исправив ошибки."}],
+    temperature=0.1,
+    top_p=0.7,
+)
+print(resp.choices[0].message.content)
+```
+
+## Качество
+
+Оценка на бенчмарке [`ai-forever/spellcheck_punctuation_benchmark`](https://huggingface.co/datasets/ai-forever/spellcheck_punctuation_benchmark) (F1 по орфографии / пунктуации / регистру):
+
+### RUSpellRU
+
+| Model | F1 (spell) | F1 (punc) | F1 (case) |
+| --- | --: | --: | --: |
+| **Spell-Corrector-RU-4B** | 64.7 | 84.5 | 94.2 |
+| sage-fredt5-large | 84.5 | 86.8 | 94.7 |
+| gpt-4 | 64.0 | 83.2 | 90.9 |
+| gpt-3.5-turbo | 42.7 | 73.7 | 79.0 |
+
+### MultidomainGold
+
+| Model | F1 (spell) | F1 (punc) | F1 (case) |
+| --- | --: | --: | --: |
+| **Spell-Corrector-RU-4B** | 62.6 | 66.5 | 80.0 |
+| sage-fredt5-large | 77.6 | 67.7 | 79.3 |
+| gpt-4 | 37.0 | 56.0 | 60.0 |
+| gpt-3.5-turbo | 27.1 | 36.2 | 49.1 |
+
+### MedSpellchecker
+
+| Model | F1 (spell) | F1 (punc) | F1 (case) |
+| --- | --: | --: | --: |
+| **Spell-Corrector-RU-4B** | 42.8 | 70.4 | 76.3 |
+| sage-fredt5-large | 72.3 | 70.3 | 82.1 |
+| gpt-4 | 49.6 | 71.9 | 67.1 |
+| gpt-3.5-turbo | 22.3 | 59.8 | 32.3 |
+
+### GitHubTypoCorpusRu
+
+| Model | F1 (spell) | F1 (punc) | F1 (case) |
+| --- | --: | --: | --: |
+| **Spell-Corrector-RU-4B** | 49.7 | 34.8 | 45.8 |
+| sage-fredt5-large | 59.5 | 42.6 | 42.7 |
+| gpt-4 | 35.7 | 38.2 | 30.2 |
+| gpt-3.5-turbo | 29.4 | 28.7 | 25.3 |
+
+> Полные таблицы (Precision / Recall / F1 + сравнение со Stage 1) — в [репозитории проекта](https://github.com/melsmm/llm-spell-corrector#-результаты).
+
+### Скорость инференса
+
+На RUSpellRU (2008 примеров) через vLLM: **45 с** (0.022 с/пример) против **284 с** (0.141 с/пример) у sage-fredt5-large — **~в 6 раз быстрее**.
+
+## Ограничения
+
+- Модель уступает SAGE по орфографии на ряде доменов, но конкурентна по пунктуации и регистру.
+- Качество может снижаться на узкоспециализированных доменах (например, медицина) — там рекомендуется дообучение под домен с помощью LoRA.
+- Модель работает с русским языком; для других языков не предназначена.
+
+## Ссылки
+
+- 🔗 **Проект на GitHub:** https://github.com/melsmm/llm-spell-corrector
+- 🤗 **Датасеты:** https://huggingface.co/datasets/melsmm/spell-correction-ru
+- 🧩 **Базовая модель:** https://huggingface.co/RefalMachine/RuadaptQwen3-4B-Instruct