> ## Documentation Index
> Fetch the complete documentation index at: https://www.meilisearch.com/docs/llms.txt
> Use this file to discover all available pages before exploring further.

# Semantic Search with Hugging Face Inference Endpoints

> This guide will walk you through the process of setting up Meilisearch with Hugging Face Inference Endpoints.

This guide shows you how to set up a Meilisearch REST embedder with [Hugging Face Inference Endpoints](https://ui.endpoints.huggingface.co/) for semantic search.

> [!NOTE]
>
> You can use Hugging Face and Meilisearch in two ways: running the model locally by setting the embedder source to `huggingFace`, or remotely on Hugging Face's servers by setting the embedder source to `rest`.

## Popular models

Hugging Face hosts hundreds of sentence embedding models. Some popular choices:

| Model | Dimensions | Notes |
| - | - | - |
| `BAAI/bge-small-en-v1.5` | 384 | Fast, English-only, great for most use cases |
| `BAAI/bge-large-en-v1.5` | 1,024 | Higher quality English embeddings |
| `BAAI/bge-multilingual-gemma2` | varies | Multilingual, based on Gemma 2 |
| `sentence-transformers/all-MiniLM-L6-v2` | 384 | Lightweight and fast |
| `sentence-transformers/all-mpnet-base-v2` | 768 | Higher quality general-purpose |
| `sentence-transformers/paraphrase-multilingual-MiniLM-L12-v2` | 384 | Multilingual, lightweight |
| `intfloat/multilingual-e5-large` | 1,024 | Strong multilingual performance |

Browse the full catalog of available models on the [Hugging Face Inference Endpoints catalog](https://ui.endpoints.huggingface.co/catalog?task=sentence-embeddings).

## Requirements

* A [Meilisearch Cloud](https://www.meilisearch.com/cloud) project or a self-hosted instance
* A [Hugging Face account](https://huggingface.co/) with a deployed inference endpoint
* The endpoint URL and API key of the deployed model

## Configure the embedder

Set up an embedder using the update settings endpoint:

```json theme={null}
{
  "hf-inference": {
    "source": "rest",
    "url": "ENDPOINT_URL",
    "apiKey": "API_KEY",
    "dimensions": 384,
    "documentTemplate": "CUSTOM_LIQUID_TEMPLATE",
    "request": {
      "inputs": ["{{text}}", "{{..}}"],
      "model": "baai/bge-small-en-v1.5"
    },
    "response": ["{{embedding}}", "{{..}}"]
  }
}
```

In this configuration:

* `source`: declares Meilisearch should connect to this embedder via its REST API
* `url`: replace `ENDPOINT_URL` with the address of your Hugging Face model endpoint
* `apiKey`: replace `API_KEY` with your Hugging Face API key
* `dimensions`: specifies the dimensions of the embeddings, which are 384 for `baai/bge-small-en-v1.5`
* `documentTemplate`: an optional but recommended [template](https://www.meilisearch.com/docs/capabilities/hybrid_search/getting_started.md) for the data you will send the embedder
* `request`: defines the structure and parameters of the request Meilisearch will send to the embedder
* `response`: defines the structure of the embedder's  response

Once you've configured the embedder, Meilisearch will automatically generate embeddings for your documents. Monitor the task using the Cloud UI or the [list tasks endpoint](https://www.meilisearch.com/docs/reference/api/tasks/list-tasks.md).

> [!NOTE]
>
> This example uses [BAAI/bge-small-en-v1.5](https://huggingface.co/BAAI/bge-small-en-v1.5) as its model. See the [popular models](#popular-models) section above for alternatives, or browse the full [Inference Endpoints catalog](https://ui.endpoints.huggingface.co/catalog?task=sentence-embeddings).

## Perform a semantic search

With the embedder set up, you can now perform semantic searches. Make a search request with the `hybrid` search parameter, setting `semanticRatio` to `1`:

```json theme={null}
{
  "q": "QUERY_TERMS",
  "hybrid": {
    "semanticRatio": 1,
    "embedder": "hf-inference"
  }
}
```

In this request:

* `q`: the search query
* `hybrid`: enables AI-powered search functionality
  * `semanticRatio`: controls the balance between semantic search and full-text search. Setting it to `1` means you will only receive semantic search results
  * `embedder`: the name of the embedder used for generating embeddings

## Conclusion

You have set up with an embedder using Hugging Face Inference Endpoints. This allows you to use pure semantic search capabilities in your application.

Consult the [embedder setting documentation](https://www.meilisearch.com/docs/reference/api/settings/list-all-settings.md) for more information on other embedder configuration options.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.