Skip to content
Tutorials Center
My learning

Topics

Lesson 35 of 41 ยท Governance and Tooling

Model Cards and Documentation

Write a model card that states intended use, data, metrics by slice and known limits, generate it from code, and check in CI that no card ships incomplete.

A model that only its author understands is a liability. Six months later the author has moved on, a new engineer wants to reuse the model for a slightly different job, and an auditor asks what data it saw. A model card is a short, structured document that answers those questions up front: what the model is for, how it was built, how well it works and where it should not be used.

Model cards were proposed as a transparency practice, and many regulated settings now expect something similar. The good news for MLOps: most of the card can be generated automatically by the training pipeline, so documentation never lags behind the model.

What belongs in a model card

Core of a model card

Intended use Who uses it, for what decision.
Data Sources, dates, size, known gaps.
Metrics Overall and per group, with sizes.
Limits Out-of-scope uses and failure modes.

Short, honest, and kept next to the model.

1 / 2
  • Intended use and out-of-scope use. "Ranks support tickets for urgency; not for evaluating staff."
  • Training and evaluation data. Where it came from, the time range, how it was split, who or what is missing.
  • Metrics. The numbers the gate used, plus per-slice numbers and the sample size behind each.
  • Limitations and risks. Known failure modes, populations with weaker results, assumptions.
  • Ethical and legal notes. Sensitive attributes, consent and retention rules, human oversight.
  • Operations. Version, owner, monitoring plan, contact.

Generate the card from the pipeline

Whatever the training script already knows (metrics, data fingerprint, parameters) should be written into the card by code. Humans then add the parts only they know: intended use and limits.

Python Build a model card as a dictionary and render it

Press Run (or Ctrl + Enter) to see the result here.

Program input ยท what you'd type while the program runs

Type the answers before you press Run, one per line. Each time the program reads a line (with input()), it gets the next line from this box.

Store the JSON next to the model artifact in the registry, and render it as Markdown or HTML for people.

Check cards in CI

A card that is missing required sections is worse than no card because it looks official. Add a check to the pipeline.

Python Block incomplete cards

Press Run (or Ctrl + Enter) to see the result here.

Program input ยท what you'd type while the program runs

Type the answers before you press Run, one per line. Each time the program reads a line (with input()), it gets the next line from this box.

Other documents worth keeping

  • Datasheet for the dataset: collection method, labelling process, consent, known biases.
  • Decision log: why this model family, why this threshold (see Lineage and Audit Trails).
  • Runbook: what to do when the service alerts or the model must be rolled back.
  • Change log: one entry per version, written for humans.

Common mistakes

  • Writing the card once at launch and never updating it.
  • Reporting only overall accuracy with no slices.
  • Vague limits such as "may be inaccurate"; say where and for whom.
  • Hiding the card where nobody finds it. Link it from the registry entry and the service.

Check your understanding

Quick check ยท 4 questions

of 4 answered You scored / 4 ยท perfect!

  1. 1. What is the main purpose of a model card?

    A card makes the model understandable and reviewable by people who did not build it.
  2. 2. Which parts of a card can usually be generated by the pipeline?

    Facts the pipeline already knows should be written by code; judgment calls are written by people.
  3. 3. Why report the size of each slice next to its metric?

    A perfect score on 12 rows means almost nothing.
  4. 4. Why check cards in CI?

    An automatic check keeps documentation from being skipped under deadline pressure.

Summary

  • A model card records intended use, data, metrics (overall and by slice), limits, version and owner.
  • Generate the factual parts from the pipeline; people write purpose and limits.
  • Store the card with the model and validate it in CI.
  • Keep datasheets, decision logs and runbooks alongside it.
  • Update the card on every release.

Next: Fairness and Bias Checks