How to upload your ML model to FathomNet Database

A major part of the FathomNet Database is the ability to share and index pretrained machine learning models to analyze underwater imagery. This collection of models is known as the FathomNet Models. Sharing your model will allow others to use and build on it for their own work. In this article, we describe how to upload your model to the FathomNet Database and ensure that other users can properly cite it.

The FathomNet Models are hosted on Hugging Face, a platform widely used by the machine learning community for sharing models, datasets, and applications.

The process is very straightforward and will look pretty familiar to anyone who has used tools like GitHub. There are three basic steps:

1. Create an account or login and join the FathomNet organization on Hugging Face.

2. Prepare your model and associated files for submission.

3. Upload the model to Hugging Face and write a model card.

What is Hugging Face?

Hugging Face is a hub for machine learning models, datasets, and applications, originally born out of a chatbot project but quickly adopted by the broader AI research community. It serves as a central repository where developers and scientists can share, collaborate on, and deploy machine learning models—from natural language processing and computer vision to audio and multimodal tasks. Users can freely upload their models, explore those created by others, and even run them in the browser with Hugging Face’s “Spaces”. All that’s needed to get started is a free account using your email, GitHub, or Google credentials. It’s open science meets open source, with an emphasis on reproducibility, community, and accessibility.

While Hugging Face isn’t the only option for publishing models online, we favor it for its active community, seamless integration with popular libraries like Transformers and Diffusers, and its robust support for versioning and collaboration.

Prepare your model

Before you start the upload, gather everything you want to put in the model repository. You do not need to share absolutely everything associated with your model. At a minimum, you will want to include the model weights and any ancillary information a user needs to run inference. Here are the basic elements your repository should include:

• Model parameters — A file that dictates model behavior. Different machine learning packages and model architectures are saved with a variety of extensions and formats. PyTorch, for example, saves model weights as .pth or .pt serialized files. Any type is fine, but be sure to specify what is needed to run it.

• Train/validation metadata — Documents listing the images, ideally itemized as URLs or Universally Unique Identifiers (UUIDs), and associated annotations used for model training and evaluation.

• Performance metrics — An image or array providing a snapshot of model performance on an independent validation or test set (not training data). A confusion matrix, for example, gives users an at-a-glance idea of how well a classification model works. Other metrics or visualizations might be more appropriate based on the model type and task.

• Model card — A description of what is contained in the repository, including a description of the model, its intended uses, how it was trained and evaluated, and the datasets used for training and evaluation. For more information, see the Hugging Face model cards documentation.

There are many other files that might be relevant for your upload. For example, we uploaded benthic_label_map.json that describes the mapping between the lowest taxonomic level annotation in the training data and the 20 final semantic classes.

Upload your model to Hugging Face

After joining the FathomNet Hugging Face community, you have permission to start uploading your model. Hugging Face’s interface is well designed and easy to use.

Create a model repository

From the FathomNet organization page, press the “New” button at the top right and click “Model” to create a repository for your model. Leave the Owner as “FathomNet” and enter a unique name for your model. Select an appropriate license – we prefer Creative Commons Attribution 4.0, a.k.a. cc-by-4.0. Leave the model visibility as Public and click “Create model”. From here, your repository will be created and you can start uploading files.

Drag and drop from your computer

Go to the “Files and versions” tab, select “Contribute” at the far right, and click “Upload files”. Drag and drop files/folders into the interface from your machine to upload them, add a commit message, and press the “Commit changes to main” button at the bottom. At this stage, you should upload your model weights, train/val metadata, and evaluation artefacts (e.g., performance metrics).

Write the model card

Go back to the “Model card” tab and click “Edit model card” to fill in the details. You can reference the MBARI Midwater Detector model card as an example of some of the details and formatting. See the Hugging Face model cards documentation for more information.

Done and done

You have published and shared your model with the world! Thank you for participating in the FathomNet community. Be sure to check out our other How-To articles describing how to upload your annotated image data and how to use the FathomNet Python API to interact with the Database. And, of course, stay tuned for more information to come.