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