Create and share Model Cards

The huggingface_hub library provides a Python interface to create, share, and update Model Cards. Visit the dedicated documentation page for a deeper view of what Model Cards on the Hub are, and how they work under the hood.

New (beta)! Try our experimental Model Card Creator App

Load a Model Card from the Hub

To load an existing card from the Hub, you can use the ModelCard.load() function. Here, we’ll load the card from nateraw/vit-base-beans.

from huggingface_hub import ModelCard

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

This card has some helpful attributes that you may want to access/leverage:

card.data: Returns a ModelCardData instance with the model card’s metadata. Call .to_dict() on this instance to get the representation as a dictionary.
card.text: Returns the text of the card, excluding the metadata header.
card.content: Returns the text content of the card, including the metadata header.

Create Model Cards

From Text

To initialize a Model Card from text, just pass the text content of the card to the ModelCard on init.

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

# My Model Card
"""

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

Another way you might want to do this is with f-strings. In the following example, we:

Use ModelCardData.to_yaml() to convert metadata we defined to YAML so we can use it to insert the YAML block in the model card.
Show how you might use a template variable via Python f-strings.

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)

The above example would leave us with a card that looks like this:

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

# My Model Card

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

From a Jinja Template

If you have Jinja2 installed, you can create Model Cards from a jinja template file. Let’s see a basic example:

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)

The resulting card’s markdown looks like this:

---
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).

If you update any card.data, it’ll reflect in the card itself.

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

Now, as you can see, the metadata header has been updated:

---
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).

As you update the card data, you can validate the card is still valid against the Hub by calling ModelCard.validate(). This ensures that the card passes any validation rules set up on the Hugging Face Hub.

From the Default Template

Instead of using your own template, you can also use the default template, which is a fully featured model card with tons of sections you may want to fill out. Under the hood, it uses Jinja2 to fill out a template file.

Note that you will have to have Jinja2 installed to use from_template. You can do so with 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)

Share Model Cards

If you’re authenticated with the Hugging Face Hub (either by using huggingface-cli login or login()), you can push cards to the Hub by simply calling ModelCard.push_to_hub(). Let’s take a look at how to do that…

First, we’ll create a new repo called ‘hf-hub-modelcards-pr-test’ under the authenticated user’s namespace:

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)

Then, we’ll create a card from the default template (same as the one defined in the section above):

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",
)

Finally, we’ll push that up to the hub

card.push_to_hub(repo_id)

You can check out the resulting card here.

If you instead wanted to push a card as a pull request, you can just say create_pr=True when calling push_to_hub:

card.push_to_hub(repo_id, create_pr=True)

A resulting PR created from this command can be seen here.

Update metadata

In this section we will see what metadata are in repo cards and how to update them.

metadata refers to a hash map (or key value) context that provides some high-level information about a model, dataset or Space. That information can include details such as the model’s pipeline type, model_id or model_description. For more detail you can take a look to these guides: Model Card, Dataset Card and Spaces Settings. Now lets see some examples on how to update those metadata.

Let’s start with a first example:

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

With these two lines of code you will update the metadata to set a new pipeline_tag.

By default, you cannot update a key that is already existing on the card. If you want to do so, you must pass overwrite=True explicitly:

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

It often happen that you want to suggest some changes to a repository on which you don’t have write permission. You can do that by creating a PR on that repo which will allow the owners to review and merge your suggestions.

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

Include Evaluation Results

To include evaluation results in the metadata model-index, you can pass an EvalResult or a list of EvalResult with your associated evaluation results. Under the hood it’ll create the model-index when you call card.data.to_dict(). For more information on how this works, you can check out this section of the Hub docs.

Note that using this function requires you to include the model_name attribute in 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)

The resulting card.data should look like this:

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

If you have more than one evaluation result you’d like to share, just pass a list of 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

Which should leave you with the following 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

Hub Python Library