Hugging Face Model Mappings 🤗

In January 2025, Hugging Face announced Inference Providers, a new feature that allows you to run models on Replicate (and other providers) right from the Hugging Face website.

What is this repo?

This repo contains a mapping of Replicate models to Hugging Face models, so we can tell Hugging Face when to display a Replicate inference widget on its model pages.

This repo also includes tooling to keep those mappings up to date using Hugging Face's Model Mappings API.

Adding a new model

To add a new model mapping, edit src/models.ts

Add your new model to the inferenceModels array, like so:

{
    hfModel: "black-forest-labs/FLUX.1-schnell",      // Hugging Face model name
    providerModel: "black-forest-labs/flux-schnell",  // Replicate model name
    task: "text-to-image",                            // Task name
}

To see allowable values for task, refer to huggingface.co/tasks.

Adding a new tag mapping

To add a new tag mapping, edit src/tags.ts

Add your new tag to the inferenceTags array, like so:

{
    type: 'tag-filter',
    task: 'text-to-image',
    tags: ['flux', 'lora'],
    providerModel: 'black-forest-labs/flux-dev-lora',
    adapterType: 'lora',
    status: 'live',
}

Tag mappings allow you to map multiple Hugging Face models to a single Replicate model based on their tags. This is useful when you have a single Replicate model that can handle multiple variations of a model (like different LoRA adapters).

Updating model mappings

This repo uses a GitHub Actions workflow to keep the model mappings up to date, as well as model warm/cold states.

The workflow runs on a schedule and is triggered on every push to the main branch, so you probably don't need to do anything!.

But if you need to run the sync manually, here's how:

1. Make sure your user is a member of the replicate organization on Hugging Face.
2. Create a Hugging Face token. It doesn't need to have any specific permissions.
3. Set the HF_TOKEN environment variable.

   export HF_TOKEN=<your-huggingface-token>

4. Run this command:

   npm install
   npm start

Listing Provider Mappings

This repo includes scripts to list available providers and their model mappings.

List Available Providers

To see all available inference providers:

npm run list-providers

This will output a JSON array of provider IDs, like:

[
  "cerebras",
  "cohere",
  "fal-ai",
  "fireworks",
  "hyperbolic",
  "hf-inference",
  "nebius",
  "novita",
  "replicate",
  "sambanova",
  "together"
]

List Provider Mappings

To see the model mappings for a specific provider:

npm run list-provider-mappings -- <provider-id>

For example, to see Replicate's mappings:

npm run list-provider-mappings -- replicate

This will output a JSON object containing all model mappings for the specified provider, organized by task type.

Delete a Mapping

To delete a specific model mapping:

npm run delete-mapping -- <mapping-id>

For example:

npm run delete-mapping -- "namespace/model-name"

This will permanently delete the specified mapping from Hugging Face. Use with caution!

Note: You'll need to set the HF_TOKEN environment variable to use these scripts:

export HF_TOKEN=<your-huggingface-token>