Skip to content
Tutorials Center
My learning

Topics

Lesson 32 of 38 ยท Deployment and Spaces

Saving, Pushing and Documenting Models

Save a fine-tuned model with save_pretrained, understand the safetensors file format, push to the Hugging Face Hub, and write a model card that makes your model usable and safe.

Training ends with a model sitting in memory. To use it tomorrow, on another machine, or in a product, you have to save it in a form that loads back exactly, then usually share it, either privately inside your team or publicly on the Hub. This lesson covers the files save_pretrained writes, what is inside the weights file, how pushing works, and what a good model card contains.

Saving and pushing real Transformers models needs the transformers library, PyTorch and (for pushing) a Hugging Face account and token, none of which run on this site. The commands below are shown read-only. The two runnable examples are stand-ins: one writes and reads a file in the real safetensors layout with numpy, the other builds and checks a model card.

What save_pretrained writes

Every model, tokenizer and config in the library follows the same pair of methods: save_pretrained(folder) and from_pretrained(folder). The folder is self-contained.

Python
trainer.save_model("my-classifier")               # model + config
tokenizer.save_pretrained("my-classifier")        # tokenizer files

# later, anywhere:
from transformers import AutoModelForSequenceClassification, AutoTokenizer
model = AutoModelForSequenceClassification.from_pretrained("my-classifier")
tokenizer = AutoTokenizer.from_pretrained("my-classifier")

A typical folder contains:

File Purpose
config.json Architecture settings (layers, hidden size) and label maps id2label / label2id
model.safetensors The weights (large models are split into shards plus an index JSON)
tokenizer.json, tokenizer_config.json, special_tokens_map.json Everything needed to tokenize identically
generation_config.json Default decoding settings for generative models
training_args.bin Optional: the TrainingArguments used (a pickle, do not load untrusted ones)

Two habits prevent most deployment bugs: always save the tokenizer next to the model, and set id2label before training so predictions come back as names instead of LABEL_0.

For a PEFT run (see LoRA explained), save_pretrained writes only the small adapter (adapter_model.safetensors plus adapter_config.json), typically a few megabytes. To ship a single standalone model you can call merge_and_unload() first and save the merged result.

Why safetensors?

Older checkpoints used Python pickle (pytorch_model.bin). Unpickling can run arbitrary code, so loading a file from a stranger was a real security risk. safetensors stores only tensors and a JSON header: nothing executable, and it can be memory-mapped so loading is fast and each tensor can be read lazily. It is the default format for new models on the Hub.

The layout is simple enough to implement yourself: 8 bytes giving the header length, a JSON header describing each tensor (dtype, shape, byte range), then the raw bytes.

Python Write and read the safetensors layout

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.

Notice that the header is plain JSON. A tool can list every tensor name and shape without reading any weights, which is how the Hub shows parameter counts for models you have not downloaded.

Pushing to the Hub

The Hub is a set of Git repositories with large-file support. After huggingface-cli login (or setting an HF_TOKEN environment variable with a write token), you can push in one call:

Python
model.push_to_hub("your-name/support-ticket-classifier", private=True)
tokenizer.push_to_hub("your-name/support-ticket-classifier")

# or, with Trainer, upload automatically at every save:
args = TrainingArguments(output_dir="out", push_to_hub=True,
                         hub_model_id="your-name/support-ticket-classifier",
                         hub_strategy="end")

Practical points:

  • Private first. Create the repo as private, test loading it with from_pretrained, then make it public if intended.
  • Tokens are secrets. Never commit them or paste them in notebooks you share. Use fine-grained tokens limited to one repo.
  • Revisions. Every push is a Git commit. You can pin consumers to a commit hash (revision="abc123") so a later push never changes their behavior.
  • Gated models. Some repos require accepting a license before download; your code needs a token that belongs to an account that accepted it.

The model card

Every Hub repo shows its README.md as the model card. It begins with YAML metadata that the Hub uses for search and widgets, followed by human-readable sections. A good card answers: what is it for, how was it trained, how good is it, and where does it fail.

Python Build and check a model card

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.

Do not skip Limitations. Reviewers, users and your future self need to know the languages, domains, lengths and groups the model was never tested on. If the training data contains personal information, say how it was handled; if the base model has a license with restrictions, your card must carry that forward in the license field and a short note.

flowchart LR
  A["Trainer finishes"] --> B["save_pretrained: weights, config, tokenizer"]
  B --> C["Reload and test locally"]
  C --> D["push_to_hub (private)"]
  D --> E["Model card + license"]
  E --> F["Make public or share with org"]

Reload and test before you push; document before you share.

Check your understanding

Quick check ยท 5 questions

of 5 answered You scored / 5 ยท perfect!

  1. 1. Why is safetensors preferred over pickle-based checkpoints?

    Pickle can execute code on load; safetensors holds data only, and can be memory-mapped.
  2. 2. What must you save next to the model so predictions match training?

    A different tokenizer produces different token ids, so the model would see the wrong inputs.
  3. 3. A PEFT LoRA run finishes. What does save_pretrained write?

    Adapters are saved on their own; merge_and_unload() produces a standalone model if you need one.
  4. 4. Which is a good first step when pushing a new model to the Hub?

    Private-first lets you verify loading and the card before anyone else depends on it.
  5. 5. Which model card section tells users where the model may fail?

    Limitations and intended use set expectations for languages, domains and lengths.

Summary

  • save_pretrained writes config, weights and tokenizer into one folder; from_pretrained reads it back from a folder or a Hub id.
  • safetensors is a JSON header plus raw tensor bytes: safe, fast and inspectable. Avoid loading untrusted pickle files.
  • push_to_hub uploads a Git-backed repo; start private, pin revisions and guard your token.
  • A model card with intended use, data, evaluation, limitations and license is part of shipping the model.

Next: Serving a model with FastAPI and batching