diff --git a/guides/ai/getting_started_with_chat.mdx b/guides/ai/getting_started_with_chat.mdx index efb2a5430..689c9c119 100644 --- a/guides/ai/getting_started_with_chat.mdx +++ b/guides/ai/getting_started_with_chat.mdx @@ -13,11 +13,20 @@ The chat completions feature is experimental and must be enabled before use. See ## Prerequisites Before starting, ensure you have: -- Meilisearch instance running (v1.15.1 or later) + +- Meilisearch instance running (v1.15.1 or later) **with a master key** (required for authentication) - An API key from an LLM provider (OpenAI, Azure OpenAI, Mistral, Gemini, or access to a vLLM server) - At least one index with searchable content - The chat completions experimental feature enabled + +**Important**: You MUST start Meilisearch with a master key to enable authentication. Without it, the chat feature will not work properly. + +Example: `meilisearch --master-key yourMasterKey` + +In some versions, you may also need to add the `--experimental-enable-chat` flag when starting Meilisearch. + + ## Quick start ### Enable the chat completions feature @@ -26,14 +35,48 @@ First, enable the chat completions experimental feature: ```bash curl \ - -X PATCH 'http://localhost:7700/experimental-features' \ - -H 'Authorization: Bearer MASTER_KEY' \ + -X PATCH 'http://localhost:7700/experimental-features/' \ + -H 'Authorization: Bearer ' \ -H 'Content-Type: application/json' \ --data-binary '{ "chatCompletions": true }' ``` +### Find your chat API key + +When Meilisearch runs with a master key, it automatically creates a "Default Chat API Key" with `chatCompletions` permission. Find it using: + +```bash +curl http://localhost:7700/keys \ + -H "Authorization: Bearer " +``` + +Look for the key with "Default Chat API Key" in the description. You'll use this key (or the master key) for chat endpoint requests. + +### Configure your indexes for chat + +Each index that you want to be searchable through chat needs specific configuration: + +```bash +curl \ + -X PATCH 'http://localhost:7700/indexes/movies/settings' \ + -H 'Authorization: Bearer ' \ + -H 'Content-Type: application/json' \ + --data-binary '{ + "chat": { + "description": "A comprehensive movie database containing titles, descriptions, genres, and release dates to help users find movies", + "documentTemplate": "{% for field in fields %}{% if field.is_searchable and field.value != nil %}{{ field.name }}: {{ field.value }}\n{% endif %}{% endfor %}", + "documentTemplateMaxBytes": 400, + "searchParameters": {} + } + }' +``` + + +The `description` field helps the LLM understand what data is in the index, improving search relevance. + + ### Configure a chat completions workspace Create a workspace with your LLM provider settings. Here are examples for different providers: @@ -42,12 +85,13 @@ Create a workspace with your LLM provider settings. Here are examples for differ ```bash openAi curl \ - -X PATCH 'http://localhost:7700/chats/my-assistant/settings' \ - -H 'Authorization: Bearer MASTER_KEY' \ + -X PUT 'http://localhost:7700/chats/my-assistant/settings' \ + -H 'Authorization: Bearer ' \ -H 'Content-Type: application/json' \ --data-binary '{ "source": "openAi", "apiKey": "sk-abc...", + "baseUrl": "https://api.openai.com/v1", "prompts": { "system": "You are a helpful assistant. Answer questions based only on the provided context." } @@ -56,8 +100,8 @@ curl \ ```bash azureOpenAi curl \ - -X PATCH 'http://localhost:7700/chats/my-assistant/settings' \ - -H 'Authorization: Bearer MASTER_KEY' \ + -X PUT 'http://localhost:7700/chats/my-assistant/settings' \ + -H 'Authorization: Bearer ' \ -H 'Content-Type: application/json' \ --data-binary '{ "source": "azureOpenAi", @@ -71,8 +115,8 @@ curl \ ```bash mistral curl \ - -X PATCH 'http://localhost:7700/chats/my-assistant/settings' \ - -H 'Authorization: Bearer MASTER_KEY' \ + -X PUT 'http://localhost:7700/chats/my-assistant/settings' \ + -H 'Authorization: Bearer ' \ -H 'Content-Type: application/json' \ --data-binary '{ "source": "mistral", @@ -85,8 +129,8 @@ curl \ ```bash gemini curl \ - -X PATCH 'http://localhost:7700/chats/my-assistant/settings' \ - -H 'Authorization: Bearer MASTER_KEY' \ + -X PUT 'http://localhost:7700/chats/my-assistant/settings' \ + -H 'Authorization: Bearer ' \ -H 'Content-Type: application/json' \ --data-binary '{ "source": "gemini", @@ -99,8 +143,8 @@ curl \ ```bash vLlm curl \ - -X PATCH 'http://localhost:7700/chats/my-assistant/settings' \ - -H 'Authorization: Bearer MASTER_KEY' \ + -X PUT 'http://localhost:7700/chats/my-assistant/settings' \ + -H 'Authorization: Bearer ' \ -H 'Content-Type: application/json' \ --data-binary '{ "source": "vLlm", @@ -115,25 +159,29 @@ curl \ ### Send your first chat completions request -Now you can start a conversation: +Now you can start a conversation. Note the `-N` flag for handling streaming responses: ```bash -curl \ +curl -N \ -X POST 'http://localhost:7700/chats/my-assistant/chat/completions' \ - -H 'Authorization: Bearer DEFAULT_CHAT_KEY' \ + -H 'Authorization: Bearer ' \ -H 'Content-Type: application/json' \ --data-binary '{ "model": "gpt-3.5-turbo", "messages": [ { "role": "user", - "content": "What is Meilisearch?" + "content": "What movies do you have about space exploration?" } ], "stream": true }' ``` + +Currently, only streaming responses (`stream: true`) are supported. Non-streaming responses are not yet available and will result in an error. + + ## Understanding workspaces Workspaces allow you to create isolated chat configurations for different use cases: @@ -143,6 +191,7 @@ Workspaces allow you to create isolated chat configurations for different use ca - **Documentation**: Tune for technical Q&A Each workspace maintains its own: + - LLM provider configuration - System prompt @@ -157,7 +206,7 @@ import OpenAI from 'openai'; const client = new OpenAI({ baseURL: 'http://localhost:7700/chats/my-assistant', - apiKey: 'YOUR_MEILISEARCH_API_KEY', + apiKey: 'YOUR_CHAT_API_KEY', }); const completion = await client.chat.completions.create({ @@ -176,7 +225,7 @@ from openai import OpenAI client = OpenAI( base_url="http://localhost:7700/chats/my-assistant", - api_key="YOUR_MEILISEARCH_API_KEY" + api_key="YOUR_CHAT_API_KEY" ) stream = client.chat.completions.create( @@ -195,7 +244,7 @@ import OpenAI from 'openai'; const client = new OpenAI({ baseURL: 'http://localhost:7700/chats/my-assistant', - apiKey: 'YOUR_MEILISEARCH_API_KEY', + apiKey: 'YOUR_CHAT_API_KEY', }); const stream = await client.chat.completions.create({ @@ -223,7 +272,7 @@ import OpenAI from 'openai'; const client = new OpenAI({ baseURL: 'http://localhost:7700/chats/my-assistant', - apiKey: 'YOUR_MEILISEARCH_API_KEY', + apiKey: 'YOUR_CHAT_API_KEY', }); try { @@ -247,7 +296,7 @@ from openai import OpenAI client = OpenAI( base_url="http://localhost:7700/chats/my-assistant", - api_key="YOUR_MEILISEARCH_API_KEY" + api_key="YOUR_CHAT_API_KEY" ) try: @@ -267,6 +316,225 @@ except Exception as error: +## Enabling database search with Meilisearch tools + + +**Critical**: Without including the Meilisearch tools in your request, the chat will only use the LLM's general knowledge and won't search your actual Meilisearch indexes! + + +To make the chat search your Meilisearch indexes, you must include these special tools in your request: + +```bash +curl -N \ + -X POST 'http://localhost:7700/chats/my-assistant/chat/completions' \ + -H 'Authorization: Bearer ' \ + -H 'Content-Type: application/json' \ + --data-binary '{ + "model": "gpt-3.5-turbo", + "messages": [ + { + "role": "user", + "content": "What movies do you have about space exploration?" + } + ], + "stream": true, + "tools": [ + { + "type": "function", + "function": { + "name": "_meiliSearchProgress", + "description": "Reports real-time search progress to the user" + } + }, + { + "type": "function", + "function": { + "name": "_meiliSearchSources", + "description": "Provides sources and references for the information" + } + } + ] + }' +``` + +These tools enable: + +- **`_meiliSearchProgress`**: Shows users what searches are being performed +- **`_meiliSearchSources`**: Provides the actual documents used to generate responses + +## Troubleshooting + +### Common issues and solutions + +#### Empty reply from server (curl error 52) + +**Causes:** + +- Meilisearch not started with a master key +- Experimental features not enabled +- Missing authentication in requests + +**Solution:** + +1. Restart Meilisearch with a master key: `meilisearch --master-key yourKey` +2. Enable experimental features (see setup instructions above) +3. Include Authorization header in all requests + +#### "Invalid API key" error + +**Cause:** Using the wrong type of API key + +**Solution:** + +- Use either the master key or the "Default Chat API Key" +- Don't use search or admin API keys for chat endpoints +- Find your chat key: `curl http://localhost:7700/keys -H "Authorization: Bearer "` + +#### "Socket connection closed unexpectedly" + +**Cause:** Usually means the OpenAI API key is missing or invalid in workspace settings + +**Solution:** + +1. Check workspace configuration: + + ```bash + curl http://localhost:7700/chats/my-assistant/settings \ + -H "Authorization: Bearer " + ``` + +2. Update with valid API key: + + ```bash + curl -X PUT http://localhost:7700/chats/my-assistant/settings \ + -H "Authorization: Bearer " \ + -H "Content-Type: application/json" \ + -d '{"apiKey": "your-valid-api-key"}' + ``` + +#### Chat not searching the database + +**Cause:** Missing Meilisearch tools in the request + +**Solution:** + +- Include `_meiliSearchProgress` and `_meiliSearchSources` tools in your request +- Ensure indexes have proper chat descriptions configured + +#### "stream: false is not supported" error + +**Cause:** Trying to use non-streaming responses + +**Solution:** + +- Always set `"stream": true` in your requests +- Non-streaming responses are not yet supported + +## Complete working example + +Here's a full example showing the complete setup process: + +### Step 1: Start Meilisearch with authentication + +```bash +meilisearch --master-key myMasterKey123 +``` + +### Step 2: Enable experimental features + +```bash +curl -X PATCH 'http://localhost:7700/experimental-features/' \ + -H 'Authorization: Bearer myMasterKey123' \ + -H 'Content-Type: application/json' \ + -d '{"chatCompletions": true}' +``` + +### Step 3: Create and populate an index + +```bash +# Create index +curl -X POST 'http://localhost:7700/indexes' \ + -H 'Authorization: Bearer myMasterKey123' \ + -H 'Content-Type: application/json' \ + -d '{"uid": "movies", "primaryKey": "id"}' + +# Add documents +curl -X POST 'http://localhost:7700/indexes/movies/documents' \ + -H 'Authorization: Bearer myMasterKey123' \ + -H 'Content-Type: application/json' \ + -d '[ + {"id": 1, "title": "Interstellar", "description": "A team of explorers travel through a wormhole in space"}, + {"id": 2, "title": "The Martian", "description": "An astronaut becomes stranded on Mars"} + ]' +``` + +### Step 4: Configure index for chat + +```bash +curl -X PATCH 'http://localhost:7700/indexes/movies/settings' \ + -H 'Authorization: Bearer myMasterKey123' \ + -H 'Content-Type: application/json' \ + -d '{ + "chat": { + "description": "A movie database with titles and descriptions", + "documentTemplate": "Title: {{ title }}\nDescription: {{ description }}\n", + "documentTemplateMaxBytes": 400 + } + }' +``` + +### Step 5: Create chat workspace + +```bash +curl -X PUT 'http://localhost:7700/chats/movie-advisor/settings' \ + -H 'Authorization: Bearer myMasterKey123' \ + -H 'Content-Type: application/json' \ + -d '{ + "source": "openAi", + "apiKey": "sk-your-openai-key", + "prompts": { + "system": "You are a movie recommendation assistant. Help users find movies based on their preferences." + } + }' +``` + +### Step 6: Get your chat API key + +```bash +curl http://localhost:7700/keys \ + -H "Authorization: Bearer myMasterKey123" \ + | grep -A 5 "Default Chat API Key" +``` + +### Step 7: Make a chat request with tools + +```bash +curl -N -X POST 'http://localhost:7700/chats/movie-advisor/chat/completions' \ + -H 'Authorization: Bearer ' \ + -H 'Content-Type: application/json' \ + -d '{ + "model": "gpt-3.5-turbo", + "messages": [{"role": "user", "content": "What space movies do you have?"}], + "stream": true, + "tools": [ + { + "type": "function", + "function": { + "name": "_meiliSearchProgress", + "description": "Reports search progress" + } + }, + { + "type": "function", + "function": { + "name": "_meiliSearchSources", + "description": "Provides source documents" + } + } + ] + }' +``` + ## Next steps - Explore [advanced chat API features](/reference/api/chats) diff --git a/reference/api/chats.mdx b/reference/api/chats.mdx index e4de0c132..07f62d525 100644 --- a/reference/api/chats.mdx +++ b/reference/api/chats.mdx @@ -19,6 +19,7 @@ curl \ "chatCompletions": true }' ``` + ## Chat completions workspace object @@ -35,10 +36,10 @@ curl \ ## Update the chat workspace settings - + -The first call to `PATCH /chats/{workspace}/settings` will create the workspace UID if it doesn’t already exist. +Both `PUT` and `PATCH` methods are supported. The first call to either method will create the workspace UID if it doesn't already exist. `PUT` replaces the entire configuration, while `PATCH` updates only the provided fields. Configure the LLM provider and settings for a chat workspace. @@ -86,7 +87,6 @@ Configure the LLM provider and settings for a chat workspace. | **`searchQParam`** | String | A prompt to explain what the `q` parameter of the search function does and how to use it | | **`searchIndexUidParam`** | String | A prompt to explain what the `indexUid` parameter of the search function does and how to use it | - ### Request body ```json @@ -250,7 +250,7 @@ data: [DONE] ```bash cURL -curl \ +curl -N \ -X POST 'http://localhost:7700/chats/customer-support/chat/completions' \ -H 'Authorization: Bearer DEFAULT_CHAT_KEY' \ -H 'Content-Type: application/json' \ @@ -553,11 +553,13 @@ This tool reports real-time progress of internal search operations. When declare **Purpose**: Provides transparency about search operations and reduces perceived latency by showing users what's happening behind the scenes. **Arguments**: + - `call_id`: Unique identifier to track the search operation - `function_name`: Name of the internal function being executed (e.g., "_meiliSearchInIndex") - `function_parameters`: JSON-encoded string containing search parameters like `q` (query) and `index_uid` **Example Response**: + ```json { "function": { @@ -574,12 +576,14 @@ Since the `/chats/{workspace}/chat/completions` endpoint is stateless, this tool **Purpose**: Maintains conversation context for better response quality in subsequent requests by preserving tool calls and results. **Arguments**: + - `role`: Message author role ("user" or "assistant") - `content`: Message content (for tool results) - `tool_calls`: Array of tool calls made by the assistant - `tool_call_id`: ID of the tool call this message responds to **Example Response**: + ```json { "function": { @@ -596,10 +600,12 @@ This tool provides the source documents that were used by the LLM to generate re **Purpose**: Shows users which documents were used to generate responses, improving trust and enabling source verification. **Arguments**: + - `call_id`: Matches the `call_id` from `_meiliSearchProgress` to associate queries with results - `documents`: JSON object containing the source documents with only displayed attributes **Example Response**: + ```json { "function": { diff --git a/reference/api/settings.mdx b/reference/api/settings.mdx index 47476cebf..ad7845256 100644 --- a/reference/api/settings.mdx +++ b/reference/api/settings.mdx @@ -2925,22 +2925,24 @@ To remove a single embedder, use the [update embedder settings endpoint](#update You can use the returned `taskUid` to get more details on [the status of the task](/reference/api/tasks#get-one-task). -## Conversation +## Chat This is an experimental feature. Use the Meilisearch Cloud UI or the experimental features endpoint to activate it: ```sh curl \ - -X PATCH 'MEILISEARCH_URL/experimental-features/' \ + -X PATCH 'http://localhost:7700/experimental-features/' \ + -H 'Authorization: Bearer ' \ -H 'Content-Type: application/json' \ --data-binary '{ "chatCompletions": true }' ``` + -Conversational querying allows a more human-like interaction with your search engine. It enables you to ask questions and receive relevant answers based on the content of your documents. +The chat settings allow you to configure how your index integrates with Meilisearch's conversational search feature. This enables the chat completions endpoint to search your index and generate responses based on your documents. ### Chat object @@ -2948,17 +2950,17 @@ The chat object in the index settings contains multiple settings to configure th ```json { - "description": "Contains a bunch of movies from the IMdb database. Each movie has a title, overview, and rating.", - "documentTemplate": "A movie titled '{{doc.title}}' whose description starts with {{doc.overview|truncatewords: 20}}", + "description": "A comprehensive movie database containing titles, overviews, genres, and release dates to help users find movies", + "documentTemplate": "{% for field in fields %}{% if field.is_searchable and field.value != nil %}{{ field.name }}: {{ field.value }}\n{% endif %}{% endfor %}", "documentTemplateMaxBytes": 400, "searchParameters": { "hybrid": { "embedder": "my-embedder" }, - "limit": 20, + "limit": 20 } } ``` -These embedder objects may contain the following fields: +The chat object may contain the following fields: | Name | Type | Default Value | Description | | ------------------------------ | ------- | --------------------------------------- | ---------------------------------------------------------------------------------------------------- | @@ -2970,13 +2972,14 @@ These embedder objects may contain the following fields: ### Search parameters object Corresponds to a subset of the [search parameters object](/reference/api/search#search-parameters-object): - - **`hybrid`** - - **`limit`** - - **`sort`** - - **`distinct`** - - **`matchingStrategy`** - - **`attributesToSearchOn`** - - **`rankingScoreThreshold`** + +- **`hybrid`** +- **`limit`** +- **`sort`** +- **`distinct`** +- **`matchingStrategy`** +- **`attributesToSearchOn`** +- **`rankingScoreThreshold`** ### Get index chat settings @@ -2992,7 +2995,11 @@ Get the index chat settings configured for an index. #### Example - +```bash +curl \ + -X GET 'http://localhost:7700/indexes/movies/settings/chat' \ + -H 'Authorization: Bearer ' +``` ##### Response: `200 OK` @@ -3035,3 +3042,34 @@ Partially update the index chat settings for an index. } } ``` + +#### Example + +```bash +curl \ + -X PATCH 'http://localhost:7700/indexes/movies/settings/chat' \ + -H 'Authorization: Bearer ' \ + -H 'Content-Type: application/json' \ + --data-binary '{ + "description": "A comprehensive movie database containing titles, descriptions, genres, and release dates to help users find movies", + "documentTemplate": "Title: {{ title }}\nDescription: {{ overview }}\nGenres: {{ genres }}\n", + "documentTemplateMaxBytes": 400, + "searchParameters": { + "limit": 20 + } + }' +``` + +##### Response: `202 Accepted` + +```json +{ + "taskUid": 1, + "indexUid": "movies", + "status": "enqueued", + "type": "settingsUpdate", + "enqueuedAt": "2024-05-11T09:33:12.691402Z" +} +``` + +You can use the returned `taskUid` to get more details on [the status of the task](/reference/api/tasks#get-one-task).