README.md

---
base_model: serda-dev/Jamba2-3B-Turkish
library_name: transformers
pipeline_tag: text-generation
language:
- tr
license: apache-2.0
tags:
- transformers
- mamba
- ssm
- safetensors
- jamba
- turkish
- text-generation
- conversational
- instruction-tuning
- continued-pretraining
- cpt
- sft
- qlora
- base_model:finetune:serda-dev/Jamba2-3B-Turkish
---

# Jamba2-3B Turkish CPT + SFT

Bu model, [`ai21labs/AI21-Jamba2-3B`](https://huggingface.co/ai21labs/AI21-Jamba2-3B) temel modeli üzerine Türkçe odaklı continued pre-training (CPT) ve ardından instruction supervised fine-tuning (SFT) uygulanarak hazırlanmıştır.

Eğitim hattı üç aşamadan oluşur:

1. **Temel model:** `ai21labs/AI21-Jamba2-3B`
2. **Türkçe CPT modeli:** `serda-dev/Jamba2-3B-Turkish`
3. **Bu model:** CPT modeli üzerine Türkçe instruction verileriyle QLoRA SFT uygulanmış sürüm

Model Türkçe sohbet, komut takip etme, soru-cevap, açıklama, özetleme ve genel metin üretimi için tasarlanmıştır.

## Model Details

| Field | Value |
| --- | --- |
| Model type | Jamba causal language model |
| Original base model | `ai21labs/AI21-Jamba2-3B` |
| CPT checkpoint | `serda-dev/Jamba2-3B-Turkish` |
| Language | Turkish (`tr`) |
| Task | Text generation, chat, instruction following |
| Architecture | `JambaForCausalLM` |
| Hidden size | 2560 |
| Layers | 28 |
| Attention heads | 20 |
| Vocabulary size | 69,632 |
| Saved dtype | bfloat16 |
| SFT context length | 1024 tokens |

## Training Overview

### 1. Continued Pre-Training

İlk aşamada `ai21labs/AI21-Jamba2-3B`, Türkçe dil dağılımına uyum sağlaması için continued pre-training ile eğitildi. CPT aşamasında yaklaşık **200 GB düzeyinde** Türkçe ağırlıklı metin verisi kullanıldı.

CPT süreci yalnızca Türkçe metinle sınırlı tutulmadı. Türkçe adaptasyon sırasında modelin genel muhakeme, matematik, yapısal metin ve kod benzeri bağımlılıkları kaybetmemesi için Türkçe veriyle birlikte seçilmiş İngilizce kaynaklar da karıştırıldı.

Repo konfigürasyonundaki dört fazlı CPT müfredatı:

| Phase | Purpose | Turkish target | English / auxiliary target |
| --- | --- | ---: | ---: |
| 1 | Turkish bridge | 30 GB | 10 GB DCLM + 5 GB English Wikipedia |
| 2 | High-quality transfer | 30 GB | 10 GB FineWeb-Edu (`score >= 4.0`) |
| 3 | Reasoning preservation | 30 GB | 10 GB OpenWebMath |
| 4 | Annealing / code preservation | 30 GB | 10 GB StarCoder Python |

Türkçe ana kaynak:

```text
***Private Repo***
```

CPT tarafında uzun JSONL/GZ shard'ları stream edilerek okunmuş, tokenlar tekrar kullanılabilir token cache shard'larına paketlenmiş ve eğitim checkpoint/resume destekli şekilde yürütülmüştür.

### 2. Supervised Fine-Tuning

CPT modeli üzerine Türkçe instruction verileriyle SFT uygulanmıştır. SFT eğitimi QLoRA ile yapılmış, ardından adapter tam modelle birleştirilebilir şekilde kaydedilmiştir.

SFT verisi farklı şemalardan tek bir eğitim formatına normalize edilmiştir:

- `prompt_answer`
- `system_prompt_answer`
- `messages`

Yerel veri hazırlama raporundaki SFT istatistikleri:

| Metric | Value |
| --- | ---: |
| Source files processed | 5 |
| Rows seen | 2,882,664 |
| Rows written | 2,882,519 |
| Rows skipped | 145 |
| Accepted SFT rows | 2,882,519 |
| `prompt_answer` rows | 2,605,516 |
| `messages` rows | 271,424 |
| `system_prompt_answer` rows | 5,579 |
| JSONL shards | 46 |

Kullanılan kaynak şemalar arasında `system/user/assistant`, `messages + answer`, `talimat/giriş/çıktı`, `soru/cevap` ve `input/output` biçimleri bulunur.

## SFT Hyperparameters

| Setting | Value |
| --- | --- |
| Method | QLoRA |
| Quantization during training | 4-bit NF4 |
| Double quantization | Enabled |
| Compute dtype | bfloat16 |
| LoRA rank | 16 |
| LoRA alpha | 32 |
| LoRA dropout | 0.05 |
| Target modules | `q_proj`, `k_proj`, `v_proj`, `o_proj`, `up_proj`, `down_proj`, `gate_proj` |
| Optimizer | `adamw_8bit` |
| Learning rate | `2e-5` |
| Weight decay | `0.01` |
| Warmup steps | 100 |
| Micro batch size | 1 |
| Gradient accumulation | 8 |
| Max sequence length | 1024 |
| Max steps | 5,000 |
| Total SFT tokens | 40,960,000 |
| Training time | about 4.44 hours |

## Evaluation

Model Turkish MMLU üzerinde yerel olarak kontrol edilmiştir. Bu sonuç kapsamlı bir benchmark iddiası değil, aynı eval scriptiyle alınmış pratik bir doğrulama sonucudur.

| Dataset | Split/File | Questions | Accuracy | Answered Accuracy |
| --- | --- | ---: | ---: | ---: |
| `alibayram/turkish_mmlu` | `train-00000-of-00001.parquet` | 2,000 | 36.5% | 36.70% |

Not: Çoktan seçmeli benchmarklarda prompt/parse formatı sonuca hassastır. Modeli farklı bir chat template, adapter merge veya generation ayarıyla değerlendirirken aynı evaluation formatının korunması önerilir.

## Intended Use

Bu model aşağıdaki kullanımlar için uygundur:

- Türkçe sohbet ve asistan uygulamaları
- Türkçe instruction-following prototipleri
- Türkçe soru-cevap ve açıklama üretimi
- Yerel RAG veya agent sistemlerinde Türkçe yanıt üretimi
- Türkçe veriyle daha ileri fine-tuning çalışmaları

## Out-of-Scope Use

Model tıbbi, hukuki, finansal veya güvenlik açısından kritik kararlar için tek başına otorite olarak kullanılmamalıdır. Zararlı içerik üretimi, kişisel veri çıkarma, kimlik avı, kötüye kullanım otomasyonu veya yasa dışı amaçlar kapsam dışıdır.

## Usage

### Full merged model

Bu repo tam model ağırlıklarını içeriyorsa doğrudan `AutoModelForCausalLM` ile yüklenebilir:

```python
import torch
from transformers import AutoModelForCausalLM, AutoTokenizer

model_id = "serda-dev/Jamba2-3B-Turkish-SFT"  # replace with this repo id

tokenizer = AutoTokenizer.from_pretrained(model_id)
model = AutoModelForCausalLM.from_pretrained(
    model_id,
    device_map="auto",
    torch_dtype=torch.bfloat16,
    attn_implementation="sdpa",
    trust_remote_code=True,
)
model.eval()

messages = [
    {"role": "system", "content": "Sen Türkçe yanıt veren yardımcı bir asistansın."},
    {"role": "user", "content": "Bu model ne için kullanılır?"},
]

input_ids = tokenizer.apply_chat_template(
    messages,
    add_generation_prompt=True,
    return_tensors="pt",
).to(model.device)

with torch.no_grad():
    output_ids = model.generate(
        input_ids,
        max_new_tokens=256,
        do_sample=True,
        temperature=0.7,
        top_p=0.9,
        repetition_penalty=1.05,
    )

print(tokenizer.decode(output_ids[0][input_ids.shape[-1]:], skip_special_tokens=True))
```

### PEFT adapter version

Bu repo yalnızca LoRA/QLoRA adapter ağırlıklarını içeriyorsa base model ile birlikte yükleyin:

```python
import torch
from peft import PeftModel
from transformers import AutoModelForCausalLM, AutoTokenizer, BitsAndBytesConfig

base_model_id = "serda-dev/Jamba2-3B-Turkish"
adapter_id = "serda-dev/Jamba2-3B-Turkish-SFT"  # replace with this repo id

bnb_config = BitsAndBytesConfig(
    load_in_4bit=True,
    bnb_4bit_quant_type="nf4",
    bnb_4bit_use_double_quant=True,
    bnb_4bit_compute_dtype=torch.bfloat16,
)

tokenizer = AutoTokenizer.from_pretrained(adapter_id)
model = AutoModelForCausalLM.from_pretrained(
    base_model_id,
    device_map="auto",
    torch_dtype=torch.bfloat16,
    quantization_config=bnb_config,
    attn_implementation="sdpa",
    trust_remote_code=True,
)
model = PeftModel.from_pretrained(model, adapter_id)
model.eval()
```

## Prompt Format

Model chat template ile eğitilmiştir. `tokenizer.apply_chat_template(...)` kullanılması önerilir.

Örnek format:

```text
<|im_start|>system
Sen Türkçe yanıt veren yardımcı bir asistansın.<|im_end|>
<|im_start|>user
Soru veya talimat<|im_end|>
<|im_start|>assistant
```

## Limitations and Risks

- Model Türkçe kullanım için optimize edilmiştir; diğer dillerde performans değişebilir.
- SFT verisi farklı kaynak ve şemalardan dönüştürüldüğü için veri kalitesi homojen değildir.
- Model yanlış, eksik veya uydurma bilgi üretebilir.
- Kod, sağlık, hukuk ve finans gibi alanlarda uzman doğrulaması gerekir.
- Safety alignment kapsamı sınırlıdır; üretimler uygulama katmanında filtrelenmelidir.
- Eğitim verisi lisansları ve dağıtım koşulları, modeli public olarak paylaşmadan önce ayrıca doğrulanmalıdır.

## Reproducibility Notes

CPT ve SFT süreçlerinde kullanılan yerel repo klasörleri:

- https://github.com/serda-dev/mamba-turkish-cptraining/tree/jamba-cpt
- https://github.com/serda-dev/jamba-sft-turkish

## Citation

Upstream model:

```bibtex
@misc{ai21jamba2,
  title = {AI21 Jamba2-3B},
  author = {AI21 Labs},
  url = {https://huggingface.co/ai21labs/AI21-Jamba2-3B}
}
```

## Framework Versions

- Transformers: 4.57.6
- PEFT: 0.18.1
- Training dtype: bfloat16