Merge pull request #3273 from meilisearch/docs/chat-feature

Add documentation for Meilisearch chat feature

Author: Kerollmops

docs.json

@@ -165,6 +165,7 @@
                 "group": "AI-powered search",
                 "pages": [
                   "learn/ai_powered_search/getting_started_with_ai_search",
+                  "learn/ai_powered_search/conversational_search_with_chat",
                   "learn/ai_powered_search/configure_rest_embedder",
                   "learn/ai_powered_search/document_template_best_practices",
                   "learn/ai_powered_search/image_search_with_user_provided_embeddings",
@@ -329,6 +330,7 @@
                   "reference/api/network",
                   "reference/api/similar",
                   "reference/api/facet_search",
+                  "reference/api/chats",
                   "reference/api/tasks",
                   "reference/api/batches",
                   "reference/api/keys",
@@ -377,6 +379,7 @@
               {
                 "group": "Artificial intelligence",
                 "pages": [
+                  "guides/ai/getting_started_with_chat",
                   "guides/ai/mcp",
                   "guides/embedders/openai",
                   "guides/langchain",

guides/ai/getting_started_with_chat.mdx

@@ -0,0 +1,276 @@
+---
+title: Getting started with conversational search
+sidebarTitle: Getting started with chat
+description: Learn how to implement AI-powered conversational search in your application
+---
+
+import { Warning, Note } from '/snippets/notice_tag.mdx'
+
+This guide walks you through implementing Meilisearch's chat completions feature to create conversational search experiences in your application.
+
+<Warning>
+The chat completions feature is experimental and must be enabled before use. See [experimental features](/reference/api/experimental_features) for activation instructions.
+</Warning>
+
+## Prerequisites
+
+Before starting, ensure you have:
+- Meilisearch instance running (v1.15.1 or later)
+- 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
+
+## Quick start
+
+### Enable the chat completions feature
+
+First, enable the chat completions experimental feature:
+
+```bash
+curl \
+  -X PATCH 'http://localhost:7700/experimental-features' \
+  -H 'Authorization: Bearer MASTER_KEY' \
+  -H 'Content-Type: application/json' \
+  --data-binary '{
+    "chatCompletions": true
+  }'
+```
+
+### Configure a chat completions workspace
+
+Create a workspace with your LLM provider settings. Here are examples for different providers:
+
+<CodeGroup>
+
+```bash openAi
+curl \
+  -X PATCH 'http://localhost:7700/chats/my-assistant/settings' \
+  -H 'Authorization: Bearer MASTER_KEY' \
+  -H 'Content-Type: application/json' \
+  --data-binary '{
+    "source": "openAi",
+    "apiKey": "sk-abc...",
+    "prompts": {
+      "system": "You are a helpful assistant. Answer questions based only on the provided context."
+    }
+  }'
+```
+
+```bash azureOpenAi
+curl \
+  -X PATCH 'http://localhost:7700/chats/my-assistant/settings' \
+  -H 'Authorization: Bearer MASTER_KEY' \
+  -H 'Content-Type: application/json' \
+  --data-binary '{
+    "source": "azureOpenAi",
+    "apiKey": "your-azure-key",
+    "baseUrl": "https://your-resource.openai.azure.com",
+    "prompts": {
+      "system": "You are a helpful assistant. Answer questions based only on the provided context."
+    }
+  }'
+```
+
+```bash mistral
+curl \
+  -X PATCH 'http://localhost:7700/chats/my-assistant/settings' \
+  -H 'Authorization: Bearer MASTER_KEY' \
+  -H 'Content-Type: application/json' \
+  --data-binary '{
+    "source": "mistral",
+    "apiKey": "your-mistral-key",
+    "prompts": {
+      "system": "You are a helpful assistant. Answer questions based only on the provided context."
+    }
+  }'
+```
+
+```bash gemini
+curl \
+  -X PATCH 'http://localhost:7700/chats/my-assistant/settings' \
+  -H 'Authorization: Bearer MASTER_KEY' \
+  -H 'Content-Type: application/json' \
+  --data-binary '{
+    "source": "gemini",
+    "apiKey": "your-gemini-key",
+    "prompts": {
+      "system": "You are a helpful assistant. Answer questions based only on the provided context."
+    }
+  }'
+```
+
+```bash vLlm
+curl \
+  -X PATCH 'http://localhost:7700/chats/my-assistant/settings' \
+  -H 'Authorization: Bearer MASTER_KEY' \
+  -H 'Content-Type: application/json' \
+  --data-binary '{
+    "source": "vLlm",
+    "baseUrl": "http://localhost:8000",
+    "prompts": {
+      "system": "You are a helpful assistant. Answer questions based only on the provided context."
+    }
+  }'
+```
+
+</CodeGroup>
+
+### Send your first chat completions request
+
+Now you can start a conversation:
+
+```bash
+curl \
+  -X POST 'http://localhost:7700/chats/my-assistant/chat/completions' \
+  -H 'Authorization: Bearer DEFAULT_CHAT_KEY' \
+  -H 'Content-Type: application/json' \
+  --data-binary '{
+    "model": "gpt-3.5-turbo",
+    "messages": [
+      {
+        "role": "user",
+        "content": "What is Meilisearch?"
+      }
+    ],
+    "stream": true
+  }'
+```
+
+## Understanding workspaces
+
+Workspaces allow you to create isolated chat configurations for different use cases:
+
+- **Customer support**: Configure with support-focused prompts
+- **Product search**: Optimize for e-commerce queries
+- **Documentation**: Tune for technical Q&A
+
+Each workspace maintains its own:
+- LLM provider configuration
+- System prompt
+
+## Building a chat interface with OpenAI SDK
+
+Since Meilisearch's chat endpoint is OpenAI-compatible, you can use the official OpenAI SDK:
+
+<CodeGroup>
+
+```javascript JavaScript
+import OpenAI from 'openai';
+
+const client = new OpenAI({
+  baseURL: 'http://localhost:7700/chats/my-assistant',
+  apiKey: 'YOUR_MEILISEARCH_API_KEY',
+});
+
+const completion = await client.chat.completions.create({
+  model: 'gpt-3.5-turbo',
+  messages: [{ role: 'user', content: 'What is Meilisearch?' }],
+  stream: true,
+});
+
+for await (const chunk of completion) {
+  console.log(chunk.choices[0]?.delta?.content || '');
+}
+```
+
+```python Python
+from openai import OpenAI
+
+client = OpenAI(
+    base_url="http://localhost:7700/chats/my-assistant",
+    api_key="YOUR_MEILISEARCH_API_KEY"
+)
+
+stream = client.chat.completions.create(
+    model="gpt-3.5-turbo",
+    messages=[{"role": "user", "content": "What is Meilisearch?"}],
+    stream=True,
+)
+
+for chunk in stream:
+    if chunk.choices[0].delta.content is not None:
+        print(chunk.choices[0].delta.content, end="")
+```
+
+```typescript TypeScript
+import OpenAI from 'openai';
+
+const client = new OpenAI({
+  baseURL: 'http://localhost:7700/chats/my-assistant',
+  apiKey: 'YOUR_MEILISEARCH_API_KEY',
+});
+
+const stream = await client.chat.completions.create({
+  model: 'gpt-3.5-turbo',
+  messages: [{ role: 'user', content: 'What is Meilisearch?' }],
+  stream: true,
+});
+
+for await (const chunk of stream) {
+  const content = chunk.choices[0]?.delta?.content || '';
+  process.stdout.write(content);
+}
+```
+
+</CodeGroup>
+
+## Error handling
+
+When using the OpenAI SDK with Meilisearch's chat completions endpoint, errors from the streamed responses are natively handled by the official OpenAI SDK. This means you can use the SDK's built-in error handling mechanisms without additional configuration:
+
+<CodeGroup>
+
+```javascript JavaScript
+import OpenAI from 'openai';
+
+const client = new OpenAI({
+  baseURL: 'http://localhost:7700/chats/my-assistant',
+  apiKey: 'YOUR_MEILISEARCH_API_KEY',
+});
+
+try {
+  const stream = await client.chat.completions.create({
+    model: 'gpt-3.5-turbo',
+    messages: [{ role: 'user', content: 'What is Meilisearch?' }],
+    stream: true,
+  });
+
+  for await (const chunk of stream) {
+    console.log(chunk.choices[0]?.delta?.content || '');
+  }
+} catch (error) {
+  // OpenAI SDK automatically handles streaming errors
+  console.error('Chat completion error:', error);
+}
+```
+
+```python Python
+from openai import OpenAI
+
+client = OpenAI(
+    base_url="http://localhost:7700/chats/my-assistant",
+    api_key="YOUR_MEILISEARCH_API_KEY"
+)
+
+try:
+    stream = client.chat.completions.create(
+        model="gpt-3.5-turbo",
+        messages=[{"role": "user", "content": "What is Meilisearch?"}],
+        stream=True,
+    )
+
+    for chunk in stream:
+        if chunk.choices[0].delta.content is not None:
+            print(chunk.choices[0].delta.content, end="")
+except Exception as error:
+    # OpenAI SDK automatically handles streaming errors
+    print(f"Chat completion error: {error}")
+```
+
+</CodeGroup>
+
+## Next steps
+
+- Explore [advanced chat API features](/reference/api/chats)
+- Learn about [conversational search concepts](/learn/ai_powered_search/conversational_search_with_chat)
+- Review [security best practices](/learn/security/basic_security)