Skip to content

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

Merged
guimachiavelli merged 1 commit into
mainfrom
docs/chat-completions-guide
Jul 17, 2025
Merged

Update chat/completions documentation with real-world implementation insights#3307
guimachiavelli merged 1 commit into
mainfrom
docs/chat-completions-guide

Conversation

@tpayet

@tpayet tpayet commented Jul 11, 2025

Copy link
Copy Markdown
Member

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 <noreply@anthropic.com>
@guimachiavelli

Copy link
Copy Markdown
Contributor

@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.

@guimachiavelli guimachiavelli marked this pull request as ready for review July 17, 2025 15:51
@guimachiavelli guimachiavelli merged commit 9335188 into main Jul 17, 2025
3 checks passed
@guimachiavelli guimachiavelli deleted the docs/chat-completions-guide branch July 17, 2025 15:51
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