Configure the embedder index setting, setting its source to userProvided:
curl \
-X PATCH 'MEILISEARCH_URL/indexes/INDEX_NAME/settings' \
-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 '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.
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]
}
}
{
"_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 'Content-Type: application/json' \
--data-binary '{
"vector": [0, 1, 2],
"hybrid": {
"embedder": "EMBEDDER_NAME"
}
}'
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 '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.
