README.md

---
library_name: transformers
license: apache-2.0
pipeline_tag: text-generation
tags:
- finetuned
inference: true
widget:
- messages:
  - role: system
    content: Je bent een behulpzame Nederlandse AI-assistent.
  - role: user
    content: Is Nederlandse wijn lekker?
datasets:
- yhavinga/mc4_nl_cleaned
- yhavinga/nedd_wiki_news
- teknium/OpenHermes-2.5
- euirim/goodwiki
- philschmid/flanv2
---

# Boreas

**NB: 20240430 model card is WIP - evaluations / example generations to be added**

![BoreasThe Mighty God of the North Wind](https://oldworldgods.com/wp-content/uploads/2023/10/boreas1.jpg)

[Boreas-7B](https://huggingface.co/yhavinga/Boreas-7B) is een Nederlands/Engels taalmodel gebaseerd op Mistral-7B.
Het is getraind op 10 miljard tokens aan Nederlandse en Engelse tekst.

**Boreas-7B-chat** (dit model) is verder getraind op instructie- en chat data.

* Boreas-7B is vergelijkbaar met [GEITje-7B](https://huggingface.co/Rijgersberg/GEITje-7B) in die zin dat
  het ook een model is dat verder getraind is op Mistral-7B, met een evenzogrote hoeveelheid tokens (10B).
* Boreas-7B-chat is vergelijkbaar met [GEITje-7B-chat](https://huggingface.co/Rijgersberg/GEITje-7B-chat) en [GEITJE-7B-ultra-sft](https://huggingface.co/BramVanroy/GEITje-7B-ultra-sft), in die zin dat het ook een 
  fine-tune is op een chat dataset.

Edwin Rijgersberg heeft [uitgebreide documentatie](https://github.com/Rijgersberg/GEITje/blob/main/README.md) geschreven voor het gebruik van GEITje,
en deze is ook van toepassing op Boreas.

De voornaamste verschillen tussen Boreas en GEITje zijn:

* Boreas-7B en Boreas-7B-chat zijn getraind met een context lengte van 2048 tokens, GEITje met 8192 tokens.
* Boreas-7B en Boreas-7B-chat zijn getraind op een mix van Engels en Nederlands, waar GEITje alleen op voornamelijk Nederlands getraind is.
* Boreas-7B-chat is getraind op een mix van zowel chat conversaties als ook 'normaal' pre-trainen.

Omdat zowel GEITje als Boreas afgeleiden zijn van hetzelfde basismodel, is het mogelijk om een [merge](https://github.com/arcee-ai/mergekit) te maken.


## Gebruik met ollama

Kies een GGUF quant van [Boreas-7B-chat-v1-GGUF](https://huggingface.co/yhavinga/Boreas-7B-chat-v1-GGUF)
en volg de instructies daar.
Belangrijk: gebruik een system prompt, anders zijn de resultaten matig.

## Doel Boreas

Creatie van een taalmodel dat wat betreft het Nederlandse gedeelte, niet getraind is op teksten gegeneerd door
een LLM. Dus geen Nederlandse chats gegeneerd door een LLM, en ook geen datasets die vertaald zijn uit het Engels door een LLM.
Er is niet strict gefilterd op LLM-gegenereerde tekst, maar dit is wel een aandachtspunt geweest bij het samenstellen van de datasets.
Bij het finetunen van Boreas-chat zijn toch 3% van de tokens Nederlandse chats gegeneerd door een LLM.
Dit is een kleine dataset die gemaakt is op basis van Nederlandse bronteksten, en een steekproef heeft uitgewezen
dat deze data van een goede kwaliteit is.

Het uiteindelijke chat model is getraind op een mix van voornamelijk:

1. Openhermes-2.5: grote, diverse Engelse chat dataset (~45%)
2. Een engels naar nederlands vertaal dataset (~34%)
3. Pre-train data: verder met Wiki en boeken (~12%)
4. Nederlandse wiki en boeken q en a (~3%)

Het Boreas model kan dus beschouwd worden als een test voor knowledge transfer van Engels naar Nederlands.

## Boreas-7B basismodel

Het basismodel is op Mistral-7B doorgetraind op 10 miljard tokens.

De dataset is samengesteld uit verschillende bronnen in zowel Nederlands en Engels:

| Datasetnaam                                    | Aantal Tokens | Percentage Tokens (%) |
|------------------------------------------------|---------------|-----------------------|
| Nederlandse romans                             | 3401M         | 34.01                 |
| Nederlandse Wikipedia                          | 2381M         | 23.81                 |
| mc4_nl_cleaned (Nederlands)                    | 1361M         | 13.61                 |
| Nederlands nieuws                              | 1361M         | 13.61                 |
| Nederlandse schoolboeken                       | 136M          | 1.36                  |
| Engelse romans                                 | 340M          | 3.40                  |
| Engelse Wikipedia (euirim/goodwiki)            | 340M          | 3.40                  |
| Engelse wiskunde- en natuurkundeboeken         | 340M          | 3.40                  |
| Engelse instructiedataset (philschmid/flanv2) | 340M          | 3.40                  |

De keuze voor deze mix is gebaseerd op zowel beschikbaarheid van data als de volgende overwegingen:

* Veel Nederlands van hoge kwaliteit, teksten primair in het Nederlands geschreven door mensen. Hieruit volgt de keuze
  voor romans, Wikipedia en nieuwsartikelen, maar bijvoorbeeld uitsluiten van forum-/twitterberichten en wetteksten.
* Erin mixen van de originele dataset voor ~5%, om ervoor te zorgen dat een model haar originele kennis niet verliest.
  Het is niet bekend op welke data Mistral getraind is, maar het is aannemelijk dat er kwalitatief goed Engels en ook instructiedata in verwerkt is. Daarom is voor de ~3% aan Engelse boeken, Wikipedia en ook instructiedata gekozen.
* Zoveel mogelijk uitsluiten van door LLM's gegenereerde teksten in de pre-train fase. Bij veel datasets, vooral Nederlands, valt me op dat
  de vertalingen of generaties van een slechte kwaliteit zijn. Daarom is gekozen voor datasets waarvan de brondata
  pre ChatGPT tijdperk zijn, (dus voor November 2022).
* mc4_nl_cleaned - de bron van deze dataset is mC4 - deduplicated data van Common
  Crawl, en gefiltered op bad-words en andere bewerkingen volgens het recept van de T5 auteurs voor de Engelse C4 dataset. In diverse vergelijkingen blijkt C4 een goede pre-train dataset, daarom is mc4_nl_cleaned ook voor dit model gebruikt.
* Er is geen sourcecode in gemixt - ik verwacht niet dat een 7B model ooit code kan genereren dat bruikbaar is.
  Misschien helpt het bij logisch redeneer-puzzels, maar ook daarvoor verwacht ik dat een 7B model dit nooit zo goed
  zal kunnen of generaliseren als grotere modellen.

Bij het pre-trainen zijn de brontexten gepackt in blokken van 2048 tokens. Hierbij is waar mogelijk geprobeerd om alleen
teksten te packen die bij elkaar passen. Ook worden kleine fragmenten weggegooid, zodat we
bijvoorbeeld nooit een fragment krijgen dat begint met een paar tokens van het einde van een wikipedia artikel, om daarna met een ander wikipedia artikel te beginnen. Dit is gedaan om 'cross sequence' ruis binnen 1 example zoveel mogelijk te voorkomen. Pas na packing zijn de examples geshuffled.

## Pre-training

* Boreas was pre-trained with the [EasyDeL JAX framework](https://github.com/erfanzar/EasyDel) on a tpu-v4-32
kindly supplied by the Google [TPU Research Cloud](https://sites.research.google/trc/about/).
* Batch size 96, gradient accumulation steps 2
* Using flash attention, block size of 512
* Max sequence length of 2048
* LION optimizer, triangle learning rate schedule with max lr 3e-6, gradient clipping to 1.0

![img_3.png](images/img_3.png)

![img_4.png](images/img_4.png)

![img_5.png](images/img_5.png)

<!-- [https://wandb.ai/yepster/EasyDeL-MistralBoreas/runs/ozw55qaq/workspace?nw=nwuseryepster](WandB Boreas 7B pre-train) -->


## Boreas-7B-chat

Het chat LLM model is net als het basismodel getraind op een mix van datasets, met een grootte van 4.7B tokens.
Het is een full finetune, dus geen LoRA finetune.

De volgende datasets zijn gemixt:

| Datasetnaam                                               | Gewicht | Percentage Tokens (%) |
|-----------------------------------------------------------|---------|-----------------------|
| (C) Diverse Engelse chat dataset (teknium/OpenHermes-2.5) | 200     | 45.15                 |
| (C) Vertaal en->nl paragrafen (romans)                    | 100     | 22.57                 |
| (C) Vertaal en->nl zinnen (romans)                        | 50      | 11.29                 |
| (P) Nederlandse wikipedia                                 | 30      | 6.77                  |
| (P) Engelse wiskunde en natuurkunde boeken                | 25      | 5.64                  |
| (C) Engelse instruct dataset (philschmid/flanv2)          | 20      | 4.51                  |
| (C) Nederlandse wiki q en a                               | 12      | 2.71                  |
| (C) Nederlandse schoolboeken q en a                       | 3       | 0.68                  |
| (P) Nederlandse schoolboeken                              | 2       | 0.45                  |
| (C) Vertaal en->nl uitdrukkingen (dictionary)             | 1       | 0.23                  |

(C) geeft aan dat de tekst geformatteerd is voor chat, (P) is ongeformatteerde tekst (gelijk aan de pre-train fase)

Het grootste gedeelte bestaat uit `teknium/OpenHermes-2.5` - wat op zichzelf ook weer een mengelmoes van diverse
gefilterde chat/instruct datasets is. Deze dataset bevat wel programmacode data, wat ertoe resulteert dat Boreas-7B-chat
wel in staat is om simpele programmavragen te beantwoorden.

De reden om zoveel Engels in de dataset te mixen, is met name om de diversiteit in de dataset zo hoog mogelijk te
krijgen, en omdat ik verwacht dat er een behoorlijke mate van cross language en naar nl knowledge transfer mogelijk is.
Het omgekeerde is zeker waar: als een fine-tune dataset niet divers is, zal het model door zijn fine-tuning niet in
staat zijn om zijn originele kunde uit te voeren. Een van de eerste Mistral finetunes die ik gemaakt heb was gefinetuned
op alleen en->nl vertalen. Dat model kon uiteindelijk niets anders meer dan vertalen naar Nederlands.

In tegenstelling tot het basismodel is het chat model _wel_ getrained op LLM-gegenereerde teksten - hierbij zijn de volgende
overwegingen van toepassing: Bij de Nederlandse gegenereerde chats heb ik wederom geprobeerd om zoveel mogelijk origineel
Nederlands taalgebruik te 'guiden' door alleen vragen en antwoorden te genereren op basis van teksten die origineel in
het Nederlands geschreven zijn door een persoon. Dit zijn de Nederlandse wiki q en a en Nederlandse schoolboeken q en a
chat datasets. Hierdoor wordt er zoveel mogelijk voor gezorgd dat bij bijvoorbeeld educatie-achtige q en a, de in onze
regio gebruikelijke termen en eenheden voorkomen in de chat database, tenminste voor de Nederlandstalige chats.

Bij alle chat datasets is er alleen getraind op de assistant-completion tokens.

## Fine-tuning

* Boreas was fine-tuned with the [EasyDeL JAX framework](https://github.com/erfanzar/EasyDel) on a tpu-v4-32
kindly supplied by the Google [TPU Research Cloud](https://sites.research.google/trc/about/).
* Batch size 96, gradient accumulation 2,
* Using flash attention, block size of 512
* Max sequence length of 2048
* LION optimizer, triangle learning rate schedule with max lr 2e-6, gradient clipping to 1.0 (NB: the schedule was not finished due to an error at the end of the dataset epoch. Since the loss had plateaued I decided then to not resume for another epoch)
  

![loss finetune](images/loss_finetune.png)

![accuracy finetune](images/accuracy_finetune.png)

![learning rate finetune](images/lr_finetune.png)

<!-- [https://wandb.ai/yepster/EasyDeL-MistralBoreas/runs/ynkl2jtx?nw=nwuseryepster](WandB Boreas 7B chat finetune) -->