Model Card
Una scheda del modello documenta l'uso previsto, i dati di addestramento, i risultati della valutazione e i limiti di un modello addestrato; è un formato proposto dai ricercatori di Google nel 2018.
Una scheda del modello è un breve documento pubblicato insieme a un modello di apprendimento automatico addestrato, che registra a cosa serve il modello, come è stato addestrato e valutato, come si comporta con gruppi e condizioni diversi e in quali casi fallisce. Margaret Mitchell, Timnit Gebru e colleghi di Google hanno proposto il formato nel 2018 nell'articolo Model Cards for Model Reporting, presentato alla conferenza FAT* 2019. Oggi le schede del modello sono una prassi standard per la trasparenza nell'IA: un repository di modelli su Hugging Face mostra la scheda del modello nella pagina principale, e i laboratori di IA pubblicano schede per le principali versioni, come la scheda del modello Claude 3 pubblicata da Anthropic nel 2024.
Cosa contiene una scheda del modello#
L'articolo originale proponeva nove sezioni:
- Dettagli del modello: sviluppatore, versione, data, architettura, licenza e contatti per le domande.
- Uso previsto: gli usi e gli utenti principali per cui il modello è stato sviluppato, nonché gli usi esclusi dal suo ambito.
- Fattori: gruppi, strumenti e ambienti che possono influire sulle prestazioni, come fascia d'età, tipo di telecamera o illuminazione.
- Metriche: quali metriche delle prestazioni vengono riportate, con quali soglie decisionali e perché sono state scelte.
- Dati di valutazione: i dataset usati per i test e i motivi della loro scelta.
- Dati di addestramento: i dati da cui il modello ha appreso, descritti con il massimo dettaglio possibile.
- Analisi quantitative: risultati suddivisi per ciascun fattore, singolarmente e in combinazione.
- Considerazioni etiche: dati sensibili, rischi per le persone e misure di mitigazione applicate.
- Avvertenze e raccomandazioni: lacune note, come condizioni mai sottoposte a test.
Le analisi quantitative sono il nucleo dell'idea. Un unico punteggio complessivo nasconde gli errori concentrati in un sottogruppo, quindi la scheda di esempio dell'articolo per un rilevatore di sorrisi addestrato sul dataset di volti CelebA riporta i tassi di errore separatamente per età e genere: questa valutazione disaggregata porta alla luce i bias algoritmici e i bias del dataset. Per un modello di rilevamento degli oggetti, la stessa sezione riporta la precisione media media (mAP) per classe e condizione, per esempio oggetti piccoli, immagini notturne o singole telecamere, insieme alla latenza di inferenza sull'hardware di destinazione.
Schede del modello su Hugging Face#
Su Hugging Face Hub, la scheda del modello è il README.md del repository: sezioni Markdown rivolte alle persone, precedute da un'intestazione di metadati YAML che Hub analizza per filtrare i modelli in base ad attività, licenza e dataset e per mostrare i risultati della valutazione. La libreria huggingface_hub genera entrambe le parti da dati strutturati:
from huggingface_hub import EvalResult, ModelCard, ModelCardData
from torchvision.models import ResNet50_Weights
# Torchvision include l'accuratezza pubblicata su ImageNet con ogni set di pesi
weights = ResNet50_Weights.IMAGENET1K_V2
top1 = weights.meta["_metrics"]["ImageNet-1K"]["acc@1"]
# Metadati leggibili automaticamente: libreria, dati di addestramento e risultati della valutazione
result = EvalResult(
task_type="image-classification",
dataset_type="imagenet-1k",
dataset_name="ImageNet-1K",
metric_type="accuracy",
metric_value=top1,
)
card_data = ModelCardData(
model_name="resnet50", library_name="torchvision", datasets=["imagenet-1k"], eval_results=[result]
)
# Compila il modello predefinito: un'intestazione YAML seguita da sezioni Markdown
card = ModelCard.from_template(card_data, model_summary="ResNet-50 image classifier trained on ImageNet-1K.")
print(card.data.to_yaml())
print([line[3:] for line in card.content.splitlines() if line.startswith("## ")])L'output YAML elenca il dataset di addestramento e un blocco model-index che registra un'accuratezza top-1 dell'80,858% su ImageNet-1K, visualizzata da Hub come risultato della valutazione. La seconda riga stampa le sezioni del modello, da Dettagli e usi del modello a Bias, rischi e limiti, fino a Valutazione e impatto ambientale: una diretta evoluzione delle nove sezioni dell'articolo originale.
Documentazione correlata#
- Schede informative dei dataset: proposte da Timnit Gebru e colleghi nel 2018, documentano come è stato raccolto ed etichettato un dataset e l'uso previsto. La scheda del modello rimanda alla scheda informativa dei dati di addestramento invece di ripeterne i contenuti.
- Schede di sistema: descrivono un sistema di IA distribuito composto da più modelli, prompt, filtri di sicurezza e processi umani. Meta ha introdotto il termine nel 2022 e oggi i laboratori che sviluppano modelli linguistici di grandi dimensioni (LLM), tra cui OpenAI, pubblicano una scheda di sistema a ogni rilascio di un modello principale.
- Registro dei modelli: archivia i file dei modelli, le versioni e la genealogia, mentre la scheda spiega per quali usi è adatta ciascuna versione registrata.
- IA spiegabile (XAI): spiega perché un modello ha generato una singola previsione, mentre una scheda descrive il comportamento su un intero set di valutazione.
La regolamentazione ha reso obbligatorio questo formato in alcuni contesti. Ai sensi dell'AI Act dell'UE, dal 2 agosto 2025 i fornitori di modelli di IA per finalità generali devono conservare la documentazione tecnica relativa all'addestramento e alla valutazione e fornire agli sviluppatori che basano i propri prodotti su questi modelli informazioni sulle capacità e sui limiti. Il Codice di buone pratiche della Commissione per l'IA per finalità generali include un modulo per la documentazione del modello, con campi simili a quelli di una scheda, come usi previsti, dati di addestramento e consumo energetico. Le schede fanno parte delle pratiche più ampie di governance dell'IA e IA responsabile.
Mantenere aggiornata una scheda#
Una scheda descrive una versione specifica del modello, quindi cambia ogni volta che cambiano il modello, i suoi dati o le condizioni di distribuzione. Il monitoraggio del modello in produzione fornisce le prove necessarie: il data drift o una nuova modalità di errore diventano un'avvertenza nella scheda della versione successiva.
Una parte della scheda può anche essere incorporata nel file del modello. Quando i modelli Ultralytics YOLO26 vengono esportati in formati come ONNX o OpenVINO, l'esportatore incorpora metadati con una descrizione che indica il dataset di addestramento, l'autore, la data di esportazione, la versione del pacchetto, la licenza, l'attività, le dimensioni dell'input e i nomi delle classi, così anche una copia distribuita continua a specificare cos'è e cosa rileva.










