## Configure HuggingFace embedder

The HuggingFace embedder runs open-source models directly on your machine or server. This eliminates external API calls, giving you full control over latency and data privacy. It is best suited for self-hosted Meilisearch instances with small, static datasets.

Running the HuggingFace embedder locally requires sufficient server resources (CPU and RAM) for the chosen model.

### Choose a model

HuggingFace hosts thousands of embedding models. Here are some recommended options for different use cases:

| Model | Dimensions | Best for |
| --- | --- | --- |
| `BAAI/bge-base-en-v1.5` | 768 | English content, good balance of speed and accuracy |
| `BAAI/bge-small-en-v1.5` | 384 | English content, faster with lower resource usage |
| `sentence-transformers/all-MiniLM-L6-v2` | 384 | General English text, lightweight |
| `sentence-transformers/paraphrase-multilingual-MiniLM-L12-v2` | 384 | Multilingual content |

For most self-hosted use cases, `BAAI/bge-base-en-v1.5` provides a good balance of accuracy and performance. If server resources are limited, choose a smaller model like `BAAI/bge-small-en-v1.5`.

### Configure the embedder

Create an embedder object with the `huggingFace` source:

```
{
  "my-hf": {
    "source": "huggingFace",
    "model": "BAAI/bge-base-en-v1.5",
    "documentTemplate": "A product named '{{doc.name}}' described as '{{doc.description}}'"
  }
}
```

In this configuration,  
- `source`: must be "huggingFace" to run the model locally  
- `model`: the HuggingFace model identifier. Meilisearch downloads the model automatically on first use  
- `documentTemplate`: a [Liquid template](/content/docs/capabilities/hybrid_search/advanced/document_template_best_practices/index.html) that converts your documents into text for embedding

Unlike cloud-based embedders, the HuggingFace source does not require an API key.

### Pin a model revision with `revision`

Use the optional `revision` field to pin a specific revision of a HuggingFace model. The value is a commit hash, branch name, or tag from the model repository.

```
{
  "my-hf": {
    "source": "huggingFace",
    "model": "BAAI/bge-base-en-v1.5",
    "revision": "a5beb1e3e68b9ab74eb54cfb186926f2123bc4b3"
  }
}
```

`revision` is optional and only valid for the `huggingFace` embedder. Pinning a revision makes your indexing output reproducible even if the upstream model is updated.

### Choose a pooling method with `pooling`

HuggingFace models combine per-token output vectors into a single document vector using a pooling strategy. The `pooling` field controls this behavior:

| Value | Behavior |
| --- | --- |
| "useModel" | Meilisearch fetches the pooling method from the model configuration. **Default value for new embedders.** |
| "forceMean" | Always use mean pooling. |
| "forceCls" | Always use CLS pooling. |

If in doubt, use "useModel". "forceMean" and "forceCls" are compatibility options that might be necessary for certain embedders and models.

`pooling` is optional for embedders with the `huggingFace` source. It is invalid for all other embedder sources.

### Update your index settings

Send the embedder configuration to Meilisearch:

```
curl \
  -X PATCH 'MEILISEARCH_URL/indexes/INDEX_NAME/settings' \
  -H 'Content-Type: application/json' \
  -H 'Authorization: Bearer MEILISEARCH_KEY' \
  --data-binary '{
    "embedders": {
      "my-hf": {
        "source": "huggingFace",
        "model": "BAAI/bge-base-en-v1.5",
        "documentTemplate": "A product named '{{doc.name}}' described as '{{doc.description}}'"
      }
    }
  }'
```

Replace `MEILISEARCH_URL` with the address of your Meilisearch instance, `INDEX_NAME` with your index name, and `MEILISEARCH_KEY` with your Meilisearch API key. On the first request, Meilisearch downloads the model from HuggingFace. This may take a few minutes depending on the model size and your internet connection. After downloading, Meilisearch generates embeddings for all documents in the index. Monitor progress through the [task queue](/content/docs/reference/api/tasks/list-tasks/index.html).

### Performance considerations

The HuggingFace embedder runs on the same machine as Meilisearch. Keep these points in mind:
- **CPU usage**: Embedding generation is computationally intensive. Expect higher CPU usage during indexing, especially with large datasets.
- **Memory**: Each model requires memory to load. Larger models like `bge-base-en-v1.5` (768 dimensions) use more RAM than smaller models like `bge-small-en-v1.5` (384 dimensions).
- **Indexing speed**: Local embedding generation is slower than cloud-based providers for large datasets. For datasets over 10,000 documents that are updated frequently, consider using a cloud-based embedder instead.
- **Search latency**: Once indexed, search performance is comparable to cloud-based embedders since the model runs locally without network overhead.

Meilisearch Cloud does not support embedders with `{ "source": "huggingFace" }`. To use HuggingFace models on Meilisearch Cloud, deploy a [HuggingFace Inference Endpoint](https://ui.endpoints.huggingface.co/) and configure a [REST embedder](/content/docs/capabilities/hybrid_search/how_to/configure_rest_embedder/index.html) pointing to it. See the [HuggingFace Inference Endpoints guide](/content/docs/capabilities/hybrid_search/providers/huggingface/index.html) for detailed instructions.

### Test the embedder

Once indexing is complete, perform a search using the `hybrid` parameter:

```
{
  "q": "something to stir soup with",
  "hybrid": {
    "semanticRatio": 0.5,
    "embedder": "my-hf"
  }
}
```

A [`semanticRatio`](/content/docs/capabilities/hybrid_search/advanced/custom_hybrid_ranking/index.html) of `0.5` returns a balanced mix of keyword and semantic results. Adjust this value based on your needs.

### Next steps

[**Full HuggingFace guide** \ 
Using HuggingFace Inference Endpoints with the REST embedder](/content/docs/capabilities/hybrid_search/providers/huggingface/index.html)  
[**Choose an embedder** \ 
Compare HuggingFace with other embedder providers](/content/docs/capabilities/hybrid_search/how_to/choose_an_embedder/index.html)