Meilisearch userProvided 檢索漏帶 vector 或 hybrid 結構寫錯

userProvided embedder 模式下，檢索請求裡 vector 和 hybrid 必須成對出現：只傳 vector 不傳 hybrid 返回 400 missing_search_hybrid；hybrid 傳了但結構或鍵名寫錯（比如 embedder 名字大小寫不對）返回 400 invalid_search_hybrid_query。解法是把 hybrid 物件補全，embedder 值與 settings 裡設定的 embedder 名逐字一致。適用 Meilisearch v1.6+。

Issue & Env（案發現場與環境）

業務場景：按官方 userProvided 指南配好 embedder、傳完帶 _vectors 的文檔，檢索時圖省事只傳了 vector 陣列，忘記帶 hybrid 物件，返回 400。或者寫了 hybrid 但 embedder 名字跟設定對不上（比如設定是 default，請求裡寫 "Default"）。
環境：Meilisearch v1.54.3，source: "userProvided" 類型 embedder，curl / 任意 SDK 均可復現。
關鍵區分：userProvided 模式檢索時 vector 是必填的，hybrid 裡 embedder 指名用哪個嵌入器；兩者缺一不可。自動嵌入（如 openAi/huggingFace 類型）模式下不傳 vector 也能搜，容易讓人在 userProvided 下沿用同樣寫法然後踩坑。

StackTrace（堆疊日誌）

官方 error codes 頁原文：

missing_search_hybrid — The hybrid parameter is missing when vector or media were provided. invalid_search_hybrid_query — The hybrid parameter is neither null nor an object, or it is an object with unknown keys.

{
  "message": "The `hybrid` parameter is missing when `vector` or `media` were provided.",
  "code": "missing_search_hybrid",
  "type": "invalid_request",
  "link": "https://docs.meilisearch.com/errors#missing_search_hybrid"
}

{
  "message": "The `hybrid` parameter is neither `null` nor an object, or it is an object with unknown keys.",
  "code": "invalid_search_hybrid_query",
  "type": "invalid_request",
  "link": "https://docs.meilisearch.com/errors#invalid_search_hybrid_query"
}

注：message 具體措辭以你本地的 Meilisearch 版本返回為準，上例展示的是該錯誤碼的標準結構。

Reproduce（復現程式碼）

# 1. 只传 vector，漏掉 hybrid —— 报 missing_search_hybrid
curl -X POST 'http://localhost:7700/indexes/books_vec/search' \
  -H 'Content-Type: application/json' \
  -H 'Authorization: Bearer aSampleMasterKey' \
  --data-binary '{"vector":[0.1,0.2,0.3,"..."]}'

{"message":"The `hybrid` parameter is missing when `vector` or `media` were provided.","code":"missing_search_hybrid","type":"invalid_request","link":"https://docs.meilisearch.com/errors#missing_search_hybrid"}

# 2. hybrid 键名写错（embedder 应为字符串 embedder 名）—— 报 invalid_search_hybrid_query
curl -X POST 'http://localhost:7700/indexes/books_vec/search' \
  -H 'Content-Type: application/json' \
  -H 'Authorization: Bearer aSampleMasterKey' \
  --data-binary '{"vector":[0.1,0.2,0.3],"hybrid":{"embeder":"default","semanticRatio":1.0}}'

{"message":"The `hybrid` parameter is neither `null` nor an object, or it is an object with unknown keys.","code":"invalid_search_hybrid_query","type":"invalid_request","link":"https://docs.meilisearch.com/errors#invalid_search_hybrid_query"}

Root Cause（根因分析）

userProvided 模式下檢索必須自帶查詢向量

userProvided 的含義是“向量全由調用方提供”。檢索時 Meilisearch 不會自己去嵌入查詢詞，所以 vector 是必填；而 hybrid 參數負責告訴 Meilisearch 這次檢索走語義/混合路徑、用哪個 embedder。官方指南原文明確：vector 在 userProvided 檢索中是 mandatory（必填），且要與 hybrid 一起出現。只給向量不給 hybrid，Meilisearch 不知道你要不要走向量檢索，直接拒絕。

hybrid 是嚴格的物件校驗

hybrid 參數只接受一個物件，且物件裡的鍵必須是指定集合（embedder、semanticRatio 等）。拼錯鍵名（embeder、semanticRatio 大小寫不對）都會落進“unknown keys”分支，報 invalid_search_hybrid_query，而不是報別的錯。這也是 v1.13 起從舊錯誤碼 invalid_hybrid_search 更名而來的統一校驗入口。

與自動嵌入模式的寫法差異

自動嵌入（openAi/huggingFace/rest 類型）模式下，檢索可以只傳 q，Meilisearch 自動調嵌入器生成查詢向量；userProvided 沒有這個兜底，寫法完全不同。從自動嵌入切到 userProvided 時最容易踩“沿用舊寫法”的坑。

The Fix（解決方案）

正確寫法：vector + hybrid 成對出現

curl -X POST 'http://localhost:7700/indexes/books_vec/search' \
  -H 'Content-Type: application/json' \
  -H 'Authorization: Bearer aSampleMasterKey' \
  --data-binary '{
    "vector": [0.1, 0.2, 0.3, "…512 维…"],
    "hybrid": {"embedder": "default", "semanticRatio": 1.0}
  }'

排查建議

報 missing_search_hybrid：補 hybrid 物件，至少帶 embedder。
報 invalid_search_hybrid_query：檢查 hybrid 裡的鍵名拼寫，embedder 必須與 GET /indexes/{uid}/settings/embedders 讀出來的名字逐字一致（含大小寫）。
只要走 userProvided，就把“檢索 = vector + hybrid.embedder”當成固定模板，別再裸傳 vector。

References（參考來源）

Error codes — Meilisearch 官方文檔meilisearch-docs
Use AI-powered search with user-provided embeddings — Meilisearch 官方文檔meilisearch-docs