Hugging Face Model Cards

Brief Introduction

Model cards are files that accompany the models and provide handy information that are essential for discoverability, reproducibility, and sharing. Model cards are Markdown files enriched with supplementary metadata. A model repository will render its README.md as a model card.

Model Card Metadata

To define the model metadata you can create a YAML section in the README.md.

It starts adding --- at the top, then it should include all of the relevant metadata, and it closes the section with another group of ---.

In the following example, this markdown file includes the specifications for the model card metadata concerning evaluation parameters.

---
# Example metadata to be added to a model card.  
# Full model card template at https://github.com/huggingface/huggingface_hub/blob/main/src/huggingface_hub/templates/modelcard_template.md
language:
- {lang_0}  # Example: fr
- {lang_1}  # Example: en
license: {license}  # Example: apache-2.0 or any license from https://hf.co/docs/hub/repositories-licenses
library_name: {library_name}  # Optional. Example: keras or any library from https://github.com/huggingface/hub-docs/blob/main/js/src/lib/interfaces/Libraries.ts
tags:
- {tag_0}  # Example: audio
- {tag_1}  # Example: automatic-speech-recognition
- {tag_2}  # Example: speech
datasets:
- {dataset_0}  # Example: common_voice. Use dataset id from https://hf.co/datasets
metrics:
- {metric_0}  # Example: wer. Use metric id from https://hf.co/metrics

# Optional. Add this if you want to encode your eval results in a structured way.
model-index:
- name: {model_id}
  results:
  - task:
      type: {task_type}             # Required. Example: automatic-speech-recognition
      name: {task_name}             # Optional. Example: Speech Recognition
    dataset:
      type: {dataset_type}          # Required. Example: common_voice. Use dataset id from https://hf.co/datasets
      name: {dataset_name}          # Required. A pretty name for the dataset. Example: Common Voice (French)
      config: {dataset_config}      # Optional. The name of the dataset configuration used in `load_dataset()`. Example: fr in `load_dataset("common_voice", "fr")`. See the `datasets` docs for more info: https://huggingface.co/docs/datasets/package_reference/loading_methods#datasets.load_dataset.name
      split: {dataset_split}        # Optional. Example: test
      revision: {dataset_revision}  # Optional. Example: 5503434ddd753f426f4b38109466949a1217c2bb
      args:
        {arg_0}: {value_0}          # Optional. Additional arguments to `load_dataset()`. Example for wikipedia: language: en
        {arg_1}: {value_1}          # Optional. Example for wikipedia: date: 20220301
    metrics:
      - type: {metric_type}         # Required. Example: wer. Use metric id from https://hf.co/metrics
        value: {metric_value}       # Required. Example: 20.90
        name: {metric_name}         # Optional. Example: Test WER
        config: {metric_config}     # Optional. The name of the metric configuration used in `load_metric()`. Example: bleurt-large-512 in `load_metric("bleurt", "bleurt-large-512")`. See the `datasets` docs for more info: https://huggingface.co/docs/datasets/v2.1.0/en/loading#load-configurations
        args:
          {arg_0}: {value_0}        # Optional. The arguments passed during `Metric.compute()`. Example for `bleu`: max_order: 4
        verified: true              # Optional. If true, indicates that evaluation was generated by Hugging Face (vs. self-reported).
---

Model Card Sections

Fully filling out a model card requires input from a few different roles:

  • the developer, who writes the code and runs training;
  • the sociotechnic, who is skilled at analyzing the interaction of technology and society long-term (this includes lawyers, ethicists, sociologists, or rights advocates);
  • and the project organizer, who understands the overall scope and reach of the model, can roughly fill out each part of the card, and who serves as a contact person for model card updates.

The full model card template is available here. It has the following sections: