Eines d'avaluació de models LLM i ASR

Aquest repositori conté eines per avaluar les capacitats de models de llenguatge gran (LLM) i de reconeixement automàtic de la parla (ASR), amb focus especial en la llengua catalana. Els resultats estan compartits a https://www.softcatala.org/la-intelligencia-artificial-al-vostre-ordinador-personal/models-dintelligencia-artificial-en-catala-per-usar-en-local/

Estructura del projecte

ai-eval-catalan/
├── render_bar_charts.py      # Genera gràfics de barres HTML
├── render_tables.py          # Genera taules HTML de resultats
├── bar_chart_template.jinja  # Plantilla per als gràfics de barres
├── llm/                      # Avaluació de models LLM
│   ├── model.py              # Pipeline d'avaluació per a un model
│   ├── run_evals.py          # Orquestrador per executar múltiples models
│   ├── summarize_results.py  # Genera el JSON i HTML de resultats
│   ├── table_template.jinja  # Plantilla per a la taula de resultats
│   └── evals/                # Resultats JSON per model
├── asr/                      # Avaluació de models ASR
│   ├── hf-eval.py            # Avaluació de WER/CER sobre FLEURS
│   ├── run_evals.py          # Orquestrador per executar múltiples models
│   ├── summarize_results.py  # Genera el JSON i HTML de resultats
│   ├── table_template.jinja  # Plantilla per a la taula de resultats
│   └── evals/                # Resultats JSON per model
└── mt/                       # Avaluació de traducció automàtica
    └── mt.py                 # Avaluació de models MT

---

Publicació automàtica de resultats (CI/CD)

Quan es fa un push a qualsevol branca, el workflow de GitHub Actions .github/workflows/publish-llms-json.yml executa automàticament els passos següents:

1. Genera els fitxers de dades a partir dels resultats JSON individuals de llm/evals/ i asr/evals/:

   • llm/summarize_results.py → llm/llms.json
   • asr/summarize_results.py → asr/asrs.json

2. Genera els fitxers HTML de taules i gràfics de barres:

   • render_tables.py → llm/llms_table.html, asr/asrs_table.html
   • render_bar_charts.py → llm/llms_bar.html, asr/asrs_bar.html

3. Puja els fitxers a la branca prod-data, que actua com a repositori de dades en producció:

   prod-data/
   ├── llms.json
   ├── llms_table.html
   ├── llms_bar.html
   ├── asrs.json
   ├── asrs_table.html
   └── asrs_bar.html
   

La web de Softcatalà llegeix directament els fitxers de la branca prod-data per mostrar els resultats actualitzats.

---

LLM — Avaluació de models de llenguatge

El pipeline llm/model.py avalua models GGUF (via llama-server) i models de l'API de Google AI (Gemini/Gemma) sobre benchmarks de català:

Benchmark	Tasca	Mètrica
VeritasQA	Preguntes obertes en català	Accuracy
STS-ca	Similitud semàntica de frases	Correlació de Pearson
CatCoLA	Acceptabilitat gramatical	MCC
CLUB / VilaQuAD	Comprensió lectora i QA	Exact Match
CaSum	Resum de notícies en català	ROUGE-1/2/L
IberBench	Múltiples tasques NLP (via lm-eval)	Diverses
FLORES+	Traducció automàtica EN↔CA	BLEU

Instal·lació (LLM)

Requereix uv i llama.cpp (el binari llama-server ha d'estar disponible al PATH).

cd llm
uv sync

Execució (LLM)

Avaluar un sol model GGUF:

cd llm
uv run python model.py --model "bartowski/Llama-3.2-3B-Instruct-GGUF:Q8_0" --device cuda

Avaluar amb l'API de Google AI (Gemma/Gemini):

uv run python model.py --model gemini --api-key "LA_TEVA_CLAU" --gemini-model gemma-3-27b-it

Avaluar benchmarks específics:

uv run python model.py --model "bartowski/Llama-3.2-3B-Instruct-GGUF:Q8_0" --benchmarks catcola flores

Executar tots els models de la llista (orquestrador):

uv run python run_evals.py
uv run python run_evals.py --n-samples 200
uv run python run_evals.py --benchmarks catcola flores

Els resultats es desen com a JSON a llm/evals/.

---

ASR — Avaluació de models de reconeixement de la parla

L'script asr/hf-eval.py mesura la taxa d'error de paraules (WER) i de caràcters (CER) sobre el dataset FLEURS per al català. Suporta models Omnilingual ASR i OpenAI Whisper.

Instal·lació (ASR)

Requereix uv.

cd asr
uv init
uv add torch torchaudio transformers datasets jiwer tqdm numpy

Si vols avaluar models Omnilingual ASR, instal·la també:

uv add omnilingual-asr

Execució (ASR)

Llistar els models disponibles:

uv run python hf-eval.py --list-models

Avaluar un o més models:

uv run python hf-eval.py whisper-large-v3 --device cuda --num_samples 500
uv run python hf-eval.py whisper-small omniASR_CTC_300M --output results.csv

---

Agraïments

Volem expressar el nostre agraïment als proveïdors dels datasets usats en l'avaluació:

• Projecte AINA (Barcelona Supercomputing Center) pels datasets VeritasQA, STS-ca, VilaQuAD i CaSum, que han fet possible l'avaluació de models en català.
• nbel pel dataset CatCoLA, corpus d'acceptabilitat lingüística en català.
• Google pel dataset FLEURS (Few-shot Learning Evaluation of Universal Representations of Speech), usat per avaluar models ASR en català.
• IberBench i l'equip de lm-evaluation-harness pels benchmarks de tasques NLP per al català.
• Meta AI pel benchmark FLORES+ de traducció automàtica.