本地搜索與索引服務的部署、設定和查詢坑，目前覆蓋 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 就搜索，用的還是舊設定。
