diff --git a/.code-samples.meilisearch.yaml b/.code-samples.meilisearch.yaml index 33b8f35b72..81c50bf266 100644 --- a/.code-samples.meilisearch.yaml +++ b/.code-samples.meilisearch.yaml @@ -1295,7 +1295,7 @@ analytics_event_conversion_1: |- curl \ -X POST 'https://PROJECT_URL/events' \ -H 'Content-Type: application/json' \ - -H 'Authorization: Bearer DEFAULT_SEARCH_API_KEY' + -H 'Authorization: Bearer DEFAULT_SEARCH_API_KEY' \ --data-binary '{ "eventType": "conversion", "eventName": "Product Added To Cart", diff --git a/docs.json b/docs.json index 1b1ecbef23..764f848db7 100644 --- a/docs.json +++ b/docs.json @@ -191,6 +191,7 @@ { "group": "Personalization", "pages": [ + "learn/personalization/making_personalized_search_queries", "learn/personalization/search_personalization" ] }, diff --git a/learn/personalization/making_personalized_search_queries.mdx b/learn/personalization/making_personalized_search_queries.mdx new file mode 100644 index 0000000000..207b97c8a6 --- /dev/null +++ b/learn/personalization/making_personalized_search_queries.mdx @@ -0,0 +1,54 @@ +--- +title: Performing personalized search queries +description: Search personalization uses context about the person performing the search to provide results more relevant to that specific user. This article guides you through configuring and performing personalized search queries. +--- + +## Requirements + +- A Meilisearch project +- Self-hosted Meilisearch users: a Cohere API key + +## Activate personalized search + +### Cloud users + +Open a support ticket requesting Meilisearch to activate search personalization for your project. + +### Self-hosted users + +Relaunch your instance using the search personalization instance option: + +```sh +meilisearch --experimental-personalization-api-key="COHERE_API_KEY" +``` + +## Generating user context + +Search personalization requires a description about the user performing the search. Meilisearch does not currently provide automated generation of user context. + +You’ll need to **dynamically generate a plain-text user description** for each search request. This should summarize relevant traits, such as: + +- Category preferences, like brand or size +- Price sensitivity, like budget-conscious +- Possible use cases, such as fitness and sport +- Other assorted information, such as general interests or location + +The re-ranking model is optimized to favor positive signals. For best results, focus on affirmatively stated preferences, behaviors, and affinities, such as "likes the color red" and "prefers cheaper brands" over "dislikes blue" and "is not interested in luxury brands". + +## Perform a personalized search + +Once search personalization is active and you have a pipeline in place to generate user profiles, you are ready to perform personalized searches. + +Submit a search query and include the `personalize` search parameter. `personalize` must be an object with a single field, `userContext`. Use the description you generated in the previous step as the value for `userContext`: + +```sh +curl \ + -X POST 'MEILISEARCH_URL/indexes/INDEX_NAME/search' \ + -H 'Content-Type: application/json' \ + --data-binary '{ + "q": "wireless keyboard", + "personalize": { + "userContext": "The user prefers compact mechanical keyboards from Keychron or Logitech, with a mid-range budget and quiet keys for remote work." + } + }' +``` diff --git a/learn/personalization/search_personalization.mdx b/learn/personalization/search_personalization.mdx index 23cf0d836c..c0f1812094 100644 --- a/learn/personalization/search_personalization.mdx +++ b/learn/personalization/search_personalization.mdx @@ -18,8 +18,12 @@ For example, in an e-commerce site, someone who often shops for sportswear might 3. Meilisearch retrieves documents based on the user's query as usual 4. Finally, the re-ranking model reorders results based on the user context you provided in the first step -## How can I enable search personalization in Meilisearch? +## How to enable search personalization in Meilisearch? -Search personalization is still in early development and not publicly available. +Search personalization is an experimental feature. -If you are a Cloud customer and would like to try it out, [get in touch](https://meetings-eu1.hubspot.com/guillaume-mourier/search-personalization)! +If you are a Meilisearch Cloud user, contact support to activate it for your projects. + +If you are self-hosting Meilisearch, relaunch it using the [search personalization instance option](/learn/self_hosted/configure_meilisearch_at_launch#search-personalization). + +Consult the [search personalization guide](/learn/personalization/making_personalized_search_queries) for more information on how to implement it in your application. diff --git a/learn/resources/experimental_features_overview.mdx b/learn/resources/experimental_features_overview.mdx index 536c71aa0e..25ef051c38 100644 --- a/learn/resources/experimental_features_overview.mdx +++ b/learn/resources/experimental_features_overview.mdx @@ -62,3 +62,4 @@ Activating or deactivating experimental features this way does not require you t | [Multimodal search](/reference/api/settings) | Enable multimodal search | API route | | [Disable new indexer](/learn/self_hosted/configure_meilisearch_at_launch) | Use previous settings indexer | CLI flag or environment variable | | [Experimental vector store](/reference/api/settings) | Enables index setting to use experimental vector store | API route | +| [Search personalization](/learn/personalization/making_personalized_search_queries) | Enables search personalization | CLI flag or environment variable | diff --git a/learn/self_hosted/configure_meilisearch_at_launch.mdx b/learn/self_hosted/configure_meilisearch_at_launch.mdx index d947ed4b83..255d90d0fa 100644 --- a/learn/self_hosted/configure_meilisearch_at_launch.mdx +++ b/learn/self_hosted/configure_meilisearch_at_launch.mdx @@ -552,6 +552,15 @@ Helps running Meilisearch in cluster environments. It does this by modifying tas Falls back to previous settings indexer. +### Search personalization + +**Environment variable**: `MEILI_EXPERIMENTAL_PERSONALIZATION_API_KEY`
+**CLI option**: `--experimental-personalization-api-key`
+**Default value**: `None`
+**Expected value**: a Cohere API key + +Enables search personalization. Must be a valid Cohere API key in string format. + ### S3 options #### Bucket URL diff --git a/reference/api/search.mdx b/reference/api/search.mdx index 5fc0cfaa07..6b38cbf244 100644 --- a/reference/api/search.mdx +++ b/reference/api/search.mdx @@ -99,6 +99,7 @@ By default, [this endpoint returns a maximum of 1000 results](/learn/resources/k | **[`retrieveVectors`](#display-_vectors-in-response)** | Boolean | `false` | Return document and query vector data | | **[`locales`](#query-locales)** | Array of strings | `null` | Explicitly specify languages used in a query | | **[`media`](#media)** | Object | `null` | Perform AI-powered search queries with multimodal content | +| **[`personalize`](#search-personalization)** | Object | `null` | Perform AI-powered searches that return different results based on a user's profile | ### Response @@ -1371,3 +1372,17 @@ It is mandatory to specify an embedder when using `media`. `media` is incompatib … } ``` + +### Search personalization + +**Parameter**: `personalize`
+**Expected value**: Object
+**Default value**: `null` + + +This is an experimental feature. Contact Meilisearch Cloud support to enable it for your projects. If self-hosting, relaunch your instance providing a Cohere key to the search personalization instance option. + + +Adds user context to [personalize search results according to user profile](/learn/personalization/making_personalized_search_queries). + +`personalize` must be an object. It must include a single field, `userContext`.`userContext` must be a string describing the user performing the search. diff --git a/snippets/samples/code_samples_get_documents_1.mdx b/snippets/samples/code_samples_get_documents_1.mdx index f391ceffa3..199e8fe7cc 100644 --- a/snippets/samples/code_samples_get_documents_1.mdx +++ b/snippets/samples/code_samples_get_documents_1.mdx @@ -13,7 +13,10 @@ client.index('movies').getDocuments({ ``` ```python Python -client.index('movies').get_documents({'limit':2, 'filter': 'genres=action'}) +client.index('movies').get_documents({ + 'limit':2, 'filter': 'genres=action', + 'sort': ['rating:desc', 'release_date:asc'] # list format +}) ``` ```php PHP diff --git a/snippets/samples/code_samples_get_documents_post_1.mdx b/snippets/samples/code_samples_get_documents_post_1.mdx index a507357f04..6fac124c55 100644 --- a/snippets/samples/code_samples_get_documents_post_1.mdx +++ b/snippets/samples/code_samples_get_documents_post_1.mdx @@ -23,7 +23,8 @@ client.index('books').getDocuments({ client.index('books').get_documents({ 'limit':3, 'fields': ['title', 'genres', 'rating', 'language'], - 'filter': '(rating > 3 AND (genres=Adventure OR genres=Fiction)) AND language=English' + 'filter': '(rating > 3 AND (genres=Adventure OR genres=Fiction)) AND language=English', + 'sort': 'rating:desc, title:asc' # comma-separated string format }) ```