Criar e compartilhar Model Cards

A biblioteca huggingface_hub fornece uma interface em Python para criar, compartilhar e atualizar Model Cards. Acesse a página de documentação dedicada para uma visão mais aprofundada do que são os Model Cards no Hub e como funcionam por baixo dos panos.

Carregar um Model Card do Hub

Para carregar um card existente do Hub, você pode usar a função ModelCard.load(). Aqui, carregaremos o card de nateraw/vit-base-beans.

from huggingface_hub import ModelCard

card = ModelCard.load('nateraw/vit-base-beans')

Este cartão possui alguns atributos úteis que você pode querer acessar/aproveitar:

card.data: Retorna uma instância de ModelCardData com os metadados do cartão do modelo. Chame .to_dict() nesta instância para obter a representação como um dicionário.
card.text: Retorna o texto do card, excluindo o cabeçalho de metadados.
card.content: Retorna o conteúdo de texto do card, incluindo o cabeçalho de metadados.

Criar Model Cards

De Texto

Para inicializar um Model Card a partir de texto, basta passar o conteúdo de texto do card para o ModelCard na inicialização.

content = """
---
language: en
license: mit
---

# My Model Card
"""

card = ModelCard(content)
card.data.to_dict() == {'language': 'en', 'license': 'mit'}  # True

Outra forma de fazer isso é com f-strings. No exemplo a seguir, nós:

Use ModelCardData.to_yaml() para converter os metadados que definimos em YAML, para que possamos usá-lo para inserir o bloco YAML no cartão do modelo.
Mostre como você pode usar uma variável de template por meio de f-strings do Python.

card_data = ModelCardData(language='en', license='mit', library='timm')

example_template_var = 'nateraw'
content = f"""
---
{ card_data.to_yaml() }
---

# My Model Card

This model created by [@{example_template_var}](https://github.com/{example_template_var})
"""

card = ModelCard(content)
print(card)

O exemplo acima nos deixaria com um cartão que se parece com este:

---
language: en
license: mit
library: timm
---

# My Model Card

This model created by [@nateraw](https://github.com/nateraw)

De um modelo Jinja

Se você tiver o Jinja2 instalado, pode criar Model Cards a partir de um arquivo de template jinja. Veja um exemplo básico:

from pathlib import Path

from huggingface_hub import ModelCard, ModelCardData

# Define your jinja template
template_text = """
---
{{ card_data }}
---

# Model Card for MyCoolModel

This model does this and that.

This model was created by [@{{ author }}](https://hf.co/{{author}}).
""".strip()

# Write the template to a file
Path('custom_template.md').write_text(template_text)

# Define card metadata
card_data = ModelCardData(language='en', license='mit', library_name='keras')

# Create card from template, passing it any jinja template variables you want.
# In our case, we'll pass author
card = ModelCard.from_template(card_data, template_path='custom_template.md', author='nateraw')
card.save('my_model_card_1.md')
print(card)

O markdown do cartão resultante é assim:

---
language: en
license: mit
library_name: keras
---

# Model Card for MyCoolModel

This model does this and that.

This model was created by [@nateraw](https://hf.co/nateraw).

Se você atualizar qualquer card.data, a alteração será refletida no próprio card.

card.data.library_name = 'timm'
card.data.language = 'fr'
card.data.license = 'apache-2.0'
print(card)

Agora, como você pode ver, o cabeçalho de metadados foi atualizado:

---
language: fr
license: apache-2.0
library_name: timm
---

# Model Card for MyCoolModel

This model does this and that.

This model was created by [@nateraw](https://hf.co/nateraw).

Ao atualizar os dados do card, você pode validar se o card ainda é válido em relação ao Hub chamando ModelCard.validate(). Isso garante que o card passe por todas as regras de validação configuradas no Hugging Face Hub.

Do Modelo Padrão

Em vez de usar seu próprio modelo, você também pode usar o modelo padrão, que é um cartão de modelo completo com muitas seções que você pode preencher. Internamente, ele usa Jinja2 para preencher um arquivo de modelo.

Observe que você precisará ter o Jinja2 instalado para usar from_template. Você pode fazer isso com pip install Jinja2.

card_data = ModelCardData(language='en', license='mit', library_name='keras')
card = ModelCard.from_template(
    card_data,
    model_id='my-cool-model',
    model_description="this model does this and that",
    developers="Nate Raw",
    repo="https://github.com/huggingface/huggingface_hub",
)
card.save('my_model_card_2.md')
print(card)

Compartilhar Model Cards

Se você estiver autenticado no Hugging Face Hub (seja usando hf auth login ou login()), você pode enviar cards para o Hub simplesmente chamando ModelCard.push_to_hub(). Vamos dar uma olhada em como fazer isso…

Primeiro, criaremos um novo repositório chamado ‘hf-hub-modelcards-pr-test’ no namespace do usuário autenticado:

from huggingface_hub import whoami, create_repo

user = whoami()['name']
repo_id = f'{user}/hf-hub-modelcards-pr-test'
url = create_repo(repo_id, exist_ok=True)

Em seguida, criaremos um card a partir do modelo padrão (o mesmo definido na seção acima):

card_data = ModelCardData(language='en', license='mit', library_name='keras')
card = ModelCard.from_template(
    card_data,
    model_id='my-cool-model',
    model_description="this model does this and that",
    developers="Nate Raw",
    repo="https://github.com/huggingface/huggingface_hub",
)

Por fim, enviaremos isso para o hub

card.push_to_hub(repo_id)

Você pode conferir o card resultante aqui.

Se você preferir enviar um card como uma pull request, basta dizer create_pr=True ao chamar push_to_hub:

card.push_to_hub(repo_id, create_pr=True)

Um PR resultante criado a partir deste comando pode ser visto aqui.

Atualizar metadados

Nesta seção, veremos quais são os metadados nos cartões de repositório e como atualizá-los.

metadata refere-se a um mapa de hashes (ou contexto de chave-valor) que fornece informações de alto nível sobre um modelo, dataset ou Space. Essas informações podem incluir detalhes como o pipeline type, model_id ou model_description do modelo. Para mais detalhes, você pode consultar estes guias: Model Card, Dataset Card e Spaces Settings. Agora, vamos ver alguns exemplos de como atualizar esses metadados.

Vamos começar com um primeiro exemplo:

>>> from huggingface_hub import metadata_update
>>> metadata_update("username/my-cool-model", {"pipeline_tag": "image-classification"})

Com essas duas linhas de código, você atualizará os metadados para definir uma nova pipeline_tag.

Por padrão, você não pode atualizar uma chave que já existe no cartão. Se você quiser fazer isso, deve passar overwrite=True explicitamente:

>>> from huggingface_hub import metadata_update
>>> metadata_update("username/my-cool-model", {"pipeline_tag": "text-generation"}, overwrite=True)

É comum que você queira sugerir algumas alterações em um repositório no qual não tem permissão de escrita. Você pode fazer isso criando um PR nesse repositório, o que permitirá que os proprietários revisem e mesclam suas sugestões.

>>> from huggingface_hub import metadata_update
>>> metadata_update("someone/model", {"pipeline_tag": "text-classification"}, create_pr=True)

Incluir resultados de avaliação

Para incluir os resultados de avaliação nos metadados model-index, você pode passar um EvalResult ou uma lista de EvalResult com seus resultados de avaliação associados. Internamente, isso criará o model-index quando você chamar card.data.to_dict(). Para mais informações sobre como isso funciona, você pode conferir esta seção da documentação do Hub.

Observe que o uso desta função exige que você inclua o atributo model_name em ModelCardData.

card_data = ModelCardData(
    language='en',
    license='mit',
    model_name='my-cool-model',
    eval_results = EvalResult(
        task_type='image-classification',
        dataset_type='beans',
        dataset_name='Beans',
        metric_type='accuracy',
        metric_value=0.7
    )
)

card = ModelCard.from_template(card_data)
print(card.data)

O card.data resultante deve ser parecido com este:

language: en
license: mit
model-index:
- name: my-cool-model
  results:
  - task:
      type: image-classification
    dataset:
      name: Beans
      type: beans
    metrics:
    - type: accuracy
      value: 0.7

Se você tiver mais de um resultado de avaliação que deseja compartilhar, basta passar uma lista de EvalResult:

card_data = ModelCardData(
    language='en',
    license='mit',
    model_name='my-cool-model',
    eval_results = [
        EvalResult(
            task_type='image-classification',
            dataset_type='beans',
            dataset_name='Beans',
            metric_type='accuracy',
            metric_value=0.7
        ),
        EvalResult(
            task_type='image-classification',
            dataset_type='beans',
            dataset_name='Beans',
            metric_type='f1',
            metric_value=0.65
        )
    ]
)
card = ModelCard.from_template(card_data)
card.data

Isso deve deixar você com o seguinte card.data:

language: en
license: mit
model-index:
- name: my-cool-model
  results:
  - task:
      type: image-classification
    dataset:
      name: Beans
      type: beans
    metrics:
    - type: accuracy
      value: 0.7
    - type: f1
      value: 0.65

Update on GitHub

Hub Python Library

Criar e compartilhar Model Cards

Carregar um Model Card do Hub

Criar Model Cards

De Texto

De um modelo Jinja

Do Modelo Padrão

Compartilhar Model Cards

Atualizar metadados

Incluir resultados de avaliação