Skip to content

Update chat/completions documentation with real-world implementation insights #3307

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Draft
wants to merge 1 commit into
base: main
Choose a base branch
from

Conversation

tpayet
Copy link
Member

@tpayet tpayet commented Jul 11, 2025

Hey @guimachiavelli 👋🏽
I've spend some time implementing the chat/completions route on the where2watch dataset, and here is some suggested updates for the documentation based on my experience implementing it.
Feel free to merge or discard the PR, I just wanted to give you visibility on what I was missing when implementing it ^^

Summary

This PR updates the Meilisearch chat/completions documentation based on real-world implementation experience and discovered requirements.

Key Updates

Prerequisites and Setup

  • ✅ Documents that Meilisearch MUST be started with a master key for authentication
  • ✅ Clarifies the experimental feature enablement process
  • ✅ Notes the potential need for --experimental-enable-chat flag in some versions

Authentication

  • ✅ Explains how to find the automatically created "Default Chat API Key"
  • ✅ Clarifies which API keys work with chat endpoints

Index Configuration for Chat

  • ✅ Documents the required chat-specific index settings
  • ✅ Includes description, documentTemplate, and searchParameters configuration

Creating Chat Workspaces

  • ✅ Shows correct usage with PUT method (in addition to PATCH)
  • ✅ Includes baseUrl configuration for OpenAI

Using the Chat Endpoint

  • ✅ Emphasizes that only streaming responses are supported
  • ✅ Adds -N flag to curl examples for proper SSE handling

Enabling Database Search

  • ✅ Documents the critical requirement to include Meilisearch tools
  • ✅ Explains that without tools, chat won't search actual indexes

Troubleshooting Guide

  • ✅ Common errors and their solutions
  • ✅ Clear explanations for authentication issues
  • ✅ Debugging steps for configuration problems

Complete Working Example

  • ✅ End-to-end example from Meilisearch startup to chat request
  • ✅ All steps with actual working commands

Files Modified

  • guides/ai/getting_started_with_chat.mdx - Main getting started guide with all new content
  • reference/api/chats.mdx - API reference updates for clarity and -N flag
  • reference/api/settings.mdx - Fixed chat settings documentation (was labeled as "Conversation")

🤖 Generated with Claude Code

…ation insights

- Add critical prerequisites: master key requirement and auth setup
- Document index chat configuration with description and documentTemplate
- Clarify PUT/PATCH methods for workspace creation
- Add authentication flow and finding Default Chat API Key
- Document enabling database search with Meilisearch tools
- Add comprehensive troubleshooting guide for common issues
- Include complete working example from setup to usage
- Fix -N flag requirement for curl streaming responses
- Update API references to match implementation

🤖 Generated with [Claude Code](https://claude.ai/code)

Co-Authored-By: Claude <[email protected]>
@guimachiavelli
Copy link
Member

@tpayet, is this ready for review or is it still a draft? I am planning to review all chat completions documentation as part of v1.16, so the best way to avoid wasting anyone's work would be to to merge this as soon as it's ready so I'm reviewing the latest version of everything.

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment
Labels
None yet
Projects
None yet
Development

Successfully merging this pull request may close these issues.

2 participants