README.md

---
license: mit
language:
- kk
library_name: transformers
pipeline_tag: text-generation
base_model: stukenov/sozkz-core-qwen-500m-kk-base-v1
tags:
- kazakh
- qwen2
- instruct
- sft
- lora
- sozkz
---

# SozKZ Core Qwen 500M KK Instruct v1

Қазақ тіліне арналған **447M параметрлі** instruct-модель. [`sozkz-core-qwen-500m-kk-base-v1`](https://huggingface.co/stukenov/sozkz-core-qwen-500m-kk-base-v1) базасынан LoRA SFT арқылы алынған.

SFT-версия базовой казахской модели. Обучена отвечать на инструкции на казахском языке через LoRA fine-tuning на ~4882 парах Alpaca-style данных, сгенерированных Qwen3.5-122B.

## Model Details

- **Base model:** [`stukenov/sozkz-core-qwen-500m-kk-base-v1`](https://huggingface.co/stukenov/sozkz-core-qwen-500m-kk-base-v1)
- **Architecture:** Qwen2 Causal LM, 447M params
- **Language:** Kazakh (kk)
- **License:** MIT
- **Tokenizer:** [`stukenov/sozkz-morphbpe-100k-kk-v1`](https://huggingface.co/stukenov/sozkz-morphbpe-100k-kk-v1) (100K vocab, морфологический BPE)
- **Training method:** LoRA SFT → merge & unload (full model, no adapter needed)

## Fine-tuning Details

| Parameter | Value |
|---|---|
| Method | LoRA (merged) |
| LoRA r | 64 |
| LoRA alpha | 128 |
| Target modules | q/k/v/o\_proj, gate/up/down\_proj |
| Trainable params | 35.2M / 447M (7.3%) |
| Dataset | [`stukenov/sozkz-corpus-instruct-kk-alpaca-qwen35-v1`](https://huggingface.co/datasets/stukenov/sozkz-corpus-instruct-kk-alpaca-qwen35-v1) |
| Dataset size | 4,882 pairs |
| Epochs | 2 |
| Effective batch | 32 (8 × 4 grad accum) |
| Peak LR | 2e-4 (cosine) |
| Precision | bfloat16 |
| Hardware | 1× A100 SXM4 80GB |

## Prompt Format

Модель ожидает формат **`### Сұрақ / ### Жауап`** (обязательно):

```
### Сұрақ:
{инструкция}

{дополнительный контекст, если есть}

### Жауап:
```

## Usage

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

REPO = "stukenov/sozkz-core-qwen-500m-kk-instruct-v1"

tok_file = hf_hub_download(REPO, "tokenizer.json")
tok = PreTrainedTokenizerFast(tokenizer_file=tok_file)
tok.pad_token_id = 1

model = AutoModelForCausalLM.from_pretrained(REPO, dtype=torch.bfloat16).to("cuda")
model.train(False)

def ask(question, context=""):
    user = question + ("\n" + context if context else "")
    prompt = f"### Сұрақ:\n{user}\n\n### Жауап:\n"
    ids = tok(prompt, return_tensors="pt").input_ids.to("cuda")
    with torch.no_grad():
        out = model.generate(
            ids,
            max_new_tokens=200,
            do_sample=True,
            temperature=0.7,
            top_p=0.9,
            repetition_penalty=1.2,
            pad_token_id=1,
        )
    text = tok.decode(out[0], skip_special_tokens=True)
    return text.split("### Жауап:")[-1].strip()

print(ask("Жасанды интеллект дегеніміз не?"))
```

## Generation Examples

Сгенерировано на NVIDIA A10 с `temperature=0.7, top_p=0.9, repetition_penalty=1.2`:

---

**Жасанды интеллект дегеніміз не?**
```
Жасанды интеллект (ЖИ) — бұл жасанды интеллекттің ең негізгі
элементтерінің бірі. Бұл технологияның ең басты мақсаты – адам
миының құрылымын және функцияларын түсінуді қамтамасыз ету.

Бұл технологияны қолдану арқылы біз адам миы мен компьютер
арасындағы байланысты толық түсінеміз. Сонымен қатар, бұл
технология «білім көзі» ретінде қарастырылады, себебі оның
көмегімен көптеген есептер шешіледі.
```

---

**Жаңа бизнесті бастау үшін қадамдарды тізімдеңіз.**
```
1. Бизнесті дамыту: Бұл — кәсіпкерлердің өз бизнесін ашуға
   деген қызығушылығын ояту процесі.
2. Өндірістік және қызмет көрсету (Сервис): Тауарлар мен
   қызметтерді ұсыну бойынша іс-шаралар кешені.
3. Маркетинг стратегиясы: Нарықты зерттеу, мақсатты аудитория
   анықтау, баға белгілеу.
4. Қаржылық жоспарлау: Бастапқы инвестиция мөлшерін және
   күтілетін табысты есептеу.
5. Заңдық тіркеу: Салықтық есепке алу, лицензия алу.
```

---

**Денсаулықты сақтау үшін не істеу керек?**
```
Денсаулықты сақтау үшін мынаны ескеру керек:

1. Дұрыс тамақтану: Денсаулық – біздің ең басты байлығымыз.
   Жеміс-жидек, көкөніс, дәнді дақылдар жеңіз.
2. Белсенді өмір салты: Күнделікті кем дегенде 30 минут
   жаяу серуендеңіз немесе жаттығу жасаңыз.
3. Ұйқы режимі: Күніне 7–8 сағат ұйықтаңыз.
4. Стрестен аулақ болу: Медитация, хобби, жақындарымен
   сөйлесу арқылы эмоциялық тепе-теңдікті сақтаңыз.
5. Дәрігерлік тексеру: Жылына бір рет профилактикалық
   тексеруден өтіңіз.
```

---

**СҰРАҚ:** Салыстыр: кітап оқу мен видео көру
```
Кітап оқу — бұл терең ойлауды, сыни пікірді және
шығармашылықты дамытатын процесс.

Видео көру — ақпаратты жылдам қабылдауға мүмкіндік береді,
бірақ назарды ұстап тұру қиынырақ.

Айырмашылықтары:
• Кітап: баяу, терең, есте жақсы қалады
• Видео: жылдам, визуалды, бірақ беткейлі болуы мүмкін

Екеуі де маңызды — мақсатқа байланысты таңдаңыз.
```

---

**СҰРАҚ:** Бұл сөйлемді жақсарт.  
**КОНТЕКСТ:** Кеше мен дүкенге барып нан сатып алдым.
```
Кеше дүкенге барып, жаңа пісірілген нан сатып алдым.
```

## Comparison: Base vs Instruct

| | Base (sozkz-core-qwen-500m-kk-base-v1) | Instruct (this) |
|---|---|---|
| Behaviour | Продолжает текст | Отвечает на инструкции |
| Output format | Неструктурированный текст | Markdown, нумерованные списки |
| Language | Только казахский | Только казахский |
| Use case | Pretrain фундамент | SFT, диалог, Q&A |

## Limitations

- **Только казахский.** Базовая модель обучена исключительно на казахских текстах. Технические вопросы (код, математика) и код на Python работают плохо — модель просто не видела таких данных в pretrain.
- **Маленький датасет.** 4,882 пар — минимально жизнеспособный SFT. Модель освоила **формат** инструкт-ответов (markdown, структуру), но глубина знаний ограничена базовой моделью.
- **Галлюцинации.** Как все LM малого размера, иногда генерирует правдоподобный, но ошибочный текст. Не использовать без верификации.
- **Нет safety fine-tuning.** Модель может генерировать неподобающий контент.
- **Обязательный repetition_penalty ≥ 1.1.** Без него уходит в повторы.

## Training Pipeline

- SFT скрипт: `autoresearch/sft_lora_qwen_500m.py`
- Dataset generation: `scripts/data/instruct_generate_kk_cloudrift.py`
- Part of the [SozKZ open Kazakh LM initiative](https://huggingface.co/stukenov).

## SozKZ Model Family

| Model | Type | Params | Val BPB |
|---|---|---|---|
| [sozkz-core-qwen-500m-kk-base-v1](https://huggingface.co/stukenov/sozkz-core-qwen-500m-kk-base-v1) | Base | 447M | 0.474 |
| **sozkz-core-qwen-500m-kk-instruct-v1 (this)** | **Instruct** | **447M** | — |
| [sozkz-core-llama-1b-kk-base-v1](https://huggingface.co/stukenov/sozkz-core-llama-1b-kk-base-v1) | Base | 1078M | 0.673 |

## Citation

```bibtex
@misc{sozkz-core-qwen-500m-kk-instruct-v1,
  author = {Saken Tukenov},
  title = {SozKZ Core Qwen 500M KK Instruct v1},
  year = {2026},
  publisher = {HuggingFace},
  howpublished = {\url{https://huggingface.co/stukenov/sozkz-core-qwen-500m-kk-instruct-v1}},
}
```

## Acknowledgements

Part of the SozKZ open Kazakh LM initiative. Base model: `sozkz-core-qwen-500m-kk-base-v1`. SFT data: `sozkz-corpus-instruct-kk-alpaca-qwen35-v1` (Qwen3.5-122B via CloudRift). Hardware: RunPod (1× A100 SXM4 80GB).