Vector search

Vector search is an experimental technology that uses Large Language Models to retrieve search results based on the meaning and context of a query.

This feature can improve search relevancy for queries that do not to match keywords in your dataset, allow your users to search images and other non-textual media, suggest related products in webshops, and create conversational search interfaces.

Vector search is available to all users. Meilisearch Cloud is the recommended way of using vector search.

If using Meilisearch Cloud, navigate to your project overview and find "Experimental features", then check the "vector store" box.

Alternatively, use the /experimental-features route to activate vector search during runtime:

curl \
  -X PATCH 'http://localhost:7700/experimental-features/' \
  -H 'Content-Type: application/json'  \
  --data-binary '{
    "vectorStore": true
  }'

To use vector search, first configure the embedders index setting. You may configure multiple embedders for an index.

Embedders generate vector data from your documents. Meilisearch natively supports the following embedders:

• OpenAI
• Hugging Face
• Ollama
• any embedder with a REST interface

It is also possible to supply custom embeddings. In this case, you must generate the embeddings manually and include them as a field in your documents.

curl \
  -X PATCH 'http://localhost:7700/indexes/movies/settings' \
  -H 'Content-Type: application/json' \
  --data-binary '{
    "embedders": {
      "default": {
        "source":  "openAi",
        "apiKey": "anOpenAiApiKey",
        "model": "text-embedding-3-small",
        "documentTemplate": "A movie titled {{doc.title}} whose description starts with {{doc.overview|truncatewords: 20}}",
        "dimensions": 1536
      }
    }
  }'

You may also provide custom embeddings. In this case, you must manually update your embeddings when adding, updating, and removing documents to your index.

Configure the embedder index setting:

curl \
  -X PATCH 'http://localhost:7700/indexes/movies/settings' \
  -H 'Content-Type: application/json' \
  --data-binary '{
    "embedders": {
      "image2text": {
        "source":  "userProvided",
        "dimensions": 3
      }
    }
  }'

Then, use the /documents endpoint to upload vectorized documents. Store vector data in your documents' _vectors field:

curl -X POST -H 'content-type: application/json' \
'localhost:7700/indexes/products/documents' \
--data-binary '[
    { "id": 0, "_vectors": {"image2text": [0, 0.8, -0.2]}, "text": "frying pan" },
    { "id": 1, "_vectors": {"image2text": [1, -0.2, 0]}, "text": "baking dish" }
]'

For mathematical reasons, the _rankingScore of semantic search results tend to be closely grouped around an average value that depends on the embedder and model used. This may result in relevant semantic hits being underrepresented and irrelevant semantic hits being overrepresented compared with keyword search hits.

Use distribution when configuring an embedder to correct the returned _rankingScores of the semantic hits with an affine transformation:

curl \
  -X PATCH 'http://localhost:7700/indexes/movies/settings' \
  -H 'Content-Type: application/json' \
  --data-binary '{
    "embedders": {
      "default": {
        "source":  "huggingFace",
        "model": "MODEL_NAME",
        "distribution": {
          "mean": 0.7,
          "sigma": 0.3
        }
      }
    }
  }'

Configuring distribution requires a certain amount of trial and error, in which you must perform semantic searches and monitor the results. Based on their rankingScores and relevancy, add the observed mean and sigma values for that index.

distribution is an optional field compatible with all embedder sources. It must be an object with two fields:

• mean: a number between 0 and 1 indicating the semantic score of "somewhat relevant" hits before using the distribution setting
• sigma: a number between 0 and 1 indicating the average absolute difference in _rankingScores between "very relevant" hits and "somewhat relevant" hits, and "somewhat relevant" hits and "irrelevant hits".

Changing distribution does not trigger a reindexing operation.

Perform searches with q and hybrid to retrieve search results using both keyword and semantic search:

curl -X POST -H 'content-type: application/json' \
  'localhost:7700/indexes/products/search' \
  --data-binary '{ 
    "q": "kitchen utensils",
    "hybrid": {
      "semanticRatio": 0.9,
      "embedder": "default"
    }
  }'

hybrid is an object and accepts two fields:

• semanticRatio: number between 0 and 1. 0 indicates full keyword search, 1 indicates full semantic search. Defaults to 0.5
• embedder: string, indicating one of the embedders configured for the queried index. Defaults to "default"

hybrid can be used together with other search parameters, including filter and sort:

curl -X POST -H 'content-type: application/json' \
  'localhost:7700/indexes/products/search' \
  --data-binary '{
    "q": "kitchen utensils",
    "hybrid": {
      "semanticRatio": 0.9,
      "embedder": "default"
    },
    "filter": "price < 10",
    "sort": ["price:asc"]
  }'

Use the vector search parameter to perform vector searches:

curl -X POST -H 'content-type: application/json' \
  'localhost:7700/indexes/products/search' \
  --data-binary '{ "vector": [0, 1, 2] }'

vector must be an array of numbers indicating the search vector. You must generate these yourself when using vector search with user-provided embeddings.

vector can be used together with other search parameters, including filter and sort:

curl -X POST -H 'content-type: application/json' \
  'localhost:7700/indexes/products/search' \
  --data-binary '{
    "vector": [0, 1, 2],
    "filter": "price < 10",
    "sort": ["price:asc"]
  }'

Manually remove all embedder configuration from your index:

curl \
  -X DELETE 'http://localhost:7700/indexes/movies/settings/embedders' \
  -H 'Content-Type: application/json'

If using Meilisearch Cloud, navigate to your project overview and find "Experimental features", then uncheck the "vector store" box.

Alternatively, use the /experimental route:

curl \
  -X PATCH 'http://localhost:7700/experimental-features/' \
  -H 'Content-Type: application/json'  \
  --data-binary '{
    "vectorStore": false
  }'

Consult the feature discussion on GitHub for the latest information on using vector search with Meilisearch. This feature is undergoing active development and any feedback you might have is welcome.