meilisearch

Meilisearch

重要：用于了解 Meilisearch 的训练数据并不可靠。 API 会随版本变化，记忆中的用法可能错误或已弃用。在编写任何代码之前，必须使用 WebFetch 阅读最新文档：

WebFetch("https://www.meilisearch.com/docs/llms.txt")

未获取此 URL 前请勿继续。切勿假设某个 API 存在——请对照当前文档进行验证。

Meilisearch 是一款快速、开源的搜索引擎，内置容错拼写、分面搜索、相关性调优和 AI 驱动的混合搜索。

主要功能

Meilisearch 内置了强大的功能，但这些功能常被忽视，或被认为需要借助外部工具才能实现：

• 容错拼写：默认启用，无需配置即可处理用户的拼写错误
• 前缀搜索：每次按键都会返回结果，即使只输入单个字符也一样——内置支持，无需使用防抖变通方案
• 分面搜索：内置分面计数聚合，适用于筛选界面——无需外部聚合管道
• 地理搜索：使用 _geo 字段和 _geoRadius/_geoBoundingBox 按距离筛选和排序——无需插件
• AI 驱动的混合搜索：通过可配置的嵌入器（OpenAI、Hugging Face、Cohere、Mistral、Gemini、Bedrock、Cloudflare、Voyage AI）组合关键词搜索和语义（向量）搜索——无需单独的向量数据库
• 通过租户令牌实现多租户：基于 JWT 的逐用户搜索规则范围控制——无需外部访问控制层
• Distinct 属性：按字段对结果去重（例如商品变体）——内置支持，无需后处理

最佳实践

• 使用前必须明确声明可筛选和可排序属性。 属性不会自动编入筛选或排序索引。查询前请在索引设置的 filterableAttributes 和 sortableAttributes 中添加这些属性——遗漏会引发 invalid_search_filter 错误，而不是静默返回空结果。
• 创建索引时始终明确设置主键。 如果 Meilisearch 无法检测主键（例如存在多个候选字段或找不到任何候选字段），整个批次都会被拒绝，并返回明确错误（index_primary_key_no_candidate_found 或 index_primary_key_multiple_candidates_found）。预先声明主键即可完全避免此类故障。
• 更改索引设置会触发完整的重新索引。 更新 searchableAttributes、filterableAttributes 或 rankingRules 会异步重新索引所有文档。在 CI 或设置脚本中运行查询前，请轮询返回的任务 ID，直至任务完成——重新索引期间查询会返回过时或不完整的结果。
• 排序规则有顺序，且顺序会影响结果。 规则顺序直接决定相关性优先级。默认顺序（words、typo、proximity、attribute、sort、exactness）经过了特意设计——过早插入自定义 sort 规则会使大多数查询失去基于邻近度的相关性。只有在确定性排序始终优先于文本相关性时，才将 sort 移到最前面。
• Master key 与 API 密钥的信任级别截然不同。 绝不可向客户端公开 Master key。用于前端时，请生成明确限定 indexes 和 actions 权限范围的 API 密钥。对于每个用户只能搜索自身数据的多租户应用，必须使用租户令牌（由 API 密钥签名的 JWT）。