Skip to content

Update model-release-checklist.md #1671

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Merged
merged 3 commits into from
Apr 8, 2025
Merged

Update model-release-checklist.md #1671

Changes from all commits
Commits
Show all changes
3 commits
Select commit Hold shift + click to select a range
8f9ba6d
Update model-release-checklist.md
gary149 Apr 3, 2025
e620c3d
Update model-release-checklist.md
gary149 Apr 3, 2025
5b36f6f
Update model-release-checklist.md
gary149 Apr 3, 2025
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
8 changes: 5 additions & 3 deletions docs/hub/model-release-checklist.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -8,8 +8,11 @@ The Hugging Face Hub is the go-to platform for sharing machine learning models.

When uploading models to the hub, it's recommended to follow a set of best practices:

- push weights to separate model repositories. Example: prefer uploading individual quantizations/precisions in a standalone repo like [this](https://huggingface.co/jameslahm/yolov10n) over all types/versions in one like [this](https://huggingface.co/kadirnar/Yolov10/tree/main).
Copy link
Contributor Author

@gary149 gary149 Apr 3, 2025

Choose a reason for hiding this comment

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

not sure this is true (or I misunderstood) tried to simplify

- leverage [safetensors](https://huggingface.co/docs/safetensors/en/index) for weights serialization as opposed to pickle.
### Uploading Weights

- **Use separate repositories for different model weights.** For example, you can store quantization variants for the same model in a single repository, but use separate repositories for different model weights.
Copy link
Member

@Vaibhavs10 Vaibhavs10 Apr 3, 2025

Choose a reason for hiding this comment

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

this goes a bit against what we preach no, each quant, precision, weight type should go in a new repo?

(the only exception is bartowski and Maziyar because they create so many quants it makes sense to have all in one)

Copy link
Contributor Author

@gary149 gary149 Apr 3, 2025

Choose a reason for hiding this comment

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

Mhh no we want a single repo with all the quants it really makes more sense imo. cc @julien-c for final decision

Copy link
Member

@julien-c julien-c Apr 4, 2025

Choose a reason for hiding this comment

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

hmm i see most GGUF repos put different quants in the same repo, yes (and we have nice UI feature for this)

I'm not sure we ever advocated for different quants of the same model to be in ≠ repos actually no?

We did push for ≠ repos for GGUF vs. other formats (Pytorch, etc)

Copy link
Member

@Vaibhavs10 Vaibhavs10 Apr 4, 2025

Choose a reason for hiding this comment

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

Not sure, I'd consider GGUFs as an exception here and more specifically GGUFs produced by model quantisers. For everything else we recommend having one quant per repo (look at MLX community: https://huggingface.co/mlx-community for example) or MLC

(this is also the reason why MLX-my-repo, gguf-my-repo they all create one quant per repo only)

Even for model releases we try to have one quant per repo:

  1. https://huggingface.co/collections/google/gemma-3-qat-67ee61ccacbf2be4195c265b
  2. https://huggingface.co/collections/kyutai/moshivis-v01-67cef4acae6a5d75d6d6c883

There's a lot more examples for this too across model releases.

Something we actively want to discourage is mixed repos - various quants and pytorch models there and the lines can be quite blurry with it.

Copy link
Member

@julien-c julien-c Apr 4, 2025

Choose a reason for hiding this comment

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

Yep.

that being said i think the wording in this PR is fine

Copy link
Member

@Vaibhavs10 Vaibhavs10 Apr 4, 2025

Choose a reason for hiding this comment

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

okay! don't want to be a blocker here! - we can always reword if people get confused!


- **Prefer [`safetensors`](https://huggingface.co/docs/safetensors/en/index) over `pickle` for weight serialization.** `safetensors` offers improved safety and performance compared to Python's `pickle`.

### Writing a Comprehensive Model Card

Expand Down Expand Up @@ -39,7 +42,6 @@ A well-crafted model card (the `README.md` file in your repository) is essential

6. **Limitations and Biases**: Transparently document any known limitations, biases, or ethical considerations associated with your model. This helps users make informed decisions about whether and how to use your model.


### Enhancing Model Discoverability and Usability

To maximize your model's reach and usability:
Expand Down