LLM Eval Harness — Framework Python open source per valutare gli LLM

LLM Eval Harness: il framework open source per valutare le risposte degli LLM

llm-eval-harness è un progetto open source firmato Innova: un framework Python leggero per costruire suite di test sulle risposte dei modelli linguistici e integrarle in qualsiasi pipeline CI/CD. Niente vendor lock-in, nessuna API key obbligatoria, una sola dipendenza nel core. Si descrive così, in una riga: “A tiny, dependency-light harness for evaluating LLM outputs with pluggable graders — runs fully offline, no API key required”.

Nasce da una domanda banale che però chiunque costruisce qualcosa sopra un modello linguistico ha già sentito mille volte: “il modello ha fatto davvero quello che gli ho chiesto?”. La differenza tra un prototipo divertente e un sistema su cui un cliente fattura è poter rispondere a quella domanda in modo automatico, ripetibile, e prima del deploy in produzione.

Il problema dietro al progetto

Negli ultimi due anni, la maggior parte dei progetti AI commerciali si è poggiata su prompt che “sembrano funzionare”. Si testa a mano, si fanno tre chiamate di prova, si screenshotta una risposta convincente in chat e si va live. Funziona finché non funziona: appena cambia il modello sotto (versione, provider, parametro temperature), o appena arriva un caso d’uso che non era nel test mentale dello sviluppatore, il sistema produce output sbagliati in produzione e nessuno se ne accorge se non quando un cliente si lamenta.

La risposta seria a questo problema esiste da un decennio nel software tradizionale e si chiama test suite. Per gli LLM serviva qualcosa di analogo, ma con una differenza fondamentale: i test su un LLM non sono booleani. Una risposta può essere “abbastanza buona”, “perfetta”, “tecnicamente corretta ma con tono sbagliato”. Servono valutatori — graders — diversi, componibili, e un orchestratore che li metta in fila e dia un verdetto leggibile.

Cosa fa llm-eval-harness

Si definiscono le suite di test in YAML dichiarativo: prompt, modello atteso, graders da applicare, soglia di passaggio. Il runner esegue ogni test contro un provider (mock per sviluppo offline, OpenAI o Anthropic per produzione), applica i graders e produce un report leggibile in tre formati: console colorato per il dev locale, Markdown per i commenti automatici nelle pull request, JSON per il diffing tra run.

L’output di esempio dice tutto:

capital_france [PASS] score=1.00
capital_japan  [PASS] score=1.00
capital_australia [FAIL] score=0.00
  ↳ contains: expected to contain 'Canberra'
  ↳ not_contains: found forbidden: ['Sydney']

5/6 passed (83%) mean score 0.83

È esattamente il livello di feedback che serve in una pipeline: secco, machine-readable, copia-incollabile in un commento di PR.

Sei graders built-in, infiniti graders custom

Il framework arriva con sei valutatori pronti all’uso:

• contains e not_contains — controllo su parole/frasi attese o vietate nella risposta
• exact_match — pattern di confronto esatto, utile per estrazioni strutturate
• regex — controllo via espressione regolare
• llm_judge — un secondo modello che valuta la risposta del primo secondo una rubric configurabile (LLM-as-judge)

Aggiungerne uno nuovo richiede un decorator e una funzione Python di poche righe: il registry plug-and-play permette di estendere il framework con grader semantici, validazioni JSON-schema, embedding similarity — qualsiasi metrica che lo specifico dominio richieda.

Multi-provider, multi-modello, offline-friendly

L’interfaccia unificata complete() astrae i provider sottostanti: lo stesso file YAML può essere eseguito su OpenAI (gpt-4o, gpt-4o-mini), su Anthropic (Claude, Haiku), o sul mock provider offline che ritorna risposte prevedibili per testare la pipeline senza spendere un centesimo di token.

È esattamente lo strumento che serve per due scenari quotidiani in agenzia. Primo: uno sviluppatore clona il repo, lancia llm-eval examples/capitals.yaml --provider=mock e capisce in 30 secondi come funziona, senza dover prima generare un’API key. Secondo: in un workflow CI/CD, il framework viene eseguito a ogni commit contro OpenAI o Anthropic, e blocca il merge se uno dei test critici fallisce. Exit code non-zero, niente sorprese in produzione.

Perché Innova ha costruito questo strumento

Sviluppiamo sempre più progetti sopra LLM — chatbot, sistemi di automazione, classificazione documentale, generazione contenuti per e-commerce. Avevamo bisogno di un modo serio per misurare la qualità delle risposte prima di consegnarle ai clienti, di non dover dipendere da SDK proprietari o piattaforme cloud chiuse, e di poter integrare la valutazione nei processi CI/CD che già usiamo per il software tradizionale.

Rilasciarlo open source con licenza MIT è stata una scelta naturale. Il codice che usiamo internamente per validare i nostri progetti è lo stesso che può aiutare un altro team a fare lo stesso lavoro — senza farsi vendere una soluzione enterprise da migliaia di euro al mese per qualcosa che, ben fatto, sta in poche centinaia di righe di Python.

A chi serve davvero

• ML engineer e prompt engineer che devono misurare la qualità degli output e non solo l’intuizione
• Sviluppatori di chatbot e assistenti AI che vogliono test di regressione veri sui propri prompt
• Agenzie e consulenti AI che devono certificare qualità di delivery prima del deploy in produzione
• Team DevOps che gestiscono pipeline CI/CD e vogliono includere i test LLM tra i gate di rilascio
• Ricercatori e curiosi che vogliono fare benchmark veloci contro modelli diversi senza setup pesanti

Roadmap aperta

Il progetto è giovane e dichiaratamente in fase beta. La direzione di crescita prevede esecuzione asincrona per parallelizzare i test su batch grandi, nuovi graders (JSON-schema, similarità semantica via embeddings), report HTML interattivo, e pubblicazione su PyPI per installazione via pip install. Tutti benvenuti a contribuire via pull request, con un solo principio guida: resta semplice, resta leggero, resta utile.

L’AI come strumento, non come marketing

In Innova non vendiamo “AI” come categoria astratta. Vendiamo sistemi che usano gli strumenti AI dove servono davvero, misurati per quello che producono. llm-eval-harness è la prova tangibile di come affrontiamo questo lavoro: con strumenti propri, codice aperto, e l’abitudine di automatizzare quello che si può automatizzare.

Per chi vuole vederlo da vicino: il repository è pubblico su GitHub, completamente documentato, con suite di esempio già pronte e una CI che gira su Python 3.10–3.12. Forkare, clonare, contribuire — il vantaggio dell’open source è esattamente questo.