README.md

---
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