---
base_model: unsloth/gemma-3-270m-it
tags:
- text-generation-inference
- transformers
- unsloth
- gemma3_text
- inverse-text-normalization
- ITN
license: apache-2.0
language:
- hu
metrics:
- wer
- cer
- exact_match
---

# Gemma-3-270M Hungarian ITN Finetune

A Gemma-3 270M Instruct modell Inverse Text Normalization (ITN) feladatra finetune-olva magyar nyelven. A modell automatikusan átalakítja a beszédfelismerés (ASR) által generált szövegben a betűvel kiírt számokat, dátumokat és mértékegységeket normalizált írott formára.

## Model Details

- **Base model**: [unsloth/gemma-3-270m-it](https://huggingface.co/unsloth/gemma-3-270m-it)
- **Model type**: Gemma-3 270M with LoRA adapters (merged to 16-bit)
- **Language**: Hungarian (hu)
- **License**: [Gemma](https://ai.google.dev/gemma/terms)
- **Finetuning framework**: [Unsloth](https://github.com/unslothai/unsloth) + TRL SFTTrainer

## Intended Use

A modell célja, hogy magyar ASR (beszédfelismerő) rendszerek kimenetét normalizálja.

### Examples

| Bemenet (ASR kimenet) | Kimenet (normalizált) |
|---|---|
| a második világháború után | a 2. világháború után |
| két fiú és két lány apja | 2 fiú és 2 lány apja |
| negyven kilométer | 40 kilométer |
| kilencszer jelölték | 9-szer jelölték |
| a tömegmészárlásnak három túlélője ismert | a tömegmészárlásnak 3 túlélője ismert |

### Direct Use

A modell közvetlenül használható magyar ASR kimenetek normalizálására. Ajánlott használati esetek:
- Beszédfelismerő rendszerek utófeldolgozása
- Automatikus feliratozás
- Diktált szövegek formázása

### Out-of-Scope Use

- Nem ASR kimenetek normalizálása (pl. helyesírási hibák javítása)
- Más nyelvű szövegek (a modell kizárólag magyarra lett optimalizálva)
- Generatív feladatok (a base modell képességei korlátozottak a finetune miatt)

## Training Data

A training dataset ~21 000 sorból áll, három forrásból:

| Forrás | Sorok | Leírás |
|---|---|---|
| Common Voice | 5 802 | Mozilla open-source magyar beszédkorpusz |
| VoxPopuli | 2 878 | EU parlament beszédek (magyar) |
| Whisper | 12 483 | OpenAI Whisper ASR által generált magyar átírások |

A dataset "needle in the haystack" megközelítéssel készült: regex alapú szűréssel csak az ITN-re releváns (számokat, dátumokat, mértékegységeket tartalmazó) sorok kerültek be. A normalizált targetek regex alapú normalizálással készültek, komplex esetekben lokális LLM-mel (Gemma 4 12B) javítva.

### Data Preprocessing

A szövegek Gemma-3 chat template-re lettek konvertálva:
- **System prompt**: "Alakítsd át a következő magyar ASR szöveget normalizált írott formára (számok, dátumok, mértékegységek):"
- **User**: az eredeti ASR szöveg
- **Assistant**: a normalizált szöveg

## Training Procedure

### Finetuning Details

- **Framework**: Unsloth + TRL SFTTrainer
- **Method**: LoRA (Low-Rank Adaptation)
- **LoRA rank**: 128
- **LoRA alpha**: 128
- **Target modules**: q_proj, k_proj, v_proj, o_proj, gate_proj, up_proj, down_proj
- **Precision**: float16
- **Max sequence length**: 2048 tokens

### Training Hyperparameters

| Parameter | Value |
|---|---|
| Learning rate | 2e-5 |
| LR scheduler | linear |
| Optimizer | adamw_8bit |
| Batch size | 16 |
| Gradient accumulation | 1 |
| Warmup steps | 150 |
| Epochs | 1 |
| Weight decay | 0.001 |
| LoRA dropout | 0 |

### Special Training Techniques

- **Train on responses only**: A loss csak az assistant válaszokra számítódik, a user input és system prompt mask-olva van (-100 ignore index). Ez növeli a finetune pontosságát.
- **Unsloth optimizations**: Gradient checkpointing "unsloth" módban (~30% VRAM megtakarítás).

## How to Use

### Installation

```
pip install unsloth transformers peft torch
```

### Inference with Unsloth

```python
from unsloth import FastModel
import torch

model, tokenizer = FastModel.from_pretrained(
    model_name="GaborMadarasz/gemma_3_270m_ITN_finetune_16bit",
    max_seq_length=2048,
    load_in_4bit=False,
    dtype=torch.float16,
)

messages = [
    {"role": "system", "content": "Alakítsd át a következő magyar ASR szöveget normalizált írott formára (számok, dátumok, mértékegységek):"},
    {"role": "user", "content": "a második világháború után negyven évvel"},
]

text = tokenizer.apply_chat_template(messages, tokenize=False, add_generation_prompt=True)
inputs = tokenizer(text, return_tensors="pt").to("cuda")

outputs = model.generate(
    **inputs,
    max_new_tokens=256,
    temperature=1.0,
    top_p=0.95,
    top_k=64,
)

print(tokenizer.decode(outputs[0], skip_special_tokens=True))
```

### Inference with Transformers

```python
from transformers import AutoModelForCausalLM, AutoTokenizer

model = AutoModelForCausalLM.from_pretrained(
    "GaborMadarasz/gemma_3_270m_ITN_finetune_16bit",
    torch_dtype="auto",
    device_map="auto",
)
tokenizer = AutoTokenizer.from_pretrained("GaborMadarasz/gemma_3_270m_ITN_finetune_16bit")
```

## Limitations and Bias

- **Méret**: A 270M paraméter korlátozza a modell által kezelhető komplex eseteket (pl. összetett dátumok, többes számok mondaton belül)
- **Domain**: A training data főleg Common Voice, VoxPopuli és Whisper forrásból származik, ami nem fedi le az összes magyar beszédtípust (pl. dialektusok, szaknyelv)
- **Hallucináció**: Ritkán előfordulhat, hogy a modell nem csak a számokat normalizálja, hanem más szavakat is módosít
- **ITN coverage**: A regex alapú normalizálás nem fedi le az összes magyar szám-kifejezést (pl. tört számok: "másfél", "háromnegyed")

## Evaluation

Az értékelés **három független, a trainingből teljesen kizárt test set-en** történt. Egyik test set sem volt benne a training datasetben (a Common Voice és VoxPopuli train splitjeiből származó adatokat használtunk csak a tanításhoz, a test splitjeiket kizárólag az értékeléshez).

### Test Datasets

| Dataset | Sorok | Forrás |
|---|---|---|
| Common Voice test | 1 000 | Mozilla Common Voice hu test split |
| VoxPopuli test | 1 110 | VoxPopuli hu test split |
| FLEURS test | 905 | Google FLEURS hu test split |
| **Összesen** | **3 015** | |

### Results

| Dataset | Exact Match | Number Accuracy | WER | CER |
|---|---|---|---|---|
| Common Voice test | 97.70% | 99.30% | 0.35% | 0.18% |
| VoxPopuli test | 96.94% | 99.28% | 0.82% | 0.59% |
| FLEURS test | 93.81% | 98.33% | 1.93% | 1.40% |
| **Összesített** | **96.25%** | **99.00%** | **1.15%** | **0.81%** |

### Error Analysis

A leggyakoribb hibatípusok a legrosszabb esetek alapján:

1. **Túl agresszív normalizálás** (leggyakoribb): A modell olyan szavakat is számra cserél, amelyek csak tartalmazzák a szám tövét, de nem számok. Például:
   - "egészen" → "1." (hibás, az "egész" nem szám)
   - "egyike" → "1." (hibás, az "egyike" főnév)
   - "egyre" → "1re" (hibás, az "egyre" határozószó)

2. **Nagybetűsítés**: A modell automatikusan nagybetűsíti a mondatkezdést, de a gold adat kisbetűs. Valójában helyesírásilag a modell kimenete a helyes, de nem egyezik a gold standarddal.

3. **Rossz számok** (ritka): A modell néha rossz számot generál (pl. "négyszer" → "2-szer").

4. **Tartalmi változtatás** (ritka): A modell néha szavakat hagy el vagy változtat meg a számokon kívül.

### Metrikák magyarázata

- **Exact Match**: A teljes normalizált szöveg pontos egyezése a gold-dal
- **Number Accuracy**: Csak a számok/dátumok/mértékegységek helyessége
- **WER** (Word Error Rate): Szószintű hibaarány
- **CER** (Character Error Rate): Karakter szintű hibaarány


## Limitations and Bias

- **Méret**: A 270M paraméter korlátozza a modell által kezelhető komplex eseteket (pl. összetett dátumok, többes számok mondaton belül)
- **Túl agresszív normalizálás**: A modell néha olyan szavakat is számra cserél, amelyek csak tartalmazzák a szám tövét ("egyike", "egész", "egyre")
- **Domain**: A training data főleg Common Voice, VoxPopuli és Whisper forrásból származik, ami nem fedi le az összes magyar beszédtípust (pl. dialektusok, szaknyelv)
  
## Citation

```bibtex
@misc{gemma3_270m_itn_hu,
  author = {Madarász, Gábor},
  title = {Gemma-3-270M Hungarian ITN Finetune},
  year = {2026},
  publisher = {HuggingFace},
  howpublished = {\url{https://huggingface.co/GaborMadarasz/gemma_3_270m_ITN_finetune_16bit}}
}
```

## Acknowledgements

- [Google Gemma Team](https://ai.google.dev/gemma) - a base modellért
- [Unsloth](https://github.com/unslothai/unsloth) - a hatékony finetuning framework-ért
- [Mozilla Common Voice](https://commonvoice.mozilla.org/hu) - a nyílt forrású magyar beszédkorpuszért
- [VoxPopuli](https://github.com/facebookresearch/voxpopuli) - az EU parlamenti beszédekért
- [OpenAI Whisper](https://github.com/openai/whisper) - az ASR kimenetekért