---
language:
  - kk
license: mit
tags:
  - grammatical-error-correction
  - kazakh
  - gec
  - qwen2
  - sozkz
base_model: stukenov/sozkz-core-qwen-500m-kk-base-v1
datasets:
  - stukenov/sozkz-gec-synthetic-gpt4o-v1
pipeline_tag: text2text-generation
---

# SozKZ Fix Qwen 500M — Kazakh GEC v1

Қазақ тіліндегі грамматикалық, орфографиялық, пунктуациялық және сөз қолданысындағы қателерді түзетуге арналған модель.

Grammatical Error Correction model for Kazakh language, fine-tuned from [sozkz-core-qwen-500m-kk-base-v1](https://huggingface.co/stukenov/sozkz-core-qwen-500m-kk-base-v1).

## Model Details

| Parameter | Value |
|-----------|-------|
| Architecture | Qwen2 (causal LM) |
| Parameters | 447M |
| Training method | LoRA SFT (r=64, alpha=128) |
| Precision | bfloat16 |
| Training data | 3,740 synthetic GEC pairs (GPT-4o generated) |
| Base model | sozkz-core-qwen-500m-kk-base-v1 |
| License | MIT |

## Usage

```python
from transformers import AutoModelForCausalLM, PreTrainedTokenizerFast
from huggingface_hub import hf_hub_download
import torch

MODEL_ID = "stukenov/sozkz-fix-qwen-500m-kk-gec-v1"

model = AutoModelForCausalLM.from_pretrained(MODEL_ID, dtype=torch.bfloat16, device_map="auto")
tok_file = hf_hub_download(MODEL_ID, "tokenizer.json")
tokenizer = PreTrainedTokenizerFast(tokenizer_file=tok_file)

INSTRUCTION = (
    "Мәтіндегі грамматикалық, орфографиялық, пунктуациялық және сөз қолданысындағы "
    "қателерді түзет. Мағынаны өзгертпе. Егер мәтін дұрыс болса, оны өзгеріссіз қайтар. "
    "Тек түзетілген мәтінді қайтар."
)

def correct(text: str) -> str:
    prompt = f"### Нұсқау:\n{INSTRUCTION}\n\n### Мәтін:\n{text}\n\n### Түзетілген:\n"
    ids = tokenizer.encode(prompt, return_tensors="pt").to(model.device)
    with torch.no_grad():
        out = model.generate(ids, max_new_tokens=len(ids[0]), do_sample=False,
                             repetition_penalty=1.1, pad_token_id=1)
    decoded = tokenizer.decode(out[0], skip_special_tokens=True)
    return decoded.split("### Түзетілген:\n")[-1].split("###")[0].strip()

print(correct("Мен бугін мектепке бардым"))
# -> Мен бүгін мектепке бардым.
```

## Prompt Format

```
### Нұсқау:
Мәтіндегі грамматикалық, орфографиялық, пунктуациялық және сөз қолданысындағы қателерді түзет. Мағынаны өзгертпе. Егер мәтін дұрыс болса, оны өзгеріссіз қайтар. Тек түзетілген мәтінді қайтар.

### Мәтін:
{input_text}

### Түзетілген:
```

## Evaluation (15 test cases)

| # | Input | Expected | Model Output | Result |
|---|-------|----------|-------------|--------|
| 1 | Мен бугін мектепке бардым | Мен бүгін мектепке бардым | Мен бугін мектепке бардым. | FAIL |
| 2 | Ол кітапты оқыды жане маған айтты | Ол кітапты оқыды және маған айтты | Ол кітапты оқыды және маған айтты. | PASS |
| 3 | Казакстанда тумыс деңгейі жоғары | Қазақстанда тұрмыс деңгейі жоғары | Қазақстанда тұрмыс деңгейі жоғары. | PASS |
| 4 | Биыл жаңа жылды отбасымен тойладык | Биыл жаңа жылды отбасымен тойладық | Биыл Жаңа жылды отбасымен тойладық. | PASS |
| 5 | Бала бакшага барады | Бала бақшаға барады | Бала бақшаға барады. | PASS |
| 6 | Мугалім сабақты тусіндірді | Мұғалім сабақты түсіндірді | Мұғалім сабақты түсіндірді. | PASS |
| 7 | Мен қазақ тілін уйреніп жатырмын | Мен қазақ тілін үйреніп жатырмын | Мен қазақ тілін үйреніп жатырмын. | PASS |
| 8 | Ол маған хат жазган | Ол маған хат жазған | Ол маған хат жазған. | PASS |
| 9 | Менің досым келді | Менің досым келді | Менің досым келді. | PASS |
| 10 | Ол кеше келіп, бүгін кетті | Ол кеше келіп, бүгін кетті | Ол кеше келіп, бүгін кетті. | PASS |
| 11 | Біздің мектеп ен жаксы мектеп | Біздің мектеп ең жақсы мектеп | Біздің мектеп ең жақсы мектеп. | PASS |
| 12 | Устаз балаларга тапсырма берді | Ұстаз балаларға тапсырма берді | Ұстаз балаларға тапсырма берді. | PASS |
| 13 | Мен кешке дукенге барамын | Мен кешке дүкенге барамын | Мен кешке дүкенге барамын. | PASS |
| 14 | Анам тамак пісірді | Анам тамақ пісірді | Анам тамақ пісірді. | PASS |
| 15 | Мен бугін жумыска бардым | Мен бүгін жұмысқа бардым | Мен бүгін жұмысқа бардым. | PASS |

**Score: 14/15 (93.3%)**

## Training Details

- **Method**: LoRA (r=64, alpha=128, all linear layers)
- **Epochs**: 3
- **Learning rate**: 2e-4 (cosine schedule)
- **Batch size**: 4 (gradient accumulation 4, effective 16)
- **Hardware**: NVIDIA L40S
- **Training time**: ~4 minutes (351 steps)
- **Dataset**: [sozkz-gec-synthetic-gpt4o-v1](https://huggingface.co/datasets/stukenov/sozkz-gec-synthetic-gpt4o-v1) (3,740 pairs)

## Demo

Try it live at [qazgramma-turbo.adapto.kz](https://qazgramma-turbo.adapto.kz)

## Limitations

- Trained on only 3,740 examples — will be retrained when dataset reaches 10K+
- Some inputs with "бугін" are not corrected
- May add punctuation (periods) even when not needed
- Best for short-to-medium sentences (up to ~100 words)

## Citation

```bibtex
@misc{sozkz-fix-qwen-500m-kk-gec-v1,
  title={SozKZ Fix Qwen 500M: Kazakh Grammatical Error Correction},
  author={Stukenov, Saken},
  year={2026},
  publisher={HuggingFace},
  url={https://huggingface.co/stukenov/sozkz-fix-qwen-500m-kk-gec-v1}
}
```

## Benchmark Results

Evaluated on **100-example custom GEC test** (pure model inference, no pre/post pipeline).

> ✅ **Top-3** в SozKZ GEC benchmark

| Category | Score |
|----------|-------|
| Орфография (емле) | 0/30 (0%) |
| Грамматика | 12/20 (60%) |
| Пунктуация | 8/15 (53%) |
| Смешанный | 0/20 (0%) |
| Identity preservation | 15/15 (100%) |
| **Total** | **35/100 (35%)** |


## Leaderboard (100-example custom benchmark)

| Модель | Total | Емле/30 | Грамм/20 | Пункт/15 | Смеш/20 | Ident/15 |
|--------|-------|---------|----------|----------|---------|---------|
| **[sozkz-core-llama-600m-kk-gec-v1](https://huggingface.co/stukenov/sozkz-core-llama-600m-kk-gec-v1)** | **47%** | 15 | 12 | 3 | 2 | 15/15 |
| [sozkz-fix-qwen-500m-kk-gec-v3](https://huggingface.co/stukenov/sozkz-fix-qwen-500m-kk-gec-v3) | 38% | 0 | 16 | 9 | 0 | 13/15 |
| [sozkz-core-llama-300m-kk-gec-v4](https://huggingface.co/stukenov/sozkz-core-llama-300m-kk-gec-v4) | 37% | 9 | 6 | 4 | 3 | 15/15 |
| [sozkz-fix-qwen-500m-kk-gec-v1](https://huggingface.co/stukenov/sozkz-fix-qwen-500m-kk-gec-v1) | 35% | 0 | 12 | 8 | 0 | 15/15 |
| [sozkz-fix-qwen-500m-kk-gec-v2](https://huggingface.co/stukenov/sozkz-fix-qwen-500m-kk-gec-v2) | 30% | 0 | 11 | 7 | 0 | 12/15 |
| [sozkz-core-llama-1b-kk-gec-v1](https://huggingface.co/stukenov/sozkz-core-llama-1b-kk-gec-v1) | 16% | 2 | 6 | 1 | 0 | 7/15 |
| [sozkz-fix-qwen-500m-kk-gec-v4](https://huggingface.co/stukenov/sozkz-fix-qwen-500m-kk-gec-v4) | 5% | 0 | 1 | 4 | 0 | 0/15 |
| [sozkz-fix-mt5b-kk-gec-run13-v1](https://huggingface.co/stukenov/sozkz-fix-mt5b-kk-gec-run13-v1) | 5% | 0 | 2 | 0 | 0 | 3/15 |
| [sozkz-nllb-1b-kk-gec-v1](https://huggingface.co/stukenov/sozkz-nllb-1b-kk-gec-v1) | 1% | 0 | 1 | 0 | 0 | 0/15 |
| [sozkz-nllb-1b-kk-pretrain-v1](https://huggingface.co/stukenov/sozkz-nllb-1b-kk-pretrain-v1) | 1% | 0 | 1 | 0 | 0 | 0/15 |
| [sozkz-core-llama-300m-kk-gec-v3](https://huggingface.co/stukenov/sozkz-core-llama-300m-kk-gec-v3) | 1% | 0 | 1 | 0 | 0 | 0/15 |
| sozkz-core-llama-300m-kk-gec-v1/v2a/v2b | 0–1% | 0 | 0 | 0 | 0 | 0–1 |
| sozkz-fix-mt5-50m-kk-gec-v1 | 0% | 0 | 0 | 0 | 0 | 0/15 |