Skip to content

docs: document training_regime field in the annotated model card#2656

Open
Sofeso wants to merge 1 commit into
huggingface:mainfrom
Sofeso:document-training-regime-1125
Open

docs: document training_regime field in the annotated model card#2656
Sofeso wants to merge 1 commit into
huggingface:mainfrom
Sofeso:document-training-regime-1125

Conversation

@Sofeso

@Sofeso Sofeso commented Jul 18, 2026

Copy link
Copy Markdown

Closes #1125.

Problem

modelcard_template.md (in huggingface_hub) has always had a training_regime field under "Training Hyperparameters":

- **Training regime:** {{ training_regime | default(...) }} <!--fp32, fp16 mixed precision, bf16 mixed precision, bf16 non-mixed precision, fp16 non-mixed precision, fp8 mixed precision -->

But docs/hub/model-card-annotated.md — the doc that's supposed to explain every field in the template — jumps straight from ### Preprocessing to ### Speeds, Sizes, Times. There's no "Training Hyperparameters" subsection at all, so training_regime is never explained anywhere a user would actually look for it, exactly as reported in #1125.

Fix

Added the missing ### Training Hyperparameters subsection between Preprocessing and Speeds/Sizes/Times, documenting training_regime with the same field-name + italicized-explanation style used for every other field in this file. The definition (fp32 / fp16 / bf16 / fp8, mixed vs. non-mixed precision) is sourced directly from the template's own inline HTML comment, not invented.

Consistency check

This repo's model_card_consistency_reminder workflow flags several files as containing duplicated model-card content, so I checked all of them before committing to a single-file fix:

  • modelcard.md (this repo) — only YAML frontmatter metadata, no body template section. Not applicable.
  • docs/hub/model-cards.md — explicitly defers body-template explanations to the annotated card ("Details on how to fill out the human-readable portion... is available in the Annotated Model Card") rather than duplicating them. Not applicable.
  • huggingface_hub's modelcard_template.md and repocard.py — already reference training_regime correctly; nothing to fix there.

So docs/hub/model-card-annotated.md is the one place this needed to change.

Disclosure

I used AI assistance (Claude) to investigate this issue and draft the fix. I reviewed the change and take responsibility for its accuracy.


Note

Low Risk
Documentation-only change with no runtime, API, or security impact.

Overview
Adds the missing Training Hyperparameters subsection to docs/hub/model-card-annotated.md, between Preprocessing and Speeds, Sizes, Times, so the annotated guide matches modelcard_template.md.

Documents the training_regime placeholder with the same backtick field + italic explanation pattern as other fields, covering precision options (fp32, fp16/bf16/fp8, mixed vs non-mixed) and why the field matters for reproduction and resource planning.

Reviewed by Cursor Bugbot for commit 2812008. Bugbot is set up for automated code reviews on this repo. Configure here.

The modelcard_template.md in huggingface_hub has a 'Training
Hyperparameters' subsection with a training_regime field, but this
annotated model card guide jumps straight from Preprocessing to
Speeds/Sizes/Times, so training_regime is never explained anywhere a
user would look for it (as reported in huggingface#1125).

Added the missing ### Training Hyperparameters subsection with a
definition sourced from the template's own inline comment (fp32,
fp16/bf16/fp8 mixed vs non-mixed precision), matching the field-name +
italicized-explanation style already used for every other field in
this file.

Checked the other files the model_card_consistency_reminder workflow
flags as duplicated content:
- modelcard.md (this repo) only contains YAML frontmatter metadata,
  no body template - not applicable.
- docs/hub/model-cards.md explicitly defers body-template details to
  this annotated file rather than duplicating them - not applicable.
- huggingface_hub's modelcard_template.md and repocard.py already
  reference training_regime correctly - no fix needed there.

So this is the single correct place to fix.

Closes huggingface#1125
@julien-c
julien-c requested a review from meg-huggingface July 19, 2026 08:15

`training_regime`

_The training regime, i.e. the numerical precision the model was actually trained with: `fp32`, `fp16` mixed precision, `bf16` mixed precision, `bf16` non-mixed precision, `fp16` non-mixed precision, or `fp8` mixed precision. This affects training speed and memory footprint, and in some cases the numerical stability of results, so it's useful for anyone trying to reproduce training or understand its resource requirements._

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Since training regime is more broad, would suggest either

`numerical_precision`

_Provide the numerical precision the model was trained with (e.g., `fp32`, `fp16` mixed precision, `bf16` mixed precision, `bf16` non-mixed precision, `fp16` non-mixed precision, or `fp8` mixed precision). This affects training speed and memory footprint, and in some cases the numerical stability of results, so it's useful for anyone trying to reproduce training or understand its resource requirements._

Or go more broad:

`training_regime`

_Provide the training details that are useful for anyone trying to reproduce training or understand its resource requirements. This can include learning rate, batch size, and regularization method, among other hyperparameters. Numerical precision is particularly relevant here (e.g., `fp32`, `fp16` mixed precision, `bf16` mixed precision, `bf16` non-mixed precision, `fp16` non-mixed precision, or `fp8` mixed precision), as it affects training speed, memory footprint, and in some cases numerical stability._

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

training_regime is not documented in the model card spec

2 participants