Qwen3-0.6B Polish Text Normalization

Polski opis modelu

A fine-tuned Qwen3-0.6B model for Polish text normalization — converting written text with numbers, dates, abbreviations, and units into fully spoken form for TTS (Text-to-Speech) systems.

This model replaces Folx/byt5-small-pl-text-normalization with 2x higher accuracy and comparable latency when served with vLLM.

Performance Comparison

Key improvements:

• +42pp exact match (43.4% → 85.7%)
• Zero digit leaks with constrained decoding (bans digit tokens from output)
• Fuzzy match 87.7% (case-insensitive, punctuation-normalized)
• 270+ samples/sec throughput via vLLM concurrent serving

What It Does

Converts written Polish text into spoken form:

Handles: numbers, dates, times, addresses, currencies, percentages, units (km/h, °C, hPa, m²), abbreviations (ul., al., prof., dr, nr, m.in., tzw., itp.), flight/train numbers, fractions, r/r (rok do roku), legal references (art., §, ust., pkt), and passthrough of clean text.

Requirements

transformers>=5.0.0
torch>=2.1.0

Important: This model requires transformers >= 5.0.0. Older versions (e.g. 4.57) tokenize the Qwen3 chat template differently, producing incorrect normalization output even at temperature=0.

Usage

With Transformers (simple)

from transformers import AutoModelForCausalLM, AutoTokenizer
import torch

model_name = "Folx/qwen3-0.6b-pl-text-normalization"
tokenizer = AutoTokenizer.from_pretrained(model_name)
model = AutoModelForCausalLM.from_pretrained(model_name, torch_dtype=torch.bfloat16, device_map="auto")
model.eval()

def normalize(text: str) -> str:
    messages = [
        {"role": "system", "content": "Zamieniasz tekst na formę mówioną."},
        {"role": "user", "content": text},
    ]
    prompt = tokenizer.apply_chat_template(messages, tokenize=False, add_generation_prompt=True)
    inputs = tokenizer(prompt, return_tensors="pt").to(model.device)
    prompt_len = inputs["input_ids"].shape[1]

    with torch.no_grad():
        output_ids = model.generate(
            **inputs,
            max_new_tokens=400,
            do_sample=False,
            temperature=1.0,
            pad_token_id=tokenizer.pad_token_id,
        )
    return tokenizer.decode(output_ids[0][prompt_len:], skip_special_tokens=True).strip()

# Example
print(normalize("Spotkanie o 14:30 przy ul. Głównej 12."))
# → Spotkanie o czternastej trzydzieści przy ulicy Głównej dwanaście.

With Constrained Decoding (zero digit leaks)

For production TTS, ban digit tokens from output to guarantee no numbers slip through:

def get_banned_token_ids(tokenizer):
    """Get token IDs for digits and symbols that should always be spoken as words."""
    banned = set()
    for tid in range(tokenizer.vocab_size):
        decoded = tokenizer.decode([tid]).strip()
        if decoded and decoded.isdigit():
            banned.add(tid)
    # Symbols that TTS must speak as words
    for sym in ["$", "%", "€", "£", "¥", "°", "§", "@", "#", "&", "×", "÷", "±",
                "©", "®", "™", "→", "←", "↑", "↓", "√", "∞", "≈", "≠", "≤", "≥"]:
        ids = tokenizer.encode(sym, add_special_tokens=False)
        if len(ids) == 1:
            banned.add(ids[0])
    return sorted(banned)

banned_ids = get_banned_token_ids(tokenizer)

def normalize_safe(text: str) -> str:
    messages = [
        {"role": "system", "content": "Zamieniasz tekst na formę mówioną."},
        {"role": "user", "content": text},
    ]
    prompt = tokenizer.apply_chat_template(messages, tokenize=False, add_generation_prompt=True)
    inputs = tokenizer(prompt, return_tensors="pt").to(model.device)
    prompt_len = inputs["input_ids"].shape[1]

    with torch.no_grad():
        output_ids = model.generate(
            **inputs,
            max_new_tokens=400,
            do_sample=False,
            temperature=1.0,
            pad_token_id=tokenizer.pad_token_id,
            suppress_tokens=banned_ids,  # Ban digits and symbols
        )
    return tokenizer.decode(output_ids[0][prompt_len:], skip_special_tokens=True).strip()

With vLLM (production, high throughput)

python -m vllm.entrypoints.openai.api_server \
    --model Folx/qwen3-0.6b-pl-text-normalization \
    --port 8094 --max-model-len 512

import aiohttp, asyncio

async def normalize(text: str) -> str:
    async with aiohttp.ClientSession() as session:
        async with session.post("http://localhost:8094/v1/chat/completions", json={
            "model": "Folx/qwen3-0.6b-pl-text-normalization",
            "messages": [
                {"role": "system", "content": "Zamieniasz tekst na formę mówioną."},
                {"role": "user", "content": text}
            ],
            "max_tokens": 400, "temperature": 0,
        }) as resp:
            data = await resp.json()
            return data["choices"][0]["message"]["content"].strip()

# ~270 samples/sec with 32 concurrent workers

Model Details

Training

• Dataset: 64K curated Polish normalization pairs (private)
• Sources: Human-curated examples, Speakleash Polish corpora (Wikipedia, news, financial), Faker-generated structured data (addresses, phone numbers, codes), targeted gap-filling for edge cases
• Teacher model: Bielik-11B-v3.0-Instruct for synthetic data generation and validation
• Quality pipeline: Reverse-normalization consistency checking — each pair verified by converting output back to written form and comparing with input (>75% similarity threshold)
• Training config: 5 epochs, lr=1e-4, cosine schedule, batch 4 × grad_accum 4, eval every 250 steps with best-by-exact-match checkpoint selection
• Hardware: Single NVIDIA RTX 5090 32GB

Evaluation

Evaluated on 1,709 held-out samples from the original human-curated dataset:

Remaining "errors" analysis: ~60% of mismatches are stylistic differences where both model output and reference are valid Polish (case differences, punctuation, grammatical case variants like "pięć procent" vs "pięciu procent"). True error rate is estimated at ~8-9%.

Limitations

• Designed specifically for Polish language
• Optimized for TTS preprocessing — the model normalizes text for pronunciation, not for grammatical correctness
• Address format 1/34 (apartment numbers) is sometimes read as a whole number rather than "jeden łamane trzydzieści cztery"
• Very rare abbreviations or domain-specific terminology may not be expanded
• Performance degrades for inputs longer than ~300 characters
• Requires GPU for reasonable latency (~46ms on RTX 5090 via vLLM)

---

Polski opis modelu

Qwen3-0.6B Polish Text Normalization to model AI do normalizacji polskiego tekstu opracowany przez Folx — butik AI specjalizujący się w systemach rozpoznawania mowy (ASR), syntezy mowy (TTS) oraz rozwiązaniach głosowych.

Model bazuje na architekturze Qwen3-0.6B i został dostrojony metodą LoRA na 64 tysiącach par normalizacyjnych. Zamienia tekst pisany — z liczbami, datami, skrótami, jednostkami — na formę mówioną, gotową do syntezy mowy.

Zastępuje nasz poprzedni model byt5-small-pl-text-normalization z dwukrotnie wyższą dokładnością (85.7% vs 43.4% exact match) i porównywalnym czasem odpowiedzi (~46ms przez vLLM).

Kluczowe cechy

• 85.7% dokładności exact match na zbiorze testowym (87.7% z normalizacją wielkości liter i interpunkcji)
• Zero wycieków cyfr w wyniku — constrained decoding blokuje tokeny cyfr
• ~46ms latencja przez vLLM, 270 zapytań/sekundę z 32 równoległymi workerami
• Obsługuje: liczby, daty, godziny, adresy, waluty, procenty, jednostki (km/h, °C, hPa, m²), skróty (ul., al., prof., dr, nr, m.in., tzw., itp.), numery lotów/pociągów, ułamki, r/r, odniesienia prawne (art., §, ust., pkt)

Zastosowania

• Synteza mowy (TTS) — naturalna wymowa polskich dat, liczb i skrótów
• Asystenci głosowi — przetwarzanie poleceń w języku polskim
• Audiobooki i podcasty — automatyczna konwersja tekstu do formatu audio
• Systemy IVR / call center — profesjonalne komunikaty głosowe
• Accessibility — czytniki ekranowe poprawnie wymawiające polski tekst
• Media i broadcasting — automatyzacja przygotowania skryptów audio

Użycie

System prompt: Zamieniasz tekst na formę mówioną.

Model przyjmuje tekst do znormalizowania jako wiadomość użytkownika i zwraca znormalizowany tekst jako odpowiedź asystenta. Format chat template Qwen3.

Szczegóły użycia i przykłady kodu — patrz sekcja Usage powyżej.

Kontakt:

Folx — deep learning, transformer models, Polish NLP, speech recognition, text-to-speech, voice AI

Changelog — v4 (2026-05-09)

Fixes the user-reported PAP fuel-prices failure. Trained continuing from qwen3-normalizer-best LoRA adapter (r=128 α=256) on:

• 65,044 cleaned base rows (existing training + 23,702 curated corrections from error_mining_corrections.csv, with REWRITE class and label-noise dropped)
• 219 hand-curated PAP-style rows × 15 upsample (synthetic Bielik-generated augmentation was tried in v4.0/v4.1/v4.2 but introduced new failure modes; hand curation produced cleaner results)

What v4 fixes vs v3

• Pb98 6,90 zł/l → no longer emits "złotych dziewięćdziesiąt złotych groszy" (token-repetition gone)
• 0,30 zł na litr → "trzydzieści groszy na litr" (was "trzydziestu złotych" — 100× off)
• oleju napędowego ... zł/l → no longer hallucinates "Q15" or appends spurious "benzyny"
• Multi-fuel comparison sentences keep each fuel's "za litr" unit clean
• Pb95 / Pb98 / Pb98+ / LPG / ON consistently expanded ("pe-be dziewięćdziesiąt pięć", "el-pe-gie", "olej napędowy")

Metrics

• Test set v1 (270 corrections-derived rows): exact_match 45.19%, fuzzy 75.19%, char 83.35%
• Regression suite (47 hand-typed rows covering reported failure surface): 47/47 = 100%
• Per-class regression vs v3: zero classes dropped ≥3pt EM

Notes

• This is the first version produced through a versioned manifest + pre-upload gate (data/run_qa_gate.py in the source repo). The class-coverage gate was relaxed for v4 because the test set is corrections-derived; v5 will tighten this with class-balanced augmentation.