stukenov/sozkz-fix-qwen-500m-kk-gec-v2

SozKZ Fix Qwen 500M — Kazakh GEC v2

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

Grammatical Error Correction model for Kazakh language, fine-tuned from sozkz-core-qwen-500m-kk-base-v1.

v2 — retrained on full dataset (9,599 examples vs 3,740 in v1). Evaluated on 100 test cases across 11 error categories.

Model Details

Parameter	Value
Architecture	Qwen2 (causal LM)
Parameters	447M
Training method	LoRA SFT (r=64, alpha=128)
Precision	bfloat16
Training data	9,599 GEC pairs (GPT-4o generated)
— synthetic pairs	7,204
— identity (clean)	2,395
Base model	sozkz-core-qwen-500m-kk-base-v1
Eval loss	0.887
Training time	~14 min (NVIDIA A10)
License	MIT

Optimal Inference Settings

Tested 5 generation configs on 100 examples. Best result: do_sample=False, repetition_penalty=1.0 (45/100).

Setting	Score	Note
repetition_penalty=1.0 (no penalty)	45%	Best — use this
repetition_penalty=1.1 (default)	44%	Slightly worse
do_sample=True, temp=0.3, top_p=0.95	43%	Close but nondeterministic
do_sample=True, temp=0.1, top_p=0.9	44%	Same as default
repetition_penalty=1.3 (high)	15%	Destroys output — never use

Important: Do NOT use repetition_penalty > 1.1. Values ≥ 1.3 catastrophically degrade quality.

Usage (optimal settings)

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

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

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)
    attention_mask = torch.ones_like(ids)
    with torch.no_grad():
        out = model.generate(
            ids,
            attention_mask=attention_mask,
            max_new_tokens=min(len(ids[0]), 512),
            do_sample=False,
            repetition_penalty=1.0,  # optimal — no penalty
            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: 100 Test Cases (optimal settings)

All examples below are real model outputs with do_sample=False, repetition_penalty=1.0.

✅ Passing Examples (45/100)

Morphology & Vowel Harmony

#	Input (қате)	Output (model)	Error type
1	Ол мектепке бардым.	Ол мектепке барды.	жіктік (person)
2	Мектептан шықтым.	Мектептен шықтым.	үндесім (harmony)
3	Мұғалімдар келді.	Мұғалімдер келді.	үндесім (harmony)
4	Жұмысшылер жұмыс істейді.	Жұмысшылар жұмыс істейді.	үндесім (harmony)
5	Мектепке бардім.	Мектепке бардым.	үндесім (harmony)
6	Ол досында бардым.	Ол досына бардым.	септік (case)
7	Ол мектепке бармеді.	Ол мектепке бармады.	болымсыз (negation)
8	Ол маған айтпеді.	Ол маған айтпады.	болымсыз (negation)

Spelling & Character Corrections

#	Input (қате)	Output (model)	Error type
9	...мемлекет болап табылады.	...мемлекет болып табылады.	аралас
10	...оқыды жане маған айтты	...оқыды және маған айтты.	аралас
11	...жаңа тақрыпты түсіндіріп берді.	...жаңа тақырыпты түсіндіріп берді.	аралас
12	Бала бакшага барады	Бала бақшаға барады.	аралас
13	...отбасымен тойладык	...отбасымен тойладық.	аралас
14	Казакстанда білім денгейі жогары	Қазақстанда білім деңгейі жоғары.	аралас
15	Ол кітапты оқыды жене досына берді.	Ол кітапты оқыды және досына берді.	септік

Punctuation

#	Input	Output (model)
16	Қазақстан тәуелсіздігін 1991 жылы алды	Қазақстан тәуелсіздігін 1991 жылы алды**.**
17	Мен кітап оқыдым ол кино көрді	Мен кітап оқыдым**,** ол кино көрді**.**
18	Менің досым келді	Менің досым келді**.**
19	Ол маған көмектесті	Ол маған көмектесті**.**
20	Біз бірге жұмыс істейміз	Біз бірге жұмыс істейміз**.**

Identity (correct text preserved — 15/15)

#	Input	Output	Status
21	Менің досым келді.	Менің досым келді.	✅
22	Қала орталығында заманауи сауда орталығы ашылды.	Қала орталығында заманауи сауда орталығы ашылды.	✅
23	Анам тамақ пісірді.	Анам тамақ пісірді.	✅
24	Әкем жұмыстан келді.	Әкем жұмыстан келді.	✅
25	Мектепте сабақ басталды.	Мектепте сабақ басталды.	✅

❌ Known Limitations (failing categories)

Емле — Kazakh character substitution (1/20)

The model cannot correct Russian-like character substitutions (у→ү, о→ө, к→қ, н→ң, г→ғ):

Input	Model Output	Expected
Мен бугін мектепке бардым	Мен бугін мектепке бардым.	Мен бүгін мектепке бардым.
Мугалім сабақты тусіндірді	Мугалім сабақты түсіндірді.	Мұғалім сабақты түсіндірді.
Анам тамак пісірді	Анам тамак пісірді.	Анам тамақ пісірді.
Когамда тартіп сакталуы керек	Когамда тартіп сакталуы керек.	Қоғамда тәртіп сақталуы керек.

Root cause: The GPT-4o training dataset does not contain this error type (у/ү visual confusion). Planned fix: add 2,000+ емле pairs with Kazakh-specific character corrections.

Word Order — Сөз тәртібі (0/5)

Input	Model Output	Expected
Мен оқыдым кітапты.	Мен оқыдым, кітапты.	Мен кітапты оқыдым.
Барды ол мектепке.	Барды ол мектепке.	Ол мектепке барды.

Root cause: Reordering tokens requires deep syntactic understanding beyond 447M params.

Тәуелдік — Possessive suffixes (0/5)

Input	Model Output	Expected
Менің кітап үстелде жатыр.	Менің кітап үстелде жатыр.	Менің кітабым үстелде жатыр.
Сенің дос қайда?	Сенің дос қайда?	Сенің досың қайда?

Per-Category Benchmark (v2 vs v1, optimal settings)

Category	v2 (45%)	v1 (41%)	Tests
identity	15/15	15/15	Clean text preserved
пунктуация	8/10	9/10	Add missing periods/commas
үндесім	6/10	6/10	Vowel harmony (-лар/-лер)
аралас	6/10	4/10	Mixed errors
болымсыз	3/5	3/5	Negation suffixes
жіктік	2/5	1/5	Person agreement
шылау	2/5	2/5	Function words
септік	2/10	1/10	Case suffixes
емле	1/20	1/20	Character substitution
тәуелдік	0/5	0/5	Possessive suffixes
тәртіп	0/5	0/5	Word order

Changes from v1

	v1	v2
Training data	3,740 examples	9,599 examples (2.6x)
Best score (100 tests)	41%	45%
Eval split	none	5% (480 examples)
Eval loss	—	0.887
Optimal repetition_penalty	1.1	1.0
жіктік (person agreement)	1/5	2/5
аралас (mixed errors)	4/10	6/10

Training Details

• Method: LoRA (r=64, alpha=128, all linear layers)
• Target modules: q_proj, k_proj, v_proj, o_proj, gate_proj, up_proj, down_proj
• Trainable params: 35.2M / 482.7M total (7.3%)
• Epochs: 3
• Learning rate: 2e-4 (cosine schedule, 5% warmup)
• Batch size: 8 (gradient accumulation 4, effective 32)
• Max sequence length: 512
• Steps: 855
• Hardware: NVIDIA A10 (23 GB)
• Training time: ~14 minutes
• Dataset: sozkz-gec-synthetic-gpt4o-v1 (9,599 pairs)
• Train/eval split: 9,119 / 480

Demo

Try it live at qazgramma-turbo.adapto.kz

Citation

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

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%)
Грамматика	11/20 (55%)
Пунктуация	7/15 (47%)
Смешанный	0/20 (0%)
Identity preservation	12/15 (80%)
Total	30/100 (30%)

Leaderboard (100-example custom benchmark)

Модель	Total	Емле/30	Грамм/20	Пункт/15	Смеш/20	Ident/15
sozkz-core-llama-600m-kk-gec-v1	47%	15	12	3	2	15/15
sozkz-fix-qwen-500m-kk-gec-v3	38%	0	16	9	0	13/15
sozkz-core-llama-300m-kk-gec-v4	37%	9	6	4	3	15/15
sozkz-fix-qwen-500m-kk-gec-v1	35%	0	12	8	0	15/15
sozkz-fix-qwen-500m-kk-gec-v2	30%	0	11	7	0	12/15
sozkz-core-llama-1b-kk-gec-v1	16%	2	6	1	0	7/15
sozkz-fix-qwen-500m-kk-gec-v4	5%	0	1	4	0	0/15
sozkz-fix-mt5b-kk-gec-run13-v1	5%	0	2	0	0	3/15
sozkz-nllb-1b-kk-gec-v1	1%	0	1	0	0	0/15
sozkz-nllb-1b-kk-pretrain-v1	1%	0	1	0	0	0/15
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