README.md

---
language:
  - nl
  - en
license: apache-2.0
datasets:
  - ToetsChecker-Research/beleg
library_name: transformers
pipeline_tag: text-generation
tags:
  - dutch
  - nederlands
  - instruction-tuned
  - conversational
  - question-answering
  - summarization
  - qwen3
---

# Boterham 0.5B

## English

### Model description

**Boterham 0.5B** is a compact, primarily Dutch decoder-only language model
developed by ToetsChecker Research. It was pretrained from scratch and then
instruction-tuned for working with Dutch text and documents. The model is
particularly intended for grounded tasks: give it a passage and ask it to
extract an answer, summarize the passage, or abstain when the requested
information is absent.

The Hugging Face export uses the `Qwen3ForCausalLM` implementation because the
architectures are compatible. **Boterham does not use Qwen weights and is not a
fine-tune or derivative of Qwen**; its tokenizer and model weights were trained
from scratch.

| Property | Value |
|---|---|
| Parameters | 488.3M total; 447.4M excluding tied token embeddings |
| Architecture | Decoder-only Transformer, RMSNorm, GQA, RoPE, SwiGLU, QK-norm |
| Layers / hidden size | 26 / 1,280 |
| Attention heads | 20 query heads, 4 key/value heads |
| Context length | 2,048 tokens |
| Vocabulary | 32,002-token byte-level BPE |
| Languages | Primarily Dutch; some English and Dutch-English translation data |
| License | Apache 2.0 |

### Intended tasks

The instruction-tuning mixture contains the following task families:

- grounded extractive question answering;
- abstention when an answer is not present in the supplied text;
- Dutch document summarization;
- arithmetic and short worked calculations;
- grammar and multiple-choice classification;
- Dutch-English translation;
- open questions, basic factual questions and short conversation.

Its main intended use is experimentation with Dutch NLP, document-grounded
assistants and retrieval-augmented generation. It is not intended as a
high-stakes decision system or as an authoritative source of facts.

### Training

The base model was pretrained from scratch on approximately **8.0 billion
tokens**. The corpus consists of public-domain and permissively licensed
material, including Dutch government publications, legislation, parliamentary
proceedings, case law and Wikimedia sources. The documented source dataset is
available at [ToetsChecker-Research/beleg](https://huggingface.co/datasets/ToetsChecker-Research/beleg).
No general web crawl or model-generated distillation dataset was used.

Instruction tuning used 575,211 training examples and a held-out set of 1,000
examples. It ran for **2 epochs / 4,786 optimizer steps** on four NVIDIA L4
GPUs, with a peak learning rate of `5e-5` and a cosine schedule. Training loss
was applied only to answer tokens and weighted globally by the number of answer
tokens. The best held-out validation loss was **0.8348**.

The instruction data was built from verifiable source documents where
possible. Extractive answers must occur in the context; abstention examples are
checked so that the answer is absent; and reference summaries originate from
the source collection. The model uses the Boterham chat tokens included in the
published tokenizer.

### Usage with Transformers

```bash
pip install "transformers>=4.51" torch
```

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

model_id = "ToetsChecker-Research/boterham"

tokenizer = AutoTokenizer.from_pretrained(model_id)
model = AutoModelForCausalLM.from_pretrained(
    model_id,
    dtype=torch.bfloat16 if torch.cuda.is_available() else torch.float32,
).to("cuda" if torch.cuda.is_available() else "cpu")

messages = [{
    "role": "user",
    "content": (
        "Answer only from the text. If the answer is absent, say exactly: "
        "Ik weet dit niet.\n\n"
        "Tekst: De vergadering begint vrijdag om 14.00 uur in Utrecht.\n\n"
        "Vraag: Hoe laat begint de vergadering?"
    ),
}]

prompt = tokenizer.apply_chat_template(
    messages,
    tokenize=False,
    add_generation_prompt=True,
)
inputs = tokenizer(prompt, return_tensors="pt").to(model.device)

with torch.inference_mode():
    output = model.generate(
        **inputs,
        max_new_tokens=128,
        do_sample=False,
        eos_token_id=tokenizer.eos_token_id,
        pad_token_id=tokenizer.pad_token_id,
    )

generated = output[0, inputs.input_ids.shape[1]:]
raw = tokenizer.decode(generated, skip_special_tokens=False)

# Some prompts produce a private reasoning block before the final answer.
answer = raw.split("<|einde_denken|>")[-1].split("<|einde|>")[0].strip()
print(answer)
```

For the most reproducible task evaluation, use greedy decoding
(`do_sample=False`) and reproduce the benchmark's required answer format.

### Checkpoints in this repository

- Root-level `model.safetensors`: compact Transformers inference export.
- `sft-0.5B/beste.pt`: best instruction-tuned native PyTorch checkpoint.
- `sft-0.5B/laatste.pt`: final native checkpoint including optimizer state,
  intended for resuming training.
- `boterham-0.5B/`: original pretrained native checkpoints.

### Limitations

Boterham is a small experimental model. It has limited world knowledge and can
produce incorrect, fabricated or biased text. Factual claims about people,
dates, numbers, law, medicine or current events should not be trusted without
verification and supporting context. Its 2,048-token context window is short by
current standards. Open-ended conversation and creative writing received less
training emphasis than document-grounded tasks.

Official EuroEval benchmark results have not yet been published. Validation
loss is a training diagnostic and must not be interpreted as a benchmark score.

---

## Nederlands

### Modelbeschrijving

**Boterham 0.5B** is een compact, voornamelijk Nederlandstalig decoder-only
taalmodel van ToetsChecker Research. Het model is vanaf nul voorgetraind en
daarna instructiegetuned voor het werken met Nederlandse tekst en documenten.
Het is vooral bedoeld voor gegronde taken: geef het een passage en laat het een
antwoord uit de tekst halen, de passage samenvatten, of aangeven dat gevraagde
informatie ontbreekt.

De Hugging Face-export gebruikt `Qwen3ForCausalLM` omdat de architecturen
compatibel zijn. **Boterham gebruikt geen Qwen-gewichten en is geen finetune of
afgeleide van Qwen**; zowel de tokenizer als de modelgewichten zijn vanaf nul
getraind.

| Eigenschap | Waarde |
|---|---|
| Parameters | 488,3M totaal; 447,4M zonder de gedeelde tokenembeddings |
| Architectuur | Decoder-only Transformer, RMSNorm, GQA, RoPE, SwiGLU, QK-norm |
| Lagen / verborgen breedte | 26 / 1.280 |
| Attention-heads | 20 query-heads, 4 key/value-heads |
| Contextlengte | 2.048 tokens |
| Woordenschat | byte-level BPE met 32.002 tokens |
| Talen | Vooral Nederlands; ook Engels en Nederlands-Engelse vertaaldata |
| Licentie | Apache 2.0 |

### Taken

De instructiefinetuning bevat de volgende taakfamilies:

- extractieve vraagbeantwoording op basis van meegegeven tekst;
- onthouding wanneer het antwoord niet in de tekst staat;
- samenvatten van Nederlandse documenten;
- rekenen en korte uitgewerkte berekeningen;
- grammatica- en meerkeuzeclassificatie;
- Nederlands-Engelse vertaling;
- open vragen, eenvoudige feitenvragen en korte gesprekken.

Het belangrijkste gebruiksdoel is onderzoek naar Nederlandse NLP,
documentgestuurde assistenten en retrieval-augmented generation. Het model is
niet bedoeld voor beslissingen met grote gevolgen of als gezaghebbende
feitenbron.

### Training

Het basismodel is vanaf nul voorgetraind op ongeveer **8,0 miljard tokens**.
Het corpus bestaat uit publiek domein en permissief gelicentieerd materiaal,
waaronder Nederlandse overheidspublicaties, wetgeving, parlementaire
Handelingen, rechtspraak en Wikimedia-bronnen. De gedocumenteerde brondataset
staat op [ToetsChecker-Research/beleg](https://huggingface.co/datasets/ToetsChecker-Research/beleg).
Er is geen algemene webcrawl of door een ander model gegenereerde
destillatiedataset gebruikt.

De instructiefinetuning gebruikte 575.211 trainingsvoorbeelden en 1.000
apart gehouden validatievoorbeelden. De run duurde **2 epochs / 4.786
optimizerstappen** op vier NVIDIA L4-GPU's, met een maximale learning rate van
`5e-5` en een cosine schedule. Alleen antwoordtokens telden mee voor de loss;
de weging gebeurde globaal op basis van het aantal antwoordtokens. De beste
validatieloss was **0,8348**.

Waar mogelijk is de instructiedata opgebouwd uit controleerbare
brondocumenten. Extractieve antwoorden moeten letterlijk in de context staan,
bij onthoudingsvoorbeelden wordt gecontroleerd dat het antwoord ontbreekt, en
referentiesamenvattingen komen uit de broncollectie. Het model gebruikt de
Boterham-chattokens die in de gepubliceerde tokenizer zijn opgenomen.

### Gebruik met Transformers

Het Python-voorbeeld in de Engelse sectie is direct bruikbaar. De belangrijke
stappen zijn `AutoTokenizer.from_pretrained`,
`AutoModelForCausalLM.from_pretrained` en `tokenizer.apply_chat_template`.
Gebruik voor reproduceerbare evaluatie greedy decoding (`do_sample=False`) en
houd het antwoordformaat van de benchmark exact aan.

### Checkpoints in deze repository

- `model.safetensors` in de hoofdmap: compacte Transformers-export voor
  inference en benchmarks.
- `sft-0.5B/beste.pt`: beste native PyTorch-checkpoint na instructiefinetuning.
- `sft-0.5B/laatste.pt`: laatste native checkpoint inclusief optimizerstaat,
  bedoeld om training te hervatten.
- `boterham-0.5B/`: oorspronkelijke voorgetrainde native checkpoints.

### Beperkingen

Boterham is een klein experimenteel model. Het heeft beperkte wereldkennis en
kan onjuiste, verzonnen of bevooroordeelde tekst produceren. Feiten over
personen, datums, getallen, recht, geneeskunde of actuele gebeurtenissen mogen
niet zonder controle en ondersteunende context worden vertrouwd. Het
contextvenster van 2.048 tokens is naar huidige maatstaven kort. Open
conversatie en creatief schrijven kregen minder nadruk dan documentgebonden
taken.

Officiële EuroEval-benchmarkresultaten zijn nog niet gepubliceerd.
Validatieloss is een trainingsdiagnose en geen benchmarkscore.