Use AI-powered search with user-provided embeddings

Configure a custom embedder

Configure the embedder index setting, setting its source to userProvided:

curl \
  -X PATCH 'MEILISEARCH_URL/indexes/INDEX_NAME/settings' \
  -H 'Authorization: Bearer API_KEY' \
  -H 'Content-Type: application/json' \
  --data-binary '{
    "embedders": {
      "EMBEDDER_NAME": {
        "source": "userProvided",
        "dimensions": MODEL_DIMENSIONS
      }
    }
  }'

Embedders with source: userProvided are incompatible with documentTemplate and documentTemplateMaxBytes.

Add documents to Meilisearch

Next, use the /documents endpoint to upload vectorized documents. Place vector data in your documents’ _vectors field:

curl \
  -X POST 'MEILISEARCH_URL/indexes/INDEX_NAME/documents' \
  -H 'Authorization: Bearer API_KEY' \
  -H 'Content-Type: application/json' \
  --data-binary '[
    { "id": 0, "_vectors": { "EMBEDDER_NAME": [0, 0.8, -0.2]}, "text": "frying pan" },
    { "id": 1, "_vectors": { "EMBEDDER_NAME": [1, -0.2, 0]}, "text": "baking dish" }
  ]'

The `_vectors` field in detail

Meilisearch stores pre-computed embeddings under the reserved _vectors field of a document. The field is an object whose keys match the names of the embedders configured in your index settings.

Full object form: `embeddings` + `regenerate`

Each embedder entry accepts two fields, embeddings and regenerate:

{
  "id": 0,
  "title": "Kung Fu Panda",
  "_vectors": {
    "default": {
      "embeddings": [0.003, 0.1, 0.75],
      "regenerate": false
    }
  }
}

embeddings is optional. It must be an array of numbers representing a single embedding for that document. It may also be an array of arrays of numbers, representing multiple embeddings for the same document. embeddings defaults to null.
regenerate is mandatory and must be a boolean. If regenerate is true, Meilisearch automatically generates embeddings for that document immediately and every time the document is updated. If regenerate is false, Meilisearch keeps the last value of embeddings on document updates and never overwrites it.

Use embeddings as an array of arrays when a single document should be represented by multiple vectors (for example, one embedding per paragraph, or one per language).

Array shorthand

You may also use an array shorthand to add embeddings to a document:

{
  "_vectors": {
    "default": [0.003, 0.1, 0.75]
  }
}

Vector embeddings added with the shorthand are not replaced when Meilisearch generates new embeddings. The example above is equivalent to:

{
  "_vectors": {
    "default": {
      "embeddings": [0.003, 0.1, 0.75],
      "regenerate": false
    }
  }
}

Null or empty embedder entries

If the key for an embedder inside _vectors is empty or null, Meilisearch treats the document as not having any embeddings for that embedder. This document is then returned last during AI-powered searches.

Vector search with user-provided embeddings

When using a custom embedder, you must vectorize both your documents and user queries. Once you have the query’s vector, pass it to the vector search parameter to perform an AI-powered search:

curl \
  -X POST 'MEILISEARCH_URL/indexes/INDEX_NAME/search' \
  -H 'Authorization: Bearer API_KEY' \
  -H 'Content-Type: application/json' \
  --data-binary '{
    "vector": [0, 1, 2],
    "hybrid": {
      "embedder": "EMBEDDER_NAME"
    }
  }'

client.index('books').search('',{
  "vector": [0, 1, 2],
  "hybrid": {
    "embedder": "EMBEDDER_NAME"
  }
})

let results = index
  .search()
  .with_vector(&[0.0, 1.0, 2.0])
  .with_hybrid("EMBEDDER_NAME", 1.0)
  .execute()
  .await
  .unwrap();

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 is mandatory when performing searches with userProvided embedders. You may also use vector with automatic embedders to override an embedder’s automatic vector generation, for example to experiment with a custom-generated query vector without changing your embedder configuration.

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

curl \
  -X POST 'MEILISEARCH_URL/indexes/INDEX_NAME/search' \
  -H 'Authorization: Bearer API_KEY' \
  -H 'Content-Type: application/json' \
  --data-binary '{
    "vector": [0, 1, 2],
    "filter": "price < 10",
    "sort": ["price:asc"],
    "hybrid": {
      "embedder": "EMBEDDER_NAME"
    }
  }'

Return stored vectors with `retrieveVectors`

Set retrieveVectors: true on a search request to return document and query embeddings alongside the search results. When enabled, Meilisearch displays vector data in each document’s _vectors field.

_vectors must be included in the index’s displayedAttributes list for it to be returned in the response. If displayedAttributes does not contain _vectors (or *), retrieveVectors has no visible effect on the response payload.

Capabilities

Full-text search

Hybrid and semantic search

Geo search

Agentic search

Multi-search

Filtering, sorting, and faceting

Personalization

Analytics

Security and tenant tokens

Search rules

Platform

Indexing

Use AI-powered search with user-provided embeddings

Configure a custom embedder

Add documents to Meilisearch

The `_vectors` field in detail

Full object form: `embeddings` + `regenerate`

Array shorthand

Null or empty embedder entries

Vector search with user-provided embeddings

Return stored vectors with `retrieveVectors`

​Configure a custom embedder

​Add documents to Meilisearch

​The _vectors field in detail

​Full object form: embeddings + regenerate

​Array shorthand

​Null or empty embedder entries

​Vector search with user-provided embeddings

​Return stored vectors with retrieveVectors

Configure a custom embedder

Add documents to Meilisearch

The `_vectors` field in detail

Full object form: `embeddings` + `regenerate`

Array shorthand

Null or empty embedder entries

Vector search with user-provided embeddings

Return stored vectors with `retrieveVectors`