Jinja 模板是包含占位符的文本结构，用于生成动态内容。这些占位符在渲染模板时会被填充。您可以在原始文档中查看 Jinja2 功能的完整列表。

您可以在 Haystack 的构建器 (Builders)、输出适配器 (OutputAdapter) 和条件路由器 (ConditionalRouter) 组件中使用这些模板。

下面是一个使用OutputAdapter 的示例，它使用一个简短的 Jinja 模板来仅输出文档数组中的第一个文档的内容字段。

from haystack import Document
from haystack.components.converters import OutputAdapter

adapter = OutputAdapter(template="{{ documents[0].content }}", output_type=str)
input_data = {"documents": [Document(content="Test content")]}
expected_output = {"output": "Test content"}
assert adapter.run(**input_data) == expected_output

使用 Python f-string 和 Jinja

当您将 Jinja 占位符嵌入 Python f-string 时，您必须通过加倍来转义 Jinja 的{ 和}（因此{{ var }} 变为{{{{ var }}}}）。否则，Python 会消耗大括号，导致 Jinja 变量找不到。

首选模板

template = """
Language: {{ language }}
Question: {{ question }}
"""
# pass both variables when rendering

如果您需要使用 f-string（转义大括号）

language = "en"
template = f"""
Language: {language}
Question: {{{{ question }}}}
"""

安全特性

由于我们在某些组件中使用 Jinja 的方式，有一些安全注意事项需要考虑。Jinja 通过执行模板中嵌入的代码来工作，因此这些代码必须来自可信来源，这一点至关重要。如果允许最终用户自定义模板，则可能导致远程代码执行。

为了减轻这种风险，Jinja 模板在沙箱环境中执行和渲染。虽然这种方法更安全，但它的灵活性也较低，并且限制了模板的表现力。如果您需要 Jinja 模板更高级的功能，使用它们的组件会提供一个unsafe 初始化参数——将其设置为False 将禁用沙箱环境并启用不安全模板渲染。

通过不安全模板渲染，OutputAdapter 和 ConditionalRouter 组件允许它们的output_type 设置为Haystack 数据类之一，例如ChatMessage, Document，或Answer.