replicate/huggingface-model-mappings

replicate/huggingface-model-mappings

Description: 🤗 Mapping Replicate models to Hugging Face models

Language: TypeScript

Stars: 9

Forks: 2

Open issues: 1

Created: 2025-02-28T21:28:29Z

Pushed: 2026-05-06T18:55:41Z

Default branch: main

Fork: no

Archived: no

README:

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](src/models.ts) 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](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](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](.github/workflows/sync.yml) 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. 1. Create a Hugging Face token. It doesn't need to have any specific permissions. 1. Set the HF_TOKEN environment variable.

export HF_TOKEN=

1. 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 --

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 --

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=