Meilisearch 向量维度与 embedder 配置不一致报 invalid_vector_dimensions

userProvided embedder 模式下，文档里的 _vectors 或检索请求里的 vector，维度只要跟索引 settings 里 embedders.<name>.dimensions 声明的不一致，就会返回 HTTP 400，错误码 invalid_vector_dimensions。最典型的触发是换了嵌入模型没改配置：bge-small-zh-v1.5 输出 512 维，换成 bge-base-zh-v1.5 变成 768 维，embedder 里还写着 512，传上去就报错。解法是把模型实际输出维度核对清楚，embedder 配置、_vectors、查询向量三处同步改，设置任务跑完（会触发全量重建）再重新上传文档。适用 Meilisearch v1.6+（embedder 功能引入后）。

Issue & Env（案发现场与环境）

业务场景：按官方 userProvided 指南走通了纯向量语义检索，之后想换更强的中文嵌入模型（如 bge-base-zh-v1.5，768 维），只改了 embed.py 里的模型名，embedders 配置里 dimensions 没动，还是 512。重新上传文档时返回 400。
环境：Meilisearch v1.54.3，source: "userProvided" 类型 embedder，curl / 任意 SDK 均可复现。
触发点有两个方向：① 写文档时 _vectors 的维度不对；② 检索时 vector 参数的维度不对。两者共用同一个错误码。
典型场景：本地 embedding 模型换代（bge-small → bge-base → bge-large，512 → 768 → 1024 维），或从 huggingFace/rest 类型 embedder 换成 userProvided 时维度配置没对齐。

StackTrace（堆栈日志）

官方 error codes 页对 invalid_vector_dimensions 的触发条件描述原文：

When an embedder returns a vector whose dimensions are not consistent with the declared dimensions for this embedder… When a document contains a manually provided vector whose dimensions are not consistent with the declared dimensions for this embedder…

即两类触发：嵌入器返回的向量维度与声明不一致（自动嵌入场景），或文档里手工提供的 _vectors 维度与声明不一致（userProvided 场景）。HTTP 状态为 400，属于 invalid_request 类。完整响应结构（官方规范 0061 的错误响应格式）：

{
  "message": "Vector dimension `768` is not the same as the dimension `512` declared in the embedder `default`",
  "code": "invalid_vector_dimensions",
  "type": "invalid_request",
  "link": "https://docs.meilisearch.com/errors#invalid_vector_dimensions"
}

注：message 具体措辞以你本地的 Meilisearch 版本返回为准，上例展示的是该错误码的标准结构。

Reproduce（复现代码）

# 1. 配置 embedder：声明 512 维（bge-small-zh-v1.5）
curl -X PATCH 'http://localhost:7700/indexes/books_vec/settings' \
  -H 'Content-Type: application/json' \
  -H 'Authorization: Bearer aSampleMasterKey' \
  --data-binary '{"embedders":{"default":{"source":"userProvided","dimensions":512}}}'

# 2. 换成 bge-base-zh-v1.5 重新生成向量（768 维），维度与声明不一致
curl -X POST 'http://localhost:7700/indexes/books_vec/documents' \
  -H 'Content-Type: application/json' \
  -H 'Authorization: Bearer aSampleMasterKey' \
  --data-binary '[{"id":1,"title":"三体","_vectors":{"default":[0.1,0.2,"..."]," /* 768 个数 */ }}]'

{"taskUid":23,"indexUid":"books_vec","status":"failed","type":"documentAdditionOrUpdate","error":{"message":"Vector dimension does not match the embedder configuration","code":"invalid_vector_dimensions","type":"invalid_request","link":"https://docs.meilisearch.com/errors#invalid_vector_dimensions"}}

检索侧同样会触发：查询向量是 768 维，embedder 声明 512 维，POST /search 返回同码 400。

Root Cause（根因分析）

维度是 userProvided embedder 的契约

userProvided 的含义是“向量全由调用方提供，Meilisearch 不生成、也不校验内容语义”。作为交换，dimensions 在 embedder 配置里是必填项，它就是 Meilisearch 侧唯一的维度契约：写入时校验 _vectors、检索时校验 vector，两边都得跟它一致。Meilisearch 的向量存储（DiskANN/HNSW 图结构）在建索引时按声明维度固定布局，维度变了布局就对不上，所以宁可拒绝也不存。

为什么“换个模型就报错”

bge 系列不同尺寸输出维度不同：small 512、base 768、large 1024。换模型后 embed.py 输出的向量维度变了，而 embedders.dimensions 还在旧值上，两边对不上，直接触发上面的校验。这不是 Meilisearch 的 bug，是 userProvided 模式下换模型必须三处同步：

embedders.<name>.dimensions 配置
文档 _vectors 里的向量
检索时 vector 参数里的查询向量

漏改任何一处，都会在对应环节报 invalid_vector_dimensions。

设置更新会触发全量重建

改 dimensions 属于 embedder 配置变更，官方文档明确：更改 embedder 的 model、source、dimensions、pooling 等字段会触发全量重嵌入/重建。userProvided 模式下则表现为全量重建向量索引，任务 succeeded 前检索可能读不到新配置的结果。

The Fix（解决方案）

第一步：确认模型实际输出维度

先跑一行命令，用当前模型打印真实维度：

python3 -c "
from sentence_transformers import SentenceTransformer
m = SentenceTransformer('BAAI/bge-base-zh-v1.5')
print('dimensions:', len(m.encode('测试')))
"

dimensions: 768

第二步：同步更新 embedder 配置

curl -X PATCH 'http://localhost:7700/indexes/books_vec/settings' \
  -H 'Content-Type: application/json' \
  -H 'Authorization: Bearer aSampleMasterKey' \
  --data-binary '{"embedders":{"default":{"source":"userProvided","dimensions":768}}}'

等设置任务 succeeded（会触发全量重建）再操作数据。

第三步：重新生成文档与查询向量

用新模型重新跑生成脚本，让 docs_with_vectors.json 和查询向量都是 768 维，再重新上传文档、重新检索。

排查建议

报错后先看任务是哪个环节 failed：写文档报 → 查 _vectors 维度；检索报 → 查 vector 参数维度。
用 GET /indexes/{uid}/settings/embedders 读当前声明维度，别凭记忆改。
同一索引里不要混用不同模型的向量——要么全部重生成，要么新建索引。

References（参考来源）

Error codes — Meilisearch 官方文档meilisearch-docs
Use AI-powered search with user-provided embeddings — Meilisearch 官方文档meilisearch-docs
Error Format and Definitions — Meilisearch 规范文档meilisearch-spec