Cartões de Modelo

O que são Model Cards?

Model cards são arquivos que acompanham os modelos e fornecem informações úteis. Por baixo dos panos, model cards são arquivos Markdown simples com metadados adicionais. Model cards são essenciais para descoberta, reprodutibilidade e compartilhamento! Você pode encontrar um model card como o arquivo README.md em qualquer repositório de modelo.

O cartão do modelo deve descrever:

• o modelo
• seus usos pretendidos & potenciais limitações, incluindo vieses e considerações éticas, conforme detalhado em Mitchell, 2018
• os parâmetros de treinamento e as informações experimentais (você pode incorporar ou linkar para uma plataforma de rastreamento de experimentos para referência)
• quais conjuntos de dados foram usados para treinar seu modelo
• os resultados de avaliação do modelo

O modelo de cartão do modelo está disponível aqui.

Como preencher cada seção do model card é descrito em the Annotated Model Card.

Os Model Cards no Hub têm duas partes principais, com informações sobrepostas:

• Metadados
• Descrições de texto

Metadados do cartão do modelo

Um repositório de modelo renderiza seu README.md como um cartão de modelo. O cartão de modelo é um arquivo Markdown, com uma seção YAML no topo que contém metadados sobre o modelo.

Os metadados que você adiciona ao cartão do modelo suportam a descoberta e o uso mais fácil do seu modelo. Por exemplo:

• Permitir que os usuários filtrem modelos em https://huggingface.co/models.
• Exibindo a licença do modelo.
• Adicionar conjuntos de dados aos metadados incluirá uma mensagem com o texto Datasets used to train: na página do seu modelo e vinculará os conjuntos de dados relevantes, caso estejam disponíveis no Hub.

Os identificadores de conjunto de dados e de idioma são aqueles listados nas páginas Datasets e Languages.

Adicionando metadados ao seu cartão de modelo

Existem algumas maneiras diferentes de adicionar metadados ao seu model card, incluindo:

• Usando a interface de metadados
• Editando diretamente a seção YAML do arquivo README.md
• Por meio da biblioteca Python huggingface_hub, consulte a documentação para mais detalhes.

Muitas bibliotecas com integração com o Hub adicionam automaticamente metadados ao cartão do modelo quando você faz o upload de um modelo.

Usando a interface de metadados

Você pode adicionar metadados ao seu model card usando a interface de metadados. Para acessar a interface de metadados, vá para a página do modelo e clique no botão Edit model card no canto superior direito do model card. Isso abrirá um editor exibindo o arquivo README.md do model card, bem como uma interface para editar os metadados.

Esta interface permitirá adicionar metadados-chave ao seu model card e muitos dos campos serão preenchidos automaticamente com base nas informações que você fornecer. Usar a interface é a maneira mais fácil de adicionar metadados ao seu model card, mas ela não suporta todos os campos de metadados. Se você quiser adicionar metadados que não são suportados pela interface, pode editar diretamente a seção YAML do arquivo README.md.

Editando a seção YAML do arquivo README.md

Você também pode editar diretamente a seção YAML do arquivo README.md. Se o cartão do modelo ainda não tiver uma seção YAML, você pode adicionar uma inserindo três --- no topo do arquivo, incluindo todos os metadados relevantes e fechando a seção com outro grupo de ---, como no exemplo abaixo:

---
language: 
  - "List of ISO 639-1 code for your language"
  - lang1
  - lang2
thumbnail: "url to a thumbnail used in social sharing"
tags:
- tag1
- tag2
license: "any valid license identifier"
datasets:
- dataset1
- dataset2
base_model: "base model Hub identifier"
---

Você pode encontrar a especificação detalhada dos metadados do cartão do modelo aqui.

Especificando uma biblioteca

Você pode especificar as bibliotecas suportadas na seção de metadados do cartão do modelo. Encontre mais informações sobre as bibliotecas suportadas aqui. A biblioteca será especificada na seguinte ordem de prioridade:

1. Especificar library_name no cartão do modelo (recomendado se o seu modelo não for um modelo transformers). Essas informações podem ser adicionadas pela interface de metadados ou diretamente na seção YAML do cartão do modelo:

library_name: flair

2. Ter uma tag com o nome de uma biblioteca que é suportada

tags:
- flair

Se não for especificado, o Hub tentará detectar automaticamente o tipo de biblioteca. No entanto, essa abordagem é desencorajada, e os criadores de repositórios devem usar o library_name explícito sempre que possível.

1. Ao verificar a presença de arquivos como *.nemo ou *.mlmodel, o Hub pode determinar se um modelo é do NeMo ou do CoreML.
2. No passado, se nada fosse detectado e houvesse um arquivo config.json, assumia-se que a biblioteca era transformers. Para repositórios de modelos criados após agosto de 2024, isso não é mais o caso, portanto você precisa definir library_name: transformers explicitamente.

Especificando um modelo base

Se o seu modelo for um fine-tune, um adapter ou uma versão quantizada de um modelo base, você pode especificar o modelo base na seção de metadados do model card. Essas informações também podem ser usadas para indicar se o seu modelo é uma mesclagem de vários modelos existentes. Portanto, o campo base_model pode ser um único ID de modelo ou uma lista de um ou mais base_models (especificados por seus identificadores no Hub).

base_model: HuggingFaceH4/zephyr-7b-beta

Esses metadados serão usados para exibir o modelo base na página do modelo. Os usuários também podem usar essas informações para filtrar modelos por modelo base ou encontrar modelos derivados de um modelo base específico:

Para um modelo ajustado:

Para um adaptador (LoRA, PEFT, etc.):

Para uma versão quantizada de outro modelo:

Para uma mesclagem de dois ou mais modelos:

No caso de mesclagem, você especifica uma lista de dois ou mais base_models:

base_model:
- Endevor/InfinityRP-v1-7B
- l3utterfly/mistral-7b-v0.1-layla-v4

O Hub inferirá o tipo de relação do modelo atual em relação ao modelo base ("adapter", "merge", "quantized", "finetune"), mas você também pode defini-lo explicitamente, se necessário: por exemplo, base_model_relation: quantized.

Especificando uma nova versão

Se uma nova versão do seu modelo estiver disponível no Hub, você pode especificá-la em um campo new_version.

Por exemplo, em l3utterfly/mistral-7b-v0.1-layla-v3:

new_version: l3utterfly/mistral-7b-v0.1-layla-v4

Esses metadados serão usados para exibir um link para a versão mais recente de um modelo na página do modelo. Se o modelo vinculado em new_version também tiver um campo new_version, a versão mais recente será sempre exibida.

Especificando um conjunto de dados

Você pode especificar os conjuntos de dados usados para treinar seu modelo na seção de metadados do cartão do modelo. Os conjuntos de dados serão exibidos na página do modelo e os usuários poderão filtrar modelos por conjunto de dados. Você deve usar o identificador do conjunto de dados do Hub, que é o mesmo que o nome do repositório do conjunto de dados, como identificador:

datasets:
- stanfordnlp/imdb
- HuggingFaceFW/fineweb

Especificando um bucket

Você pode especificar os storage buckets vinculados ao seu modelo na seção de metadados do model card. Os buckets serão exibidos como tags na página do modelo e as páginas dos buckets vinculados mostrarão o modelo em contrapartida. Você deve usar o identificador de bucket do Hub, que é o mesmo que o nome do repositório do bucket:

buckets:
- my-org/my-bucket
- my-org/another-bucket

Especificando uma tarefa ( pipeline_tag )

Você pode especificar o pipeline_tag nos metadados do cartão do modelo. O pipeline_tag indica o tipo de tarefa para a qual o modelo foi projetado. Essa tag será exibida na página do modelo e os usuários podem filtrar modelos no Hub por tarefa. Essa tag também é usada para determinar qual widget usar para o modelo e quais APIs usar por baixo dos panos.

Para modelos do transformers, a tag de pipeline é inferida automaticamente a partir do arquivo config.json do modelo, mas você pode sobrescrevê-la nos metadados do cartão do modelo, se necessário. Editar esse campo na interface de metadados garante que a tag de pipeline seja válida. Outras bibliotecas com integração ao Hub também adicionam automaticamente a tag de pipeline aos metadados do cartão do modelo.

Especificando uma licença

Você pode especificar a licença na seção de metadados do cartão do modelo. A licença será exibida na página do modelo e os usuários poderão filtrar modelos por licença. Ao usar a interface de metadados, você verá uma lista suspensa com as licenças mais comuns.

Se necessário, você também pode especificar uma licença personalizada adicionando other como o valor da licença e especificando o nome e um link para a licença nos metadados.

# Example from https://huggingface.co/coqui/XTTS-v1
---
license: other
license_name: coqui-public-model-license
license_link: https://coqui.ai/cpml
---

Se a licença não estiver disponível por meio de uma URL, você pode fazer um link para um arquivo LICENSE armazenado no repositório do modelo.

Resultados da Avaliação

Você pode especificar os resultados de avaliação do seu modelo de forma estruturada nos metadados do cartão do modelo. Os resultados são analisados pelo Hub e exibidos em um widget na página do modelo. Aqui está um exemplo de como fica para o modelo bigcode/starcoder:

A especificação inicial de metadados foi baseada na especificação model-index do Papers with code. Isso nos permitiu indexar diretamente os resultados nos rankings do Papers with code quando apropriado. Também era possível vincular a fonte de onde os resultados de avaliação foram calculados.

NOVO: Temos um novo formato de metadados mais simples para resultados de avaliação. Confira em a página de documentação dedicada.

Aqui está um exemplo parcial de um model-index que descrevia a pontuação de 01-ai/Yi-34B no benchmark ARC. O resultado veio do Open LLM Leaderboard, que é definido como a source:

---
model-index:
  - name: Yi-34B
    results:
      - task:
          type: text-generation
        dataset:
          name: ai2_arc
          type: ai2_arc
        metrics:
          - name: AI2 Reasoning Challenge (25-Shot)
            type: AI2 Reasoning Challenge (25-Shot)
            value: 64.59
        source:
          name: Open LLM Leaderboard
          url: https://huggingface.co/spaces/open-llm-leaderboard/open_llm_leaderboard
---

Para mais detalhes sobre como formatar esses dados, consulte as especificações do Model Card.

Emissões de CO2

O cartão do modelo também é um ótimo lugar para exibir informações sobre o impacto de CO₂ do seu modelo. Visite nosso guia sobre rastreamento e relatórios de emissões de CO₂ para saber mais.

Vinculando um Artigo

Se o cartão do modelo incluir um link para uma página de Paper (seja no HF ou um resumo/PDF do Arxiv), o Hugging Face Hub extrairá o ID do arXiv e o incluirá nas tags do modelo com o formato arxiv:<PAPER ID>. Clicar na tag permitirá que você:

• Acesse a página do Paper
• Filtre por outros modelos no Hub que citam o mesmo artigo.

Saiba mais sobre as páginas de Paper aqui.

Texto do Model Card

Os detalhes sobre como preencher a parte legível por humanos do cartão do modelo (para que ele possa ser impresso, cortado e colado, etc.) estão disponíveis no Cartão de Modelo Anotado.

Perguntas frequentes

Como as tags de modelo são determinadas?

Cada página de modelo lista todas as tags do modelo no cabeçalho da página, abaixo do nome do modelo. Essas tags são calculadas principalmente a partir dos metadados do cartão do modelo, embora algumas sejam adicionadas automaticamente, conforme descrito em Enabling a Widget.

Posso adicionar tags personalizadas ao meu modelo?

Sim, você pode adicionar tags personalizadas ao seu modelo incluíndo-as no campo tags dos metadados do cartão do modelo. A interface de metadados sugerirá algumas tags populares, mas você pode adicionar qualquer tag que desejar. Por exemplo, você pode indicar que seu modelo é focado em finanças adicionando a tag finance.

Como posso indicar que meu modelo não é adequado para todos os públicos

Você pode adicionar a tag not-for-all-audiences aos metadados do seu model card. Quando essa tag está presente, uma mensagem será exibida na página do modelo indicando que o modelo não é para todos os públicos. Os usuários podem clicar nessa mensagem para visualizar o model card.

Como posso exibir imagens diferentes para o modo escuro e o modo claro?

Você pode exibir diferentes versões de uma imagem otimizadas para cada tema. Isso é particularmente útil para logotipos, diagramas ou capturas de tela que precisam de esquemas de cores diferentes para manter a visibilidade e a estética nos modos claro e escuro. Para usar esse recurso, você precisará fornecer ambas as versões da sua imagem.

Para imagens enviadas por meio do editor de markdown

Ao enviar uma imagem diretamente do editor de markdown (usando arrastar e soltar), acrescente o fragmento de URI #hf-light-mode-only ou #hf-dark-mode-only ao final da URL da imagem para especificar em qual tema ela deve ser exibida:

Image only displays when viewing in light mode
![Logo](https://cdn-uploads.huggingface.co/production/uploads/logo-light.png#hf-light-mode-only)

Image only displays when viewing in dark mode
![Logo](https://cdn-uploads.huggingface.co/production/uploads/logo-dark.png#hf-dark-mode-only)

Para imagens já hospedadas

Se você quiser referenciar imagens que já estão hospedadas sem reenviá-las, use as tags HTML <img> com as seguintes classes do Tailwind CSS para especificar em qual tema elas devem ser exibidas:

// Image only displays when viewing in dark mode
<img class="hidden dark:block" src="https://hf.co/logo-dark.png" alt="Logo" />

// Image only displays when viewing in light mode
<img class="dark:hidden" src="https://hf.co/logo-light.png" alt="Logo" />

Posso escrever LaTeX no meu cartão de modelo?

Sim! O Hub usa a biblioteca de formatação matemática KaTeX para renderizar fórmulas matemáticas no servidor antes de analisar o Markdown.

Você deve usar os seguintes delimitadores:

• $$ ... $$ para o modo de exibição
• \\(...\\) para o modo inline (sem espaço entre as barras e o parêntese).

Em seguida, você poderá escrever: $$\LaTeX$$ $$\mathrm{MSE} = \left(\frac{1}{n}\right)\sum_{i=1}^{n}(y_{i} - x_{i})^{2}$$ $$E=mc^2$$