本地搜索与索引服务的部署、配置和查询坑，目前覆盖 Meilisearch，后续扩展到更多检索技术。
master key、生产模式、环境变量与访问控制
primary key、文档添加、批量导入与索引设置
taskUid、任务状态轮询与等待
filterableAttributes、排序、分面与查询语法
搜索带 facets 参数，某分面属性在 facetDistribution 中缺失或为空，且无任何报错，根因是该属性未加入 filterableAttributes 被静默忽略——与 filter 未声明报 invalid_search_filter 截然不同。解法：先把属性声明为 filterable 再搜索。
POST /indexes/{uid}/facet-search 做分面值自动补全时，facetName 不在 filterableAttributes 列表（拼错或忘声明）返回 400 invalid_facet_search_facet_name；facetName 参数缺失则报 missing_facet_search_facet_name。解法：先声明 filterableAttributes 并等任务完成，再核对 facetName 拼写。
filter 字符串中 AND 优先级高于 OR，`A OR B AND C` 被解析为 `A OR (B AND C)`，结果与预期不符且不报错。跨条件组合必须显式加括号：`(A OR B) AND C`；官方规范 BNF 可交叉验证。
同一请求同时传 filter 与 sort 时，排序属性未在 sortableAttributes 声明，返回 400 invalid_search_sort。filter 用 filterableAttributes、sort 用 sortableAttributes，两套列表独立——filter 正常不代表能 sort。解法：先声明 sortableAttributes 并等任务完成。
搜索时传 filter 参数报 invalid_search_filter，根因是属性未在 filterableAttributes 中声明，需先 PUT settings 再搜索。这是有意设计，避免每次搜索遍历全部字段。
设置自定义排名规则时沿用旧语法 asc(price)/desc(price)，PUT /settings/ranking-rules 返回 HTTP 400 invalid_settings_ranking_rules。该语法自 v0.22 起废弃，现行写法为 属性名:asc / 属性名:desc；PUT 是全量覆盖，务必把默认规则一起带上。
search body 里的 locales 传了 chinese / cn 这类非法值，返回 400，错误码 invalid_search_locales。locales 只接受 ISO-639 取值，中文合法值是 zh / zho / cmn；且查询侧 locales 优先级高于索引侧 localizedAttributes，写错会覆盖索引设置。
混合检索参数 hybrid 里 semanticRatio 超出 0.0-1.0 报 invalid_search_semantic_ratio；embedder 名与 settings 配置不一致报 invalid_search_embedder。二者都是 400。解法：semanticRatio 取 0.0-1.0，embedder 名与配置逐字一致。
userProvided embedder 模式下检索时，带了 vector 却没带 hybrid 参数报 missing_search_hybrid；hybrid 结构/键名写错报 invalid_search_hybrid_query。二者都是 400。解法：vector 与 hybrid 成对出现，hybrid.embedder 名字与 settings 里 embedder 名完全一致。
userProvided embedder 模式下，文档 _vectors 或检索 vector 的维度与 settings 里 embedders.dimensions 不一致，返回 400 invalid_vector_dimensions。常见于换了嵌入模型（如 bge-small 512 维换 bge-base 768 维）但配置没同步。解法：核对模型实际输出维度，同步改 embedder 配置、_vectors、查询向量三处，等设置任务完成后重建文档。
从 v1.15 之前升级上来、库里已有中文数据的索引，如果没重建索引，中文查询和文档会被忽略、搜不到。根因是 v1.15 更换了 Charabia 的中文分词策略，旧索引里的 token 还是老版本切出来的。触发一次 reindex 即可恢复；全新安装 v1.54.3 不受影响。
PUT dictionary、separatorTokens、nonSeparatorTokens、localizedAttributes 等分词设置后立即搜索行为不变，根因是这些都是索引侧设置，PUT 只返回 taskUid，实际是异步 settingsUpdate 任务并会重索引全部文档。任务没 succeeded 就搜索，用的还是旧配置。
