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