发布日期: 2026-06-22
版本号: v1.48.0

本次更新主要包含三方面内容：一是新增实验性的 POST /render-template 路由，允许用户在启用 renderRoute 功能后，测试和渲染索引中的文档模板或片段，并支持从内联数据或索引文档中获取输入进行渲染；二是调整了外部过滤器的使用范围，现在仅在检索类路由中支持，而编辑、删除文档等写入路由已不再支持该功能；此外还修复了前缀搜索、日志记录、内存预算等若干问题，更新了部分实验性功能的默认行为，并进行了依赖管理和安全改进。

更新内容 （中文）

✨ 增强功能

【实验性】渲染 🫎​ 模板路由

由 @Mubelotix 在 https://github.com/meilisearch/meilisearch/pull/5765 中贡献

引入新的 POST /render-template 路由，可用于在任何输入上渲染任意模板或片段，并受 renderRoute 实验性功能控制访问权限。

该路由可用于在配置嵌入器前后测试文档模板和片段。

该路由的请求体格式如下：

{
  "template": /* templateTarget 对象 */,
  "input": /* inputTarget 对象或 null */
}

其中 template 描述要渲染的模板或片段，input 描述用于渲染模板的输入内容。

调用此路由时，Meilisearch 响应如下：

{
  "template": "{{doc.text}}",
  "rendered": "使用输入渲染后的模板文本"
}

其中 template 包含文档模板的未渲染基础文本，或片段的未渲染基础 JSON 对象，rendered 包含使用所选输入渲染模板的结果。

如果请求中的 input 为 null，则响应中的 rendered 为 null，该路由可用于仅从索引设置中检索模板或片段。

调用路由前须知

该路由的 API 可能发生变化，因此在调用此路由前，请启用 renderRoute 实验性功能：

PATCH /experimental-features --json '{"renderRoute": true}'

示例

  1. 在索引的嵌入器上，使用文档模板渲染索引中的文档
请求 
// POST /render-template

{
  "template": {
    "kind": "documentTemplate",
    "indexUid": "movies",
    "embedder": "myMoviesEmbedder"
  },
  "input": {
    "kind": "indexDocument",
    "indexUid": "movies",
    "id": "2"
}
响应 
{
  "template": "A movie titled {{doc.title}} whose description starts with {{doc.overview|truncatewords:10}}",
  "rendered": "A movie titled Ariel whose description starts with Taisto Kasurinen is a Finnish coal miner whose father has..."
}
  1. 在索引嵌入器的片段上，渲染内联文档
请求 
// POST /render-template

{
  "template": { 
    "kind": "indexingFragment", 
    "indexUid": "dogs", 
    "embedder": "multi",
    "fragment": "captionedImage" 
  },
  "input": { 
    "kind": "inlineDocument", 
    "inline": { // 以 JSON 对象形式内联传递您的文档
      "kind": "dog",
      "name": "iko",
      "breed": "jack russell",
      "mime": "image/png",
      "image": "/9j/4AAQSk..."
    } 
  }
}
响应 
{
  "template": {
    "content": [
      {
        "type": "text",
        "text": "A picture of a {{doc.kind}} of breed {{doc.breed}}"
      },
      {
        "type": "image_base64",
        "image_base64": "data:{{doc.mime}};base64,{{doc.image}}"
      }
    ]
  },
  "rendered": {
    "content": [
      {
        "type": "text",
        "text": "A picture of a dog of breed jack russell"
      },
      {
        "type": "image_base64",
        "image_base64": "data:image/png;base64,/9j/4AAQSk..."
      }
    ]
  }
}
  1. 在索引的多模态嵌入器的搜索片段上，渲染搜索查询
请求 
// POST /render-template
{
  "template": { 
    "kind": "searchFragment", 
    "indexUid": "testIndex", 
    "embedder": "testEmbedder",
    "fragment": "justBreed"
  },
  "input": {
    "kind": "inlineSearch",
    "inline": { // 内联传递搜索查询
      "q": "unused",
      "media": {
        "name": "iko",
        "breed": "jack russell"
      },
      "filter": "ignored"
    }
  }
}
响应 
    {
      "template": "It's a {{ media.breed }}",
      "rendered": "It's a jack russell"
    }
  1. 在索引聊天设置的文档模板上，渲染内联文档
请求 
// POST /render-template

{
  "template": {
    "kind": "chatDocumentTemplate",
    "indexUid": "movies"
	// 无需指定嵌入器，因为聊天文档模板是索引全局的
  },
  "input": {
    "kind": "indexDocument",
    "indexUid": "movies",
    "id": "2"
}
响应 
{
  "template": "{% for field in fields %}{% if field.is_searchable and field.value != nil %}{{ field.name }}: {{ field.value }}
{% endif %}{% endfor %}",
  "rendered": "id: 2
title: Ariel
overview: Taisto Kasurinen is a Finnish coal miner whose father has just committed suicide and who is framed for a crime he did not commit. In jail, he starts to dream about leaving the country and starting a new life. He escapes from prison but things don't go as planned...
genres: DramaCrimeComedy
poster: https://image.tmdb.org/t/p/w500/ojDg0PGvs6R9xYFodRct2kdI6wC.jpg
release_date: 593395200
"
}
  1. 在内联文档模板上渲染索引中的文档
请求 
// POST /render-template

{
  "template": {
    "kind": "inlineDocumentTemplate",
    "inline": "You can pass templates inline as well: nice to test them! {{doc.id}}"
  },
  "input": {
    "kind": "indexDocument",
    "indexUid": "movies",
    "id": "2"
}
响应 
{
  "template": "You can pass templates inline as well: nice to test them! {{doc.id}}",
  "rendered": "You can pass templates inline as well: nice to test them! 2"
}
  1. 在内联索引片段上渲染内联文档
请求 
// POST /render-template

{
  "template": {
    "kind": "inlineFragment",
    "inline": {
      "json_maps": "supported for fragments",
      "any_string": "is in liquid format: {{doc.test}}"
    }
  },
  "input": {
     "kind": "inlineDocument",
    "inline": {
      "test": true
    }
  }
}
响应 
{
  "template": {
    "json_maps": "supported for fragments",
    "any_string": "is in liquid format: {{doc.test}}"
  },
  "rendered": {
    "json_maps": "supported for fragments",
    "any_string": "is in liquid format: true"
  }
}

【实验性】仅在检索路由支持外部过滤器

由 @ManyTheFish 在 https://github.com/meilisearch/meilisearch/pull/6446 中贡献

外部过滤器旨在检索上下文（搜索、获取文档…）中使用，但如果接受外部过滤器，所有与写入或修改文档相关的操作可能会产生一些意外行为。我们更倾向于禁止在写入路由上使用此功能。

以下路由不再支持外部过滤器：

额外变更：我们现在在解析过滤器时确保检查实验性功能。

🪲 错误修复

🔒 安全性

🔩 杂项

❤️ 再次感谢 @genisis0x 和 @antcybersec

更新内容 （原始）

✨ Enhancement

[Experimental] Render 🫎​ template route

by @Mubelotix in https://github.com/meilisearch/meilisearch/pull/5765

Introduces a new POST /render-template route that can be used to render any template or fragment on any input and associated renderRoute experimental feature that gates access to the route.

This route can be used to test document templates and fragments before and after having configured an embedder.

A body payload for the route is of the form:

{
  "template": /* templateTarget object */,
  "input": /* inputTarget object or null */
}

where template describes the template or fragment to render, and input describes what to use to render the template.

Upon calling this route, Meilisearch responds with:

{
  "template": "{{doc.text}}",
  "rendered": "template text after rendering using the input"
}

where template contains the unrendered base text of the document template, or the unrendered base JSON object of a fragment, and rendered contains the result of rendering the template of the chosen input.

If input is null in the request, then rendered is null in the response, and the route can be used solely to retrieve a template or fragment from the settings of an index.

Before calling the route

The API of this route is subject to change, so before calling this route, please enable the renderRoute experimental feature:

PATCH /experimental-features --json '{"renderRoute": true}'

Examples

  1. Rendering a document from an index on a document template from an embedder of that index
request 
// POST /render-template

{
  "template": {
    "kind": "documentTemplate",
    "indexUid": "movies",
    "embedder": "myMoviesEmbedder"
  },
  "input": {
    "kind": "indexDocument",
    "indexUid": "movies",
    "id": "2"
}
response 
{
  "template": "A movie titled {{doc.title}} whose description starts with {{doc.overview|truncatewords:10}}",
  "rendered": "A movie titled Ariel whose description starts with Taisto Kasurinen is a Finnish coal miner whose father has..."
}
  1. Rendering an inline document on a fragment from an embedder of an index
request 
// POST /render-template

{
  "template": { 
    "kind": "indexingFragment", 
    "indexUid": "dogs", 
    "embedder": "multi",
    "fragment": "captionedImage" 
  },
  "input": { 
    "kind": "inlineDocument", 
    "inline": { // pass your document inline as a JSON object
      "kind": "dog",
      "name": "iko",
      "breed": "jack russell",
      "mime": "image/png",
      "image": "/9j/4AAQSk..."
    } 
  }
}
response 
{
  "template": {
    "content": [
      {
        "type": "text",
        "text": "A picture of a {{doc.kind}} of breed {{doc.breed}}"
      },
      {
        "type": "image_base64",
        "image_base64": "data:{{doc.mime}};base64,{{doc.image}}"
      }
    ]
  },
  "rendered": {
    "content": [
      {
        "type": "text",
        "text": "A picture of a dog of breed jack russell"
      },
      {
        "type": "image_base64",
        "image_base64": "data:image/png;base64,/9j/4AAQSk..."
      }
    ]
  }
}
  1. Rendering a search query on a search fragment from a multimodal embedder of an index
request 
// POST /render-template
{
  "template": { 
    "kind": "searchFragment", 
    "indexUid": "testIndex", 
    "embedder": "testEmbedder",
    "fragment": "justBreed"
  },
  "input": {
    "kind": "inlineSearch",
    "inline": { // pass the search query inline
      "q": "unused",
      "media": {
        "name": "iko",
        "breed": "jack russell"
      },
      "filter": "ignored"
    }
  }
}
response 
    {
      "template": "It's a {{ media.breed }}",
      "rendered": "It's a jack russell"
    }
  1. Rendering an inline document on the document template from the chat settings of an index
request 
// POST /render-template

{
  "template": {
    "kind": "chatDocumentTemplate",
    "indexUid": "movies"
	// no embedder to specify since chat document template is global to index
  },
  "input": {
    "kind": "indexDocument",
    "indexUid": "movies",
    "id": "2"
}
response 
{
  "template": "{% for field in fields %}{% if field.is_searchable and field.value != nil %}{{ field.name }}: {{ field.value }}\n{% endif %}{% endfor %}",
  "rendered": "id: 2\ntitle: Ariel\noverview: Taisto Kasurinen is a Finnish coal miner whose father has just committed suicide and who is framed for a crime he did not commit. In jail, he starts to dream about leaving the country and starting a new life. He escapes from prison but things don't go as planned...\ngenres: DramaCrimeComedy\nposter: https://image.tmdb.org/t/p/w500/ojDg0PGvs6R9xYFodRct2kdI6wC.jpg\nrelease_date: 593395200\n"
}
  1. Rendering a document from an index on an inline document template
request 
// POST /render-template

{
  "template": {
    "kind": "inlineDocumentTemplate",
    "inline": "You can pass templates inline as well: nice to test them! {{doc.id}}"
  },
  "input": {
    "kind": "indexDocument",
    "indexUid": "movies",
    "id": "2"
}
response 
{
  "template": "You can pass templates inline as well: nice to test them! {{doc.id}}",
  "rendered": "You can pass templates inline as well: nice to test them! 2"
}
  1. Rendering an inline document on an inline indexing fragment
request 
// POST /render-template

{
  "template": {
    "kind": "inlineFragment",
    "inline": {
      "json_maps": "supported for fragments",
      "any_string": "is in liquid format: {{doc.test}}"
    }
  },
  "input": {
     "kind": "inlineDocument",
    "inline": {
      "test": true
    }
  }
}
response 
{
  "template": {
    "json_maps": "supported for fragments",
    "any_string": "is in liquid format: {{doc.test}}"
  },
  "rendered": {
    "json_maps": "supported for fragments",
    "any_string": "is in liquid format: true"
  }
}

[Experimental] Only support foreign filters on retrieval routes

by @ManyTheFish in https://github.com/meilisearch/meilisearch/pull/6446

Foreign filters are meant to be used in a retrieval context (search, get document…), but all the actions related to writing or modifying a document could have several unexpected behaviors if foreign filters are accepted. We prefer forbidding the usage of this feature on the writing routes.

The following routes do not support Foreign-filter anymore:

Additional change: we now ensure that the experimental features are checked when parsing a filter

🪲 Bug fixes

🔒 Security

🔩 Miscellaneous

❤️ Thanks again to @genisis0x and @antcybersec

下载链接