ContextQMD
Back to Transformers

Sharing

docs/source/en/model_sharing.md

5.8.06.4 KB
Original Source
<!--Copyright 2024 The HuggingFace Team. All rights reserved. Licensed under the Apache License, Version 2.0 (the "License"); you may not use this file except in compliance with the License. You may obtain a copy of the License at http://www.apache.org/licenses/LICENSE-2.0 Unless required by applicable law or agreed to in writing, software distributed under the License is distributed on an "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. See the License for the specific language governing permissions and limitations under the License. ⚠️ Note that this file is in Markdown but contain specific syntax for our doc-builder (similar to MDX) that may not be rendered properly in your Markdown viewer. -->

Sharing

The Hugging Face Hub is a platform for sharing, discovering, and consuming models of all different types and sizes. We highly recommend sharing your model on the Hub to push open-source machine learning forward for everyone!

This guide will show you how to share a model to the Hub from Transformers.

Set up

To share a model to the Hub, you need a Hugging Face account. Create a User Access Token (stored in the cache by default) and login to your account from either the command line or notebook.

<hfoptions id="share"> <hfoption id="huggingface-CLI">
bash
hf auth login
</hfoption> <hfoption id="notebook">
py
from huggingface_hub import notebook_login

notebook_login()
</hfoption> </hfoptions>

Repository features

<Youtube id="XvSGPZFEjDY"/>

Each model repository features versioning, commit history, and diff visualization.

<div class="flex justify-center"> </div>

Versioning is based on Git and Git Large File Storage (LFS), and it enables revisions, a way to specify a model version with a commit hash, tag or branch.

For example, use the revision parameter in [~PreTrainedModel.from_pretrained] to load a specific model version from a commit hash.

py
model = AutoModel.from_pretrained(
    "julien-c/EsperBERTo-small", revision="4c77982"
)

Model repositories also support gating to control who can access a model. Gating is common for allowing a select group of users to preview a research model before it's made public.

<div class="flex justify-center"> </div>

A model repository also includes an inference widget for users to directly interact with a model on the Hub.

Check out the Hub Models documentation to for more information.

Uploading a model

There are several ways to upload a model to the Hub depending on your workflow preference. You can push a model with [Trainer], call [~PreTrainedModel.push_to_hub] directly on a model, or use the Hub web interface.

<Youtube id="Z1-XMy-GNLQ"/>

Trainer

[Trainer] can push a model directly to the Hub after training. Set push_to_hub=True in [TrainingArguments] and pass it to [Trainer]. Once training is complete, call [~transformers.Trainer.push_to_hub] to upload the model.

[~transformers.Trainer.push_to_hub] automatically adds useful information like training hyperparameters and results to the model card.

py
from transformers import TrainingArguments, Trainer

training_args = TrainingArguments(output_dir="my-awesome-model", push_to_hub=True)
trainer = Trainer(
    model=model,
    args=training_args,
    train_dataset=small_train_dataset,
    eval_dataset=small_eval_dataset,
    compute_metrics=compute_metrics,
)
trainer.push_to_hub()

PushToHubMixin

The [~utils.PushToHubMixin] provides functionality for pushing a model or tokenizer to the Hub.

Call [~utils.PushToHubMixin.push_to_hub] directly on a model to upload it to the Hub. It creates a repository under your namespace with the model name specified in [~utils.PushToHubMixin.push_to_hub].

py
model.push_to_hub("my-awesome-model")

Other objects like a tokenizer are also pushed to the Hub in the same way.

py
tokenizer.push_to_hub("my-awesome-model")

Your Hugging Face profile should now display the newly created model repository. Navigate to the Files tab to see all the uploaded files.

Refer to the Upload files to the Hub guide for more information about pushing files to the Hub.

Hub web interface

The Hub web interface is a no-code approach for uploading a model.

  1. Create a new repository by selecting New Model.
<div class="flex justify-center"> </div>

Add some information about your model:

  • Select the owner of the repository. This can be yourself or any of the organizations you belong to.
  • Pick a name for your model, which will also be the repository name.
  • Choose whether your model is public or private.
  • Set the license usage.

  1. Click on Create model to create the model repository.

  2. Select the Files tab and click on the Add file button to drag-and-drop a file to your repository. Add a commit message and click on Commit changes to main to commit the file.

<div class="flex justify-center"> </div>

Model card

Model cards inform users about a models performance, limitations, potential biases, and ethical considerations. It is highly recommended to add a model card to your repository!

A model card is a README.md file in your repository. Add this file by:

  • manually creating and uploading a README.md file
  • clicking on the Edit model card button in the repository

Take a look at the Llama 3.1 model card for an example of what to include on a model card.

Learn more about other model card metadata (carbon emissions, license, link to paper, etc.) available in the Model Cards guide.