Meilisearch 中文文档

/chats 路由通过将大型语言模型（LLMs）与您的 Meilisearch 数据集成，实现了基于 AI 的对话式搜索功能。该特性允许用户使用自然语言提问，并根据您索引的内容获取上下文相关的答案。

这是一个实验性功能。使用 Meilisearch Cloud 用户界面或实验性功能端点来激活它：

curl \
  -X PATCH 'MEILISEARCH_URL/experimental-features/' \
  -H 'Content-Type: application/json' \
  --data-binary '{
    "chatCompletions": true
  }'

聊天补全工作区对象

{
  "uid": "customer-support"
}

名称	类型	描述
`uid`	字符串	聊天补全工作区的唯一标识符

更新聊天工作区设置

PATCH

/chats/{workspace}/settings

为聊天工作区配置 LLM 提供商及相关设置。

{
  "source": "openAi",
  "orgId": null,
  "projectId": null,
  "apiVersion": null,
  "deploymentId": null,
  "baseUrl": null,
  "apiKey": "sk-abc...",
  "prompts": {
    "system": "你是一个基于提供上下文回答问题的助手。"
  }
}

路径参数

名称	类型	描述
`workspace`	字符串	工作区标识符

设置参数

名称	类型	描述
`source`	字符串	LLM 来源：可选 `"openAi"`, `"azureOpenAi"`, `"mistral"`, `"gemini"` 或 `"vLlm"`
`orgId`	字符串	LLM 提供商的组织 ID (azureOpenAi 必填)
`projectId`	字符串	LLM 提供商的项目 ID
`apiVersion`	字符串	LLM 提供商的 API 版本 (azureOpenAi 必填)
`deploymentId`	字符串	LLM 提供商的部署 ID (azureOpenAi 必填)
`baseUrl`	字符串	提供商的基础 URL (azureOpenAi 和 vLlm 必填)
`apiKey`	字符串	LLM 提供商的 API 密钥 (vLlm 可选)
`prompts`	对象	包含系统提示词和其他配置的提示词对象

提示词对象

名称	类型	描述
`system`	字符串	添加到对话开头的提示词，用于引导 LLM
`searchDescription`	字符串	解释内部搜索功能作用的提示词
`searchQParam`	字符串	解释搜索函数 `q` 参数作用及使用方法的提示词
`searchIndexUidParam`	字符串	解释搜索函数 `indexUid` 参数作用及使用方法的提示词

请求体

{
  "source": "openAi",
  "apiKey": "sk-...",
  "prompts": {
    "system": "You are a helpful assistant."
  }
}

所有字段都是可选的。只有提供的字段会被更新。

响应: `200 OK`

返回更新后的设置对象。请注意 apiKey 是只写字段，不会在响应中返回。

示例

curl \
  -X PATCH 'http://localhost:7700/chats/customer-support/settings' \
  -H 'Authorization: Bearer MASTER_KEY' \
  -H 'Content-Type: application/json' \
  --data-binary '{
    "source": "openAi",
    "apiKey": "sk-abc...",
    "prompts": {
      "system": "You are a helpful customer support assistant."
    }
  }'

聊天补全

POST

/chats/{workspace}/chat/completions

使用与 OpenAI 兼容的接口创建聊天补全。该端点会搜索相关索引并基于检索到的内容生成响应。

路径参数

名称	类型	描述
`workspace`	String	聊天补全工作区的唯一标识符 (uid)

请求体

{
  "model": "gpt-3.5-turbo",
  "messages": [
    {
      "role": "user",
      "content": "What are the main features of Meilisearch?"
    }
  ],
  "stream": true
}

名称	类型	必填	描述
`model`	String	是	使用的模型，将与工作区设置中的源 LLM 相关联
`messages`	Array	是	包含 `role` 和 `content` 的消息对象数组
`stream`	Boolean	否	启用流式响应 (默认: `true`)

当前仅支持流式响应 (stream: true)。非流式响应将在未来版本中提供。

消息对象

名称	类型	描述
`role`	String	消息角色: `"system"`(系统), `"user"`(用户), 或 `"assistant"`(助手)
`content`	String	消息内容

响应

响应遵循 OpenAI 聊天补全格式。对于流式响应，端点返回 Server-Sent Events (SSE) 协议。

流式响应示例

data: {"id":"chatcmpl-123","object":"chat.completion.chunk","created":1677652288,"model":"gpt-3.5-turbo","choices":[{"index":0,"delta":{"content":"Meilisearch"},"finish_reason":null}]}

data: {"id":"chatcmpl-123","object":"chat.completion.chunk","created":1677652288,"model":"gpt-3.5-turbo","choices":[{"index":0,"delta":{"content":" is"},"finish_reason":null}]}

data: {"id":"chatcmpl-123","object":"chat.completion.chunk","created":1677652288,"model":"gpt-3.5-turbo","choices":[{"index":0,"delta":{},"finish_reason":"stop"}]}

data: [DONE]

示例

curl \
  -X POST 'http://localhost:7700/chats/customer-support/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
  }'

获取聊天设置

GET

/chats/{workspace}/settings

获取指定聊天工作区的当前设置。

路径参数

名称	类型	描述
`workspace`	String	工作区标识符

响应: `200 OK`

返回不包含 apiKey 字段的设置对象。

{
  "source": "openAi",
  "prompts": {
    "system": "You are a helpful assistant."
  }
}

示例

curl \
  -X GET 'http://localhost:7700/chats/customer-support/settings' \
  -H 'Authorization: Bearer MASTER_KEY'

列出聊天工作区

GET

/chats

列出所有可用的聊天工作区。可以使用查询参数进行分页。

查询参数

查询参数	描述	默认值
`offset`	要跳过的工作区数量	`0`
`limit`	要返回的工作区数量	`20`

响应

名称	类型	描述
`results`	数组	聊天工作区对象数组
`offset`	整数	跳过的工作区数量
`limit`	整数	返回的工作区数量
`total`	整数	工作区总数

示例

curl \
  -X GET 'http://localhost:7700/chats?limit=10' \
  -H 'Authorization: Bearer MASTER_KEY'

响应: `200 OK`

{
  "results": [
    {
      "uid": "customer-support"
    },
    {
      "uid": "internal-docs"
    }
  ],
  "offset": 0,
  "limit": 10,
  "total": 2
}

认证

聊天功能与 Meilisearch 的认证系统集成：

默认聊天 API 密钥：启用聊天功能时会创建一个新的默认密钥，具有访问聊天端点的权限
租户令牌：完全支持多租户应用场景
索引可见性：聊天搜索仅能访问提供的 API 密钥有权访问的索引

工具调用

聊天功能通过内部工具调用来搜索您的索引并提供增强的用户体验。为了获得最佳性能和用户体验，您应该在聊天补全请求中声明三个特殊工具。这些工具由 Meilisearch 内部处理，可提供关于搜索操作、对话上下文和源文档的实时反馈。

特殊工具概览

_meiliSearchProgress：报告实时搜索进度和操作状态
_meiliAppendConversationMessage：维护对话上下文以获得更好的响应
_meiliSearchSources：提供生成响应时使用的源文档

工具声明

将以下工具包含在请求的 tools 数组中，以启用增强功能：

{
  "model": "gpt-3.5-turbo",
  "stream": true,
  "messages": [
    {
      "role": "user",
      "content": "What is Meilisearch?"
    }
  ],
  "tools": [
    {
      "type": "function",
      "function": {
        "name": "_meiliSearchProgress",
        "description": "提供当前 Meilisearch 搜索操作的信息",
        "parameters": {
          "type": "object",
          "properties": {
            "call_id": {
              "type": "string",
              "description": "用于追踪搜索来源的调用 ID"
            },
            "function_name": {
              "type": "string",
              "description": "正在执行的函数名称"
            },
            "function_parameters": {
              "type": "string",
              "description": "正在执行的函数参数，以 JSON 格式编码"
            }
          },
          "required": ["call_id", "function_name", "function_parameters"],
          "additionalProperties": false
        },
        "strict": true
      }
    },
    {
      "type": "function",
      "function": {
        "name": "_meiliAppendConversationMessage",
        "description": "根据内部发生的情况向对话追加新消息",
        "parameters": {
          "type": "object",
          "properties": {
            "role": {
              "type": "string",
              "description": "消息作者的角色，可以是 `role` 或 `assistant`"
            },
            "content": {
              "type": "string",
              "description": "`assistant` 或 `tool` 消息的内容。除非指定了 `tool_calls`，否则为必填项。"
            },
            "tool_calls": {
              "type": ["array", "null"],
              "description": "模型生成的工具调用，例如函数调用",
              "items": {
                "type": "object",
                "properties": {
                  "function": {
                    "type": "object",
                    "description": "模型调用的函数",
                    "properties": {
                      "name": {
                        "type": "string",
                        "description": "要调用的函数名称"
                      },
                      "arguments": {
                        "type": "string",
                        "description": "调用函数时使用的参数，由模型以 JSON 格式生成。请注意，模型生成的 JSON 不一定有效，可能会生成未在函数模式中定义的参数。在调用函数前，请验证参数的正确性。"
                      }
                    }
                  },
                  "id": {
                    "type": "string",
                    "description": "工具调用的 ID"
                  },
                  "type": {
                    "type": "string",
                    "description": "工具的类型。目前仅支持 function"
                  }
                }
              }
            },
            "tool_call_id": {
              "type": ["string", "null"],
              "description": "此消息所响应的工具调用 ID"
            }
          },
          "required": ["role", "content", "tool_calls", "tool_call_id"],
          "additionalProperties": false
        },
        "strict": true
      }
    },
    {
      "type": "function",
      "function": {
        "name": "_meiliSearchSources",
        "description": "提供搜索的来源",
        "parameters": {
          "type": "object",
          "properties": {
            "call_id": {
              "type": "string",
              "description": "用于追踪与这些来源关联的原始搜索的调用 ID"
            },
            "documents": {
              "type": "object",
              "description": "与搜索（call_id）关联的文档。仅返回文档的显示属性"
            }
          },
          "required": ["call_id", "documents"],
          "additionalProperties": false
        },
        "strict": true
      }
    }
  ]
}

工具函数详解

`_meiliSearchProgress`

该工具用于实时报告内部搜索操作的进度。当声明此函数后，Meilisearch 会在后台执行搜索操作时调用它。

用途：提供搜索操作的透明度，通过向用户展示后台进程来减少感知延迟。

参数：

call_id：用于追踪搜索操作的唯一标识符
function_name：正在执行的内部函数名称（例如 “_meiliSearchInIndex”）
function_parameters：包含搜索参数的 JSON 编码字符串，如 q（查询）和 index_uid

示例响应：

{
  "function": {
    "name": "_meiliSearchProgress",
    "arguments": "{\"call_id\":\"89939d1f-6857-477c-8ae2-838c7a504e6a\",\"function_name\":\"_meiliSearchInIndex\",\"function_parameters\":\"{\\\"index_uid\\\":\\\"movies\\\",\\\"q\\\":\\\"search engine\\\"}\"}"
  }
}

`_meiliAppendConversationMessage`

由于 /chats/{workspace}/chat/completions 端点是无状态的，该工具通过请求客户端将内部消息追加到会话历史中来维护对话上下文。

用途：通过保留工具调用和结果来维护对话上下文，从而提高后续请求的响应质量。

参数：

role：消息作者角色（“user” 或 “assistant”）
content：消息内容（针对工具结果）
tool_calls：助手发起的工具调用数组
tool_call_id：该消息所对应的工具调用 ID

示例响应：

{
  "function": {
    "name": "_meiliAppendConversationMessage",
    "arguments": "{\"role\":\"assistant\",\"tool_calls\":[{\"id\":\"call_ijAdM42bixq9lAF4SiPwkq2b\",\"type\":\"function\",\"function\":{\"name\":\"_meiliSearchInIndex\",\"arguments\":\"{\\\"index_uid\\\":\\\"movies\\\",\\\"q\\\":\\\"search engine\\\"}\"}}]}"
  }
}

`_meiliSearchSources`

该工具提供了 LLM 用于生成回复的源文档，确保透明度并允许用户验证信息来源。

用途：向用户展示哪些文档被用于生成回复，增强信任度并支持来源验证。

参数：

call_id：与 _meiliSearchProgress 中的 call_id 匹配，用于关联查询与结果
documents：包含源文档的 JSON 对象，仅包含显示的属性

示例响应：

{
  "function": {
    "name": "_meiliSearchSources",
    "arguments": "{\"call_id\":\"abc123\",\"documents\":[{\"id\":197302,\"title\":\"The Sacred Science\",\"overview\":\"Diabetes. Prostate cancer...\",\"genres\":[\"Documentary\",\"Adventure\",\"Drama\"]}]}"
  }
}

实现最佳实践

始终声明所有三个工具 以获得最佳用户体验
处理进度更新 在流式传输期间向用户显示搜索状态
按要求附加对话消息 为后续请求保持上下文
向用户展示源文档 确保透明度和可验证性
使用 call_id 将进度更新与其对应的源结果关联

这些特殊工具由 Meilisearch 内部处理，不会转发给 LLM 提供商。它们作为 Meilisearch 与您的应用程序之间的通信机制，用于提供增强的用户体验功能。

API 参考

错误

聊天功能

聊天补全工作区对象

更新聊天工作区设置

路径参数

设置参数

提示词对象

请求体

响应: `200 OK`

示例

聊天补全

路径参数

请求体

消息对象

响应

流式响应示例

示例

获取聊天设置

路径参数

响应: `200 OK`

示例

列出聊天工作区

查询参数

响应

示例

响应: `200 OK`

认证

工具调用

特殊工具概览

工具声明

工具函数详解

`_meiliSearchProgress`

`_meiliAppendConversationMessage`

`_meiliSearchSources`

实现最佳实践

API 参考

错误

​聊天补全工作区对象

​更新聊天工作区设置

​路径参数

​设置参数

​提示词对象

​请求体

​响应: 200 OK

​示例

​聊天补全

​路径参数

​请求体

​消息对象

​响应

​流式响应示例

​示例

​获取聊天设置

​路径参数

​响应: 200 OK

​示例

​列出聊天工作区

​查询参数

​响应

​示例

​响应: 200 OK

​认证

​工具调用

​特殊工具概览

​工具声明

​工具函数详解

​_meiliSearchProgress

​_meiliAppendConversationMessage

​_meiliSearchSources

​实现最佳实践

聊天补全工作区对象

更新聊天工作区设置

路径参数

设置参数

提示词对象

请求体

响应: `200 OK`

示例

聊天补全

路径参数

请求体

消息对象

响应

流式响应示例

示例

获取聊天设置

路径参数

响应: `200 OK`

示例

列出聊天工作区

查询参数

响应

示例

响应: `200 OK`

认证

工具调用

特殊工具概览

工具声明

工具函数详解

`_meiliSearchProgress`

`_meiliAppendConversationMessage`

`_meiliSearchSources`

实现最佳实践