Dify模板转换节点全解析｜核心引擎Jinja2详解｜8种典型应用场景｜AI生成动态数据分析报告

一、节点介绍

Dify的模板转换节点，是基于Jinja2模板引擎，为用户提供灵活的数据转换能力。借助Jinja2，可以在Dify工作流中快速完成文本拼接、格式转换、数据结构重组等操作，实现"多源数据的无缝衔接与随心转换"。

本文将展开介绍Dify模版转换节点的设计引擎——Jinja2，同时，也将展示介绍Dify模版转化节点的8种典型应用场景，包括：多源文本合成、知识检索结构化、动态表单生成、动态数据报告、智能邮件生成、API数据转换、多语言内容渲染、系统告警模板。

二、核心引擎Jinja2

介绍Dify模版转换节点8种应用场景之前，我们先来了解一下Dify模版转换节点的设计引擎——Jinja2。

1. Jinja2定义与核心目的

• 是什么？

Jinja2 是一款成熟、功能丰富、安全且高效的 Python 模板引擎。它通过优雅的语法、强大的模板继承和宏系统、丰富的过滤器以及良好的可扩展性，完美地实现了业务逻辑与展示逻辑的分离。

• 核心目的：

它的主要作用是分离应用程序逻辑（通常是 Python 代码）和展示逻辑（HTML、XML、配置文件等）。实现将动态内容嵌入到静态的文本模板中。

• 核心思想：

遵循 “Don't Repeat Yourself” 原则，提供强大的工具（如模板继承、宏）来避免代码重复，使模板更易于维护和重用。

2. Jinja2主要特性与优势

• 直观的语法：Jinja2 的语法清晰、简洁，借鉴了 Django 模板，但通常被认为更强大、更灵活。
• {{ ... }}
• 用于输出变量或表达式的结果（会进行自动转义）。
• {% ... %}
• 用于控制语句（如循环、条件判断）、宏定义、块定义、模板继承等。
• {# ... #}
• 用于添加注释。

• 强大的模板继承：
• 这是 Jinja2 的杀手锏之一。
• 你可以定义一个基础模板 (base.html)，在其中使用 {% block block_name %} ... {% endblock %} 标记出可被子模板覆盖的区域。
• 子模板
• 使用 {% extends "base.html" %} 声明继承关系，然后使用 {% block block_name %} ... {% endblock %} 来覆盖或扩展父模板中对应的块。
• 极大提高了模板结构的组织性和可维护性，避免了重复的布局代码。

• 灵活的宏：
• 类似于编程语言中的函数。
• 使用 {% macro macro_name(arg1, arg2) %} ... {% endmacro %} 定义。
• 在其他地方使用 {{ macro_name(val1, val2) }} 调用。
• 封装可重用的 HTML 片段或逻辑，减少重复代码。

• 丰富的过滤器：
• 用于在模板中修改变量的显示格式。
• 语法： {{ variable | filter_name }} 或 {{ variable | filter_name(arg) }}。
• 内置大量过滤器：capitalize, lower, upper, trim, striptags, safe (标记字符串为安全，不转义), default, length, join, format, date, tojson 等等。
• 可以轻松自定义过滤器。

• 自动 HTML 转义：
• 出于安全考虑（防止 XSS 攻击），Jinja2 默认会对 {{ ... }} 中输出的变量进行 HTML 转义（将 <, >, &, " 等字符转换为实体）。如果你确定内容是安全的 HTML，可以使用 | safe 过滤器关闭转义。

• 控制结构：
• 支持完整的编程逻辑：
• 条件判断：{% if condition %} ... {% elif condition2 %} ... {% else %} ... {% endif %}
• 循环：{% for item in sequence %} ... {% endfor %} (支持 loop 变量访问索引、是否首次/末次等状态)
• 变量赋值：{% set variable_name = value %}

• 模板包含：
• 使用 {% include 'template_name.html' %} 将另一个模板的内容包含进来。适用于复用小的、独立的组件（如页眉、页脚）。

• 可扩展性：
• 自定义过滤器：
• 通过 Python 函数轻松扩展。
• 自定义测试：
• {% if variable is test_name %}，用于检查变量是否符合某种条件（如 defined, even, odd, none 等，也可自定义）。
• 自定义全局函数/变量：
• 在模板上下文中注入自定义的函数或常量。
• 自定义扩展：
• 可以编写更复杂的扩展来修改解析器行为或添加新标签。

• 沙箱环境：
• 可以在受限环境中执行模板，增强安全性（尤其当模板内容来自不可信来源时）。

• 高性能：
• Jinja2 将模板编译为 Python 字节码进行缓存，后续渲染速度非常快。虽然可能不是绝对最快的（如 Mako），但其易用性和功能丰富性在性能上做了很好的平衡。

3. Jinja2主要应用场景

• Web 开发：
• 这是最经典的用法。作为 Flask 框架的默认模板引擎，也广泛用于 Django（作为 Django Templates 的替代选择）、Bottle、Pyramid 等其他 Python Web 框架。用于生成动态 HTML 页面。

• 配置管理：
• 在 DevOps 和基础设施即代码 (IaC) 中非常流行。工具如 Ansible、SaltStack 的核心模板引擎就是 Jinja2。用于根据变量和环境动态生成配置文件（如 Nginx, Apache, systemd, 各种应用的 .conf 文件等）。

• 文档生成：
• 结合静态网站生成器（如 Pelican）或自定义脚本，动态生成报告、文档、邮件内容等。

• 代码生成：
• 自动化生成重复性代码片段或基于模板的结构化代码。

• 任何需要文本动态化的场景：
• 生成 XML、JSON（需要 | tojson 过滤器）、CSV、纯文本邮件等。

4. 安装与使用

• 安装：
• 通过 pip 安装非常简单：pip install Jinja2

• 核心组件：
• Environment：
• 核心类，存储配置（如加载器、过滤器、测试、全局变量等）、编译模板。
• Template：
• 表示一个编译好的模板对象，通过 render(**context) 方法渲染，传入一个字典作为上下文（包含模板中可用的变量）。
• FileSystemLoader / PackageLoader 等：
• 用于从文件系统或 Python 包中加载模板。

• 官方文档：
• Jinja2 的官方文档（https://jinja.palletsprojects.com/）非常详尽且清晰，是学习的最佳资源。强烈建议阅读。

三、8种典型应用场景

Dify模版转化节点的8种典型应用场景，包括：多源文本合成、知识检索结构化、动态表单生成、动态数据报告、智能邮件生成、API数据转换、多语言内容渲染、系统告警模板。

场景1：多源文本合成

将分散的标题、摘要、正文内容组合成完整文档：

代码实例：

{{ title }}

{{ intro }}

{{ body }}

场景2：知识检索结构化

将知识检索节点获取的信息及其相关的元数据，整理成一个结构化的 Markdown 格式：

代码实例：

{% for item in chunks %}

### 知识片段 {{ loop.index }}

**相关度**: {{ item.metadata.score | default('未评分') }}

#### {{ item.title | trim }}

{{ item.content | replace('\n', '\n\n') }}

---

{% endfor %}

代码解释：

{% for item in chunks %}

• 循环开始
• 遍历名为chunks的列表，每次迭代将当前元素赋值给item变量

### 知识片段 {{ loop.index }}

• 三级标题
• 使用Markdown的###创建标题
• loop.index
• Jinja2内置变量，表示当前循环的索引（从1开始计数）
• 输出示例
• ### 知识片段 1

**相关度**: {{ item.metadata.score | default('未评分') }}

• 加粗文本
• 显示"相关度"标签
• item.metadata.score
• 访问当前知识片段的评分值
• | default('未评分')
• 过滤器，如果评分为空则显示"未评分"
• 输出示例
• **相关度**: 85 或 **相关度**: 未评分

#### {{ item.title | trim }}

• 四级标题
• 使用Markdown的####创建子标题
• item.title
• 知识片段的标题
• | trim
• 过滤器，去除标题两端的空白字符
• 输出示例
• #### 人工智能发展简史

{{ item.content | replace('\n', '\n\n') }}

• 内容显示
• 输出知识片段的主体内容
• | replace('\n', '\n\n')
• 过滤器，将单换行符\n替换为双换行符\n\n
• 目的
• 在Markdown中，单换行符不会产生新段落，双换行符会创建段落分隔
• 效果
• 保留原文换行结构的同时确保正确分段

{% endfor %}

• 循环结束
• 标记循环结构结束

最终输出示例：

### 知识片段 1

**相关度**: 92

#### 机器学习基础

监督学习需要标注数据...

无监督学习发现数据内在结构...

---

### 知识片段 2

**相关度**: 未评分

#### 神经网络原理

神经元模拟生物神经细胞...

反向传播算法优化权重...

---

场景3：动态表单生成

创建支持多种数据格式的交互式表单：

代码实例：

<form data-format="json">

 <label>用户登录</label>

 <input type="text" name="username" placeholder="请输入账号">

 <input type="password" name="password" placeholder="请输入密码">

 <label>内容编辑</label>

 <textarea name="content"></textarea>

 <div class="datetime-group">

  <input type="date" name="schedule_date">

  <input type="time" name="schedule_time">

 </div>

 <button data-variant="primary">提交</button>

</form>

场景4：动态数据报告生成

将数据库查询结果转换为可视化报告：

代码实例：

# 销售报告 {{ date.today() | date_format("%Y-%m-%d") }}

**总销售额**: ¥{{ total_sales | round(2) | thousands_separator }}

## 区域表现

{% for region in regions %}

- {{ region.name }}: 

 - 完成率: {{ (region.actual/region.target*100) | round(1) }}%

 - 同比增长: {{ region.growth_rate | percent }}

{% endfor %}

代码解释：

1. 报告标题和日期

# 销售报告 {{ date.today() | date_format("%Y-%m-%d") }}

• # 销售报告
• Markdown格式的一级标题
• {{ ... }}
• Jinja2动态表达式
• date.today()
• 调用日期对象获取当前日期
• date_format("%Y-%m-%d")
• 使用过滤器格式化日期%Y-%m-%d，输出格式如2023-10-05
• 最终输出
• # 销售报告 2023-10-05

2. 总销售额显示

**总销售额**: ¥{{ total_sales | round(2) | thousands_separator }}

• **总销售额**:
• Markdown加粗文本
• {{ total_sales ... }}
• 动态变量
• 双重过滤器处理：
• round(2)
• 四舍五入保留2位小数（如123456.789 → 123456.79）
• thousands_separator
• 添加千位分隔符（如123456.79 → 123,456.79）
• 最终输出
• **总销售额**: ¥123,456.79

3. 区域数据循环

{% for region in regions %}

- {{ region.name }}:

- 完成率: {{ (region.actual/region.target*100) | round(1) }}%

- 同比增长: {{ region.growth_rate | percent }}

{% endfor %}

循环结构：

• {% for region in regions %}
• 遍历regions列表中的每个区域对象
• {% endfor %}
• 循环结束标记

每项输出内容：

• {{ region.name }}
• 区域名称，列表项格式（如- 华东地区）
• 完成率:{{ (region.actual/region.target*100) | round(1) }}%
• 实际值/目标值)×100，结果保留1位小数（如85.714% → 85.7%）
• 同比增长: {{ region.growth_rate | percent }}
• 增长率格式化,小数转为百分比（如0.15 → 15%）

完整输出示例：

假设数据为：

regions = [

{"name": "华东", "actual": 85, "target": 100, "growth_rate": 0.15},

{"name": "华北", "actual": 42, "target": 50, "growth_rate": 0.08}

]

生成的报告内容：

# 销售报告 2023-10-05

**总销售额**: ¥1,234,567.89

## 区域表现

- 华东:

- 完成率: 85.0%

- 同比增长: 15%

- 华北:

- 完成率: 84.0%

- 同比增长: 8%

场景5：智能邮件生成

根据用户行为生成个性化邮件内容：

代码实例：

尊敬的{{ user.name }}：

{% if last_login_days > 30 %}

我们注意到您已有{{ last_login_days }}天未登录，为您准备了专属回归礼包！

{% elif unpaid_orders %}

您的订单#{{ unpaid_orders[0].id }}尚未支付，点击完成支付：

{{ unpaid_orders[0].pay_link }}

{% else %}

根据您的浏览记录，为您推荐以下商品：

{% for item in recommended_items %}

- {{ item.name }}（同类用户评分：{{ item.rating }}/5）

{% endfor %}

{% endif %}

场景6：API数据转换

将内部数据结构转换为标准API响应：

代码实例：

{

 "status": "success",

 "data": {

  "userInfo": {

   "userId": "{{ user.uid | string }}",

   "displayName": "{{ user.first_name }} {{ user.last_name[:1] }}.",

   "membershipLevel": "{{ 'VIP' if user.points > 1000 else '普通' }}"

  },

  "features": [

   {% for feature in enabled_features %}

   {

    "name": "{{ feature.name }}",

    "config": {{ feature.config | tojson }}

   }{{ "," if not loop.last }}

   {% endfor %}

  ]

 }

}

场景7：多语言内容渲染

根据区域设置动态切换展示内容：

代码实例：

{% set lang = request.headers.get('Accept-Language', 'en')[:2] %}

{% if lang == 'zh' %}

欢迎回来，{{ user.name }}！您有{{ notification_count }}条未读消息

{% elif lang == 'ja' %}

{{ user.name }}様、未読通知が{{ notification_count }}件あります

{% else %}

Welcome back, {{ user.name }}! You have {{ notification_count }} unread messages

{% endif %}

{{ _('current_balance') }}: 

{{ balance | currency(locale=lang) }}{{ _('current_balance') }}: {{ balance | currency(locale=lang) }}

场景8：系统告警模板

生成可定制的监控告警信息：

代码实例：

[{{ alert.level | upper }}] 系统告警

**触发时间**: {{ alert.timestamp | datetimeformat('%Y-%m-%d %H:%M:%S') }}

**影响服务**: {{ alert.services | join(', ') }}

{% if alert.metrics %}

## 监控指标

{% for metric in alert.metrics %}

- {{ metric.name }}: 

 - 当前值: {{ metric.value }}

 - 阈值: {{ metric.threshold }}

 - 持续时间: {{ metric.duration }}分钟

{% endfor %}

{% endif %}

{% if alert.suggestions %}

## 处理建议

{{ alert.suggestions | bulleted_list }}

{% endif %}

文章来自于“耳东AI”，作者“耳东AI”。