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