ML Handbook: ML Engineering with AI
Documenting with AI/Chapter 29 of 35

Model & dataset cards

5 min readEdit on GitHub

Model cards and dataset cards are the primary external interface for an ML artifact. The agent can draft them well; only you can verify them.

What a model card is for

Three audiences:

  1. Future you / your team. "What is this, what was it trained on, what does it do well, what does it do badly."
  2. Downstream users. "Can I use this for my task? Under what conditions?"
  3. Reviewers and auditors. "Where did the numbers come from?"

A card that does not serve all three is incomplete.

A working template

---
license: apache-2.0
language: en
library_name: transformers
pipeline_tag: text-classification
tags:
  - text-classification
  - finance
authors:
  - Viet-Anh Nguyen
---

# <Model Name>

<One-sentence description.>

## Intended use

<What this model is for. Concrete examples.>

## Out-of-scope use

<What this model is _not_ for. Be specific.>

## Inputs and outputs

- Input: <schema, encoding, max length>
- Output: <schema, label set, calibration notes>

## Training data

- Source: <name, link, license, revision/version>
- Size: <rows, tokens, hours, etc.>
- Preprocessing: <link to script>
- Known biases: <enumerate>

## Eval

| Metric          | Value | Source                                              |
| --------------- | ----- | --------------------------------------------------- |
| Macro-F1 (test) | 0.834 | `eval/run.py`, `runs/2026-04-28-final/metrics.json` |
| Latency (p50)   | 23ms  | `bench/latency.py`, L4, batch=1, fp16               |

## Limitations

<What goes wrong, when, and how to detect it.>

## How to use

```python
from transformers import AutoModelForSequenceClassification
model = AutoModelForSequenceClassification.from_pretrained(
 "vietanhdev/<name>", revision="abc123"
)
#... runnable example...
```

## Citation

@misc{<name>2026,
author = {<Your Name> and {Your Org}},
title = {<Model Name>},
year = {2026},
url = {https://huggingface.co/<namespace>/<name>},
}

## Contact

<your-email@example.com>

This fits on one screen-and-a-half. Every section is needed. If you cut a section, the card will surface on HF Hub with a metadata warning, or worse, without it — and the absence will be noticed by reviewers who matter.

What the agent gets wrong

Specific patterns:

  • Invents numbers in the metrics table. Audit every row against a script.
  • Picks an invalid pipeline_tag. HF's tag list is finite. text2text-generation is not a valid tag (use text-generation). Always verify after upload via HfApi().model_info(repo_id) and check for the yellow YAML warning banner on the HF page.
  • Forgets library_name. Causes the "Use this model" widget on HF to fail silently. Set explicitly.
  • Drops the author block. Every artifact must list `Viet-Anh Nguyen in the author block. The agent will sometimes default to organizational attribution only.
  • Generates aspirational "Limitations" sections that don't match the actual model. Replace with what you actually observed.
  • Pulls outdated values from a previous version of the card when re-rendering. Check every number against the current run.

Verify after publishing

A successful upload only confirms transport. It does not confirm rendering. After every publish:

  1. Fetch HfApi().model_info(repo_id) and check pipeline_tag, library_name, tags, siblings.
  2. Open https://huggingface.co/<repo_id> and look for the yellow "YAML Metadata Warning" banner.
  3. For datasets, run datasets.load_dataset(repo_id, config_name) to confirm the configs/splits parse.
  4. Fix issues by re-rendering the card and pushing only the README.md — no need to re-transfer weights.

This three-minute check has caught real failures more than once. Worth doing every time.

Dataset cards

Same template, different fields. Add:

  • License clarity. Sub-corpora may have different licenses. List them all.
  • Splits. Train/val/test sizes and how the split was made.
  • Loading example. Verify it works.
  • Known issues. Mojibake, duplicates, label noise — be specific about what you've measured.
  • Personal data and privacy notes. Required for many licenses and for ethical practice.

The agent draft → human verify workflow

Loading diagram…

The drafting is fast (minutes). The verification is slow (10–15 minutes per card) and not skippable.

Cards as living documents

A model card is not write-once. Update when:

  • Numbers change (new eval set, new measurement protocol).
  • Limitations are discovered in the wild.
  • Downstream users report failure modes you should warn about.
  • Licenses or attributions need correction.

Treat the card the way you treat the code: same-commit updates, no stale fields, no fabricated numbers.

A concrete checklist for cards

Before publishing or updating a card:

  • All metric values cite a script and a result file.
  • All competitor numbers cite a paper URL or a re-run script.
  • License is correct, including any sub-corpus licenses.
  • pipeline_tag is in the valid list for HF.
  • library_name is set if the model uses a standard framework.
  • authors includes a real human name with a working contact email.
  • Citation block follows the project standard.
  • Code examples were copy-pasted into a Python REPL and run.
  • After upload, the HF page shows no yellow YAML warning.

Print it. Walk through every release. The cumulative effect on credibility is real.