Writing a 'Model Card' is an AI best practice

A 'Model Card' is a valuable document to share all relevant facts about an AI model.

September 7, 2023 - 5 min.

Many of our favorite software projects, like Python, Jupyter or Tensorflow, provide helpful extensive documentation. Virtually every github project at least has a minimal README.md featured prominently. So what is the equivalent of that for a Machine Learning model?

Medication comes with a leaflet. The intention of the leaflet is to give very concise and informative facts about the contained drugs in the shortest time possible. The important stuff is not burried in endless texts. It’s brief, but exact and allows to quickly get a grasp of different perspectives of the medication like ingredients, possible side effects, how much to take and when. It’s a success story, even when we struggle to fold the leaflet back to its original compact state. The leaflet targets users of the drug as well as emergency responders, pharmacists and doctors.

tear out of the original paper

The Model Cards Paper

However, concerning just the model itself, something like a leaflet would be helpful, too. Enter the world of “Model Cards”. Model Cards have nothing to do with data about people presenting fashion, they are a fairly new concept.

Model Cards have been proposed in 2018 by Margaret Mitchell et al. in the paper “Model Cards for Model Reporting” paper. A Model Card is like an ID card for your AI model, mixed with birth certificate information.

The motivation for proposing Model Cards came out of the apparent lack of AI model documentation.

Currently, there are no standardized documentation procedures to communicate the performance characteristics of trained machine learning (ML) and artificial intelligence (AI) models. This lack of documentation is especially problematic when models are used in applications that have serious impacts on people’s lives, such as in health care, employment, education and law enforcement.

I often noticed that in system architecture documentation, when it is written by a person very familiar with the system at hand, only information is given that is top of mind to the writer, while important information for the intended readership is left out. More often than not, no appropriate context is given and a lot of what is in the document is not-really-important “inside baseball”-kind of stuff showing off the knowledge of the producers of the system rather than educating outsiders. Such documentation is mostly useless.


Therefore it’s helpful to follow a standard document structure. For software systems, this is for example a lightweight architecture documentation framework like arc42. Yet, the proposed Model Card approach is much more focused on AI models (not AI systems). It gives a very good structure, much more like a leaflet than an architecture documentation. In the end, you probably need both for your AI, but let’s put that aside for now. Let’s start with the Model Card.

In short, the paper proposes the have the following sections:

  • Model Details
  • Intended Use
  • Factors
  • Metrics
  • Evaluation Data
  • Training Data
  • Quantitative Analyses
  • Ethical Considerations
  • Caveats and Recommendations

While any kind of documentation can contain from half a dozen to up to hundreds of pages, a Model Card should be very brief. The examples in the paper are one-pagers, and this is a good approach. It still gives enough information for transparency while not exposing any internal intellectual property.

Cards in the Wild

Hugging Face supports creating Model Cards, and they even provide a template along with a guidebook. Kaggle promotes Model Cards as well.

Open AI has posted a Model Card for whisper online and there are other good cases out there.

As a good AI citizen, Salesforce publishes them, although they uploaded them as PDFs to github instead of raw text or markdown.

Yet, I’d like to see much more actual model cards out there. The NIST AI risk framework doesn’t contain Model Cards, unfortunately, while the OECD’s responsible AI framework does.

Model Cards vs. System Cards

The big players like OpenAI and Meta often provide “System Cards” for some of their products.

In my article “It’s the System, Not the Model!”, I emphasized the importance of differentiating between the raw AI model and the final AI-based software system, where the AI model is a crucial component, but which has other important components that make the final product. Following the same thought, “System Cards” have been proposed as a means to cover not only the model, but also the whole system. I cannot really argue with that. I firmly believe that Model Cards are still an important artefact, for the following reasons:

  • Models might be integrated into a system only later in the development lifecycle. The producer of the model might no longer be involved here (see Hugging Face for example). So the model-producing team should deliver it along with a Model Card for integrators. This way it can also become part of the System Card downstream.
  • Model Card one-pagers are concise and relevant. Maybe it’s the only information that’s looked at downstream, actually.
  • It’s a very good start. Data Scientists can easily fill a Model Card, while a system documentation like a System Card requires much more knowledge.
  • When an AI system is composed of multiple models, which will be happening a lot more as AI evolves, every model should bring its distinct Model Card.


You can expect that in the future, Model Cards will be the minimum requirement to bring with any AI model that is proliferated or used in actual products, certainly as far as AI regulation is concerned. Model Cards have low overhead, are easy to write, relevant and serve a good purpose. Let me know if you need help writing your first model card.

We take the risk out of your AI.
Do you need to make your AI products conformant with regulation? algo consult specializes in helping companies to master regulation. Let's go through the process together.