Meilisearch semanticRatio 越界或 embedder 名寫錯報錯

檢索請求 hybrid 物件裡，semanticRatio 必須落在 0.0 到 1.0 之間，超出範圍返回 400 invalid_search_semantic_ratio；embedder 必須對應索引 settings 裡已設定的 embedder 名，寫錯返回 400 invalid_search_embedder。解法：semanticRatio 取 0.0（純關鍵詞）/0.5（預設均衡）/1.0（純語義）之一，embedder 與 GET /settings/embedders 讀出的名字逐字一致。適用 Meilisearch v1.6+。

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

業務場景：調 semanticRatio 做混合檢索效果實驗時，手滑寫了 1.5 或者傳了字符串 "1.0"，返回 400；或者 hybrid.embedder 按記憶寫了個名字，跟設定對不上（比如設定叫 default，請求寫 "zh_model"），同樣返回 400。
環境：Meilisearch v1.54.3，任意 embedder 類型（userProvided / openAi / huggingFace 均可復現，報錯不依賴 source 類型）。
關鍵區分：這兩個錯誤碼都是對 hybrid 物件字段值的校驗失敗，屬於請求參數錯誤，不是索引或文檔的問題。語義上 semanticRatio 是“音量旋鈕”，embedder 是“選哪條嵌入通道”。

StackTrace（堆疊日誌）

官方 error codes 頁原文：

invalid_search_semantic_ratio — The hybrid.semanticRatio parameter is invalid. It should be a number between 0.0 and 1.0. invalid_search_embedder — embedder is invalid. It should be a string corresponding to the name of a configured embedder.

{
  "message": "The `hybrid.semanticRatio` parameter is invalid. It should be a number between 0.0 and 1.0.",
  "code": "invalid_search_semantic_ratio",
  "type": "invalid_request",
  "link": "https://docs.meilisearch.com/errors#invalid_search_semantic_ratio"
}

{
  "message": "`embedder` is invalid. It should be a string corresponding to the name of a configured embedder.",
  "code": "invalid_search_embedder",
  "type": "invalid_request",
  "link": "https://docs.meilisearch.com/errors#invalid_search_embedder"
}

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

Reproduce（復現程式碼）

# 1. semanticRatio 越界（1.5 不在 0.0-1.0）—— 报 invalid_search_semantic_ratio
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":{"embedder":"default","semanticRatio":1.5}}'

{"message":"The `hybrid.semanticRatio` parameter is invalid. It should be a number between 0.0 and 1.0.","code":"invalid_search_semantic_ratio","type":"invalid_request","link":"https://docs.meilisearch.com/errors#invalid_search_semantic_ratio"}

# 2. embedder 名与配置不一致 —— 报 invalid_search_embedder
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":{"embedder":"zh_model","semanticRatio":1.0}}'

{"message":"`embedder` is invalid. It should be a string corresponding to the name of a configured embedder.","code":"invalid_search_embedder","type":"invalid_request","link":"https://docs.meilisearch.com/errors#invalid_search_embedder"}

Root Cause（根因分析）

semanticRatio 是一個有邊界的浮點旋鈕

hybrid.semanticRatio 的合法範圍是 0.0 到 1.0（閉區間），語義由官方“Custom hybrid ranking”文檔定義：0.0 只走關鍵詞檢索，0.5 是預設的均衡混合，1.0 只走語義（向量）檢索。它本質是一個比例權重，超出邊界的值在數學上沒有意義（比如 1.5 等於“150% 語義”，無法解釋），所以 Meilisearch 在請求層直接拒絕，屬於同步 400，而不是任務失敗。

embedder 名是索引設定的索引

hybrid.embedder 必須命中當前索引 settings.embedders 裡已設定的鍵名，大小寫敏感、逐字匹配。Meilisearch 在請求校驗階段查不到這個名字就報 invalid_search_embedder，不會靜默回退到某個預設嵌入器。文檔 _vectors 的鍵名、檢索 hybrid.embedder 的值、settings 裡的 embedder 名，三處必須完全一致，這是 userProvided 模式下的基本契約。

多 embedder 場景更容易寫錯

一個索引可以配多個 embedder（比如中文模型 + 英文模型各一個），檢索時按 embedder 名選通道。設定多了之後，憑記憶寫名字就很容易串，這也是該錯誤碼在實踐中最常見的觸發路徑。

The Fix（解決方案）

第一步：先讀當前 embedder 設定，別憑記憶

curl 'http://localhost:7700/indexes/books_vec/settings/embedders' \
  -H 'Authorization: Bearer aSampleMasterKey'

{"default":{"source":"userProvided","dimensions":512}}

第二步：按讀到的名字和合法範圍重發檢索

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":{"embedder":"default","semanticRatio":1.0}}'

排查建議

semanticRatio 只取 0.0 / 0.5 / 1.0 三個常用檔位起步，調優時以 0.1 為步進，別跳界。
embedder 值直接從 GET /settings/embedders 的返回鍵複製，不要手打。
報錯都是同步 400，改完請求體立即重發即可，無需等待任何異步任務。

References（參考來源）

Error codes — Meilisearch 官方文檔meilisearch-docs
Custom hybrid ranking — Meilisearch 官方文檔meilisearch-docs