Model Card
Um cartão de modelo documenta o uso previsto, os dados de treinamento, os resultados de avaliação e as limitações de um modelo treinado. O formato foi proposto por pesquisadores do Google em 2018.
Uma ficha de modelo é um documento breve publicado com um modelo de aprendizagem automática treinado, que regista a finalidade do modelo, a forma como foi treinado e avaliado, o seu desempenho com diferentes grupos e condições e as situações em que falha. Margaret Mitchell, Timnit Gebru e colegas da Google propuseram o formato em 2018, no artigo Model Cards for Model Reporting, apresentado na conferência FAT* 2019. As fichas de modelo são agora uma prática padrão de transparência em IA: o repositório de um modelo no Hugging Face mostra a respetiva ficha na página inicial, e os laboratórios de IA publicam fichas para lançamentos importantes, como a ficha de modelo do Claude 3 que a Anthropic publicou em 2024.
O que contém um cartão de modelo#
O artigo original propôs nove secções:
- Detalhes do modelo: Programador, versão, data, arquitetura, licença e contacto para perguntas.
- Utilização prevista: Os principais usos e utilizadores para os quais o modelo foi criado e os usos que estão fora do âmbito previsto.
- Fatores: Os grupos, instrumentos e ambientes que podem alterar o desempenho, como a faixa etária, o tipo de câmara ou a iluminação.
- Métricas: Que métricas de desempenho são apresentadas, com que limiares de decisão e por que motivo foram escolhidas.
- Dados de avaliação: Os conjuntos de dados usados nos testes e os motivos da sua escolha.
- Dados de treino: Os dados a partir dos quais o modelo aprendeu, descritos com o máximo de detalhe que possa ser partilhado.
- Análises quantitativas: Resultados discriminados por cada fator, individualmente e em combinação.
- Considerações éticas: Dados sensíveis, riscos para as pessoas e medidas de mitigação aplicadas.
- Ressalvas e recomendações: Lacunas conhecidas, como condições que nunca foram testadas.
As análises quantitativas são a essência da ideia. Uma única pontuação de destaque oculta falhas concentradas num subgrupo, por isso o exemplo de ficha do artigo, para um detetor de sorrisos treinado no conjunto de dados faciais CelebA, apresenta taxas de erro discriminadas por idade e género; esta avaliação desagregada revela o enviesamento algorítmico e o enviesamento do conjunto de dados. Para um modelo de deteção de objetos, a mesma secção apresenta a precisão média média (mAP) por classe e condição, como objetos pequenos, imagens noturnas ou cada câmara, juntamente com a latência de inferência no hardware de destino.
Fichas de modelo no Hugging Face#
No Hugging Face Hub, uma ficha de modelo é o README.md do repositório: secções Markdown para as pessoas, sob um cabeçalho de metadados YAML que o Hub analisa para filtrar modelos por tarefa, licença e conjunto de dados, e apresentar resultados de avaliação. A biblioteca huggingface_hub cria ambas as partes a partir de dados estruturados:
from huggingface_hub import EvalResult, ModelCard, ModelCardData
from torchvision.models import ResNet50_Weights
# O Torchvision inclui a precisão publicada no ImageNet com cada conjunto de pesos
weights = ResNet50_Weights.IMAGENET1K_V2
top1 = weights.meta["_metrics"]["ImageNet-1K"]["acc@1"]
# Metadados legíveis por máquina: biblioteca, dados de treino e resultados da avaliação
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]
)
# Preencher o modelo predefinido: um cabeçalho YAML seguido de secções 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("## ")])O resultado YAML lista o conjunto de dados de treino e um bloco model-index que regista uma precisão top-1 de 80,858% no ImageNet-1K, que o Hub apresenta como resultado de avaliação. A segunda linha imprime as secções do modelo, de Detalhes do Modelo e Usos a Enviesamento, Riscos e Limitações, passando por Avaliação e Impacto Ambiental; é um descendente direto das nove secções do artigo original.
Documentação relacionada#
- Folhas de dados para conjuntos de dados: Propostas por Timnit Gebru e colegas em 2018, documentam como um conjunto de dados foi recolhido e rotulado, e para que finalidade se destinava. Em vez de repetir essas informações, uma ficha de modelo remete para a folha de dados do respetivo conjunto de dados de treino.
- Fichas de sistema: Descrevem um sistema de IA implementado, composto por vários modelos, prompts, filtros de segurança e processos humanos. A Meta introduziu o termo em 2022, e os laboratórios que desenvolvem modelos de linguagem grandes (LLMs), incluindo a OpenAI, publicam agora uma ficha de sistema com cada lançamento importante de modelo.
- Registo de modelos: Armazena ficheiros de modelos, versões e linhagem, enquanto a ficha explica para que serve cada versão registada.
- IA explicável (XAI): Explica por que motivo um modelo fez uma previsão específica, enquanto uma ficha descreve o comportamento em todo um conjunto de avaliação.
A regulamentação tornou o formato obrigatório em alguns contextos. Ao abrigo do Regulamento da UE relativo à IA, desde 2 de agosto de 2025, os fornecedores de modelos de IA de finalidade geral têm de manter documentação técnica sobre o treino e a avaliação e fornecer aos programadores que desenvolvem com os seus modelos informações sobre capacidades e limitações. O Código de Prática da Comissão para a IA de Finalidade Geral inclui um Formulário de Documentação do Modelo para esse fim, com campos semelhantes aos de uma ficha, como utilizações previstas, dados de treino e consumo de energia. As fichas fazem parte das práticas mais amplas de governação da IA e IA responsável.
Manter uma ficha atualizada#
Uma ficha descreve uma versão específica do modelo, pelo que muda sempre que o modelo, os respetivos dados ou as condições de implementação mudam. A monitorização de modelos em produção fornece os dados necessários: o desvio de dados ou um novo modo de falha passa a ser uma ressalva na ficha da versão seguinte.
Parte de uma ficha também pode ser incorporada no ficheiro do modelo. Quando os modelos Ultralytics YOLO26 são exportados para formatos como ONNX ou OpenVINO, o exportador incorpora metadados com uma descrição que identifica o conjunto de dados de treino, o autor, a data de exportação, a versão do pacote, a licença, a tarefa, o tamanho da entrada e os nomes das classes, para que uma cópia implementada continue a identificar o que é e o que deteta.










