Meilisearch documentTemplate 引用缺失字段報 template_rendering_error

設定 huggingFace / openAi 等內置 embedder 時，documentTemplate 用 {{doc.字段名}} 引用了文檔裡不存在的字段，Meilisearch 渲染模板失敗，整個索引任務返回 failed，錯誤碼 template_rendering_error。解法：提交前用 POST /render-template 預演，模板裡給可選字段加 {% if %} 守衛，或只引用所有文檔都有的字段。適用 Meilisearch v1.6+（內置 embedder 自動嵌入）。

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

• 業務場景：給內置 embedder 寫 documentTemplate 時想當然地引用了 {{doc.genre}}，但當前索引的文檔只 id / title / author 三個字段，提交設置後任務隊列裡的 settingsUpdate 變成 failed，索引的向量一直沒生成，搜索也搜不出語義結果。
• 環境：Meilisearch v1.54.3，source: "huggingFace" 的 embedder（openAi / rest 源同理可復現——任何帶 documentTemplate 的內置 embedder 都走同一套模板渲染）。
• 關鍵區分：這是索引任務失敗（異步、任務隊列裡報錯），不是搜索請求的 400。報錯時整批文檔都不會嵌入。

StackTrace（堆疊日誌）

官方文檔（Document template best practices）給出的渲染失敗報錯原文：

{
  "message": "error while rendering template: user error: missing field in document: liquid: Unknown index\n with:\n variable=doc\n requested index=doesnotexist\n available indexes=id, title, overview, genres, poster, release_date\n",
  "code": "template_rendering_error",
  "type": "invalid_request",
  "link": "https://docs.meilisearch.com/errors#template_rendering_error"
}

注：requested index 是你寫錯的那個字段名，available indexes 列出文檔實際擁有的字段——排查時直接看這兩行就能對上號。message 具體措辭以你本地的 Meilisearch 版本返回為準。

任務隊列裡的形態：

{
  "uid": 27,
  "indexUid": "books_vec",
  "status": "failed",
  "type": "settingsUpdate",
  "error": {
    "message": "error while rendering template: user error: missing field in document: liquid: Unknown index",
    "code": "template_rendering_error",
    "type": "invalid_request",
    "link": "https://docs.meilisearch.com/errors#template_rendering_error"
  }
}

Reproduce（復現程式碼）

# 1. 建索引并传 6 条只含 id/title/author 的纯文本文档（可复用 quickstart 系列 books_vec）
# 2. 配置 huggingFace embedder，documentTemplate 引用不存在的 genre 字段
curl -X PATCH 'http://localhost:7700/indexes/books_vec/settings/embedders' \
  -H 'Content-Type: application/json' \
  -H 'Authorization: Bearer aSampleMasterKey' \
  --data-binary '{"default":{"source":"huggingFace","model":"BAAI/bge-small-zh-v1.5","documentTemplate":"中文书籍，书名《{{doc.title}}》，类型 {{doc.genre}}"}}'

{"taskUid":27,"indexUid":"books_vec","status":"enqueued","type":"settingsUpdate","enqueuedAt":"2026-10-11T10:15:00.000Z"}

# 3. 轮询任务，status 变 failed，error.code = template_rendering_error
curl 'http://localhost:7700/tasks/27' \
  -H 'Authorization: Bearer aSampleMasterKey'

Root Cause（根因分析）

Liquid 模板渲染是“取字段即出錯”

documentTemplate 是 Liquid 模板，{{doc.xxx}} 在渲染時直接讀取文檔字段。字段不存在時 Liquid 渲染器直接拋錯（missing field in document），Meilisearch 拿到渲染失敗就終止整批嵌入。

預設行為：一條壞文檔拖垮整批

預設情況下，只要批次裡有一個文檔模板渲染失敗，整個索引批次就失敗——官方文檔原話：a single problematic document can block all other documents in the same batch。所以出錯後不只是那條文檔沒有向量，是整批都沒嵌入。

不寫 documentTemplate 不會觸發，但質量差

不手動設置 documentTemplate 時，Meilisearch 回退到預設模板（全部可搜索非空字段），不會報這個錯。但官方明確不推薦預設模板：生成的嵌入文本又長又雜，稀釋語義，檢索質量差。自定義模板才是正路，代價就是字段名必須寫對。

The Fix（解決方案）

方案一（推薦）：提交前用 render-template 預演

POST /render-template 可以在不改任何設定的情況下，把模板套到一條樣例文檔上看渲染結果，字段寫錯當場暴露：

curl -X POST 'http://localhost:7700/render-template' \
  -H 'Content-Type: application/json' \
  -H 'Authorization: Bearer aSampleMasterKey' \
  --data-binary '{"template":{"kind":"inlineDocumentTemplate","inline":"中文书籍，书名《{{doc.title}}》，类型 {{doc.genre}}"},"input":{"kind":"inlineDocument","inline":{"id":1,"title":"三体","author":"刘慈欣"}}}'

{"message":"error while rendering template: user error: missing field in document: liquid: Unknown index\n with:\n variable=doc\n requested index=genre\n available indexes=id, title, author\n","code":"template_rendering_error","type":"invalid_request","link":"https://docs.meilisearch.com/errors#template_rendering_error"}

available indexes=id, title, author 直接告訴你文檔裡有什麼，照它改字段名即可。

方案二：用 if 守衛包裹可選字段

有些字段只存在於部分文檔（比如 genre 只有科幻書才有），用 Liquid 的 if 包一層，字段缺失時不渲染該段、不報錯：

{
  "default": {
    "source": "huggingFace",
    "model": "BAAI/bge-small-zh-v1.5",
    "documentTemplate": "中文书籍，书名《{{doc.title}}》，{% if doc.genre %}类型 {{doc.genre}}{% endif %}"
  }
}

方案三：只引用所有文檔都有的字段

字段要麼補全到所有文檔，要麼模板裡不寫。最省事的做法：模板只引用主鍵之外的公共文本字段（如 title、author、description）。

提交修復後的驗證

curl -X PATCH 'http://localhost:7700/indexes/books_vec/settings/embedders' \
  -H 'Content-Type: application/json' \
  -H 'Authorization: Bearer aSampleMasterKey' \
  --data-binary '{"default":{"source":"huggingFace","model":"BAAI/bge-small-zh-v1.5","documentTemplate":"中文书籍，书名《{{doc.title}}》，作者 {{doc.author}}"}}'

# 轮询任务到 succeeded，然后搜索验证语义生效
curl -X POST 'http://localhost:7700/indexes/books_vec/search' \
  -H 'Content-Type: application/json' \
  -H 'Authorization: Bearer aSampleMasterKey' \
  --data-binary '{"q":"仰望星空，讲人类文明命运的科幻巨作","hybrid":{"embedder":"default","semanticRatio":1.0}}'

補充：想跳過失敗文檔繼續嵌入

官方提供實驗性環境變數 MEILI_EXPERIMENTAL_CONFIG_EMBEDDER_FAILURE_MODES，可設定忽略模板渲染失敗（ignore_document_template_failures）或忽略嵌入請求失敗（ignore_embedder_failures）。注意：被忽略的文檔沒有向量，不會出現在語義/hybrid 檢索結果裡，屬於“寧可少幾條也不卡整批”的取捨。

排查建議

• 字段名直接從 GET /indexes/{uid}/documents 的返回鍵裡複製，別憑記憶寫。
• 報錯信息裡 available indexes= 是排錯最快的線索，先看它再改模板。
• 改了模板任務仍失敗，先確認是 template_rendering_error（模板問題）還是別的錯誤碼（比如模型下載失敗），兩類問題的修法完全不同。

References（參考來源）

• Document template best practices — Meilisearch 官方文檔meilisearch-docs
• Error codes（template_rendering_error）— Meilisearch 官方文檔meilisearch-docs