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