README.md

---
language:
- uk
license: cc-by-nc-4.0
tags:
- surzhyk
- ukrainian
- text-normalization
- translation
- seq2seq
- nllb
- qlora
- transformers
datasets:
- vlddshk/syrzyk-dataset
metrics:
- chrf
- bleu
- cer
- wer
widget:
- text: "Пойшлі на кофе с утра, а то якось грусно."
  example_title: "Приклад 1"
- text: "Канєшно ми прийдемо на празнік"
  example_title: "Приклад 2"
- text: "Я когда то куплю дом"
  example_title: "Приклад 3"
- text: "Сколько можно це терпіть"
  example_title: "Приклад 4"
- text: "Я нікогда так не думал!"
  example_title: "Приклад 5"
- text: "Чому ми должні про це розговарювать?"
  example_title: "Приклад 6"
---

# 🇺🇦 SyrzykAI: Модель перекладу з суржику на літературну українську

<div align="center">

[![Base Model](https://img.shields.io/badge/Base_Model-NLLB--200--distilled--600M-blue.svg)](https://huggingface.co/facebook/nllb-200-distilled-600M)
[![Dataset](https://img.shields.io/badge/Dataset-Syrzyk_Dataset-green.svg)](https://huggingface.co/datasets/vlddshk/syrzyk-dataset)
[![License: cc-by-nc-4.0](https://img.shields.io/badge/License-cc--by--nc--4.0-lightgrey.svg)](https://opensource.org/licenses/cc-by-nc-4.0)

</div>

**SyrzykAI** — це нейромережева модель для автоматичного виправлення суржику, русизмів, кальок та граматичних інтерференцій у текстах. Модель перекладає (нормалізує) текст із суржику на чисту, нормативну літературну українську мову.

Модель заснована на багатомовній архітектурі **NLLB-200** (600M параметрів) та донавчена за допомогою методології **QLoRA** на спеціалізованому паралельному корпусі українського суржику. Адаптери LoRA були злиті з базовою моделлю, що дозволяє легко використовувати її для 8-бітного інференсу без додаткових залежностей PEFT.

## Деталі моделі
- **Базова модель:** `facebook/nllb-200-distilled-600M`
- **Метод донавчання:** QLoRA (4-bit, `nf4`, `bfloat16`) + злиття ваг (Merge and Unload)
- **Токенізатор:** Специфічні мовні токени `src_lang="ukr_Cyrl"`, `tgt_lang="ukr_Cyrl"`
- **Навчальні дані:** [vlddshk/syrzyk-dataset](https://huggingface.co/datasets/vlddshk/syrzyk-dataset) (6,299 ретельно перевірених пар речень)

## Як використовувати (Quickstart)

Для використання моделі рекомендується використовувати **8-бітну квантизацію** (через бібліотеку `bitsandbytes`), що суттєво зменшує використання VRAM та прискорює генерацію тексту.

### Встановлення залежностей
```bash
pip install torch transformers accelerate bitsandbytes
```

### Код для інференсу
```python
import torch
from transformers import AutoModelForSeq2SeqLM, AutoTokenizer, BitsAndBytesConfig

model_name = "vlddshk/SyrzykAI"

# 1. Завантаження токенізатора з вказанням української мови
tokenizer = AutoTokenizer.from_pretrained(
    model_name,
    src_lang="ukr_Cyrl", 
    tgt_lang="ukr_Cyrl"
)

# 2. Налаштування 8-бітної квантизації для економії пам'яті
bnb_config = BitsAndBytesConfig(load_in_8bit=True)

# 3. Завантаження моделі
model = AutoModelForSeq2SeqLM.from_pretrained(
    model_name,
    quantization_config=bnb_config,
    device_map="auto"
)
model.eval()

# 4. Функція для перекладу
def translate_surzhyk(text: str) -> str:
    inputs = tokenizer(text, return_tensors="pt", truncation=True, max_length=128)
    inputs = {k: v.to(model.device) for k, v in inputs.items()}
    
    with torch.no_grad():
        outputs = model.generate(
            **inputs,
            max_new_tokens=128,
            num_beams=4,
            early_stopping=True
        )
        
    return tokenizer.decode(outputs[0], skip_special_tokens=True)

# Тестування
surzhyk_text = "Пойшлі на кофе с утра, а то якось грусно."
print("Суржик:", surzhyk_text)
print("Літературна:", translate_surzhyk(surzhyk_text))
# Очікуваний результат: Пішли на каву зранку, а то якось сумно.
```

## Оцінка та метрики (Evaluation)

Модель оцінюється за допомогою стандартних метрик перекладу та нормалізації тексту на тестовій вибірці (545 речень) датасету `Syrzyk-Dataset`:

- **chrF**: Найкраще підходить для оцінки морфологічно багатих слов'янських мов, оскільки працює на рівні символьних n-грам (гарно ловить виправлені закінчення).
- **SacreBLEU**: Стандартна метрика для машинного перекладу.
- **CER (Character Error Rate)** та **WER (Word Error Rate)**: Допомагають зрозуміти ступінь необхідних змін у порівнянні з ідеальною літературною формою.

*(Конкретні цифри бенчмарків оновлюються після кожного значного релізу моделі).*

## ⚠️ Обмеження моделі (Limitations & Biases)
- **Специфічний домен:** Модель призначена **виключно** для виправлення суржику та русизмів. Її не слід використовувати як класичний перекладач з російської на українську.
- **Регіональні особливості:** Суржик варіюється від регіону до регіону. Модель може не розпізнати специфічні локальні діалектизми (закарпатський, галицький тощо), які не належать до типової російсько-української інтерференції.
- **Надмірна корекція:** Іноді модель може виправляти слова, які є рідковживаними, але все ж нормативними українськими, замінюючи їх на більш поширені синоніми.
- **Довгі тексти:** Модель оптимізована на рівні речень (`max_length=128`). Для великих абзаців рекомендується розбивати текст на окремі речення перед генерацією.

## Автори та Citation
Проект розроблено в рамках ініціативи **SyrzykAI**. 
Репозиторій датасету: [vlddshk/syrzyk-dataset](https://huggingface.co/datasets/vlddshk/syrzyk-dataset).

Якщо ви використовуєте цю модель, будь ласка, посилайтеся на:
```bibtex
@misc{vlddshk_syrzykai_2026,
  title={SyrzykAI: Text Normalization Model for Surzhyk-to-Ukrainian Translation},
  author={vlddshk},
  year={2026},
  publisher={Hugging Face},
  howpublished={\url{https://huggingface.co/vlddshk/SyrzykAI}},
  license={cc-by-nc-4.0}
}
```